upstream-man-pages/man2/glGetActiveUniform.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="glGetActiveUniform">
   5     <refmeta>
   6         <refentrytitle>glGetActiveUniform</refentrytitle>
   7         <manvolnum>3G</manvolnum>
   8     </refmeta>
   9     <refnamediv>
  10         <refname>glGetActiveUniform</refname>
  11         <refpurpose>Returns information about an active uniform variable for the specified program object</refpurpose>
  12     </refnamediv>
  13     <refsynopsisdiv><title>C Specification</title>
  14         <funcsynopsis>
  15             <funcprototype>
  16                 <funcdef>void <function>glGetActiveUniform</function></funcdef>
  17                 <paramdef>GLuint <parameter>program</parameter></paramdef>
  18                 <paramdef>GLuint <parameter>index</parameter></paramdef>
  19                 <paramdef>GLsizei <parameter>bufSize</parameter></paramdef>
  20                 <paramdef>GLsizei *<parameter>length</parameter></paramdef>
  21                 <paramdef>GLint *<parameter>size</parameter></paramdef>
  22                 <paramdef>GLenum *<parameter>type</parameter></paramdef>
  23                 <paramdef>GLchar *<parameter>name</parameter></paramdef>
  24             </funcprototype>
  25         </funcsynopsis>
  26     </refsynopsisdiv>
  27     <refsect1 id="parameters"><title>Parameters</title>
  28         <variablelist>
  29             <varlistentry>
  30                 <term><parameter>program</parameter></term>
  31                 <listitem>
  32                     <para>Specifies the program object to be
  33                     queried.</para>
  34                 </listitem>
  35             </varlistentry>
  36             <varlistentry>
  37                 <term><parameter>index</parameter></term>
  38                 <listitem>
  39                     <para>Specifies the index of the uniform variable to
  40                     be queried.</para>
  41                 </listitem>
  42             </varlistentry>
  43             <varlistentry>
  44                 <term><parameter>bufSize</parameter></term>
  45                 <listitem>
  46                     <para>Specifies the maximum number of characters
  47                     OpenGL is allowed to write in the character buffer
  48                     indicated by <parameter>name</parameter>.</para>
  49                 </listitem>
  50             </varlistentry>
  51             <varlistentry>
  52                 <term><parameter>length</parameter></term>
  53                 <listitem>
  54                     <para>Returns the number of characters actually
  55                     written by OpenGL in the string indicated by
  56                     <parameter>name</parameter> (excluding the null
  57                     terminator) if a value other than
  58                     <constant>NULL</constant> is passed.</para>
  59                 </listitem>
  60             </varlistentry>
  61             <varlistentry>
  62                 <term><parameter>size</parameter></term>
  63                 <listitem>
  64                     <para>Returns the size of the uniform
  65                     variable.</para>
  66                 </listitem>
  67             </varlistentry>
  68             <varlistentry>
  69                 <term><parameter>type</parameter></term>
  70                 <listitem>
  71                     <para>Returns the data type of the uniform
  72                     variable.</para>
  73                 </listitem>
  74             </varlistentry>
  75             <varlistentry>
  76                 <term><parameter>name</parameter></term>
  77                 <listitem>
  78                     <para>Returns a null terminated string containing
  79                     the name of the uniform variable.</para>
  80                 </listitem>
  81             </varlistentry>
  82         </variablelist>
  83     </refsect1>
  84     <refsect1 id="description"><title>Description</title>
  85         <para><function>glGetActiveUniform</function> returns
  86         information about an active uniform variable in the program
  87         object specified by <parameter>program</parameter>. The number
  88         of active uniform variables can be obtained by calling
  89         <citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
  90         with the value <constant>GL_ACTIVE_UNIFORMS</constant>. A value
  91         of 0 for <parameter>index</parameter> selects the first active
  92         uniform variable. Permissible values for
  93         <parameter>index</parameter> range from 0 to the number of
  94         active uniform variables minus 1.</para>
  95
  96         <para>Shaders may use either built-in uniform variables,
  97         user-defined uniform variables, or both. Built-in uniform
  98         variables have a prefix of &quot;gl_&quot; and reference
  99         existing OpenGL state or values derived from such state (e.g.,
 100         <parameter>gl_Fog</parameter>,
 101         <parameter>gl_ModelViewMatrix</parameter>, etc., see the OpenGL
 102         Shading Language specification for a complete list.)
 103         User-defined uniform variables have arbitrary names and obtain
 104         their values from the application through calls to
 105         <citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry>.
 106         A uniform variable (either built-in or user-defined) is
 107         considered active if it is determined during the link operation
 108         that it may be accessed during program execution. Therefore,
 109         <parameter>program</parameter> should have previously been the
 110         target of a call to
 111         <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
 112         but it is not necessary for it to have been linked
 113         successfully.</para>
 114
 115         <para>The size of the character buffer required to store the
 116         longest uniform variable name in <parameter>program</parameter>
 117         can be obtained by calling
 118         <citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
 119         with the value
 120         <constant>GL_ACTIVE_UNIFORM_MAX_LENGTH</constant>. This value
 121         should be used to allocate a buffer of sufficient size to store
 122         the returned uniform variable name. The size of this character
 123         buffer is passed in <parameter>bufSize</parameter>, and a
 124         pointer to this character buffer is passed in
 125         <parameter>name.</parameter></para>
 126
 127         <para><function>glGetActiveUniform</function> returns the name
 128         of the uniform variable indicated by
 129         <parameter>index</parameter>, storing it in the character buffer
 130         specified by <parameter>name</parameter>. The string returned
 131         will be null terminated. The actual number of characters written
 132         into this buffer is returned in <parameter>length</parameter>,
 133         and this count does not include the null termination character.
 134         If the length of the returned string is not required, a value of
 135         <constant>NULL</constant> can be passed in the
 136         <parameter>length</parameter> argument.</para>
 137
 138         <para>The <parameter>type</parameter>
 139         argument will return a pointer to the uniform variable's data
 140         type. The symbolic constants
 141         <constant>GL_FLOAT</constant>,
 142         <constant>GL_FLOAT_VEC2</constant>,
 143         <constant>GL_FLOAT_VEC3</constant>,
 144         <constant>GL_FLOAT_VEC4</constant>,
 145         <constant>GL_INT</constant>,
 146         <constant>GL_INT_VEC2</constant>,
 147         <constant>GL_INT_VEC3</constant>,
 148         <constant>GL_INT_VEC4</constant>,
 149         <constant>GL_BOOL</constant>,
 150         <constant>GL_BOOL_VEC2</constant>,
 151         <constant>GL_BOOL_VEC3</constant>,
 152         <constant>GL_BOOL_VEC4</constant>,
 153         <constant>GL_FLOAT_MAT2</constant>,
 154         <constant>GL_FLOAT_MAT3</constant>,
 155         <constant>GL_FLOAT_MAT4</constant>,
 156         <constant>GL_FLOAT_MAT2x3</constant>,
 157         <constant>GL_FLOAT_MAT2x4</constant>,
 158         <constant>GL_FLOAT_MAT3x2</constant>,
 159         <constant>GL_FLOAT_MAT3x4</constant>,
 160         <constant>GL_FLOAT_MAT4x2</constant>,
 161         <constant>GL_FLOAT_MAT4x3</constant>,
 162         <constant>GL_SAMPLER_1D</constant>,
 163         <constant>GL_SAMPLER_2D</constant>,
 164         <constant>GL_SAMPLER_3D</constant>,
 165         <constant>GL_SAMPLER_CUBE</constant>,
 166         <constant>GL_SAMPLER_1D_SHADOW</constant>, or
 167         <constant>GL_SAMPLER_2D_SHADOW</constant>
 168         may be returned.</para>
 169
 170         <para>If one or more elements of an array are active, the name
 171         of the array is returned in <parameter>name</parameter>, the
 172         type is returned in <parameter>type</parameter>, and the
 173         <parameter>size</parameter> parameter returns the highest array
 174         element index used, plus one, as determined by the compiler
 175         and/or linker. Only one active uniform variable will be reported
 176         for a uniform array.</para>
 177
 178         <para>Uniform variables that are declared as structures or
 179         arrays of structures will not be returned directly by this
 180         function. Instead, each of these uniform variables will be
 181         reduced to its fundamental components containing the
 182         &quot;.&quot; and &quot;[]&quot; operators such that each of the
 183         names is valid as an argument to
 184         <citerefentry><refentrytitle>glGetUniformLocation</refentrytitle></citerefentry>.
 185         Each of these reduced uniform variables is counted as one active
 186         uniform variable and is assigned an index. A valid name cannot
 187         be a structure, an array of structures, or a subcomponent of a
 188         vector or matrix.</para>
 189
 190         <para>The size of the uniform variable will be returned in
 191         <parameter>size</parameter>. Uniform variables other than arrays
 192         will have a size of 1. Structures and arrays of structures will
 193         be reduced as described earlier, such that each of the names
 194         returned will be a data type in the earlier list. If this
 195         reduction results in an array, the size returned will be as
 196         described for uniform arrays; otherwise, the size returned will
 197         be 1.</para>
 198
 199         <para>The list of active uniform variables may include both
 200         built-in uniform variables (which begin with the prefix
 201         &quot;gl_&quot;) as well as user-defined uniform variable
 202         names.</para>
 203
 204         <para>This function will return as much information as it can
 205         about the specified active uniform variable. If no information
 206         is available, <parameter>length</parameter> will be 0, and
 207         <parameter>name</parameter> will be an empty string. This
 208         situation could occur if this function is called after a link
 209         operation that failed. If an error occurs, the return values
 210         <parameter>length</parameter>, <parameter>size</parameter>,
 211         <parameter>type</parameter>, and <parameter>name</parameter>
 212         will be unmodified.</para>
 213     </refsect1>
 214     <refsect1 id="notes"><title>Notes</title>
 215         <para><function>glGetActiveUniform</function> is available only
 216         if the GL version is 2.0 or greater.</para>
 217
 218         <para><constant>GL_FLOAT_MAT2x3</constant>,
 219         <constant>GL_FLOAT_MAT2x4</constant>,
 220         <constant>GL_FLOAT_MAT3x2</constant>,
 221         <constant>GL_FLOAT_MAT3x4</constant>,
 222         <constant>GL_FLOAT_MAT4x2</constant>, and
 223         <constant>GL_FLOAT_MAT4x3</constant>
 224         will only be returned as a <parameter>type</parameter>
 225         if the GL version is 2.1 or greater.</para>
 226     </refsect1>
 227     <refsect1 id="errors"><title>Errors</title>
 228         <para><constant>GL_INVALID_VALUE</constant> is generated if
 229         <parameter>program</parameter> is not a value generated by
 230         OpenGL.</para>
 231
 232         <para><constant>GL_INVALID_OPERATION</constant> is generated if
 233         <parameter>program</parameter> is not a program object.</para>
 234
 235         <para><constant>GL_INVALID_VALUE</constant> is generated if
 236         <parameter>index</parameter> is greater than or equal to the
 237         number of active uniform variables in
 238         <parameter>program</parameter>.</para>
 239
 240         <para><constant>GL_INVALID_OPERATION</constant> is generated if
 241         <function>glGetActiveUniform</function> is executed between the
 242         execution of
 243         <citerefentry><refentrytitle>glBegin</refentrytitle></citerefentry>
 244         and the corresponding execution of
 245         <citerefentry><refentrytitle>glEnd</refentrytitle></citerefentry>.</para>
 246
 247         <para><constant>GL_INVALID_VALUE</constant> is generated if
 248         <parameter>bufSize</parameter> is less than 0.</para>
 249     </refsect1>
 250     <refsect1 id="associatedgets"><title>Associated Gets</title>
 251         <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 252         with argument <constant>GL_MAX_VERTEX_UNIFORM_COMPONENTS
 253         </constant> or
 254         <constant>GL_MAX_FRAGMENT_UNIFORM_COMPONENTS</constant>.</para>
 255
 256         <para><citerefentry><refentrytitle>glGetProgram</refentrytitle></citerefentry>
 257         with argument <constant>GL_ACTIVE_UNIFORMS</constant> or
 258         <constant>GL_ACTIVE_UNIFORM_MAX_LENGTH</constant>.</para>
 259
 260         <para><citerefentry><refentrytitle>glIsProgram</refentrytitle></citerefentry></para>
 261     </refsect1>
 262     <refsect1 id="seealso"><title>See Also</title>
 263         <para><citerefentry><refentrytitle>glGetUniform</refentrytitle></citerefentry>,
 264         <citerefentry><refentrytitle>glGetUniformLocation</refentrytitle></citerefentry>,
 265         <citerefentry><refentrytitle>glLinkProgram</refentrytitle></citerefentry>,
 266         <citerefentry><refentrytitle>glUniform</refentrytitle></citerefentry>,
 267         <citerefentry><refentrytitle>glUseProgram</refentrytitle></citerefentry></para>
 268     </refsect1>
 269     <refsect1 id="Copyright"><title>Copyright</title>
 270         <para>
 271             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 272             This material may be distributed subject to the terms and conditions set forth in
 273             the Open Publication License, v 1.0, 8 June 1999.
 274             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 275         </para>
 276     </refsect1>
 277 </refentry>