upstream-man-pages/man2/glGetString.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
   3               "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
   4 <refentry id="glGetString">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glGetString</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glGetString</refname>
  17         <refpurpose>return a string describing the current GL connection</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>const GLubyte* <function>glGetString</function></funcdef>
  23                 <paramdef>GLenum <parameter>name</parameter></paramdef>
  24             </funcprototype>
  25         </funcsynopsis>
  26     </refsynopsisdiv>
  27     <refsect1 id="parameters"><title>Parameters</title>
  28         <variablelist>
  29         <varlistentry>
  30             <term><parameter>name</parameter></term>
  31             <listitem>
  32                 <para>
  33                     Specifies a symbolic constant, one of
  34                     <constant>GL_VENDOR</constant>, <constant>GL_RENDERER</constant>, <constant>GL_VERSION</constant>, <constant>GL_SHADING_LANGUAGE_VERSION</constant>, or <constant>GL_EXTENSIONS</constant>.
  35                 </para>
  36             </listitem>
  37         </varlistentry>
  38         </variablelist>
  39     </refsect1>
  40     <refsect1 id="description"><title>Description</title>
  41         <para>
  42             <function>glGetString</function> returns a pointer to a static string
  43             describing some aspect of the current GL connection.
  44             <parameter>name</parameter> can be one of the following:
  45         </para>
  46         <variablelist>
  47             <varlistentry>
  48                 <term><constant>GL_VENDOR</constant></term>
  49                 <listitem>
  50                     <para>
  51                     </para>
  52                     <para>
  53                         Returns the company responsible for this GL implementation.
  54                         This name does not change from release to release.
  55                     </para>
  56                 </listitem>
  57             </varlistentry>
  58             <varlistentry>
  59                 <term><constant>GL_RENDERER</constant></term>
  60                 <listitem>
  61                     <para>
  62                     </para>
  63                     <para>
  64                         Returns the name of the renderer.
  65                         This name is typically specific to a particular configuration of a hardware
  66                         platform.
  67                         It does not change from release to release.
  68                     </para>
  69                 </listitem>
  70             </varlistentry>
  71             <varlistentry>
  72                 <term><constant>GL_VERSION</constant></term>
  73                 <listitem>
  74                     <para>
  75                     </para>
  76                     <para>
  77                         Returns a version or release number.
  78                     </para>
  79                 </listitem>
  80             </varlistentry>
  81             <varlistentry>
  82                 <term><constant>GL_SHADING_LANGUAGE_VERSION</constant></term>
  83                 <listitem>
  84                     <para>
  85                     </para>
  86                     <para>
  87                         Returns a version or release number for the shading language.
  88                     </para>
  89                 </listitem>
  90             </varlistentry>
  91             <varlistentry>
  92                 <term><constant>GL_EXTENSIONS</constant></term>
  93                 <listitem>
  94                     <para>
  95                     </para>
  96                     <para>
  97                         Returns a space-separated list of supported extensions to GL.
  98                     </para>
  99                 </listitem>
 100             </varlistentry>
 101         </variablelist>
 102         <para>
 103             Because the GL does not include queries for the performance
 104             characteristics of an implementation, some applications are written to
 105             recognize known platforms and modify their GL usage based on known
 106             performance characteristics of these platforms.
 107             Strings <constant>GL_VENDOR</constant> and <constant>GL_RENDERER</constant> together uniquely specify
 108             a platform. They do not change from release to release and should be used
 109             by platform-recognition algorithms.
 110         </para>
 111         <para>
 112             Some applications want to make use of features that
 113             are not part of the standard GL. These features
 114             may be implemented as extensions to the standard GL.
 115             The <constant>GL_EXTENSIONS</constant> string is a space-separated
 116             list of supported GL extensions.
 117             (Extension names never contain a space character.)
 118         </para>
 119         <para>
 120             The <constant>GL_VERSION</constant> and <constant>GL_SHADING_LANGUAGE_VERSION</constant> strings begin with a version number.
 121             The version number uses one
 122             of these forms:
 123         </para>
 124         <para>
 125             <emphasis>major_number.minor_number</emphasis>
 126             <emphasis>major_number.minor_number.release_number</emphasis>
 127         </para>
 128         <para>
 129             Vendor-specific information may follow the version
 130             number. Its format depends on the implementation, but
 131             a space always separates the version number and
 132             the vendor-specific information.
 133         </para>
 134         <para>
 135             All strings are null-terminated.
 136         </para>
 137     </refsect1>
 138     <refsect1 id="notes"><title>Notes</title>
 139         <para>
 140             If an error is generated, <function>glGetString</function> returns 0.
 141         </para>
 142         <para>
 143             The client and server may support different versions or extensions.
 144             <function>glGetString</function> always returns a compatible version number or list of extensions.
 145             The release number always describes the server.
 146         </para>
 147         <para>
 148             <constant>GL_SHADING_LANGUAGE_VERSION</constant> is available only if the GL version is 2.0 or greater.
 149         </para>
 150     </refsect1>
 151     <refsect1 id="errors"><title>Errors</title>
 152         <para>
 153             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>name</parameter> is not an accepted value.
 154         </para>
 155         <para>
 156             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glGetString</function>
 157             is executed between the execution of <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 158             and the corresponding execution of <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.
 159         </para>
 160     </refsect1>
 161     <refsect1 id="Copyright"><title>Copyright</title>
 162         <para>
 163             Copyright <trademark class="copyright"></trademark> 1991-2006
 164             Silicon Graphics, Inc. This document is licensed under the SGI
 165             Free Software B License. For details, see
 166             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 167         </para>
 168     </refsect1>
 169 </refentry>