upstream-man-pages/man3/glCompressedTexImage3D.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="glCompressedTexImage3D">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glCompressedTexImage3D</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glCompressedTexImage3D</refname>
  17         <refpurpose>specify a three-dimensional texture image in a compressed format</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glCompressedTexImage3D</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLint <parameter>level</parameter></paramdef>
  25                 <paramdef>GLenum <parameter>internalformat</parameter></paramdef>
  26                 <paramdef>GLsizei <parameter>width</parameter></paramdef>
  27                 <paramdef>GLsizei <parameter>height</parameter></paramdef>
  28                 <paramdef>GLsizei <parameter>depth</parameter></paramdef>
  29                 <paramdef>GLint <parameter>border</parameter></paramdef>
  30                 <paramdef>GLsizei <parameter>imageSize</parameter></paramdef>
  31                 <paramdef>const GLvoid * <parameter>data</parameter></paramdef>
  32             </funcprototype>
  33         </funcsynopsis>
  34     </refsynopsisdiv>
  35     <!-- eqn: ignoring delim $$ -->
  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_3D</constant>, <constant>GL_PROXY_TEXTURE_3D</constant>,
  44                     <constant>GL_TEXTURE_2D_ARRAY</constant> or <constant>GL_PROXY_TEXTURE_2D_ARRAY</constant>.
  45                 </para>
  46             </listitem>
  47         </varlistentry>
  48         <varlistentry>
  49             <term><parameter>level</parameter></term>
  50             <listitem>
  51                 <para>
  52                     Specifies the level-of-detail number.
  53                     Level 0 is the base image level.
  54                     Level <emphasis>n</emphasis> is the <emphasis>n</emphasis>th mipmap reduction image.
  55                 </para>
  56             </listitem>
  57         </varlistentry>
  58         <varlistentry>
  59             <term><parameter>internalformat</parameter></term>
  60             <listitem>
  61                 <para>
  62                     Specifies the format of the compressed image data stored at address <parameter>data</parameter>.
  63                 </para>
  64             </listitem>
  65         </varlistentry>
  66         <varlistentry>
  67             <term><parameter>width</parameter></term>
  68             <listitem>
  69                 <para>
  70                     Specifies the width of the texture image.
  71                     All implementations support 3D texture images that are at least 16 texels wide.
  72                 </para>
  73             </listitem>
  74         </varlistentry>
  75         <varlistentry>
  76             <term><parameter>height</parameter></term>
  77             <listitem>
  78                 <para>
  79                     Specifies the height of the texture image.
  80                     All implementations support 3D texture images that are at least 16 texels
  81                     high.
  82                 </para>
  83             </listitem>
  84         </varlistentry>
  85         <varlistentry>
  86             <term><parameter>depth</parameter></term>
  87             <listitem>
  88                 <para>
  89                     Specifies the depth of the texture image.
  90                     All implementations support 3D texture images that are at least 16 texels
  91                     deep.
  92                 </para>
  93             </listitem>
  94         </varlistentry>
  95         <varlistentry>
  96             <term><parameter>border</parameter></term>
  97             <listitem>
  98                 <para>
  99                     This value must be 0.
 100                 </para>
 101             </listitem>
 102         </varlistentry>
 103         <varlistentry>
 104             <term><parameter>imageSize</parameter></term>
 105             <listitem>
 106                 <para>
 107                     Specifies the number of unsigned bytes of image data starting at the
 108                     address specified by <parameter>data</parameter>.
 109                 </para>
 110             </listitem>
 111         </varlistentry>
 112         <varlistentry>
 113             <term><parameter>data</parameter></term>
 114             <listitem>
 115                 <para>
 116                     Specifies a pointer to the compressed image data in memory.
 117                 </para>
 118             </listitem>
 119         </varlistentry>
 120         </variablelist>
 121     </refsect1>
 122     <refsect1 id="description"><title>Description</title>
 123         <para>
 124             Texturing allows elements of an image array to be read by shaders.
 125         </para>
 126         <para>
 127             <function>glCompressedTexImage3D</function> loads a previously defined, and retrieved, compressed three-dimensional
 128             texture image if <parameter>target</parameter> is <constant>GL_TEXTURE_3D</constant> (see <citerefentry><refentrytitle>glTexImage3D</refentrytitle></citerefentry>).
 129         </para>
 130         <para>
 131             If <parameter>target</parameter> is <constant>GL_TEXTURE_2D_ARRAY</constant>, <parameter>data</parameter> is
 132             treated as an array of compressed 2D textures.
 133         </para>
 134         <para>
 135             If <parameter>target</parameter> is <constant>GL_PROXY_TEXTURE_3D</constant> or <constant>GL_PROXY_TEXTURE_2D_ARRAY</constant>,
 136             no data is read from <parameter>data</parameter>, but
 137             all of the texture image state is recalculated, checked for consistency,
 138             and checked against the implementation's capabilities.  If the
 139             implementation cannot handle a texture of the requested texture size, it
 140             sets all of the image state to 0, but does not generate an error (see
 141             <citerefentry><refentrytitle>glGetError</refentrytitle></citerefentry>). To query for an entire mipmap array, use an image array level
 142             greater than or equal to 1.
 143         </para>
 144         <para>
 145             <parameter>internalformat</parameter> must be a known compressed image format (such as <constant>GL_RGTC</constant>)
 146             or an extension-specified compressed-texture format.
 147             When a texture is loaded with <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry> using a generic compressed
 148             texture format (e.g., <constant>GL_COMPRESSED_RGB</constant>), the GL selects from one of
 149             its extensions supporting compressed textures.  In order to load the
 150             compressed texture image using <function>glCompressedTexImage3D</function>, query the compressed texture image's
 151             size and format using <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry>.
 152         </para>
 153         <para>
 154             If a non-zero named buffer object is bound to the <constant>GL_PIXEL_UNPACK_BUFFER</constant> target
 155             (see <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>) while a texture image is
 156             specified, <parameter>data</parameter> is treated as a byte offset into the buffer object's data store.
 157         </para>
 158     </refsect1>
 159     <refsect1 id="errors"><title>Errors</title>
 160         <para>
 161           <constant>GL_INVALID_ENUM</constant> is generated if <parameter>internalformat</parameter> is not one of the generic
 162           compressed internal formats:
 163           <constant>GL_COMPRESSED_RED</constant>,
 164           <constant>GL_COMPRESSED_RG</constant>,
 165           <constant>GL_COMPRESSED_RGB</constant>,
 166           <constant>GL_COMPRESSED_RGBA</constant>.
 167           <constant>GL_COMPRESSED_SRGB</constant>, or
 168           <constant>GL_COMPRESSED_SRGB_ALPHA</constant>.
 169         </para>
 170         <para>
 171             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>imageSize</parameter> is not consistent with
 172             the format, dimensions, and contents of the specified compressed image data.
 173         </para>
 174         <para>
 175             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>border</parameter> is not 0.
 176         </para>
 177         <para>
 178             <constant>GL_INVALID_OPERATION</constant> is generated if parameter combinations are not
 179             supported by the specific compressed internal format as specified in the
 180             specific texture compression extension.
 181         </para>
 182         <para>
 183             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 184             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the buffer object's data store is currently mapped.
 185         </para>
 186         <para>
 187             <constant>GL_INVALID_OPERATION</constant> is generated if a non-zero buffer object name is bound to the
 188             <constant>GL_PIXEL_UNPACK_BUFFER</constant> target and the data would be unpacked from the buffer
 189             object such that the memory reads required would exceed the data store size.
 190         </para>
 191         <para>
 192             Undefined results, including abnormal program termination, are generated if <parameter>data</parameter> is not encoded in a manner consistent with the extension specification defining the internal compression format.
 193         </para>
 194     </refsect1>
 195     <refsect1 id="associatedgets"><title>Associated Gets</title>
 196         <para>
 197             <citerefentry><refentrytitle>glGetCompressedTexImage</refentrytitle></citerefentry>
 198         </para>
 199         <para>
 200             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_TEXTURE_COMPRESSED</constant>
 201         </para>
 202         <para>
 203             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_PIXEL_UNPACK_BUFFER_BINDING</constant>
 204         </para>
 205         <para>
 206             <citerefentry><refentrytitle>glGetTexLevelParameter</refentrytitle></citerefentry> with arguments <constant>GL_TEXTURE_INTERNAL_FORMAT</constant>
 207             and <constant>GL_TEXTURE_COMPRESSED_IMAGE_SIZE</constant>
 208         </para>
 209     </refsect1>
 210     <refsect1 id="seealso"><title>See Also</title>
 211         <para>
 212             <citerefentry><refentrytitle>glActiveTexture</refentrytitle></citerefentry>,
 213             <citerefentry><refentrytitle>glCompressedTexImage1D</refentrytitle></citerefentry>,
 214             <citerefentry><refentrytitle>glCompressedTexImage2D</refentrytitle></citerefentry>,
 215             <citerefentry><refentrytitle>glCompressedTexSubImage1D</refentrytitle></citerefentry>,
 216             <citerefentry><refentrytitle>glCompressedTexSubImage2D</refentrytitle></citerefentry>,
 217             <citerefentry><refentrytitle>glCompressedTexSubImage3D</refentrytitle></citerefentry>,
 218             <citerefentry><refentrytitle>glCopyTexImage1D</refentrytitle></citerefentry>,
 219             <citerefentry><refentrytitle>glCopyTexSubImage1D</refentrytitle></citerefentry>,
 220             <citerefentry><refentrytitle>glCopyTexSubImage2D</refentrytitle></citerefentry>,
 221             <citerefentry><refentrytitle>glCopyTexSubImage3D</refentrytitle></citerefentry>,
 222             <citerefentry><refentrytitle>glPixelStore</refentrytitle></citerefentry>,
 223             <citerefentry><refentrytitle>glTexImage1D</refentrytitle></citerefentry>,
 224             <citerefentry><refentrytitle>glTexImage2D</refentrytitle></citerefentry>,
 225             <citerefentry><refentrytitle>glTexSubImage1D</refentrytitle></citerefentry>,
 226             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>,
 227             <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>,
 228             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry>
 229         </para>
 230     </refsect1>
 231     <refsect1 id="Copyright"><title>Copyright</title>
 232         <para>
 233             Copyright <trademark class="copyright"></trademark> 1991-2006
 234             Silicon Graphics, Inc. This document is licensed under the SGI
 235             Free Software B License. For details, see
 236             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 237         </para>
 238     </refsect1>
 239 </refentry>