upstream-doc/man4/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>, if <parameter>name</parameter>
  52     starts with the reserved prefix &quot;gl_&quot;, or if
  53     <parameter>name</parameter> is associated with an atomic counter or
  54     a named uniform block.</para>
  55
  56     <para>Uniform variables that are structures or arrays of
  57     structures may be queried by calling
  58     <function>glGetUniformLocation</function> for each field within
  59     the structure. The array element operator &quot;[]&quot; and the
  60     structure field operator &quot;.&quot; may be used in
  61     <parameter>name</parameter> in order to select elements within
  62     an array or fields within a structure. The result of using these
  63     operators is not allowed to be another structure, an array of
  64     structures, or a subcomponent of a vector or a matrix. Except if
  65     the last part of <parameter>name</parameter> indicates a uniform
  66     variable array, the location of the first element of an array
  67     can be retrieved by using the name of the array, or by using the
  68     name appended by &quot;[0]&quot;.</para>
  69
  70     <para>The actual locations assigned to uniform variables are not
  71     known until the program object is linked successfully. After
  72     linking has occurred, the command
  73     <function>glGetUniformLocation</function> can be used to obtain
  74     the location of a uniform variable. This location value can then
  75     be passed to
  76     <citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry>
  77     to set the value of the uniform variable or to
  78     <citerefentry><refentrytitle>glGetUniform</refentrytitle></citerefentry>
  79     in order to query the current value of the uniform variable.
  80     After a program object has been linked successfully, the index
  81     values for uniform variables remain fixed until the next link
  82     command occurs. Uniform variable locations and values can only
  83     be queried after a link if the link was successful.</para>
  84     </refsect1>
  85     <refsect1 id="errors"><title>Errors</title>
  86     <para><constant>GL_INVALID_VALUE</constant> is generated if
  87     <parameter>program</parameter> is not a value generated by
  88     OpenGL.</para>
  89
  90     <para><constant>GL_INVALID_OPERATION</constant> is generated if
  91     <parameter>program</parameter> is not a program object.</para>
  92
  93     <para><constant>GL_INVALID_OPERATION</constant> is generated if
  94     <parameter>program</parameter> has not been successfully
  95     linked.</para>
  96
  97     </refsect1>
  98     <refsect1 id="associatedgets"><title>Associated Gets</title>
  99     <para><citerefentry><refentrytitle>glGetActiveUniform</refentrytitle></citerefentry>
 100     with arguments <parameter>program</parameter> and the index of
 101     an active uniform variable</para>
 102
 103     <para><citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
 104     with arguments <parameter>program</parameter> and
 105     <constant>GL_ACTIVE_UNIFORMS</constant> or
 106     <constant>GL_ACTIVE_UNIFORM_MAX_LENGTH</constant></para>
 107
 108     <para><citerefentry><refentrytitle>glGetUniform</refentrytitle></citerefentry>
 109     with arguments <parameter>program</parameter> and the name of a
 110     uniform variable</para>
 111     <para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
 112     </refsect1>
 113     <refsect1 id="seealso"><title>See Also</title>
 114     <para><citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
 115     <citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry></para>
 116     </refsect1>
 117     <refsect1 id="Copyright"><title>Copyright</title>
 118         <para>
 119             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 120             <trademark class="copyright"></trademark> 2011 Khronos Group.
 121             This material may be distributed subject to the terms and conditions set forth in
 122             the Open Publication License, v 1.0, 8 June 1999.
 123             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 124         </para>
 125     </refsect1>
 126 </refentry>