upstream-man-pages/man2/glCopyTexSubImage1D.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="glCopyTexSubImage1D">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glCopyTexSubImage1D</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glCopyTexSubImage1D</refname>
  17         <refpurpose>copy a one-dimensional texture subimage</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glCopyTexSubImage1D</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>GLint <parameter>x</parameter></paramdef>
  27                 <paramdef>GLint <parameter>y</parameter></paramdef>
  28                 <paramdef>GLsizei <parameter>width</parameter></paramdef>
  29             </funcprototype>
  30         </funcsynopsis>
  31     </refsynopsisdiv>
  32     <!-- eqn: ignoring delim $$ -->
  33     <para>
  34     </para>
  35     <refsect1 id="parameters"><title>Parameters</title>
  36         <variablelist>
  37         <varlistentry>
  38             <term><parameter>target</parameter></term>
  39             <listitem>
  40                 <para>
  41                     Specifies the target texture.
  42                     Must be <constant>GL_TEXTURE_1D</constant>.
  43                 </para>
  44             </listitem>
  45         </varlistentry>
  46         <varlistentry>
  47             <term><parameter>level</parameter></term>
  48             <listitem>
  49                 <para>
  50                     Specifies the level-of-detail number.
  51                     Level 0 is the base image level.
  52                     Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
  53                 </para>
  54             </listitem>
  55         </varlistentry>
  56         <varlistentry>
  57             <term><parameter>xoffset</parameter></term>
  58             <listitem>
  59                 <para>
  60                     Specifies the texel offset within the texture array.
  61                 </para>
  62             </listitem>
  63         </varlistentry>
  64         <varlistentry>
  65             <term><parameter>x</parameter></term>
  66             <term><parameter>y</parameter></term>
  67             <listitem>
  68                 <para>
  69                     Specify the window coordinates of the left corner
  70                     of the row of pixels to be copied.
  71                 </para>
  72             </listitem>
  73         </varlistentry>
  74         <varlistentry>
  75             <term><parameter>width</parameter></term>
  76             <listitem>
  77                 <para>
  78                     Specifies the width of the texture subimage.
  79                 </para>
  80             </listitem>
  81         </varlistentry>
  82         </variablelist>
  83     </refsect1>
  84     <refsect1 id="description"><title>Description</title>
  85         <para>
  86             <function>glCopyTexSubImage1D</function> replaces a portion of a one-dimensional
  87             texture image with pixels from the current <constant>GL_READ_BUFFER</constant> (rather
  88             than from main memory, as is the case for <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>).
  89         </para>
  90         <para>
  91             The screen-aligned pixel row with left corner at (<parameter>x</parameter>,\ <parameter>y</parameter>), and with
  92             length <parameter>width</parameter> replaces the portion of the
  93             texture array with x indices <parameter>xoffset</parameter> through
  94             <inlineequation><mml:math>
  95                 <!-- eqn: xoffset  +  width  -  1:-->
  96                 <mml:mrow>
  97                     <mml:mi mathvariant="italic">xoffset</mml:mi>
  98                     <mml:mo>+</mml:mo>
  99                     <mml:mi mathvariant="italic">width</mml:mi>
 100                     <mml:mo>-</mml:mo>
 101                     <mml:mn>1</mml:mn>
 102                 </mml:mrow>
 103             </mml:math></inlineequation>,
 104             inclusive. The destination in the texture array may not
 105             include any texels outside the texture array as it was
 106             originally specified.
 107         </para>
 108         <para>
 109             The pixels in the row are processed exactly as if
 110             <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry> had been called, but the process stops just before
 111             final conversion.
 112             At this point, all pixel component values are clamped to the range
 113             <inlineequation><mml:math>
 114                 <!-- eqn: [0,1]:-->
 115                 <mml:mfenced open="[" close="]">
 116                     <mml:mn>0</mml:mn>
 117                     <mml:mn>1</mml:mn>
 118                 </mml:mfenced>
 119             </mml:math></inlineequation>
 120             and then converted to the texture's internal format for storage in the texel
 121             array.
 122         </para>
 123         <para>
 124             It is not an error to specify a subtexture with zero width, but
 125             such a specification has no effect.
 126             If any of the pixels within the specified row of the current
 127             <constant>GL_READ_BUFFER</constant> are outside the read window associated with the current
 128             rendering context, then the values obtained for those pixels are undefined.
 129         </para>
 130         <para>
 131             No change is made to the <emphasis>internalformat</emphasis>, <emphasis>width</emphasis>,
 132             or <emphasis>border</emphasis> parameters of the specified texture
 133             array or to texel values outside the specified subregion.
 134         </para>
 135     </refsect1>
 136     <refsect1 id="notes"><title>Notes</title>
 137         <para>
 138             <function>glCopyTexSubImage1D</function> is available only if the GL version is 1.1 or greater.
 139         </para>
 140         <para>
 141             Texturing has no effect in color index mode.
 142         </para>
 143         <para>
 144             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry> and <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry> modes affect texture images
 145             in exactly the way they affect <citerefentry><refentrytitle>glDrawPixels</refentrytitle></citerefentry>.
 146         </para>
 147         <para>
 148             When the <code>ARB_imaging</code> extension is supported, the RGBA components
 149             copied from the framebuffer may be processed by the imaging pipeline.  See
 150             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> for specific details.
 151         </para>
 152     </refsect1>
 153     <refsect1 id="errors"><title>Errors</title>
 154         <para>
 155             <constant>GL_INVALID_ENUM</constant> is generated if /<parameter>target</parameter> is not <constant>GL_TEXTURE_1D</constant>.
 156         </para>
 157         <para>
 158             <constant>GL_INVALID_OPERATION</constant> is generated if the texture array has not
 159             been defined by a previous <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry> operation.
 160         </para>
 161         <para>
 162             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
 163         </para>
 164         <para>
 165             <constant>GL_INVALID_VALUE</constant> may be generated if
 166             <inlineequation><mml:math>
 167                 <!-- eqn: level  >  log sub 2(max):-->
 168                 <mml:mrow>
 169                     <mml:mi mathvariant="italic">level</mml:mi>
 170                     <mml:mo>&gt;</mml:mo>
 171                     <mml:mrow>
 172                         <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 173                         <mml:mn>2</mml:mn>
 174                         </mml:msub>
 175                         <mml:mo>&af;</mml:mo>
 176                         <mml:mfenced open="(" close=")">
 177                             <mml:mi mathvariant="italic">max</mml:mi>
 178                         </mml:mfenced>
 179                     </mml:mrow>
 180                 </mml:mrow>
 181             </mml:math></inlineequation>,
 182             where <emphasis>max</emphasis> is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
 183         </para>
 184         <para>
 185             <constant>GL_INVALID_VALUE</constant> is generated if
 186             <inlineequation><mml:math>
 187                 <!-- eqn: xoffset  <   -b:-->
 188                 <mml:mrow>
 189                     <mml:mi mathvariant="italic">xoffset</mml:mi>
 190                     <mml:mo>&lt;</mml:mo>
 191                     <mml:mrow>
 192                         <mml:mo>-</mml:mo>
 193                         <mml:mi mathvariant="italic">b</mml:mi>
 194                     </mml:mrow>
 195                 </mml:mrow>
 196             </mml:math></inlineequation>,
 197             or
 198             <inlineequation><mml:math>
 199                 <!-- eqn: (xoffset + width)  >  (w-b):-->
 200                 <mml:mrow>
 201                     <mml:mfenced open="(" close=")">
 202                         <mml:mrow>
 203                             <mml:mi mathvariant="italic">xoffset</mml:mi>
 204                             <mml:mo>+</mml:mo>
 205                             <mml:mi mathvariant="italic">width</mml:mi>
 206                         </mml:mrow>
 207                     </mml:mfenced>
 208                     <mml:mo>&gt;</mml:mo>
 209                     <mml:mfenced open="(" close=")">
 210                         <mml:mrow>
 211                             <mml:mi mathvariant="italic">w</mml:mi>
 212                             <mml:mo>-</mml:mo>
 213                             <mml:mi mathvariant="italic">b</mml:mi>
 214                         </mml:mrow>
 215                     </mml:mfenced>
 216                 </mml:mrow>
 217             </mml:math></inlineequation>,
 218             where
 219             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 220             is the <constant>GL_TEXTURE_WIDTH</constant> and
 221             <inlineequation><mml:math><mml:mi mathvariant="italic">b</mml:mi></mml:math></inlineequation>
 222             is the <constant>GL_TEXTURE_BORDER</constant>
 223             of the texture image being modified.
 224             Note that
 225             <inlineequation><mml:math><mml:mi mathvariant="italic">w</mml:mi></mml:math></inlineequation>
 226             includes twice the border width.
 227         </para>
 228         <para>
 229         </para>
 230     </refsect1>
 231     <refsect1 id="associatedgets"><title>Associated Gets</title>
 232         <para>
 233             <citerefentry><refentrytitle>glGetTexImage</refentrytitle></citerefentry>
 234         </para>
 235         <para>
 236             <citerefentry><refentrytitle>glIsEnabled</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_1D</constant>
 237         </para>
 238     </refsect1>
 239     <refsect1 id="seealso"><title>See Also</title>
 240         <para>
 241             <citerefentry><refentrytitle>glCopyPixels</refentrytitle></citerefentry>,
 242             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 243             <citerefentry><refentrytitle>glCopyTexImage2D</refentrytitle></citerefentry>,
 244             <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
 245             <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
 246             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 247             <citerefentry><refentrytitle>glPixelTransfer</refentrytitle></citerefentry>,
 248             <citerefentry><refentrytitle>glReadBuffer</refentrytitle></citerefentry>,
 249             <citerefentry><refentrytitle>glTexEnv</refentrytitle></citerefentry>,
 250             <citerefentry><refentrytitle>glTexGen</refentrytitle></citerefentry>,
 251             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 252             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 253             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 254             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>,
 255             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 256             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 257             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>
 258         </para>
 259     </refsect1>
 260     <refsect1 id="Copyright"><title>Copyright</title>
 261         <para>
 262             Copyright <trademark class="copyright"></trademark> 1991-2006
 263             Silicon Graphics, Inc. This document is licensed under the SGI
 264             Free Software B License. For details, see
 265             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 266         </para>
 267     </refsect1>
 268 </refentry>