upstream-man-pages/man4/glTexBufferRange.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="glTexBufferRange">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2012</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glTexBufferRange</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glTexBufferRange</refname>
  17         <refpurpose>bind a range of a buffer's data store to a buffer texture</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glTexBufferRange</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>internalFormat</parameter></paramdef>
  25                 <paramdef>GLuint <parameter>buffer</parameter></paramdef>
  26                 <paramdef>GLintptr <parameter>offset</parameter></paramdef>
  27                 <paramdef>GLsizeiptr <parameter>size</parameter></paramdef>
  28             </funcprototype>
  29         </funcsynopsis>
  30     </refsynopsisdiv>
  31     <refsect1 id="parameters"><title>Parameters</title>
  32         <variablelist>
  33         <varlistentry>
  34             <term><parameter>target</parameter></term>
  35             <listitem>
  36                 <para>
  37                     Specifies the target of the operation and must be <constant>GL_TEXTURE_BUFFER</constant>.
  38                 </para>
  39             </listitem>
  40         </varlistentry>
  41         <varlistentry>
  42             <term><parameter>internalFormat</parameter></term>
  43             <listitem>
  44                 <para>
  45                     Specifies the internal format of the data in the store belonging to <parameter>buffer</parameter>.
  46                 </para>
  47             </listitem>
  48         </varlistentry>
  49         <varlistentry>
  50             <term><parameter>buffer</parameter></term>
  51             <listitem>
  52                 <para>
  53                     Specifies the name of the buffer object whose storage to attach to the active buffer texture.
  54                 </para>
  55             </listitem>
  56         </varlistentry>
  57         <varlistentry>
  58             <term><parameter>offset</parameter></term>
  59             <listitem>
  60                 <para>
  61                     Specifies the offset of the start of the range of the buffer's data store to attach.
  62                 </para>
  63             </listitem>
  64         </varlistentry>
  65         <varlistentry>
  66             <term><parameter>size</parameter></term>
  67             <listitem>
  68                 <para>
  69                     Specifies the size of the range of the buffer's data store to attach.
  70                 </para>
  71             </listitem>
  72         </varlistentry>
  73         </variablelist>
  74     </refsect1>
  75     <refsect1 id="description"><title>Description</title>
  76         <para>
  77             <function>glTexBufferRange</function> attaches the a range of the data store of the buffer object named <parameter>buffer</parameter> to the active
  78             buffer texture, and specifies the internal format for the texel array found in the attached buffer object. If <parameter>buffer</parameter>
  79             is zero, any buffer object attached to the buffer texture is detached and no new buffer object is attached. If <parameter>buffer</parameter>
  80             is non-zero, it must be the name of an existing buffer object. <parameter>target</parameter> must be <constant>GL_TEXTURE_BUFFER</constant>.
  81             The start of the range is specified by <parameter>offset</parameter> and the size of the range is specified by <parameter>size</parameter>,
  82             both measured in basic machine units. <parameter>offset</parameter> must be greater than or equal to zero, <parameter>size</parameter> must be greater
  83             than zero, and the sum of <parameter>offset</parameter> and <parameter>size</parameter> not exceed the value
  84             of <constant>GL_BUFFER_SIZE</constant> for <parameter>buffer</parameter>. Furthermore, <parameter>offset</parameter> must be
  85             an integer multiple of the value of <constant>GL_TEXTURE_BUFFER_OFFSET_ALIGNMENT</constant>.
  86             <parameter>internalformat</parameter> specifies the storage format, and must be one of the following sized internal formats:
  87         </para>
  88         <informaltable frame="topbot">
  89             <tgroup cols="8" align="left">
  90                 <colspec colnum="1" colname="col1" colwidth="1*"/>
  91                 <colspec colnum="2" colname="col2" colwidth="2*"/>
  92                 <colspec colnum="3" colname="col3" colwidth="1.5*"/>
  93                 <colspec colnum="4" colname="col4" colwidth="1*"/>
  94                 <colspec colnum="5" colname="col5" colwidth="1*"/>
  95                 <colspec colnum="6" colname="col6" colwidth="2*"/>
  96                 <colspec colnum="7" colname="col7" colwidth="1.5*"/>
  97                 <colspec colnum="8" colname="col8" colwidth="1*"/>
  98                 <thead>
  99                     <row>
 100                         <entry morerows="1" rowsep="1" align="center"></entry>
 101                         <entry morerows="1" rowsep="1" align="center"></entry>
 102                         <entry morerows="1" rowsep="1" align="center"></entry>
 103                         <entry morerows="1" rowsep="1" align="center"></entry>
 104                         <entry namest="col5" nameend="col8" rowsep="1" align="left"><emphasis role="bold">
 105                         Component
 106                         </emphasis></entry>
 107                     </row>
 108                 </thead>
 109                 <tbody>
 110                     <row>
 111                         <entry align="left"><emphasis role="bold">Sized Internal Format</emphasis></entry>
 112                         <entry align="left"><emphasis role="bold">Base Type</emphasis></entry>
 113                         <entry align="left"><emphasis role="bold">Components</emphasis></entry>
 114                         <entry align="left"><emphasis role="bold">Norm</emphasis></entry>
 115                         <entry align="center">0</entry>
 116                         <entry align="center">1</entry>
 117                         <entry align="center">2</entry>
 118                         <entry align="center">3</entry>
 119                     </row>
 120                     <row>
 121                         <entry align="left"><constant>GL_R8</constant></entry>
 122                         <entry align="left">ubyte</entry>
 123                         <entry align="left">1</entry>
 124                         <entry align="left">YES</entry>
 125                         <entry align="center">R</entry>
 126                         <entry align="center">0</entry>
 127                         <entry align="center">0</entry>
 128                         <entry align="center">1</entry>
 129                     </row>
 130                     <row>
 131                         <entry align="left"><constant>GL_R16</constant></entry>
 132                         <entry align="left">ushort</entry>
 133                         <entry align="left">1</entry>
 134                         <entry align="left">YES</entry>
 135                         <entry align="center">R</entry>
 136                         <entry align="center">0</entry>
 137                         <entry align="center">0</entry>
 138                         <entry align="center">1</entry>
 139                     </row>
 140                     <row>
 141                         <entry align="left"><constant>GL_R16F</constant></entry>
 142                         <entry align="left">half</entry>
 143                         <entry align="left">1</entry>
 144                         <entry align="left">NO</entry>
 145                         <entry align="center">R</entry>
 146                         <entry align="center">0</entry>
 147                         <entry align="center">0</entry>
 148                         <entry align="center">1</entry>
 149                     </row>
 150                     <row>
 151                         <entry align="left"><constant>GL_R32F</constant></entry>
 152                         <entry align="left">float</entry>
 153                         <entry align="left">1</entry>
 154                         <entry align="left">NO</entry>
 155                         <entry align="center">R</entry>
 156                         <entry align="center">0</entry>
 157                         <entry align="center">0</entry>
 158                         <entry align="center">1</entry>
 159                     </row>
 160                     <row>
 161                         <entry align="left"><constant>GL_R8I</constant></entry>
 162                         <entry align="left">byte</entry>
 163                         <entry align="left">1</entry>
 164                         <entry align="left">NO</entry>
 165                         <entry align="center">R</entry>
 166                         <entry align="center">0</entry>
 167                         <entry align="center">0</entry>
 168                         <entry align="center">1</entry>
 169                     </row>
 170                     <row>
 171                         <entry align="left"><constant>GL_R16I</constant></entry>
 172                         <entry align="left">short</entry>
 173                         <entry align="left">1</entry>
 174                         <entry align="left">NO</entry>
 175                         <entry align="center">R</entry>
 176                         <entry align="center">0</entry>
 177                         <entry align="center">0</entry>
 178                         <entry align="center">1</entry>
 179                     </row>
 180                     <row>
 181                         <entry align="left"><constant>GL_R32I</constant></entry>
 182                         <entry align="left">int</entry>
 183                         <entry align="left">1</entry>
 184                         <entry align="left">NO</entry>
 185                         <entry align="center">R</entry>
 186                         <entry align="center">0</entry>
 187                         <entry align="center">0</entry>
 188                         <entry align="center">1</entry>
 189                     </row>
 190                     <row>
 191                         <entry align="left"><constant>GL_R8UI</constant></entry>
 192                         <entry align="left">ubyte</entry>
 193                         <entry align="left">1</entry>
 194                         <entry align="left">NO</entry>
 195                         <entry align="center">R</entry>
 196                         <entry align="center">0</entry>
 197                         <entry align="center">0</entry>
 198                         <entry align="center">1</entry>
 199                     </row>
 200                     <row>
 201                         <entry align="left"><constant>GL_R16UI</constant></entry>
 202                         <entry align="left">ushort</entry>
 203                         <entry align="left">1</entry>
 204                         <entry align="left">NO</entry>
 205                         <entry align="center">R</entry>
 206                         <entry align="center">0</entry>
 207                         <entry align="center">0</entry>
 208                         <entry align="center">1</entry>
 209                     </row>
 210                     <row>
 211                         <entry align="left"><constant>GL_R32UI</constant></entry>
 212                         <entry align="left">uint</entry>
 213                         <entry align="left">1</entry>
 214                         <entry align="left">NO</entry>
 215                         <entry align="center">R</entry>
 216                         <entry align="center">0</entry>
 217                         <entry align="center">0</entry>
 218                         <entry align="center">1</entry>
 219                     </row>
 220                     <row>
 221                         <entry align="left"><constant>GL_RG8</constant></entry>
 222                         <entry align="left">ubyte</entry>
 223                         <entry align="left">2</entry>
 224                         <entry align="left">YES</entry>
 225                         <entry align="center">R</entry>
 226                         <entry align="center">G</entry>
 227                         <entry align="center">0</entry>
 228                         <entry align="center">1</entry>
 229                     </row>
 230                     <row>
 231                         <entry align="left"><constant>GL_RG16</constant></entry>
 232                         <entry align="left">ushort</entry>
 233                         <entry align="left">2</entry>
 234                         <entry align="left">YES</entry>
 235                         <entry align="center">R</entry>
 236                         <entry align="center">G</entry>
 237                         <entry align="center">0</entry>
 238                         <entry align="center">1</entry>
 239                     </row>
 240                     <row>
 241                         <entry align="left"><constant>GL_RG16F</constant></entry>
 242                         <entry align="left">half</entry>
 243                         <entry align="left">2</entry>
 244                         <entry align="left">NO</entry>
 245                         <entry align="center">R</entry>
 246                         <entry align="center">G</entry>
 247                         <entry align="center">0</entry>
 248                         <entry align="center">1</entry>
 249                     </row>
 250                     <row>
 251                         <entry align="left"><constant>GL_RG32F</constant></entry>
 252                         <entry align="left">float</entry>
 253                         <entry align="left">2</entry>
 254                         <entry align="left">NO</entry>
 255                         <entry align="center">R</entry>
 256                         <entry align="center">G</entry>
 257                         <entry align="center">0</entry>
 258                         <entry align="center">1</entry>
 259                     </row>
 260                     <row>
 261                         <entry align="left"><constant>GL_RG8I</constant></entry>
 262                         <entry align="left">byte</entry>
 263                         <entry align="left">2</entry>
 264                         <entry align="left">NO</entry>
 265                         <entry align="center">R</entry>
 266                         <entry align="center">G</entry>
 267                         <entry align="center">0</entry>
 268                         <entry align="center">1</entry>
 269                     </row>
 270                     <row>
 271                         <entry align="left"><constant>GL_RG16I</constant></entry>
 272                         <entry align="left">short</entry>
 273                         <entry align="left">2</entry>
 274                         <entry align="left">NO</entry>
 275                         <entry align="center">R</entry>
 276                         <entry align="center">G</entry>
 277                         <entry align="center">0</entry>
 278                         <entry align="center">1</entry>
 279                     </row>
 280                     <row>
 281                         <entry align="left"><constant>GL_RG32I</constant></entry>
 282                         <entry align="left">int</entry>
 283                         <entry align="left">2</entry>
 284                         <entry align="left">NO</entry>
 285                         <entry align="center">R</entry>
 286                         <entry align="center">G</entry>
 287                         <entry align="center">0</entry>
 288                         <entry align="center">1</entry>
 289                     </row>
 290                     <row>
 291                         <entry align="left"><constant>GL_RG8UI</constant></entry>
 292                         <entry align="left">ubyte</entry>
 293                         <entry align="left">2</entry>
 294                         <entry align="left">NO</entry>
 295                         <entry align="center">R</entry>
 296                         <entry align="center">G</entry>
 297                         <entry align="center">0</entry>
 298                         <entry align="center">1</entry>
 299                     </row>
 300                     <row>
 301                         <entry align="left"><constant>GL_RG16UI</constant></entry>
 302                         <entry align="left">ushort</entry>
 303                         <entry align="left">2</entry>
 304                         <entry align="left">NO</entry>
 305                         <entry align="center">R</entry>
 306                         <entry align="center">G</entry>
 307                         <entry align="center">0</entry>
 308                         <entry align="center">1</entry>
 309                     </row>
 310                     <row>
 311                         <entry align="left"><constant>GL_RG32UI</constant></entry>
 312                         <entry align="left">uint</entry>
 313                         <entry align="left">2</entry>
 314                         <entry align="left">NO</entry>
 315                         <entry align="center">R</entry>
 316                         <entry align="center">G</entry>
 317                         <entry align="center">0</entry>
 318                         <entry align="center">1</entry>
 319                     </row>
 320                     <row>
 321                         <entry align="left"><constant>GL_RGB32F</constant></entry>
 322                         <entry align="left">float</entry>
 323                         <entry align="left">3</entry>
 324                         <entry align="left">NO</entry>
 325                         <entry align="center">R</entry>
 326                         <entry align="center">G</entry>
 327                         <entry align="center">B</entry>
 328                         <entry align="center">1</entry>
 329                     </row>
 330                     <row>
 331                         <entry align="left"><constant>GL_RGB32I</constant></entry>
 332                         <entry align="left">int</entry>
 333                         <entry align="left">3</entry>
 334                         <entry align="left">NO</entry>
 335                         <entry align="center">R</entry>
 336                         <entry align="center">G</entry>
 337                         <entry align="center">B</entry>
 338                         <entry align="center">1</entry>
 339                     </row>
 340                     <row>
 341                         <entry align="left"><constant>GL_RGB32UI</constant></entry>
 342                         <entry align="left">uint</entry>
 343                         <entry align="left">3</entry>
 344                         <entry align="left">NO</entry>
 345                         <entry align="center">R</entry>
 346                         <entry align="center">G</entry>
 347                         <entry align="center">B</entry>
 348                         <entry align="center">1</entry>
 349                     </row>
 350                     <row>
 351                         <entry align="left"><constant>GL_RGBA8</constant></entry>
 352                         <entry align="left">uint</entry>
 353                         <entry align="left">4</entry>
 354                         <entry align="left">YES</entry>
 355                         <entry align="center">R</entry>
 356                         <entry align="center">G</entry>
 357                         <entry align="center">B</entry>
 358                         <entry align="center">A</entry>
 359                     </row>
 360                     <row>
 361                         <entry align="left"><constant>GL_RGBA16</constant></entry>
 362                         <entry align="left">short</entry>
 363                         <entry align="left">4</entry>
 364                         <entry align="left">YES</entry>
 365                         <entry align="center">R</entry>
 366                         <entry align="center">G</entry>
 367                         <entry align="center">B</entry>
 368                         <entry align="center">A</entry>
 369                     </row>
 370                     <row>
 371                         <entry align="left"><constant>GL_RGBA16F</constant></entry>
 372                         <entry align="left">half</entry>
 373                         <entry align="left">4</entry>
 374                         <entry align="left">NO</entry>
 375                         <entry align="center">R</entry>
 376                         <entry align="center">G</entry>
 377                         <entry align="center">B</entry>
 378                         <entry align="center">A</entry>
 379                     </row>
 380                     <row>
 381                         <entry align="left"><constant>GL_RGBA32F</constant></entry>
 382                         <entry align="left">float</entry>
 383                         <entry align="left">4</entry>
 384                         <entry align="left">NO</entry>
 385                         <entry align="center">R</entry>
 386                         <entry align="center">G</entry>
 387                         <entry align="center">B</entry>
 388                         <entry align="center">A</entry>
 389                     </row>
 390                     <row>
 391                         <entry align="left"><constant>GL_RGBA8I</constant></entry>
 392                         <entry align="left">byte</entry>
 393                         <entry align="left">4</entry>
 394                         <entry align="left">NO</entry>
 395                         <entry align="center">R</entry>
 396                         <entry align="center">G</entry>
 397                         <entry align="center">B</entry>
 398                         <entry align="center">A</entry>
 399                     </row>
 400                     <row>
 401                         <entry align="left"><constant>GL_RGBA16I</constant></entry>
 402                         <entry align="left">short</entry>
 403                         <entry align="left">4</entry>
 404                         <entry align="left">NO</entry>
 405                         <entry align="center">R</entry>
 406                         <entry align="center">G</entry>
 407                         <entry align="center">B</entry>
 408                         <entry align="center">A</entry>
 409                     </row>
 410                     <row>
 411                         <entry align="left"><constant>GL_RGBA32I</constant></entry>
 412                         <entry align="left">int</entry>
 413                         <entry align="left">4</entry>
 414                         <entry align="left">NO</entry>
 415                         <entry align="center">R</entry>
 416                         <entry align="center">G</entry>
 417                         <entry align="center">B</entry>
 418                         <entry align="center">A</entry>
 419                     </row>
 420                     <row>
 421                         <entry align="left"><constant>GL_RGBA8UI</constant></entry>
 422                         <entry align="left">ubyte</entry>
 423                         <entry align="left">4</entry>
 424                         <entry align="left">NO</entry>
 425                         <entry align="center">R</entry>
 426                         <entry align="center">G</entry>
 427                         <entry align="center">B</entry>
 428                         <entry align="center">A</entry>
 429                     </row>
 430                     <row>
 431                         <entry align="left"><constant>GL_RGBA16UI</constant></entry>
 432                         <entry align="left">ushort</entry>
 433                         <entry align="left">4</entry>
 434                         <entry align="left">NO</entry>
 435                         <entry align="center">R</entry>
 436                         <entry align="center">G</entry>
 437                         <entry align="center">B</entry>
 438                         <entry align="center">A</entry>
 439                     </row>
 440                     <row>
 441                         <entry align="left"><constant>GL_RGBA32UI</constant></entry>
 442                         <entry align="left">uint</entry>
 443                         <entry align="left">4</entry>
 444                         <entry align="left">NO</entry>
 445                         <entry align="center">R</entry>
 446                         <entry align="center">G</entry>
 447                         <entry align="center">B</entry>
 448                         <entry align="center">A</entry>
 449                     </row>
 450                 </tbody>
 451             </tgroup>
 452         </informaltable>
 453     </refsect1>
 454     <refsect1 id="errors"><title>Errors</title>
 455         <para>
 456             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not
 457             <constant>GL_TEXTURE_BUFFER</constant>.
 458         </para>
 459         <para>
 460             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>offset</parameter> is less than zero.
 461         </para>
 462         <para>
 463             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>size</parameter> is less than or equal to zero.
 464         </para>
 465         <para>
 466             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>offset</parameter> + <parameter>size</parameter> is
 467             greater than the value of <constant>GL_BUFFER_SIZE</constant> for <parameter>buffer</parameter>.
 468         </para>
 469         <para>
 470             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>offset</parameter> is not
 471             an integer multiple of the value of <constant>GL_TEXTURE_BUFFER_OFFSET_ALIGNMENT</constant>.
 472         </para>
 473     </refsect1>
 474     <refsect1 id="associatedgets"><title>Associated Gets</title>
 475         <para>
 476             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_BUFFER_OFFSET_ALIGNMENT</constant>
 477         </para>
 478         <para>
 479             <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with arguments <constant>GL_TEXTURE_BUFFER_OFFSET</constant>
 480             or <constant>GL_TEXTURE_BUFFER_SIZE</constant>.
 481         </para>
 482     </refsect1>
 483     <refsect1 id="seealso"><title>See Also</title>
 484         <para>
 485             <citerefentry><refentrytitle>glTexBuffer</refentrytitle></citerefentry>.
 486         </para>
 487     </refsect1>
 488     <refsect1 id="Copyright"><title>Copyright</title>
 489         <para>
 490             Copyright <trademark class="copyright"></trademark> 2012 Khronos Group.
 491             This material may be distributed subject to the terms and conditions set forth in
 492             the Open Publication License, v 1.0, 8 June 1999.
 493             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 494         </para>
 495     </refsect1>
 496 </refentry>