upstream-man-pages/man3/glGetUniformLocation.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="glGetUniformLocation">
   5     <refmeta>
   6     <refentrytitle>glGetUniformLocation</refentrytitle>
   7     <manvolnum>3G</manvolnum>
   8     </refmeta>
   9     <refnamediv>
  10     <refname>glGetUniformLocation</refname>
  11     <refpurpose>Returns the location of a uniform variable</refpurpose>
  12     </refnamediv>
  13     <refsynopsisdiv><title>C Specification</title>
  14     <funcsynopsis>
  15         <funcprototype>
  16         <funcdef>GLint <function>glGetUniformLocation</function></funcdef>
  17         <paramdef>GLuint <parameter>program</parameter></paramdef>
  18         <paramdef>const GLchar *<parameter>name</parameter></paramdef>
  19         </funcprototype>
  20     </funcsynopsis>
  21     </refsynopsisdiv>
  22     <refsect1 id="parameters"><title>Parameters</title>
  23     <variablelist>
  24         <varlistentry>
  25         <term><parameter>program</parameter></term>
  26         <listitem>
  27             <para>Specifies the program object to be
  28             queried.</para>
  29         </listitem>
  30         </varlistentry>
  31         <varlistentry>
  32         <term><parameter>name</parameter></term>
  33         <listitem>
  34             <para>Points to a null terminated string containing
  35             the name of the uniform variable whose location is
  36             to be queried.</para>
  37         </listitem>
  38         </varlistentry>
  39     </variablelist>
  40     </refsect1>
  41     <refsect1 id="description"><title>Description</title>
  42     <para><function>glGetUniformLocation </function> returns an
  43     integer that represents the location of a specific uniform
  44     variable within a program object. <parameter>name</parameter>
  45     must be a null terminated string that contains no white space.
  46     <parameter>name</parameter> must be an active uniform variable
  47     name in <parameter>program</parameter> that is not a structure,
  48     an array of structures, or a subcomponent of a vector or a
  49     matrix. This function returns -1 if <parameter>name</parameter>
  50     does not correspond to an active uniform variable in
  51     <parameter>program</parameter> or if <parameter>name</parameter>
  52     starts with the reserved prefix &quot;gl_&quot;.</para>
  53
  54     <para>Uniform variables that are structures or arrays of
  55     structures may be queried by calling
  56     <function>glGetUniformLocation</function> for each field within
  57     the structure. The array element operator &quot;[]&quot; and the
  58     structure field operator &quot;.&quot; may be used in
  59     <parameter>name</parameter> in order to select elements within
  60     an array or fields within a structure. The result of using these
  61     operators is not allowed to be another structure, an array of
  62     structures, or a subcomponent of a vector or a matrix. Except if
  63     the last part of <parameter>name</parameter> indicates a uniform
  64     variable array, the location of the first element of an array
  65     can be retrieved by using the name of the array, or by using the
  66     name appended by &quot;[0]&quot;.</para>
  67
  68     <para>The actual locations assigned to uniform variables are not
  69     known until the program object is linked successfully. After
  70     linking has occurred, the command
  71     <function>glGetUniformLocation</function> can be used to obtain
  72     the location of a uniform variable. This location value can then
  73     be passed to
  74     <citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry>
  75     to set the value of the uniform variable or to
  76     <citerefentry><refentrytitle>glGetUniform</refentrytitle></citerefentry>
  77     in order to query the current value of the uniform variable.
  78     After a program object has been linked successfully, the index
  79     values for uniform variables remain fixed until the next link
  80     command occurs. Uniform variable locations and values can only
  81     be queried after a link if the link was successful.</para>
  82     </refsect1>
  83     <refsect1 id="errors"><title>Errors</title>
  84     <para><constant>GL_INVALID_VALUE</constant> is generated if
  85     <parameter>program</parameter> is not a value generated by
  86     OpenGL.</para>
  87
  88     <para><constant>GL_INVALID_OPERATION</constant> is generated if
  89     <parameter>program</parameter> is not a program object.</para>
  90
  91     <para><constant>GL_INVALID_OPERATION</constant> is generated if
  92     <parameter>program</parameter> has not been successfully
  93     linked.</para>
  94
  95     </refsect1>
  96     <refsect1 id="associatedgets"><title>Associated Gets</title>
  97     <para><citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>
  98     with arguments <parameter>program</parameter> and the index of
  99     an active uniform variable</para>
 100
 101     <para><citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
 102     with arguments <parameter>program</parameter> and
 103     <constant>GL_ACTIVE_UNIFORMS</constant> or
 104     <constant>GL_ACTIVE_UNIFORM_MAX_LENGTH</constant></para>
 105
 106     <para><citerefentry><refentrytitle>glGetUniform</refentrytitle></citerefentry>
 107     with arguments <parameter>program</parameter> and the name of a
 108     uniform variable</para>
 109     <para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
 110     </refsect1>
 111     <refsect1 id="seealso"><title>See Also</title>
 112     <para><citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
 113     <citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry></para>
 114     </refsect1>
 115     <refsect1 id="Copyright"><title>Copyright</title>
 116         <para>
 117             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 118             This material may be distributed subject to the terms and conditions set forth in
 119             the Open Publication License, v 1.0, 8 June 1999.
 120             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 121         </para>
 122     </refsect1>
 123 </refentry>