upstream-man-pages/man4/glTexSubImage1D.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="glTexSubImage1D">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glTexSubImage1D</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glTexSubImage1D</refname>
  17         <refpurpose>specify a one-dimensional texture subimage</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glTexSubImage1D</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLint <parameter>level</parameter></paramdef>
  25                 <paramdef>GLint <parameter>xoffset</parameter></paramdef>
  26                 <paramdef>GLsizei <parameter>width</parameter></paramdef>
  27                 <paramdef>GLenum <parameter>format</parameter></paramdef>
  28                 <paramdef>GLenum <parameter>type</parameter></paramdef>
  29                 <paramdef>const GLvoid * <parameter>data</parameter></paramdef>
  30             </funcprototype>
  31         </funcsynopsis>
  32     </refsynopsisdiv>
  33     <!-- eqn: ignoring delim $$ -->
  34     <para>
  35     </para>
  36     <refsect1 id="parameters"><title>Parameters</title>
  37         <variablelist>
  38         <varlistentry>
  39             <term><parameter>target</parameter></term>
  40             <listitem>
  41                 <para>
  42                     Specifies the target texture.
  43                     Must be <constant>GL_TEXTURE_1D</constant>.
  44                 </para>
  45             </listitem>
  46         </varlistentry>
  47         <varlistentry>
  48             <term><parameter>level</parameter></term>
  49             <listitem>
  50                 <para>
  51                     Specifies the level-of-detail number.
  52                     Level 0 is the base image level.
  53                     Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
  54                 </para>
  55             </listitem>
  56         </varlistentry>
  57         <varlistentry>
  58             <term><parameter>xoffset</parameter></term>
  59             <listitem>
  60                 <para>
  61                     Specifies a texel offset in the x direction within the texture array.
  62                 </para>
  63             </listitem>
  64         </varlistentry>
  65         <varlistentry>
  66             <term><parameter>width</parameter></term>
  67             <listitem>
  68                 <para>
  69                     Specifies the width of the texture subimage.
  70                 </para>
  71             </listitem>
  72         </varlistentry>
  73         <varlistentry>
  74             <term><parameter>format</parameter></term>
  75             <listitem>
  76                 <para>
  77                     Specifies the format of the pixel data.
  78                     The following symbolic values are accepted:
  79                     <constant>GL_RED</constant>,
  80                     <constant>GL_RG</constant>,
  81                     <constant>GL_RGB</constant>,
  82                     <constant>GL_BGR</constant>,
  83                     <constant>GL_RGBA</constant>, and
  84                     <constant>GL_BGRA</constant>.
  85                 </para>
  86             </listitem>
  87         </varlistentry>
  88         <varlistentry>
  89             <term><parameter>type</parameter></term>
  90             <listitem>
  91                 <para>
  92                     Specifies the data type of the pixel data.
  93                     The following symbolic values are accepted:
  94                     <constant>GL_UNSIGNED_BYTE</constant>,
  95                     <constant>GL_BYTE</constant>,
  96                     <constant>GL_UNSIGNED_SHORT</constant>,
  97                     <constant>GL_SHORT</constant>,
  98                     <constant>GL_UNSIGNED_INT</constant>,
  99                     <constant>GL_INT</constant>,
 100                     <constant>GL_FLOAT</constant>,
 101                     <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 102                     <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 103                     <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
 104                     <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
 105                     <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 106                     <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 107                     <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 108                     <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 109                     <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 110                     <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 111                     <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, and
 112                     <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>.
 113                 </para>
 114             </listitem>
 115         </varlistentry>
 116         <varlistentry>
 117             <term><parameter>data</parameter></term>
 118             <listitem>
 119                 <para>
 120                     Specifies a pointer to the image data in memory.
 121                 </para>
 122             </listitem>
 123         </varlistentry>
 124         </variablelist>
 125     </refsect1>
 126     <refsect1 id="description"><title>Description</title>
 127         <para>
 128             Texturing maps a portion of a specified texture image
 129             onto each graphical primitive for which texturing is enabled.
 130             To enable or disable one-dimensional texturing, call <citerefentry><refentrytitle>glEnable</refentrytitle></citerefentry>
 131             and <citerefentry><refentrytitle>glDisable</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_1D</constant>.
 132         </para>
 133         <para>
 134             <function>glTexSubImage1D</function> redefines a contiguous subregion of an existing one-dimensional
 135             texture image.
 136             The texels referenced by <parameter>data</parameter> replace the portion of the
 137             existing texture array with x indices <parameter>xoffset</parameter> and
 138             <inlineequation><mml:math>
 139                 <!-- eqn: xoffset + width - 1: -->
 140                 <mml:mrow>
 141                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 142                     <mml:mo>+</mml:mo>
 143                     <mml:mi mathvariant="italic">width</mml:mi>
 144                     <mml:mo>-</mml:mo>
 145                     <mml:mn>1</mml:mn>
 146                 </mml:mrow>
 147             </mml:math></inlineequation>,
 148             inclusive.
 149             This region may not include any texels outside the range of the
 150             texture array as it was originally specified.
 151             It is not an error to specify a subtexture with width of 0, but
 152             such a specification has no effect.
 153         </para>
 154         <para>
 155             If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
 156             (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
 157             specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
 158         </para>
 159     </refsect1>
 160     <refsect1 id="notes"><title>Notes</title>
 161         <para>
 162             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> modes affect texture images.
 163         </para>
 164         <para>
 165             <function>glTexSubImage1D</function> specifies a one-dimensional subtexture for the current texture unit,
 166             specified with <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>.
 167         </para>
 168     </refsect1>
 169     <refsect1 id="errors"><title>Errors</title>
 170         <para>
 171             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not one of the
 172             allowable values.
 173         </para>
 174         <para>
 175             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>format</parameter> is not an accepted
 176             format constant.
 177         </para>
 178         <para>
 179             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>type</parameter> is not a type constant.
 180         </para>
 181         <para>
 182             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
 183         </para>
 184         <para>
 185             <constant>GL_INVALID_VALUE</constant> may be generated if <parameter>level</parameter> is greater
 186             than
 187             <inlineequation><mml:math>
 188                 <!-- eqn: log sub 2: -->
 189                 <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 190                 <mml:mn>2</mml:mn>
 191                 </mml:msub>
 192             </mml:math></inlineequation>
 193             <emphasis>max</emphasis>,
 194             where <emphasis>max</emphasis> is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
 195         </para>
 196         <para>
 197             <constant>GL_INVALID_VALUE</constant> is generated if
 198             <inlineequation><mml:math>
 199                 <!-- eqn: xoffset  <   -b: -->
 200                 <mml:mrow>
 201                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 202                     <mml:mo>&lt;</mml:mo>
 203                     <mml:mrow>
 204                         <mml:mo>-</mml:mo>
 205                         <mml:mi mathvariant="italic">b</mml:mi>
 206                     </mml:mrow>
 207                 </mml:mrow>
 208             </mml:math></inlineequation>,
 209             or if
 210             <inlineequation><mml:math>
 211                 <!-- eqn: (xoffset + width)  >  (w  -  b): -->
 212                 <mml:mrow>
 213                     <mml:mfenced open="(" close=")">
 214                         <mml:mrow>
 215                             <mml:mi mathvariant="italic">xoffset</mml:mi>
 216                             <mml:mo>+</mml:mo>
 217                             <mml:mi mathvariant="italic">width</mml:mi>
 218                         </mml:mrow>
 219                     </mml:mfenced>
 220                     <mml:mo>&gt;</mml:mo>
 221                     <mml:mfenced open="(" close=")">
 222                         <mml:mrow>
 223                             <mml:mi mathvariant="italic">w</mml:mi>
 224                             <mml:mo>-</mml:mo>
 225                             <mml:mi mathvariant="italic">b</mml:mi>
 226                         </mml:mrow>
 227                     </mml:mfenced>
 228                 </mml:mrow>
 229             </mml:math></inlineequation>,
 230             where
 231             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 232             is the <constant>GL_TEXTURE_WIDTH</constant>, and
 233             <inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
 234             is
 235             the width of the <constant>GL_TEXTURE_BORDER</constant>
 236             of the texture image being modified.
 237             Note that
 238             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 239             includes twice the border width.
 240         </para>
 241         <para>
 242             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>width</parameter> is less than 0.
 243         </para>
 244         <para>
 245             <constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not
 246             been defined by a previous <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> operation.
 247         </para>
 248         <para>
 249             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
 250             <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 251             <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 252             <constant>GL_UNSIGNED_SHORT_5_6_5</constant>, or
 253             <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>
 254             and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
 255         </para>
 256         <para>
 257             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>type</parameter> is one of
 258             <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 259             <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 260             <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 261             <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 262             <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 263             <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 264             <constant>GL_UNSIGNED_INT_10_10_10_2</constant>, or
 265             <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>
 266             and <parameter>format</parameter> is neither <constant>GL_RGBA</constant> nor <constant>GL_BGRA</constant>.
 267         </para>
 268         <para>
 269             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 270             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
 271         </para>
 272         <para>
 273             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 274             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
 275             object such that the memory reads required would exceed the data store size.
 276         </para>
 277         <para>
 278             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 279             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and <parameter>data</parameter> is not evenly divisible
 280             into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
 281         </para>
 282     </refsect1>
 283     <refsect1 id="associatedgets"><title>Associated Gets</title>
 284         <para>
 285             <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
 286         </para>
 287         <para>
 288             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
 289         </para>
 290     </refsect1>
 291     <refsect1 id="seealso"><title>See Also</title>
 292         <para>
 293             <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
 294             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 295             <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
 296             <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
 297             <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
 298             <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
 299             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 300             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 301             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 302             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 303             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
 304             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 305             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
 306         </para>
 307     </refsect1>
 308     <refsect1 id="Copyright"><title>Copyright</title>
 309         <para>
 310             Copyright <trademark class="copyright"></trademark> 1991-2006
 311             Silicon Graphics, Inc. This document is licensed under the SGI
 312             Free Software B License. For details, see
 313             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 314         </para>
 315     </refsect1>
 316 </refentry>