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