upstream-doc/man4/glTextureView.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="glTextureView">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2012</year>
   9                 <holder>Khronos Group</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glTextureView</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glTextureView</refname>
  17         <refpurpose>initialize a texture as a data alias of another texture's data store</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glTextureView</function></funcdef>
  23                 <paramdef>GLuint <parameter>texture</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  25                 <paramdef>GLuint <parameter>origtexture</parameter></paramdef>
  26                 <paramdef>GLenum <parameter>internalformat</parameter></paramdef>
  27                 <paramdef>GLuint <parameter>minlevel</parameter></paramdef>
  28                 <paramdef>GLuint <parameter>numlevels</parameter></paramdef>
  29                 <paramdef>GLuint <parameter>minlayer</parameter></paramdef>
  30                 <paramdef>GLuint <parameter>numlayers</parameter></paramdef>
  31             </funcprototype>
  32         </funcsynopsis>
  33     </refsynopsisdiv>
  34     <refsect1 id="parameters"><title>Parameters</title>
  35         <variablelist>
  36         <varlistentry>
  37             <term><parameter>texture</parameter></term>
  38             <listitem>
  39                 <para>
  40                     Specifies the texture object to be initialized as a view.
  41                 </para>
  42             </listitem>
  43         </varlistentry>
  44         <varlistentry>
  45             <term><parameter>target</parameter></term>
  46             <listitem>
  47                 <para>
  48                     Specifies the target to be used for the newly initialized texture.
  49                 </para>
  50             </listitem>
  51         </varlistentry>
  52         <varlistentry>
  53             <term><parameter>origtexture</parameter></term>
  54             <listitem>
  55                 <para>
  56                     Specifies the name of a texture object of which to make a view.
  57                 </para>
  58             </listitem>
  59         </varlistentry>
  60         <varlistentry>
  61             <term><parameter>internalFormat</parameter></term>
  62             <listitem>
  63                 <para>
  64                     Specifies the internal format for the newly created view.
  65                 </para>
  66             </listitem>
  67         </varlistentry>
  68         <varlistentry>
  69             <term><parameter>minlevel</parameter></term>
  70             <listitem>
  71                 <para>
  72                     Specifies lowest level of detail of the view.
  73                 </para>
  74             </listitem>
  75         </varlistentry>
  76         <varlistentry>
  77             <term><parameter>numlevels</parameter></term>
  78             <listitem>
  79                 <para>
  80                     Specifies the number of levels of detail to include in the view.
  81                 </para>
  82             </listitem>
  83         </varlistentry>
  84         <varlistentry>
  85             <term><parameter>minlayer</parameter></term>
  86             <listitem>
  87                 <para>
  88                     Specifies the index of the first layer to include in the view.
  89                 </para>
  90             </listitem>
  91         </varlistentry>
  92         <varlistentry>
  93             <term><parameter>numlayers</parameter></term>
  94             <listitem>
  95                 <para>
  96                     Specifies the number of layers to include in the view.
  97                 </para>
  98             </listitem>
  99         </varlistentry>
 100         </variablelist>
 101     </refsect1>
 102     <refsect1 id="description"><title>Description</title>
 103         <para>
 104             <function>glTextureView</function> initializes a texture object as an
 105             alias, or view of another texture object, sharing some or all of the
 106             parent texture's data store with the initialized texture. <parameter>texture</parameter>
 107             specifies a name previously reserved by a successful call to <citerefentry><refentrytitle>glGenTextures</refentrytitle></citerefentry>
 108             but that has not yet been bound or given a target. <parameter>target</parameter>
 109             specifies the target for the newly initialized texture and must be compatible
 110             with the target of the parent texture, given in <parameter>origtexture</parameter>
 111             as specified in the following table:
 112         </para>
 113         <informaltable frame="topbot">
 114             <tgroup cols="2" align="left">
 115                 <colspec colnum="1" colname="col1" colwidth="1*"/>
 116                 <colspec colnum="2" colname="col2" colwidth="2*"/>
 117                 <thead>
 118                     <row>
 119                         <entry rowsep="1" align="center">Original Target</entry>
 120                         <entry rowsep="1" align="center">Compatible New Targets</entry>
 121                     </row>
 122                 </thead>
 123                 <tbody>
 124                     <row>
 125                         <entry align="left"><constant>GL_TEXTURE_1D</constant></entry>
 126                         <entry align="left"><constant>GL_TEXTURE_1D</constant>, <constant>GL_TEXTURE_1D_ARRAY</constant></entry>
 127                     </row>
 128                     <row>
 129                         <entry align="left"><constant>GL_TEXTURE_2D</constant></entry>
 130                         <entry align="left"><constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_2D_ARRAY</constant></entry>
 131                     </row>
 132                     <row>
 133                         <entry align="left"><constant>GL_TEXTURE_3D</constant></entry>
 134                         <entry align="left"><constant>GL_TEXTURE_3D</constant></entry>
 135                     </row>
 136                     <row>
 137                         <entry align="left"><constant>GL_TEXTURE_CUBE_MAP</constant></entry>
 138                         <entry align="left"><constant>GL_TEXTURE_CUBE_MAP</constant>, <constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_2D_ARRAY</constant>, <constant>GL_TEXTUER_CUBE_MAP_ARRAY</constant></entry>
 139                     </row>
 140                     <row>
 141                         <entry align="left"><constant>GL_TEXTURE_RECTANGLE</constant></entry>
 142                         <entry align="left"><constant>GL_TEXTURE_RECTANGLE</constant></entry>
 143                     </row>
 144                     <row>
 145                         <entry align="left"><constant>GL_TEXTURE_BUFFER</constant></entry>
 146                         <entry align="left"><emphasis>none</emphasis></entry>
 147                     </row>
 148                     <row>
 149                         <entry align="left"><constant>GL_TEXTURE_1D_ARRAY</constant></entry>
 150                         <entry align="left"><constant>GL_TEXTURE_1D</constant>, <constant>GL_TEXTURE_1D_ARRAY</constant></entry>
 151                     </row>
 152                     <row>
 153                         <entry align="left"><constant>GL_TEXTURE_2D_ARRAY</constant></entry>
 154                         <entry align="left"><constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_2D_ARRAY</constant></entry>
 155                     </row>
 156                     <row>
 157                         <entry align="left"><constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant></entry>
 158                         <entry align="left"><constant>GL_TEXTURE_CUBE_MAP</constant>, <constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_2D_ARRAY</constant>, <constant>GL_TEXTUER_CUBE_MAP_ARRAY</constant></entry>
 159                     </row>
 160                     <row>
 161                         <entry align="left"><constant>GL_TEXTURE_2D_MULTISAMPLE</constant></entry>
 162                         <entry align="left"><constant>GL_TEXTURE_2D_MULTISAMPLE</constant>, <constant>GL_TEXTURE_MULTISAMPLE_ARRAY</constant></entry>
 163                     </row>
 164                     <row>
 165                         <entry align="left"><constant>GL_TEXTURE_2D_MULTISAMPLE_ARRAY</constant></entry>
 166                         <entry align="left"><constant>GL_TEXTURE_2D_MULTISAMPLE</constant>, <constant>GL_TEXTURE_MULTISAMPLE_ARRAY</constant></entry>
 167                     </row>
 168                 </tbody>
 169             </tgroup>
 170         </informaltable>
 171         <para>
 172             The value of <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant> for <parameter>origtexture</parameter>
 173             must be <constant>GL_TRUE</constant>.
 174             After initialization, <parameter>texture</parameter> inherits the data store of
 175             the parent texture, <parameter>origtexture</parameter> and is usable as a normal
 176             texture object with target <parameter>target</parameter>. Data in the shared store
 177             is reinterpreted with the new internal format specified by <parameter>internalformat</parameter>.
 178             <parameter>internalformat</parameter> must be compatible with the internal format
 179             of the parent texture as specified in the following table:
 180         </para>
 181         <informaltable frame="topbot">
 182             <tgroup cols="2" align="left">
 183                 <colspec colnum="1" colname="col1" colwidth="1*"/>
 184                 <colspec colnum="2" colname="col2" colwidth="2*"/>
 185                 <thead>
 186                     <row>
 187                         <entry align="center">Class</entry>
 188                         <entry align="center">Internal Formats</entry>
 189                     </row>
 190                 </thead>
 191                 <tbody>
 192                     <row>
 193                         <entry align="left">128-bit</entry>
 194                         <entry align="left"><constant>GL_RGBA32F</constant>, <constant>GL_RGBA32UI</constant>, <constant>GL_RGBA32I</constant></entry>
 195                     </row>
 196                     <row>
 197                         <entry align="left">96-bit</entry>
 198                         <entry align="left"><constant>GL_RGB32F</constant>, <constant>GL_RGB32UI</constant>, <constant>GL_RGB32I</constant></entry>
 199                     </row>
 200                     <row>
 201                         <entry align="left">64-bit</entry>
 202                         <entry align="left"><constant>GL_RGBA16F</constant>, <constant>GL_RG32F</constant>, <constant>GL_RGBA16UI</constant>,
 203                         <constant>GL_RG32UI</constant>, <constant>GL_RGBA16I</constant>, <constant>GL_RG32I</constant>, <constant>GL_RGBA16</constant>, <constant>GL_RGBA16_SNORM</constant></entry>
 204                     </row>
 205                     <row>
 206                         <entry align="left">48-bit</entry>
 207                         <entry align="left"><constant>GL_RGB16</constant>, <constant>GL_RGB16_SNORM</constant>, <constant>GL_RGB16F</constant>, <constant>GL_RGB16UI</constant>, <constant>GL_RGB16I</constant></entry>
 208                     </row>
 209                     <row>
 210                         <entry align="left">32-bit</entry>
 211                         <entry align="left"><constant>GL_RG16F</constant>, <constant>GL_R11F_G11F_B10F</constant>, <constant>GL_R32F</constant>, <constant>GL_RGB10_A2UI</constant>,
 212                                             <constant>GL_RGBA8UI</constant>, <constant>GL_RG16UI</constant>, <constant>GL_R32UI</constant>, <constant>GL_RGBA8I</constant>,
 213                                             <constant>GL_RG16I</constant>, <constant>GL_R32I</constant>, <constant>GL_RGB10_A2</constant>, <constant>GL_RGBA8</constant>,
 214                                             <constant>GL_RG16</constant>, <constant>GL_RGBA8_SNORM</constant>, <constant>GL_RG16_SNORM</constant>, <constant>GL_SRGB8_ALPHA8</constant>,
 215                                             <constant>GL_RGB9_E5</constant></entry>
 216                     </row>
 217                     <row>
 218                         <entry align="left">24-bit</entry>
 219                         <entry align="left"><constant>GL_RGB8</constant>, <constant>GL_RGB8_SNORM</constant>, <constant>GL_SRGB8</constant>,
 220                                             <constant>GL_RGB8UI</constant>, <constant>GL_RGB8I</constant></entry>
 221                     </row>
 222                     <row>
 223                         <entry align="left">16-bit</entry>
 224                         <entry align="left"><constant>GL_R16F</constant>, <constant>GL_RG8UI</constant>, <constant>GL_R16UI</constant>, <constant>GL_RG8I</constant>,
 225                                             <constant>GL_R16I</constant>, <constant>GL_RG8</constant>, <constant>GL_R16</constant>, <constant>GL_RG8_SNORM</constant>, <constant>GL_R16_SNORM</constant></entry>
 226                     </row>
 227                     <row>
 228                         <entry align="left">8-bit</entry>
 229                         <entry align="left"><constant>GL_R8UI</constant>, <constant>GL_R8I</constant>, <constant>GL_R8</constant>, <constant>GL_R8_SNORM</constant></entry>
 230                     </row>
 231                     <row>
 232                         <entry align="left"><constant>GL_RGTC1_RED</constant></entry>
 233                         <entry align="left"><constant>GL_COMPRESSED_RED_RGTC1</constant>, <constant>GL_COMPRESSED_SIGNED_RED_RGTC1</constant></entry>
 234                     </row>
 235                     <row>
 236                         <entry align="left"><constant>GL_RGTC2_RG</constant></entry>
 237                         <entry align="left"><constant>GL_COMPRESSED_RG_RGTC2</constant>, <constant>GL_COMPRESSED_SIGNED_RG_RGTC2</constant></entry>
 238                     </row>
 239                     <row>
 240                         <entry align="left"><constant>GL_BPTC_UNORM</constant></entry>
 241                         <entry align="left"><constant>GL_COMPRESSED_RGBA_BPTC_UNORM</constant>, <constant>GL_COMPRESSED_SRGB_ALPHA_BPTC_UNORM</constant></entry>
 242                     </row>
 243                     <row>
 244                         <entry align="left"><constant>GL_BPTC_FLOAT</constant></entry>
 245                         <entry align="left"><constant>GL_COMPRESSED_RGB_BPTC_SIGNED_FLOAT</constant>, <constant>GL_COMPRESSED_RGB_BPTC_UNSIGNED_FLOAT</constant></entry>
 246                     </row>
 247                 </tbody>
 248             </tgroup>
 249         </informaltable>
 250         <para>
 251             If the original texture is an array or has multiple mipmap levels,
 252             the parameters <parameter>minlayer</parameter>, <parameter>numlayers</parameter>, <parameter>minlevel</parameter>, and <parameter>numlevels</parameter>
 253             control which of those slices and levels are considered part of the texture.
 254             The <parameter>minlevel</parameter> and <parameter>minlayer</parameter> parameters are relative to the view of the
 255             original texture. If <parameter>numlayers</parameter> or <parameter>numlevels</parameter> extend beyond the original
 256             texture, they are clamped to the max extent of the original texture.
 257         </para>
 258         <para>
 259             If the new texture's target is <constant>GL_TEXTURE_CUBE_MAP</constant>, the clamped <parameter>numlayers</parameter>
 260             must be equal to 6. If the new texture's target is <constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant>,
 261             then <parameter>numlayers</parameter> counts layer-faces rather than layers, and the clamped
 262             <parameter>numlayers</parameter> must be a multiple of 6. If the new texture's target is <constant>GL_TEXTURE_CUBE_MAP</constant> or
 263             <constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant>, the width and height of the original texture's
 264             levels must be equal.
 265         </para>
 266         <para>
 267             When the original texture's target is <constant>GL_TEXTURE_CUBE_MAP</constant>, the layer
 268             parameters are interpreted in the same order as if it were a
 269             <constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant> with 6 layer-faces.
 270         </para>
 271         <para>
 272             If <parameter>target</parameter> is <constant>GL_TEXTURE_1D</constant>, <constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_3D</constant>, <constant>GL_TEXTURE_RECTANGLE</constant>, or
 273             <constant>GL_TEXTURE_2D_MULTISAMPLE</constant>, <parameter>numlayers</parameter> must equal 1.
 274         </para>
 275         <para>
 276             The dimensions of the original texture must be less than or equal to the maximum
 277             supported dimensions of the new target. For example, if the original texture has a <constant>GL_TEXTURE_2D_ARRAY</constant>
 278             target and its width is greater than <constant>GL_MAX_CUBE_MAP_TEXTURE_SIZE</constant>, an error
 279             will be generated if <function>glTextureView</function> is called to create a <constant>GL_TEXTURE_CUBE_MAP</constant>
 280             view.
 281         </para>
 282         <para>
 283             Texture commands that take a <parameter>level</parameter> or <parameter>layer</parameter> parameter, such as
 284             <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>, interpret that parameter to be relative to the view of the
 285             texture. i.e. the mipmap level of the data store that would be updated via
 286             <citerefentry><refentrytitle>TexSubImage2D</refentrytitle></citerefentry> would be the sum of <parameter>level</parameter> and the value of
 287             <constant>GL_TEXTURE_VIEW_MIN_LEVEL</constant>.
 288         </para>
 289     </refsect1>
 290     <refsect1 id="errors"><title>Errors</title>
 291         <para>
 292             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>minlayer</parameter> or <parameter>minlevel</parameter>
 293             are larger than the greatest layer or level of <parameter>origtexture</parameter>.
 294         </para>
 295         <para>
 296             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>target</parameter> is not compatible
 297             with the target of <parameter>origtexture</parameter>.
 298         </para>
 299         <para>
 300             <constant>GL_INVALID_OPERATION</constant> is generated if the dimensions of <parameter>origtexture</parameter>
 301             are greater than the maximum supported dimensions for <parameter>target</parameter>.
 302         </para>
 303         <para>
 304             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>internalformat</parameter> is not compatible
 305             with the internal format of <parameter>origtexture</parameter>.
 306         </para>
 307         <para>
 308             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>texture</parameter> has already been bound
 309             or otherwise given a target.
 310         </para>
 311         <para>
 312             <constant>GL_INVALID_OPERATION</constant> is generated if the value of <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant>
 313             for <parameter>origtexture</parameter> is not <constant>GL_TRUE</constant>.
 314         </para>
 315         <para>
 316             <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>origtexture</parameter> is not the name of an
 317             existing texture object.
 318         </para>
 319         <para>
 320             <constant>GL_INVALID_VALUE</constant> is generaged if <parameter>target</parameter> is <constant>GL_TEXTURE_CUBE_MAP</constant>
 321             and <parameter>numlayers</parameter> is not 6, or if <parameter>target</parameter> is <constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant>
 322             and <parameter>numlayers</parameter> is not an integer multiple of 6.
 323         </para>
 324         <para>
 325             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>target</parameter> is <constant>GL_TEXTURE_1D</constant>,
 326             <constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_3D</constant>, <constant>GL_TEXTURE_RECTANGLE</constant>, or
 327             <constant>GL_TEXTURE_2D_MULTISAMPLE</constant> and <parameter>numlayers</parameter> does not equal 1.
 328         </para>
 329         <para>
 330             <constant>GL_INVALID_VALUE</constant> is generated if <parameter>texture</parameter> zero or is not the name of a texture previously
 331             returned from a successful call to <citerefentry><refentrytitle>glGenTextures</refentrytitle></citerefentry>.
 332         </para>
 333     </refsect1>
 334     <refsect1 id="associatedgets"><title>Associated Gets</title>
 335         <para>
 336             <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry> with arguments <constant>GL_TEXTURE_VIEW_MIN_LEVEL</constant>,
 337             <constant>GL_TEXTURE_VIEW_NUM_LEVELS</constant>, <constant>GL_TEXTURE_VIEW_MIN_LAYER</constant>,
 338             <constant>GL_TEXTURE_VIEW_NUM_LAYERS</constant>, or <constant>GL_TEXTURE_IMMUTABLE_LEVELS</constant>.
 339         </para>
 340     </refsect1>
 341     <refsect1 id="seealso"><title>See Also</title>
 342         <para>
 343             <citerefentry><refentrytitle>glTexStorage1D</refentrytitle></citerefentry>,
 344             <citerefentry><refentrytitle>glTexStorage2D</refentrytitle></citerefentry>,
 345             <citerefentry><refentrytitle>glTexStorage3D</refentrytitle></citerefentry>,
 346             <citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry>.
 347         </para>
 348     </refsect1>
 349     <refsect1 id="Copyright"><title>Copyright</title>
 350         <para>
 351             Copyright <trademark class="copyright"></trademark> 2012 Khronos Group.
 352             This material may be distributed subject to the terms and conditions set forth in
 353             the Open Publication License, v 1.0, 8 June 1999.
 354             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 355         </para>
 356     </refsect1>
 357 </refentry>