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