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