upstream-doc/man2/xhtml/glGetActiveUniform.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glGetActiveUniform</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glGetActiveUniform"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glGetActiveUniform — Returns information about an active uniform variable for the specified program object</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void <b class="fsfunc">glGetActiveUniform</b>(</code></td><td>GLuint  </td><td><var class="pdparam">program</var>, </td></tr><tr><td> </td><td>GLuint  </td><td><var class="pdparam">index</var>, </td></tr><tr><td> </td><td>GLsizei  </td><td><var class="pdparam">bufSize</var>, </td></tr><tr><td> </td><td>GLsizei * </td><td><var class="pdparam">length</var>, </td></tr><tr><td> </td><td>GLint * </td><td><var class="pdparam">size</var>, </td></tr><tr><td> </td><td>GLenum * </td><td><var class="pdparam">type</var>, </td></tr><tr><td> </td><td>GLchar * </td><td><var class="pdparam">name</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>program</code></em></span></dt><dd><p>Specifies the program object to be
   4                     queried.</p></dd><dt><span class="term"><em class="parameter"><code>index</code></em></span></dt><dd><p>Specifies the index of the uniform variable to
   5                     be queried.</p></dd><dt><span class="term"><em class="parameter"><code>bufSize</code></em></span></dt><dd><p>Specifies the maximum number of characters
   6                     OpenGL is allowed to write in the character buffer
   7                     indicated by <em class="parameter"><code>name</code></em>.</p></dd><dt><span class="term"><em class="parameter"><code>length</code></em></span></dt><dd><p>Returns the number of characters actually
   8                     written by OpenGL in the string indicated by
   9                     <em class="parameter"><code>name</code></em> (excluding the null
  10                     terminator) if a value other than
  11                     <code class="constant">NULL</code> is passed.</p></dd><dt><span class="term"><em class="parameter"><code>size</code></em></span></dt><dd><p>Returns the size of the uniform
  12                     variable.</p></dd><dt><span class="term"><em class="parameter"><code>type</code></em></span></dt><dd><p>Returns the data type of the uniform
  13                     variable.</p></dd><dt><span class="term"><em class="parameter"><code>name</code></em></span></dt><dd><p>Returns a null terminated string containing
  14                     the name of the uniform variable.</p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p><code class="function">glGetActiveUniform</code> returns
  15         information about an active uniform variable in the program
  16         object specified by <em class="parameter"><code>program</code></em>. The number
  17         of active uniform variables can be obtained by calling
  18         <a class="citerefentry" href="glGetProgram.xml"><span class="citerefentry"><span class="refentrytitle">glGetProgram</span></span></a>
  19         with the value <code class="constant">GL_ACTIVE_UNIFORMS</code>. A value
  20         of 0 for <em class="parameter"><code>index</code></em> selects the first active
  21         uniform variable. Permissible values for
  22         <em class="parameter"><code>index</code></em> range from 0 to the number of
  23         active uniform variables minus 1.</p><p>Shaders may use either built-in uniform variables,
  24         user-defined uniform variables, or both. Built-in uniform
  25         variables have a prefix of "gl_" and reference
  26         existing OpenGL state or values derived from such state (e.g.,
  27         <em class="parameter"><code>gl_Fog</code></em>,
  28         <em class="parameter"><code>gl_ModelViewMatrix</code></em>, etc., see the OpenGL
  29         Shading Language specification for a complete list.)
  30         User-defined uniform variables have arbitrary names and obtain
  31         their values from the application through calls to
  32         <a class="citerefentry" href="glUniform.xml"><span class="citerefentry"><span class="refentrytitle">glUniform</span></span></a>.
  33         A uniform variable (either built-in or user-defined) is
  34         considered active if it is determined during the link operation
  35         that it may be accessed during program execution. Therefore,
  36         <em class="parameter"><code>program</code></em> should have previously been the
  37         target of a call to
  38         <a class="citerefentry" href="glLinkProgram.xml"><span class="citerefentry"><span class="refentrytitle">glLinkProgram</span></span></a>,
  39         but it is not necessary for it to have been linked
  40         successfully.</p><p>The size of the character buffer required to store the
  41         longest uniform variable name in <em class="parameter"><code>program</code></em>
  42         can be obtained by calling
  43         <a class="citerefentry" href="glGetProgram.xml"><span class="citerefentry"><span class="refentrytitle">glGetProgram</span></span></a>
  44         with the value
  45         <code class="constant">GL_ACTIVE_UNIFORM_MAX_LENGTH</code>. This value
  46         should be used to allocate a buffer of sufficient size to store
  47         the returned uniform variable name. The size of this character
  48         buffer is passed in <em class="parameter"><code>bufSize</code></em>, and a
  49         pointer to this character buffer is passed in
  50         <em class="parameter"><code>name.</code></em></p><p><code class="function">glGetActiveUniform</code> returns the name
  51         of the uniform variable indicated by
  52         <em class="parameter"><code>index</code></em>, storing it in the character buffer
  53         specified by <em class="parameter"><code>name</code></em>. The string returned
  54         will be null terminated. The actual number of characters written
  55         into this buffer is returned in <em class="parameter"><code>length</code></em>,
  56         and this count does not include the null termination character.
  57         If the length of the returned string is not required, a value of
  58         <code class="constant">NULL</code> can be passed in the
  59         <em class="parameter"><code>length</code></em> argument.</p><p>The <em class="parameter"><code>type</code></em>
  60         argument will return a pointer to the uniform variable's data
  61         type. The symbolic constants
  62         <code class="constant">GL_FLOAT</code>,
  63         <code class="constant">GL_FLOAT_VEC2</code>,
  64         <code class="constant">GL_FLOAT_VEC3</code>,
  65         <code class="constant">GL_FLOAT_VEC4</code>,
  66         <code class="constant">GL_INT</code>,
  67         <code class="constant">GL_INT_VEC2</code>,
  68         <code class="constant">GL_INT_VEC3</code>,
  69         <code class="constant">GL_INT_VEC4</code>,
  70         <code class="constant">GL_BOOL</code>,
  71         <code class="constant">GL_BOOL_VEC2</code>,
  72         <code class="constant">GL_BOOL_VEC3</code>,
  73         <code class="constant">GL_BOOL_VEC4</code>,
  74         <code class="constant">GL_FLOAT_MAT2</code>,
  75         <code class="constant">GL_FLOAT_MAT3</code>,
  76         <code class="constant">GL_FLOAT_MAT4</code>,
  77         <code class="constant">GL_FLOAT_MAT2x3</code>,
  78         <code class="constant">GL_FLOAT_MAT2x4</code>,
  79         <code class="constant">GL_FLOAT_MAT3x2</code>,
  80         <code class="constant">GL_FLOAT_MAT3x4</code>,
  81         <code class="constant">GL_FLOAT_MAT4x2</code>,
  82         <code class="constant">GL_FLOAT_MAT4x3</code>,
  83         <code class="constant">GL_SAMPLER_1D</code>,
  84         <code class="constant">GL_SAMPLER_2D</code>,
  85         <code class="constant">GL_SAMPLER_3D</code>,
  86         <code class="constant">GL_SAMPLER_CUBE</code>,
  87         <code class="constant">GL_SAMPLER_1D_SHADOW</code>, or
  88         <code class="constant">GL_SAMPLER_2D_SHADOW</code>
  89         may be returned.</p><p>If one or more elements of an array are active, the name
  90         of the array is returned in <em class="parameter"><code>name</code></em>, the
  91         type is returned in <em class="parameter"><code>type</code></em>, and the
  92         <em class="parameter"><code>size</code></em> parameter returns the highest array
  93         element index used, plus one, as determined by the compiler
  94         and/or linker. Only one active uniform variable will be reported
  95         for a uniform array.</p><p>Uniform variables that are declared as structures or
  96         arrays of structures will not be returned directly by this
  97         function. Instead, each of these uniform variables will be
  98         reduced to its fundamental components containing the
  99         "." and "[]" operators such that each of the
 100         names is valid as an argument to
 101         <a class="citerefentry" href="glGetUniformLocation.xml"><span class="citerefentry"><span class="refentrytitle">glGetUniformLocation</span></span></a>.
 102         Each of these reduced uniform variables is counted as one active
 103         uniform variable and is assigned an index. A valid name cannot
 104         be a structure, an array of structures, or a subcomponent of a
 105         vector or matrix.</p><p>The size of the uniform variable will be returned in
 106         <em class="parameter"><code>size</code></em>. Uniform variables other than arrays
 107         will have a size of 1. Structures and arrays of structures will
 108         be reduced as described earlier, such that each of the names
 109         returned will be a data type in the earlier list. If this
 110         reduction results in an array, the size returned will be as
 111         described for uniform arrays; otherwise, the size returned will
 112         be 1.</p><p>The list of active uniform variables may include both
 113         built-in uniform variables (which begin with the prefix
 114         "gl_") as well as user-defined uniform variable
 115         names.</p><p>This function will return as much information as it can
 116         about the specified active uniform variable. If no information
 117         is available, <em class="parameter"><code>length</code></em> will be 0, and
 118         <em class="parameter"><code>name</code></em> will be an empty string. This
 119         situation could occur if this function is called after a link
 120         operation that failed. If an error occurs, the return values
 121         <em class="parameter"><code>length</code></em>, <em class="parameter"><code>size</code></em>,
 122         <em class="parameter"><code>type</code></em>, and <em class="parameter"><code>name</code></em>
 123         will be unmodified.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p><code class="function">glGetActiveUniform</code> is available only
 124         if the GL version is 2.0 or greater.</p><p><code class="constant">GL_FLOAT_MAT2x3</code>,
 125         <code class="constant">GL_FLOAT_MAT2x4</code>,
 126         <code class="constant">GL_FLOAT_MAT3x2</code>,
 127         <code class="constant">GL_FLOAT_MAT3x4</code>,
 128         <code class="constant">GL_FLOAT_MAT4x2</code>, and
 129         <code class="constant">GL_FLOAT_MAT4x3</code>
 130         will only be returned as a <em class="parameter"><code>type</code></em>
 131         if the GL version is 2.1 or greater.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p><code class="constant">GL_INVALID_VALUE</code> is generated if
 132         <em class="parameter"><code>program</code></em> is not a value generated by
 133         OpenGL.</p><p><code class="constant">GL_INVALID_OPERATION</code> is generated if
 134         <em class="parameter"><code>program</code></em> is not a program object.</p><p><code class="constant">GL_INVALID_VALUE</code> is generated if
 135         <em class="parameter"><code>index</code></em> is greater than or equal to the
 136         number of active uniform variables in
 137         <em class="parameter"><code>program</code></em>.</p><p><code class="constant">GL_INVALID_OPERATION</code> is generated if
 138         <code class="function">glGetActiveUniform</code> is executed between the
 139         execution of
 140         <a class="citerefentry" href="glBegin.xml"><span class="citerefentry"><span class="refentrytitle">glBegin</span></span></a>
 141         and the corresponding execution of
 142         <a class="citerefentry" href="glEnd.xml"><span class="citerefentry"><span class="refentrytitle">glEnd</span></span></a>.</p><p><code class="constant">GL_INVALID_VALUE</code> is generated if
 143         <em class="parameter"><code>bufSize</code></em> is less than 0.</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p><a class="citerefentry" href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a>
 144         with argument <code class="constant">GL_MAX_VERTEX_UNIFORM_COMPONENTS
 145         </code> or
 146         <code class="constant">GL_MAX_FRAGMENT_UNIFORM_COMPONENTS</code>.</p><p><a class="citerefentry" href="glGetProgram.xml"><span class="citerefentry"><span class="refentrytitle">glGetProgram</span></span></a>
 147         with argument <code class="constant">GL_ACTIVE_UNIFORMS</code> or
 148         <code class="constant">GL_ACTIVE_UNIFORM_MAX_LENGTH</code>.</p><p><a class="citerefentry" href="glIsProgram.xml"><span class="citerefentry"><span class="refentrytitle">glIsProgram</span></span></a></p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p><a class="citerefentry" href="glGetUniform.xml"><span class="citerefentry"><span class="refentrytitle">glGetUniform</span></span></a>,
 149         <a class="citerefentry" href="glGetUniformLocation.xml"><span class="citerefentry"><span class="refentrytitle">glGetUniformLocation</span></span></a>,
 150         <a class="citerefentry" href="glLinkProgram.xml"><span class="citerefentry"><span class="refentrytitle">glLinkProgram</span></span></a>,
 151         <a class="citerefentry" href="glUniform.xml"><span class="citerefentry"><span class="refentrytitle">glUniform</span></span></a>,
 152         <a class="citerefentry" href="glUseProgram.xml"><span class="citerefentry"><span class="refentrytitle">glUseProgram</span></span></a></p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 153             Copyright <span class="trademark"></span>© 2003-2005 3Dlabs Inc. Ltd.
 154             This material may be distributed subject to the terms and conditions set forth in
 155             the Open Publication License, v 1.0, 8 June 1999.
 156             <a class="ulink" href="http://opencontent.org/openpub/" target="_top">http://opencontent.org/openpub/</a>.
 157         </p></div></div></body></html>