upstream-doc/man4/glVertexAttribFormat.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="glVertexAttribFormat">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2012</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glVertexAttribFormat</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glVertexAttribFormat</refname>
  17         <refpurpose>specify the organization of vertex arrays</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glVertexAttribFormat</function></funcdef>
  23                 <paramdef>GLuint <parameter>attribindex</parameter></paramdef>
  24                 <paramdef>GLint <parameter>size</parameter></paramdef>
  25                 <paramdef>GLenum <parameter>type</parameter></paramdef>
  26                 <paramdef>GLboolean <parameter>normalized</parameter></paramdef>
  27                 <paramdef>GLuint <parameter>relativeoffset</parameter></paramdef>
  28             </funcprototype>
  29         </funcsynopsis>
  30         <funcsynopsis>
  31             <funcprototype>
  32                 <funcdef>void <function>glVertexAttribIFormat</function></funcdef>
  33                 <paramdef>GLuint <parameter>attribindex</parameter></paramdef>
  34                 <paramdef>GLint <parameter>size</parameter></paramdef>
  35                 <paramdef>GLenum <parameter>type</parameter></paramdef>
  36                 <paramdef>GLuint <parameter>relativeoffset</parameter></paramdef>
  37             </funcprototype>
  38         </funcsynopsis>
  39         <funcsynopsis>
  40             <funcprototype>
  41                 <funcdef>void <function>glVertexAttribLFormat</function></funcdef>
  42                 <paramdef>GLuint <parameter>attribindex</parameter></paramdef>
  43                 <paramdef>GLint <parameter>size</parameter></paramdef>
  44                 <paramdef>GLenum <parameter>type</parameter></paramdef>
  45                 <paramdef>GLuint <parameter>relativeoffset</parameter></paramdef>
  46             </funcprototype>
  47         </funcsynopsis>
  48     </refsynopsisdiv>
  49     <refsect1 id="parameters"><title>Parameters</title>
  50         <variablelist>
  51         <varlistentry>
  52             <term><parameter>attribindex</parameter></term>
  53             <listitem>
  54                 <para>
  55                     The generic vertex attribute array being described.
  56                 </para>
  57             </listitem>
  58         </varlistentry>
  59         <varlistentry>
  60             <term><parameter>size</parameter></term>
  61             <listitem>
  62                 <para>
  63                     The number of values per vertex that are stored in the array.
  64                 </para>
  65             </listitem>
  66         </varlistentry>
  67         <varlistentry>
  68             <term><parameter>type</parameter></term>
  69             <listitem>
  70                 <para>
  71                     The type of the data stored in the array.
  72                 </para>
  73             </listitem>
  74         </varlistentry>
  75         <varlistentry>
  76             <term><parameter>normalized</parameter></term>
  77             <listitem>
  78                 <para>
  79                     The distance between elements within the buffer.
  80                 </para>
  81             </listitem>
  82         </varlistentry>
  83         <varlistentry>
  84             <term><parameter>relativeoffset</parameter></term>
  85             <listitem>
  86                 <para>
  87                     The distance between elements within the buffer.
  88                 </para>
  89             </listitem>
  90         </varlistentry>
  91         </variablelist>
  92     </refsect1>
  93     <refsect1 id="description"><title>Description</title>
  94         <para>
  95             <function>glVertexAttribFormat</function>, <function>glVertexAttribIFormat</function> and
  96             <function>glVertexAttribLFormat</function> specify the organization of data in vertex arrays.
  97             <parameter>attribindex</parameter> specifies the index of the generic vertex attribute
  98             array whose data layout is being described, and must be less
  99             than the value of <constant>GL_MAX_VERTEX_ATTRIBS</constant>.
 100         </para>
 101         <para>
 102             <parameter>size</parameter> determines the number of components per vertex are allocated
 103             to the specifed attribute and must be 1, 2, 3 or 4. <parameter>type</parameter> indicates
 104             the type of the data. If <parameter>type</parameter> is one of <constant>GL_BYTE</constant>,
 105             <constant>GL_SHORT</constant>, <constant>GL_INT</constant>, <constant>GL_FIXED</constant>,
 106             <constant>GL_FLOAT</constant>, <constant>GL_HALF_FLOAT</constant>, and
 107             <constant>GL_DOUBLE</constant> indicate types <code>GLbyte</code>, <code>GLshort</code>,
 108             <code>GLint</code>, <code>GLfixed</code>, <code>GLfloat</code>, <code>GLhalf</code>, and
 109             <code>GLdouble</code>, respectively; the values <constant>GL_UNSIGNED_BYTE</constant>,
 110             <constant>GL_UNSIGNED_SHORT</constant>, and <constant>GL_UNSIGNED_INT</constant> indicate types
 111             <code>GLubyte</code>, <code>GLushort</code>, and <code>GLuint</code>,
 112             respectively; and the values <constant>GL_INT_2_10_10_10_REV</constant> and
 113             <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant> indicating respectively four signed or
 114             unsigned elements packed into a single <code>GLuint</code>.
 115         </para>
 116         <para>
 117             <function>glVertexAttribLFormat</function> is used to specify layout for
 118             data associated with a generic attribute variable declared as 64-bit double precision
 119             components. For <function>glVertexAttribLFormat</function>, <parameter>type</parameter>
 120             must be <constant>GL_DOUBLE</constant>. In contrast to <function>glVertexAttribFormat</function>,
 121             which will cause data declared as <constant>GL_DOUBLE</constant> to be converted to 32-bit
 122             representation, <function>glVertexAttribLFormat</function> causes such data to be left
 123             in its natural, 64-bit representation.
 124         </para>
 125         <para>
 126             For <function>glVertexAttribFormat</function>, if <parameter>normalized</parameter> is
 127             <constant>GL_TRUE</constant>, then integer data is normalized to the range [-1, 1] or
 128             [0, 1] if it is signed or unsigned, respectively. If <parameter>noramlized</parameter> is
 129             <constant>GL_FALSE</constant> then integer data is directly converted to floating point.
 130         </para>
 131         <para>
 132             <parameter>relativeoffset</parameter> is the offset, measured in basic machine units
 133             of the first element relative to the start of the vertex buffer binding this attribute
 134             fetches from.
 135         </para>
 136         <para>
 137             <function>glVertexAttribFormat</function> should be used to describe vertex attribute
 138             layout for floating-point vertex attributes, <function>glVertexAttribIFormat</function>
 139             should be used to describe vertex attribute layout for integer vertex attribute
 140             and <function>glVertexAttribLFormat</function> should be used to describe the layout
 141             for 64-bit vertex attributes. Data for an array specified by
 142             <function>glVertexAttribIFormat</function> will always be left as integer values;
 143             such data are referred to as pure integers.
 144         </para>
 145     </refsect1>
 146     <refsect1 id="errors"><title>Errors</title>
 147         <para>
 148             <constant>GL_INVAILD_VALUE</constant> is generated if <parameter>attribindex</parameter> is greater than
 149             or equal to the value of <constant>GL_MAX_VERTEX_ATTRIBS</constant>.
 150         </para>
 151         <para>
 152             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>size</parameter> is not
 153             one of the accepted values.
 154         </para>
 155         <para>
 156             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>relativeoffset</parameter> is greater
 157             than the value of <constant>GL_MAX_VERTEX_ATTRIB_RELATIVE_OFFSET</constant>.
 158         </para>
 159         <para>
 160             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not
 161             one of the accepted tokens.
 162         </para>
 163         <para>
 164             <constant>GL_INVALID_OPERATION</constant> is generated if no vertex array object is bound.
 165         </para>
 166     </refsect1>
 167     <refsect1 id="associatedgets"><title>Associated Gets</title>
 168         <para>
 169             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with arguments <constant>GL_MAX_VERTEX_ATTRIB_BINDINGS</constant>,
 170             or <constant>GL_MAX_VERTEX_ATTRIB_RELATIVE_OFFSET</constant>.
 171         </para>
 172         <para>
 173             <citerefentry><refentrytitle>glGetVertexAttrib</refentrytitle></citerefentry> with argument <constant>GL_VERTEX_ATTRIB_RELATIVE_OFFSET</constant>.
 174         </para>
 175     </refsect1>
 176     <refsect1 id="seealso"><title>See Also</title>
 177         <para>
 178             <citerefentry><refentrytitle>glBindVertexBuffer</refentrytitle></citerefentry>,
 179             <citerefentry><refentrytitle>glVertexAttribBinding</refentrytitle></citerefentry>,
 180             <citerefentry><refentrytitle>glVertexAttribPointer</refentrytitle></citerefentry>,
 181             <citerefentry><refentrytitle>glVertexBindingDivisor</refentrytitle></citerefentry>,
 182             <citerefentry><refentrytitle>glVertexAttribPointer</refentrytitle></citerefentry>.
 183         </para>
 184     </refsect1>
 185     <refsect1 id="Copyright"><title>Copyright</title>
 186         <para>
 187             Copyright <trademark class="copyright"></trademark> 2012 Khronos Group.
 188             This material may be distributed subject to the terms and conditions set forth in
 189             the Open Publication License, v 1.0, 8 June 1999.
 190             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 191         </para>
 192     </refsect1>
 193 </refentry>