upstream-man-pages/man2/glGetUniform.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="glGetUniform">
   5     <refmeta>
   6         <refentrytitle>glGetUniform</refentrytitle>
   7         <manvolnum>3G</manvolnum>
   8     </refmeta>
   9     <refnamediv>
  10         <refdescriptor>glGetUniform</refdescriptor>
  11         <refname>glGetUniformfv</refname>
  12         <refname>glGetUniformiv</refname>
  13         <refpurpose>Returns the value of a uniform variable</refpurpose>
  14     </refnamediv>
  15     <refsynopsisdiv><title>C Specification</title>
  16         <funcsynopsis>
  17             <funcprototype>
  18                 <funcdef>void <function>glGetUniformfv</function></funcdef>
  19                 <paramdef>GLuint <parameter>program</parameter></paramdef>
  20                 <paramdef>GLint <parameter>location</parameter></paramdef>
  21                 <paramdef>GLfloat *<parameter>params</parameter></paramdef>
  22             </funcprototype>
  23             <funcprototype>
  24                 <funcdef>void <function>glGetUniformiv</function></funcdef>
  25                 <paramdef>GLuint <parameter>program</parameter></paramdef>
  26                 <paramdef>GLint <parameter>location</parameter></paramdef>
  27                 <paramdef>GLint *<parameter>params</parameter></paramdef>
  28             </funcprototype>
  29         </funcsynopsis>
  30     </refsynopsisdiv>
  31     <refsect1 id="parameters"><title>Parameters</title>
  32         <variablelist>
  33             <varlistentry>
  34                 <term><parameter>program</parameter></term>
  35                 <listitem>
  36                     <para>Specifies the program object to be
  37                     queried.</para>
  38                 </listitem>
  39             </varlistentry>
  40             <varlistentry>
  41                 <term><parameter>location</parameter></term>
  42                 <listitem>
  43                     <para>Specifies the location of the uniform variable
  44                     to be queried.</para>
  45                 </listitem>
  46             </varlistentry>
  47             <varlistentry>
  48                 <term><parameter>params</parameter></term>
  49                 <listitem>
  50                     <para>Returns the value of the specified uniform
  51                     variable.</para>
  52                 </listitem>
  53             </varlistentry>
  54         </variablelist>
  55     </refsect1>
  56     <refsect1 id="description"><title>Description</title>
  57         <para><function>glGetUniform</function> returns in
  58         <parameter>params</parameter> the value(s) of the specified
  59         uniform variable. The type of the uniform variable specified by
  60         <parameter>location</parameter> determines the number of values
  61         returned. If the uniform variable is defined in the shader as a
  62         boolean, int, or float, a single value will be returned. If it
  63         is defined as a vec2, ivec2, or bvec2, two values will be
  64         returned. If it is defined as a vec3, ivec3, or bvec3, three
  65         values will be returned, and so on. To query values stored in
  66         uniform variables declared as arrays, call
  67         <function>glGetUniform</function> for each element of the array.
  68         To query values stored in uniform variables declared as
  69         structures, call <function>glGetUniform</function> for each
  70         field in the structure. The values for uniform variables
  71         declared as a matrix will be returned in column major
  72         order.</para>
  73
  74         <para>The locations assigned to uniform variables are not known
  75         until the program object is linked. After linking has occurred,
  76         the command
  77         <citerefentry><refentrytitle>glGetUniformLocation</refentrytitle></citerefentry>
  78         can be used to obtain the location of a uniform variable. This
  79         location value can then be passed to
  80         <function>glGetUniform</function> in order to query the current
  81         value of the uniform variable. After a program object has been
  82         linked successfully, the index values for uniform variables
  83         remain fixed until the next link command occurs. The uniform
  84         variable values can only be queried after a link if the link was
  85         successful.</para>
  86     </refsect1>
  87     <refsect1 id="notes"><title>Notes</title>
  88         <para><function>glGetUniform</function> is available only if the
  89         GL version is 2.0 or greater.</para>
  90
  91         <para>If an error is generated, no change is made to the
  92         contents of <parameter>params</parameter>.</para>
  93     </refsect1>
  94     <refsect1 id="errors"><title>Errors</title>
  95         <para><constant>GL_INVALID_VALUE</constant> is generated if
  96         <parameter>program</parameter> is not a value generated by
  97         OpenGL.</para>
  98
  99         <para><constant>GL_INVALID_OPERATION</constant> is generated if
 100         <parameter>program</parameter> is not a program object.</para>
 101
 102         <para><constant>GL_INVALID_OPERATION</constant> is generated if
 103         <parameter>program</parameter> has not been successfully
 104         linked.</para>
 105
 106         <para><constant>GL_INVALID_OPERATION</constant> is generated if
 107         <parameter>location</parameter> does not correspond to a valid
 108         uniform variable location for the specified program object.</para>
 109
 110         <para><constant>GL_INVALID_OPERATION</constant> is generated if
 111         <function>glGetUniform</function> is executed between the
 112         execution of
 113         <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 114         and the corresponding execution of
 115         <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
 116     </refsect1>
 117     <refsect1 id="associatedgets"><title>Associated Gets</title>
 118         <para><citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>
 119         with arguments <parameter>program</parameter> and the index of an active
 120         uniform variable</para>
 121
 122         <para><citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
 123         with arguments <parameter>program</parameter> and
 124         <constant>GL_ACTIVE_UNIFORMS</constant> or
 125         <constant>GL_ACTIVE_UNIFORM_MAX_LENGTH</constant></para>
 126
 127         <para><citerefentry><refentrytitle>glGetUniformLocation</refentrytitle></citerefentry>
 128         with arguments <parameter>program</parameter> and the name of a
 129         uniform variable</para>
 130         <para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
 131     </refsect1>
 132     <refsect1 id="seealso"><title>See Also</title>
 133         <para><citerefentry><refentrytitle>glCreateProgram</refentrytitle></citerefentry>,
 134         <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
 135         <citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry></para>
 136     </refsect1>
 137     <refsect1 id="Copyright"><title>Copyright</title>
 138         <para>
 139             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 140             This material may be distributed subject to the terms and conditions set forth in
 141             the Open Publication License, v 1.0, 8 June 1999.
 142             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 143         </para>
 144     </refsect1>
 145 </refentry>