upstream-man-pages/man4/glGetTexImage.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="glGetTexImage">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glGetTexImage</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glGetTexImage</refname>
  17         <refpurpose>return a texture image</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glGetTexImage</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLint <parameter>level</parameter></paramdef>
  25                 <paramdef>GLenum <parameter>format</parameter></paramdef>
  26                 <paramdef>GLenum <parameter>type</parameter></paramdef>
  27                 <paramdef>GLvoid * <parameter>img</parameter></paramdef>
  28             </funcprototype>
  29         </funcsynopsis>
  30     </refsynopsisdiv>
  31     <!-- eqn: ignoring delim $$ -->
  32     <refsect1 id="parameters"><title>Parameters</title>
  33         <variablelist>
  34         <varlistentry>
  35             <term><parameter>target</parameter></term>
  36             <listitem>
  37                 <para>
  38                     Specifies which texture is to be obtained.
  39                     <constant>GL_TEXTURE_1D</constant>,
  40                     <constant>GL_TEXTURE_2D</constant>,
  41                     <constant>GL_TEXTURE_3D</constant>,
  42                     <constant>GL_TEXTURE_1D_ARRAY</constant>,
  43                     <constant>GL_TEXTURE_2D_ARRAY</constant>,
  44                     <constant>GL_TEXTURE_RECTANGLE</constant>,
  45                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_X</constant>,
  46                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_X</constant>,
  47                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Y</constant>,
  48                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Y</constant>,
  49                     <constant>GL_TEXTURE_CUBE_MAP_POSITIVE_Z</constant>, and
  50                     <constant>GL_TEXTURE_CUBE_MAP_NEGATIVE_Z</constant>
  51                     are accepted.
  52                 </para>
  53             </listitem>
  54         </varlistentry>
  55         <varlistentry>
  56             <term><parameter>level</parameter></term>
  57             <listitem>
  58                 <para>
  59                     Specifies the level-of-detail number of the desired image.
  60                     Level 0 is the base image level.
  61                     Level
  62                     <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>
  63                     is the
  64                     <inlineequation><mml:math><mml:mi mathvariant="italic">n</mml:mi></mml:math></inlineequation>th
  65                     mipmap reduction image.
  66                 </para>
  67             </listitem>
  68         </varlistentry>
  69         <varlistentry>
  70             <term><parameter>format</parameter></term>
  71             <listitem>
  72                 <para>
  73                     Specifies a pixel format for the returned data.
  74                     The supported formats are
  75                     <constant>GL_STENCIL_INDEX</constant>,
  76                     <constant>GL_DEPTH_COMPONENT</constant>,
  77                     <constant>GL_DEPTH_STENCIL</constant>,
  78                     <constant>GL_RED</constant>,
  79                     <constant>GL_GREEN</constant>,
  80                     <constant>GL_BLUE</constant>,
  81                     <constant>GL_RG</constant>,
  82                     <constant>GL_RGB</constant>,
  83                     <constant>GL_RGBA</constant>,
  84                     <constant>GL_BGR</constant>,
  85                     <constant>GL_BGRA</constant>,
  86                     <constant>GL_RED_INTEGER</constant>,
  87                     <constant>GL_GREEN_INTEGER</constant>,
  88                     <constant>GL_BLUE_INTEGER</constant>,
  89                     <constant>GL_RG_INTEGER</constant>,
  90                     <constant>GL_RGB_INTEGER</constant>,
  91                     <constant>GL_RGBA_INTEGER</constant>,
  92                     <constant>GL_BGR_INTEGER</constant>,
  93                     <constant>GL_BGRA_INTEGER</constant>.
  94                 </para>
  95             </listitem>
  96         </varlistentry>
  97         <varlistentry>
  98             <term><parameter>type</parameter></term>
  99             <listitem>
 100                 <para>
 101                     Specifies a pixel type for the returned data.
 102                     The supported types are
 103                     <constant>GL_UNSIGNED_BYTE</constant>,
 104                     <constant>GL_BYTE</constant>,
 105                     <constant>GL_UNSIGNED_SHORT</constant>,
 106                     <constant>GL_SHORT</constant>,
 107                     <constant>GL_UNSIGNED_INT</constant>,
 108                     <constant>GL_INT</constant>,
 109                     <constant>GL_HALF_FLOAT</constant>,
 110                     <constant>GL_FLOAT</constant>,
 111                     <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 112                     <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 113                     <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
 114                     <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>,
 115                     <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 116                     <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 117                     <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 118                     <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 119                     <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 120                     <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 121                     <constant>GL_UNSIGNED_INT_10_10_10_2</constant>,
 122                     <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>,
 123                     <constant>GL_UNSIGNED_INT_24_8</constant>,
 124                     <constant>GL_UNSIGNED_INT_10F_11F_11F_REV</constant>,
 125                     <constant>GL_UNSIGNED_INT_5_9_9_9_REV</constant>, and
 126                     <constant>GL_FLOAT_32_UNSIGNED_INT_24_8_REV</constant>.
 127                 </para>
 128             </listitem>
 129         </varlistentry>
 130         <varlistentry>
 131             <term><parameter>img</parameter></term>
 132             <listitem>
 133                 <para>
 134                     Returns the texture image.
 135                     Should be a pointer to an array of the type specified by <parameter>type</parameter>.
 136                 </para>
 137             </listitem>
 138         </varlistentry>
 139         </variablelist>
 140     </refsect1>
 141     <refsect1 id="description"><title>Description</title>
 142         <para>
 143             <function>glGetTexImage</function> returns a texture image into <parameter>img</parameter>.
 144             <parameter>target</parameter> specifies whether the desired texture image is one specified by
 145             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry> (<constant>GL_TEXTURE_1D</constant>),
 146             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> (<constant>GL_TEXTURE_1D_ARRAY</constant>, <constant>GL_TEXTURE_RECTANGLE</constant>,
 147             <constant>GL_TEXTURE_2D</constant> or any of
 148             <constant>GL_TEXTURE_CUBE_MAP_*</constant>),
 149             or
 150             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry> (<constant>GL_TEXTURE_2D_ARRAY</constant>,
 151             <constant>GL_TEXTURE_3D</constant>).
 152             <parameter>level</parameter> specifies the level-of-detail number of the desired image.
 153             <parameter>format</parameter> and <parameter>type</parameter> specify the format and type of the desired image array.
 154             See the reference page for <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>
 155             for a description of the acceptable values for the <parameter>format</parameter> and <parameter>type</parameter>
 156             parameters, respectively.
 157         </para>
 158         <para>
 159             If a non-zero named buffer object is bound to the <constant>GL_PIXEL_PACK_BUFFER</constant> target
 160             (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
 161             requested, <parameter>img</parameter> is treated as a byte offset into the buffer object's data store.
 162         </para>
 163         <para>
 164             To understand the operation of <function>glGetTexImage</function>, consider the selected internal
 165             four-component texture image to be an RGBA color buffer the size of the image.
 166             The semantics of <function>glGetTexImage</function> are then identical to those of <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
 167             with the exception that no pixel transfer operations are performed,
 168             when called with the same <parameter>format</parameter> and <parameter>type</parameter>,
 169             with <emphasis>x</emphasis> and <emphasis>y</emphasis> set to 0,
 170             <emphasis>width</emphasis> set to the width of the texture image
 171             and <emphasis>height</emphasis> set to 1 for 1D images,
 172             or to the height of the texture image
 173             for 2D images.
 174         </para>
 175         <para>
 176             If the selected texture image does not contain four components,
 177             the following mappings are applied.
 178             Single-component textures are treated as RGBA buffers with red set
 179             to the single-component value,
 180             green set to 0, blue set to 0, and alpha set to 1.
 181             Two-component textures are treated as RGBA buffers with red set to
 182             the value of component zero,
 183             alpha set to the value of component one,
 184             and green and blue set to 0.
 185             Finally,
 186             three-component textures are treated as RGBA buffers with red set to
 187             component zero,
 188             green set to component one,
 189             blue set to component two,
 190             and alpha set to 1.
 191         </para>
 192         <para>
 193             To determine the required size of <parameter>img</parameter>,
 194             use <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> to determine the dimensions of the
 195             internal texture image,
 196             then scale the required number of pixels by the storage required for
 197             each pixel,
 198             based on <parameter>format</parameter> and <parameter>type</parameter>.
 199             Be sure to take the pixel storage parameters into account,
 200             especially <constant>GL_PACK_ALIGNMENT</constant>.
 201         </para>
 202     </refsect1>
 203     <refsect1 id="notes"><title>Notes</title>
 204         <para>
 205             If an error is generated,
 206             no change is made to the contents of <parameter>img</parameter>.
 207         </para>
 208         <para>
 209             <function>glGetTexImage</function> returns the texture image for the active texture unit.
 210         </para>
 211     </refsect1>
 212     <refsect1 id="errors"><title>Errors</title>
 213         <para>
 214             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter>, <parameter>format</parameter>, or <parameter>type</parameter> is not
 215             an accepted value.
 216         </para>
 217         <para>
 218             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is less than 0.
 219         </para>
 220         <para>
 221             <constant>GL_INVALID_VALUE</constant> may be generated if <parameter>level</parameter> is greater
 222             than
 223             <inlineequation><mml:math>
 224                 <!-- eqn: log sub 2 (max): -->
 225                 <mml:mrow>
 226                     <mml:msub><mml:mi mathvariant="italic">log</mml:mi>
 227                     <mml:mn>2</mml:mn>
 228                     </mml:msub>
 229                     <mml:mo>&af;</mml:mo>
 230                     <mml:mfenced open="(" close=")">
 231                         <mml:mi mathvariant="italic">max</mml:mi>
 232                     </mml:mfenced>
 233                 </mml:mrow>
 234             </mml:math></inlineequation>,
 235             where
 236             <inlineequation><mml:math><mml:mi mathvariant="italic">max</mml:mi></mml:math></inlineequation>
 237             is the returned value of <constant>GL_MAX_TEXTURE_SIZE</constant>.
 238         </para>
 239         <para>
 240             <constant>GL_INVALID_OPERATION</constant> is returned if <parameter>type</parameter> is one of
 241             <constant>GL_UNSIGNED_BYTE_3_3_2</constant>,
 242             <constant>GL_UNSIGNED_BYTE_2_3_3_REV</constant>,
 243             <constant>GL_UNSIGNED_SHORT_5_6_5</constant>,
 244             <constant>GL_UNSIGNED_SHORT_5_6_5_REV</constant>, or
 245             <constant>GL_UNSIGNED_INT_10F_11F_11F_REV</constant> and <parameter>format</parameter> is not <constant>GL_RGB</constant>.
 246         </para>
 247         <para>
 248             <constant>GL_INVALID_OPERATION</constant> is returned if <parameter>type</parameter> is one of
 249             <constant>GL_UNSIGNED_SHORT_4_4_4_4</constant>,
 250             <constant>GL_UNSIGNED_SHORT_4_4_4_4_REV</constant>,
 251             <constant>GL_UNSIGNED_SHORT_5_5_5_1</constant>,
 252             <constant>GL_UNSIGNED_SHORT_1_5_5_5_REV</constant>,
 253             <constant>GL_UNSIGNED_INT_8_8_8_8</constant>,
 254             <constant>GL_UNSIGNED_INT_8_8_8_8_REV</constant>,
 255             <constant>GL_UNSIGNED_INT_10_10_10_2</constant>,
 256             <constant>GL_UNSIGNED_INT_2_10_10_10_REV</constant>, or
 257             <constant>GL_UNSIGNED_INT_5_9_9_9_REV</constant> and <parameter>format</parameter> is neither <constant>GL_RGBA</constant>
 258             or <constant>GL_BGRA</constant>.
 259         </para>
 260         <para>
 261             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 262             <constant>GL_PIXEL_PACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
 263         </para>
 264         <para>
 265             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 266             <constant>GL_PIXEL_PACK_BUFFER</constant> target and the data would be packed to the buffer
 267             object such that the memory writes required would exceed the data store size.
 268         </para>
 269         <para>
 270             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 271             <constant>GL_PIXEL_PACK_BUFFER</constant> target and <parameter>img</parameter> is not evenly divisible
 272             into the number of bytes needed to store in memory a datum indicated by <parameter>type</parameter>.
 273         </para>
 274     </refsect1>
 275     <refsect1 id="associatedgets"><title>Associated Gets</title>
 276         <para>
 277             <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_WIDTH</constant>
 278         </para>
 279         <para>
 280             <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_HEIGHT</constant>
 281         </para>
 282         <para>
 283             <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>
 284         </para>
 285         <para>
 286             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with arguments <constant>GL_PACK_ALIGNMENT</constant> and others
 287         </para>
 288         <para>
 289             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_PACK_BUFFER_BINDING</constant>
 290         </para>
 291     </refsect1>
 292     <refsect1 id="seealso"><title>See Also</title>
 293         <para>
 294             <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
 295             <citerefentry><refentrytitle>glReadPixels</refentrytitle></citerefentry>,
 296             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 297             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 298             <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>,
 299             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 300             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 301             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
 302             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
 303         </para>
 304     </refsect1>
 305     <refsect1 id="Copyright"><title>Copyright</title>
 306         <para>
 307             Copyright <trademark class="copyright"></trademark> 1991-2006
 308             Silicon Graphics, Inc. Copyright <trademark class="copyright"></trademark> 2010
 309             Khronos Group. This document is licensed under the SGI
 310             Free Software B License. For details, see
 311             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 312         </para>
 313     </refsect1>
 314 </refentry>