upstream-doc/man4/glGetVertexAttrib.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="glGetVertexAttrib">
   5     <refmeta>
   6     <refentrytitle>glGetVertexAttrib</refentrytitle>
   7     <manvolnum>3G</manvolnum>
   8     </refmeta>
   9     <refnamediv>
  10     <refdescriptor>glGetVertexAttrib</refdescriptor>
  11     <refname>glGetVertexAttribdv</refname>
  12     <refname>glGetVertexAttribfv</refname>
  13     <refname>glGetVertexAttribiv</refname>
  14     <refname>glGetVertexAttribIiv</refname>
  15     <refname>glGetVertexAttribIuiv</refname>
  16     <refname>glGetVertexAttribLdv</refname>
  17     <refpurpose>Return a generic vertex attribute parameter</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20     <funcsynopsis>
  21         <funcprototype>
  22         <funcdef>void <function>glGetVertexAttribdv</function></funcdef>
  23         <paramdef>GLuint <parameter>index</parameter></paramdef>
  24         <paramdef>GLenum <parameter>pname</parameter></paramdef>
  25         <paramdef>GLdouble *<parameter>params</parameter></paramdef>
  26         </funcprototype>
  27         <funcprototype>
  28         <funcdef>void <function>glGetVertexAttribfv</function></funcdef>
  29         <paramdef>GLuint <parameter>index</parameter></paramdef>
  30         <paramdef>GLenum <parameter>pname</parameter></paramdef>
  31         <paramdef>GLfloat *<parameter>params</parameter></paramdef>
  32         </funcprototype>
  33         <funcprototype>
  34         <funcdef>void <function>glGetVertexAttribiv</function></funcdef>
  35         <paramdef>GLuint <parameter>index</parameter></paramdef>
  36         <paramdef>GLenum <parameter>pname</parameter></paramdef>
  37         <paramdef>GLint *<parameter>params</parameter></paramdef>
  38         </funcprototype>
  39         <funcprototype>
  40         <funcdef>void <function>glGetVertexAttribIiv</function></funcdef>
  41         <paramdef>GLuint <parameter>index</parameter></paramdef>
  42         <paramdef>GLenum <parameter>pname</parameter></paramdef>
  43         <paramdef>GLint *<parameter>params</parameter></paramdef>
  44         </funcprototype>
  45         <funcprototype>
  46         <funcdef>void <function>glGetVertexAttribIuiv</function></funcdef>
  47         <paramdef>GLuint <parameter>index</parameter></paramdef>
  48         <paramdef>GLenum <parameter>pname</parameter></paramdef>
  49         <paramdef>GLuint *<parameter>params</parameter></paramdef>
  50         </funcprototype>
  51         <funcprototype>
  52         <funcdef>void <function>glGetVertexAttribLdv</function></funcdef>
  53         <paramdef>GLuint <parameter>index</parameter></paramdef>
  54         <paramdef>GLenum <parameter>pname</parameter></paramdef>
  55         <paramdef>GLdouble *<parameter>params</parameter></paramdef>
  56         </funcprototype>
  57     </funcsynopsis>
  58     </refsynopsisdiv>
  59     <refsect1 id="parameters"><title>Parameters</title>
  60     <variablelist>
  61         <varlistentry>
  62         <term><parameter>index</parameter></term>
  63         <listitem>
  64             <para>Specifies the generic vertex attribute
  65             parameter to be queried.</para>
  66         </listitem>
  67         </varlistentry>
  68         <varlistentry>
  69         <term><parameter>pname</parameter></term>
  70         <listitem>
  71             <para>Specifies the symbolic name of the vertex
  72             attribute parameter to be queried. Accepted values are
  73             <constant>GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING</constant>,
  74             <constant>GL_VERTEX_ATTRIB_ARRAY_ENABLED</constant>,
  75             <constant>GL_VERTEX_ATTRIB_ARRAY_SIZE</constant>,
  76             <constant>GL_VERTEX_ATTRIB_ARRAY_STRIDE</constant>,
  77             <constant>GL_VERTEX_ATTRIB_ARRAY_TYPE</constant>,
  78             <constant>GL_VERTEX_ATTRIB_ARRAY_NORMALIZED</constant>,
  79             <constant>GL_VERTEX_ATTRIB_ARRAY_INTEGER</constant>,
  80             <constant>GL_VERTEX_ATTRIB_ARRAY_DIVISOR</constant>, or
  81             <constant>GL_CURRENT_VERTEX_ATTRIB</constant>.</para>
  82         </listitem>
  83         </varlistentry>
  84         <varlistentry>
  85         <term><parameter>params</parameter></term>
  86         <listitem>
  87             <para>Returns the requested data.</para>
  88         </listitem>
  89         </varlistentry>
  90     </variablelist>
  91     </refsect1>
  92     <refsect1 id="description"><title>Description</title>
  93     <para><function>glGetVertexAttrib</function> returns in
  94     <parameter>params</parameter> the value of a generic vertex
  95     attribute parameter. The generic vertex attribute to be queried
  96     is specified by <parameter>index</parameter>, and the parameter
  97     to be queried is specified by <parameter>pname</parameter>.</para>
  98
  99     <para>The accepted parameter names are as follows:</para>
 100
 101     <variablelist>
 102         <varlistentry>
 103         <term><constant>GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING</constant></term>
 104         <listitem>
 105                 <para>
 106                 </para>
 107             <para> <parameter>params</parameter> returns a
 108             single value, the name of the buffer object currently bound to
 109                     the binding point corresponding to generic vertex attribute array
 110                     <parameter>index</parameter>. If no buffer object is bound,
 111                     0 is returned. The initial value is 0.</para>
 112         </listitem>
 113         </varlistentry>
 114
 115         <varlistentry>
 116         <term><constant>GL_VERTEX_ATTRIB_ARRAY_ENABLED</constant></term>
 117         <listitem>
 118                 <para>
 119                 </para>
 120             <para> <parameter>params</parameter> returns a
 121             single value that is non-zero (true) if the vertex
 122             attribute array for <parameter>index</parameter> is
 123             enabled and 0 (false) if it is disabled. The initial
 124             value is <constant>GL_FALSE</constant>.</para>
 125         </listitem>
 126         </varlistentry>
 127
 128         <varlistentry>
 129         <term><constant>GL_VERTEX_ATTRIB_ARRAY_SIZE</constant></term>
 130         <listitem>
 131                 <para>
 132                 </para>
 133             <para> <parameter>params</parameter> returns a
 134             single value, the size of the vertex attribute array
 135             for <parameter>index</parameter>. The size is the
 136             number of values for each element of the vertex
 137             attribute array, and it will be 1, 2, 3, or 4. The
 138             initial value is 4.</para>
 139         </listitem>
 140         </varlistentry>
 141
 142         <varlistentry>
 143         <term><constant>GL_VERTEX_ATTRIB_ARRAY_STRIDE</constant></term>
 144         <listitem>
 145                 <para>
 146                 </para>
 147             <para> <parameter>params</parameter> returns a
 148             single value, the array stride for (number of bytes
 149             between successive elements in) the vertex attribute
 150             array for <parameter>index</parameter>. A value of 0
 151             indicates that the array elements are stored
 152             sequentially in memory. The initial value is 0.</para>
 153         </listitem>
 154         </varlistentry>
 155
 156         <varlistentry>
 157         <term><constant>GL_VERTEX_ATTRIB_ARRAY_TYPE</constant></term>
 158         <listitem>
 159                 <para>
 160                 </para>
 161             <para> <parameter>params</parameter> returns a
 162             single value, a symbolic constant indicating the
 163             array type for the vertex attribute array for
 164             <parameter>index</parameter>. Possible values are
 165             <constant>GL_BYTE</constant>,
 166             <constant>GL_UNSIGNED_BYTE</constant>,
 167             <constant>GL_SHORT</constant>,
 168             <constant>GL_UNSIGNED_SHORT</constant>,
 169             <constant>GL_INT</constant>,
 170             <constant>GL_UNSIGNED_INT</constant>,
 171             <constant>GL_FLOAT</constant>, and
 172             <constant>GL_DOUBLE</constant>. The initial value is
 173             <constant>GL_FLOAT</constant>.</para>
 174         </listitem>
 175         </varlistentry>
 176
 177         <varlistentry>
 178         <term><constant>GL_VERTEX_ATTRIB_ARRAY_NORMALIZED</constant></term>
 179         <listitem>
 180                 <para>
 181                 </para>
 182             <para> <parameter>params</parameter> returns a
 183             single value that is non-zero (true) if fixed-point
 184             data types for the vertex attribute array indicated
 185             by <parameter>index</parameter> are normalized when
 186             they are converted to floating point, and 0 (false)
 187             otherwise. The initial value is
 188             <constant>GL_FALSE</constant>.</para>
 189         </listitem>
 190         </varlistentry>
 191
 192         <varlistentry>
 193         <term><constant>GL_VERTEX_ATTRIB_ARRAY_INTEGER</constant></term>
 194         <listitem>
 195                 <para>
 196                 </para>
 197             <para> <parameter>params</parameter> returns a
 198             single value that is non-zero (true) if fixed-point
 199             data types for the vertex attribute array indicated
 200             by <parameter>index</parameter> have integer data types, and 0 (false)
 201             otherwise. The initial value is
 202             0 (<constant>GL_FALSE</constant>).</para>
 203         </listitem>
 204         </varlistentry>
 205
 206         <varlistentry>
 207         <term><constant>GL_VERTEX_ATTRIB_ARRAY_DIVISOR</constant></term>
 208         <listitem>
 209                 <para>
 210                 </para>
 211             <para> <parameter>params</parameter> returns a
 212             single value that is the frequency divisor used for instanced
 213             rendering. See <citerefentry><refentrytitle>glVertexAttribDivisor</refentrytitle></citerefentry>.
 214             The initial value is 0.</para>
 215         </listitem>
 216         </varlistentry>
 217
 218         <varlistentry>
 219         <term><constant>GL_CURRENT_VERTEX_ATTRIB</constant></term>
 220         <listitem>
 221                 <para>
 222                 </para>
 223             <para> <parameter>params</parameter> returns four
 224             values that represent the current value for the
 225             generic vertex attribute specified by index. Generic
 226             vertex attribute 0 is unique in that it has no
 227             current state, so an error will be generated if
 228             <parameter>index</parameter> is 0. The initial value
 229             for all other generic vertex attributes is
 230             (0,0,0,1).</para>
 231             <para>
 232                 <function>glGetVertexAttribdv</function> and <function>glGetVertexAttribfv</function>
 233                 return the current attribute values as four single-precision floating-point values;
 234                 <function>glGetVertexAttribiv</function> reads them as floating-point values and
 235                 converts them to four integer values; <function>glGetVertexAttribIiv</function> and
 236                 <function>glGetVertexAttribIuiv</function> read and return them as signed or unsigned
 237                 integer values, respectively; <function>glGetVertexAttribLdv</function> reads and returns
 238                 them as four double-precision floating-point values.
 239             </para>
 240         </listitem>
 241         </varlistentry>
 242     </variablelist>
 243
 244     <para>All of the parameters except <constant>GL_CURRENT_VERTEX_ATTRIB</constant>
 245     represent state stored in the currently bound vertex array object.</para>
 246
 247     </refsect1>
 248     <refsect1 id="notes"><title>Notes</title>
 249     <para>If an error is generated, no change is made to the
 250     contents of <parameter>params</parameter>.</para>
 251     </refsect1>
 252     <refsect1 id="errors"><title>Errors</title>
 253     <para><constant>GL_INVALID_OPERATION</constant> is generated if <parameter>pname</parameter>
 254     is not <constant>GL_CURRENT_VERTEX_ATTRIB</constant> and there is no
 255     currently bound vertex array object.</para>
 256
 257     <para><constant>GL_INVALID_VALUE</constant> is generated if
 258     <parameter>index</parameter> is greater than or equal to
 259     <constant>GL_MAX_VERTEX_ATTRIBS</constant>.</para>
 260
 261     <para><constant>GL_INVALID_ENUM</constant> is generated if
 262     <parameter>pname</parameter> is not an accepted value.</para>
 263
 264     <para><constant>GL_INVALID_OPERATION</constant> is generated if
 265     <parameter>index</parameter> is 0 and
 266     <parameter>pname</parameter> is
 267     <constant>GL_CURRENT_VERTEX_ATTRIB</constant>.</para>
 268     </refsect1>
 269     <refsect1 id="associatedgets"><title>Associated Gets</title>
 270     <para><citerefentry><refentrytitle>glGet</refentrytitle></citerefentry>
 271     with argument <constant>GL_MAX_VERTEX_ATTRIBS</constant></para>
 272
 273     <para><citerefentry><refentrytitle>glGetVertexAttribPointerv</refentrytitle></citerefentry>
 274     with arguments <parameter>index</parameter> and
 275     <constant>GL_VERTEX_ATTRIB_ARRAY_POINTER</constant></para>
 276     </refsect1>
 277     <refsect1 id="seealso"><title>See Also</title>
 278     <para><citerefentry><refentrytitle>glBindAttribLocation</refentrytitle></citerefentry>,
 279     <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>,
 280     <citerefentry><refentrytitle>glDisableVertexAttribArray</refentrytitle></citerefentry>,
 281     <citerefentry><refentrytitle>glEnableVertexAttribArray</refentrytitle></citerefentry>,
 282     <citerefentry><refentrytitle>glVertexAttrib</refentrytitle></citerefentry>,
 283     <citerefentry><refentrytitle>glVertexAttribDivisor</refentrytitle></citerefentry>,
 284     <citerefentry><refentrytitle>glVertexAttribPointer</refentrytitle></citerefentry></para>
 285     </refsect1>
 286     <refsect1 id="Copyright"><title>Copyright</title>
 287         <para>
 288             Copyright <trademark class="copyright"></trademark> 2003-2005 3Dlabs Inc. Ltd.
 289             Copyright <trademark class="copyright"></trademark> 2010 Khronos Group.
 290             This material may be distributed subject to the terms and conditions set forth in
 291             the Open Publication License, v 1.0, 8 June 1999.
 292             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 293         </para>
 294     </refsect1>
 295 </refentry>