[clinton/guile-figl.git] / upstream-doc / man4 / glTextureView.xml

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