<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
              "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glTextureView">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>2012</year>
                <holder>Khronos Group</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glTextureView</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glTextureView</refname>
        <refpurpose>initialize a texture as a data alias of another texture's data store</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glTextureView</function></funcdef>
                <paramdef>GLuint <parameter>texture</parameter></paramdef>
                <paramdef>GLenum <parameter>target</parameter></paramdef>
                <paramdef>GLuint <parameter>origtexture</parameter></paramdef>
                <paramdef>GLenum <parameter>internalformat</parameter></paramdef>
                <paramdef>GLuint <parameter>minlevel</parameter></paramdef>
                <paramdef>GLuint <parameter>numlevels</parameter></paramdef>
                <paramdef>GLuint <parameter>minlayer</parameter></paramdef>
                <paramdef>GLuint <parameter>numlayers</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>texture</parameter></term>
            <listitem>
                <para>
                    Specifies the texture object to be initialized as a view.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>target</parameter></term>
            <listitem>
                <para>
                    Specifies the target to be used for the newly initialized texture.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>origtexture</parameter></term>
            <listitem>
                <para>
                    Specifies the name of a texture object of which to make a view.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>internalFormat</parameter></term>
            <listitem>
                <para>
                    Specifies the internal format for the newly created view.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>minlevel</parameter></term>
            <listitem>
                <para>
                    Specifies lowest level of detail of the view.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>numlevels</parameter></term>
            <listitem>
                <para>
                    Specifies the number of levels of detail to include in the view.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>minlayer</parameter></term>
            <listitem>
                <para>
                    Specifies the index of the first layer to include in the view.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>numlayers</parameter></term>
            <listitem>
                <para>
                    Specifies the number of layers to include in the view.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glTextureView</function> initializes a texture object as an
            alias, or view of another texture object, sharing some or all of the
            parent texture's data store with the initialized texture. <parameter>texture</parameter>
            specifies a name previously reserved by a successful call to <citerefentry><refentrytitle>glGenTextures</refentrytitle></citerefentry>
            but that has not yet been bound or given a target. <parameter>target</parameter>
            specifies the target for the newly initialized texture and must be compatible
            with the target of the parent texture, given in <parameter>origtexture</parameter>
            as specified in the following table:
        </para>
        <informaltable frame="topbot">
            <tgroup cols="2" align="left">
                <colspec colnum="1" colname="col1" colwidth="1*"/>
                <colspec colnum="2" colname="col2" colwidth="2*"/>
                <thead>
                    <row>
                        <entry rowsep="1" align="center">Original Target</entry>
                        <entry rowsep="1" align="center">Compatible New Targets</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry align="left"><constant>GL_TEXTURE_1D</constant></entry>
                        <entry align="left"><constant>GL_TEXTURE_1D</constant>, <constant>GL_TEXTURE_1D_ARRAY</constant></entry>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_TEXTURE_2D</constant></entry>
                        <entry align="left"><constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_2D_ARRAY</constant></entry>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_TEXTURE_3D</constant></entry>
                        <entry align="left"><constant>GL_TEXTURE_3D</constant></entry>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_TEXTURE_CUBE_MAP</constant></entry>
                        <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>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_TEXTURE_RECTANGLE</constant></entry>
                        <entry align="left"><constant>GL_TEXTURE_RECTANGLE</constant></entry>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_TEXTURE_BUFFER</constant></entry>
                        <entry align="left"><emphasis>none</emphasis></entry>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_TEXTURE_1D_ARRAY</constant></entry>
                        <entry align="left"><constant>GL_TEXTURE_1D</constant>, <constant>GL_TEXTURE_1D_ARRAY</constant></entry>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_TEXTURE_2D_ARRAY</constant></entry>
                        <entry align="left"><constant>GL_TEXTURE_2D</constant>, <constant>GL_TEXTURE_2D_ARRAY</constant></entry>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant></entry>
                        <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>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_TEXTURE_2D_MULTISAMPLE</constant></entry>
                        <entry align="left"><constant>GL_TEXTURE_2D_MULTISAMPLE</constant>, <constant>GL_TEXTURE_MULTISAMPLE_ARRAY</constant></entry>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_TEXTURE_2D_MULTISAMPLE_ARRAY</constant></entry>
                        <entry align="left"><constant>GL_TEXTURE_2D_MULTISAMPLE</constant>, <constant>GL_TEXTURE_MULTISAMPLE_ARRAY</constant></entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>
        <para>
            The value of <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant> for <parameter>origtexture</parameter>
            must be <constant>GL_TRUE</constant>.
            After initialization, <parameter>texture</parameter> inherits the data store of
            the parent texture, <parameter>origtexture</parameter> and is usable as a normal
            texture object with target <parameter>target</parameter>. Data in the shared store
            is reinterpreted with the new internal format specified by <parameter>internalformat</parameter>.
            <parameter>internalformat</parameter> must be compatible with the internal format
            of the parent texture as specified in the following table:
        </para>
        <informaltable frame="topbot">
            <tgroup cols="2" align="left">
                <colspec colnum="1" colname="col1" colwidth="1*"/>
                <colspec colnum="2" colname="col2" colwidth="2*"/>
                <thead>
                    <row>
                        <entry align="center">Class</entry>
                        <entry align="center">Internal Formats</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry align="left">128-bit</entry>
                        <entry align="left"><constant>GL_RGBA32F</constant>, <constant>GL_RGBA32UI</constant>, <constant>GL_RGBA32I</constant></entry>
                    </row>
                    <row>
                        <entry align="left">96-bit</entry>
                        <entry align="left"><constant>GL_RGB32F</constant>, <constant>GL_RGB32UI</constant>, <constant>GL_RGB32I</constant></entry>
                    </row>
                    <row>
                        <entry align="left">64-bit</entry>
                        <entry align="left"><constant>GL_RGBA16F</constant>, <constant>GL_RG32F</constant>, <constant>GL_RGBA16UI</constant>,
                        <constant>GL_RG32UI</constant>, <constant>GL_RGBA16I</constant>, <constant>GL_RG32I</constant>, <constant>GL_RGBA16</constant>, <constant>GL_RGBA16_SNORM</constant></entry>
                    </row>
                    <row>
                        <entry align="left">48-bit</entry>
                        <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>
                    </row>
                    <row>
                        <entry align="left">32-bit</entry>
                        <entry align="left"><constant>GL_RG16F</constant>, <constant>GL_R11F_G11F_B10F</constant>, <constant>GL_R32F</constant>, <constant>GL_RGB10_A2UI</constant>,
                                            <constant>GL_RGBA8UI</constant>, <constant>GL_RG16UI</constant>, <constant>GL_R32UI</constant>, <constant>GL_RGBA8I</constant>,
                                            <constant>GL_RG16I</constant>, <constant>GL_R32I</constant>, <constant>GL_RGB10_A2</constant>, <constant>GL_RGBA8</constant>,
                                            <constant>GL_RG16</constant>, <constant>GL_RGBA8_SNORM</constant>, <constant>GL_RG16_SNORM</constant>, <constant>GL_SRGB8_ALPHA8</constant>,
                                            <constant>GL_RGB9_E5</constant></entry>
                    </row>
                    <row>
                        <entry align="left">24-bit</entry>
                        <entry align="left"><constant>GL_RGB8</constant>, <constant>GL_RGB8_SNORM</constant>, <constant>GL_SRGB8</constant>,
                                            <constant>GL_RGB8UI</constant>, <constant>GL_RGB8I</constant></entry>
                    </row>
                    <row>
                        <entry align="left">16-bit</entry>
                        <entry align="left"><constant>GL_R16F</constant>, <constant>GL_RG8UI</constant>, <constant>GL_R16UI</constant>, <constant>GL_RG8I</constant>,
                                            <constant>GL_R16I</constant>, <constant>GL_RG8</constant>, <constant>GL_R16</constant>, <constant>GL_RG8_SNORM</constant>, <constant>GL_R16_SNORM</constant></entry>
                    </row>
                    <row>
                        <entry align="left">8-bit</entry>
                        <entry align="left"><constant>GL_R8UI</constant>, <constant>GL_R8I</constant>, <constant>GL_R8</constant>, <constant>GL_R8_SNORM</constant></entry>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_RGTC1_RED</constant></entry>
                        <entry align="left"><constant>GL_COMPRESSED_RED_RGTC1</constant>, <constant>GL_COMPRESSED_SIGNED_RED_RGTC1</constant></entry>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_RGTC2_RG</constant></entry>
                        <entry align="left"><constant>GL_COMPRESSED_RG_RGTC2</constant>, <constant>GL_COMPRESSED_SIGNED_RG_RGTC2</constant></entry>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_BPTC_UNORM</constant></entry>
                        <entry align="left"><constant>GL_COMPRESSED_RGBA_BPTC_UNORM</constant>, <constant>GL_COMPRESSED_SRGB_ALPHA_BPTC_UNORM</constant></entry>
                    </row>
                    <row>
                        <entry align="left"><constant>GL_BPTC_FLOAT</constant></entry>
                        <entry align="left"><constant>GL_COMPRESSED_RGB_BPTC_SIGNED_FLOAT</constant>, <constant>GL_COMPRESSED_RGB_BPTC_UNSIGNED_FLOAT</constant></entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>
        <para>
            If the original texture is an array or has multiple mipmap levels,
            the parameters <parameter>minlayer</parameter>, <parameter>numlayers</parameter>, <parameter>minlevel</parameter>, and <parameter>numlevels</parameter>
            control which of those slices and levels are considered part of the texture.
            The <parameter>minlevel</parameter> and <parameter>minlayer</parameter> parameters are relative to the view of the
            original texture. If <parameter>numlayers</parameter> or <parameter>numlevels</parameter> extend beyond the original
            texture, they are clamped to the max extent of the original texture.
        </para>
        <para>
            If the new texture's target is <constant>GL_TEXTURE_CUBE_MAP</constant>, the clamped <parameter>numlayers</parameter>
            must be equal to 6. If the new texture's target is <constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant>,
            then <parameter>numlayers</parameter> counts layer-faces rather than layers, and the clamped
            <parameter>numlayers</parameter> must be a multiple of 6. If the new texture's target is <constant>GL_TEXTURE_CUBE_MAP</constant> or
            <constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant>, the width and height of the original texture's 
            levels must be equal.
        </para>
        <para>
            When the original texture's target is <constant>GL_TEXTURE_CUBE_MAP</constant>, the layer
            parameters are interpreted in the same order as if it were a
            <constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant> with 6 layer-faces.
        </para>
        <para>
            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 
            <constant>GL_TEXTURE_2D_MULTISAMPLE</constant>, <parameter>numlayers</parameter> must equal 1.
        </para>
        <para>
            The dimensions of the original texture must be less than or equal to the maximum 
            supported dimensions of the new target. For example, if the original texture has a <constant>GL_TEXTURE_2D_ARRAY</constant>
            target and its width is greater than <constant>GL_MAX_CUBE_MAP_TEXTURE_SIZE</constant>, an error
            will be generated if <function>glTextureView</function> is called to create a <constant>GL_TEXTURE_CUBE_MAP</constant>
            view.
        </para>
        <para>
            Texture commands that take a <parameter>level</parameter> or <parameter>layer</parameter> parameter, such as 
            <citerefentry><refentrytitle>glTexSubImage2D</refentrytitle></citerefentry>, interpret that parameter to be relative to the view of the 
            texture. i.e. the mipmap level of the data store that would be updated via 
            <citerefentry><refentrytitle>TexSubImage2D</refentrytitle></citerefentry> would be the sum of <parameter>level</parameter> and the value of 
            <constant>GL_TEXTURE_VIEW_MIN_LEVEL</constant>.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>minlayer</parameter> or <parameter>minlevel</parameter>
            are larger than the greatest layer or level of <parameter>origtexture</parameter>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>target</parameter> is not compatible
            with the target of <parameter>origtexture</parameter>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if the dimensions of <parameter>origtexture</parameter>
            are greater than the maximum supported dimensions for <parameter>target</parameter>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>internalformat</parameter> is not compatible
            with the internal format of <parameter>origtexture</parameter>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>texture</parameter> has already been bound
            or otherwise given a target.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if the value of <constant>GL_TEXTURE_IMMUTABLE_FORMAT</constant>
            for <parameter>origtexture</parameter> is not <constant>GL_TRUE</constant>.
        </para>
        <para>
            <constant>GL_INVALID_OPERATION</constant> is generated if <parameter>origtexture</parameter> is not the name of an
            existing texture object.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generaged if <parameter>target</parameter> is <constant>GL_TEXTURE_CUBE_MAP</constant>
            and <parameter>numlayers</parameter> is not 6, or if <parameter>target</parameter> is <constant>GL_TEXTURE_CUBE_MAP_ARRAY</constant>
            and <parameter>numlayers</parameter> is not an integer multiple of 6.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated 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
            <constant>GL_TEXTURE_2D_MULTISAMPLE</constant> and <parameter>numlayers</parameter> does not equal 1.
        </para>
        <para>
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>texture</parameter> zero or is not the name of a texture previously
            returned from a successful call to <citerefentry><refentrytitle>glGenTextures</refentrytitle></citerefentry>.
        </para>
    </refsect1>
    <refsect1 id="associatedgets"><title>Associated Gets</title>
        <para>
            <citerefentry><refentrytitle>glTexParameter</refentrytitle></citerefentry> with arguments <constant>GL_TEXTURE_VIEW_MIN_LEVEL</constant>,
            <constant>GL_TEXTURE_VIEW_NUM_LEVELS</constant>, <constant>GL_TEXTURE_VIEW_MIN_LAYER</constant>,
            <constant>GL_TEXTURE_VIEW_NUM_LAYERS</constant>, or <constant>GL_TEXTURE_IMMUTABLE_LEVELS</constant>.
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glTexStorage1D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexStorage2D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glTexStorage3D</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glGetTexParameter</refentrytitle></citerefentry>.
        </para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 2012 Khronos Group. 
            This material may be distributed subject to the terms and conditions set forth in 
            the Open Publication License, v 1.0, 8 June 1999.
            <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
        </para>
    </refsect1>
</refentry>
