[clinton/guile-figl.git] / upstream-doc / man4 / glInvalidateTexSubImage.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="glInvalidateTexSubImage">\r
    <refmeta>\r
        <refmetainfo>\r
            <copyright>\r
                <year>2012</year>\r
                <holder>Khronos Group</holder>\r
            </copyright>\r
        </refmetainfo>\r
        <refentrytitle>glInvalidateTexSubImage</refentrytitle>\r
        <manvolnum>3G</manvolnum>\r
    </refmeta>\r
    <refnamediv>\r
        <refname>glInvalidateTexSubImage</refname>\r
        <refpurpose>invalidate a region of a texture image</refpurpose>\r
    </refnamediv>\r
    <refsynopsisdiv><title>C Specification</title>\r
        <funcsynopsis>\r
            <funcprototype>\r
                <funcdef>void <function>glInvalidateTexSubImage</function></funcdef>\r
                <paramdef>GLuint <parameter>texture</parameter></paramdef>\r
                <paramdef>GLint <parameter>level</parameter></paramdef>\r
                <paramdef>GLint <parameter>xoffset</parameter></paramdef>\r
                <paramdef>GLint <parameter>yoffset</parameter></paramdef>\r
                <paramdef>GLint <parameter>zoffset</parameter></paramdef>\r
                <paramdef>GLsizei <parameter>width</parameter></paramdef>\r
                <paramdef>GLsizei <parameter>height</parameter></paramdef>\r
                <paramdef>GLsizei <parameter>depth</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
                    The name of a texture object a subregion of which to invalidate.\r
                </para>\r
            </listitem>\r
        </varlistentry>\r
        <varlistentry>\r
            <term><parameter>level</parameter></term>\r
            <listitem>\r
                <para>\r
                    The level of detail of the texture object within which the region resides.\r
                </para>\r
            </listitem>\r
        </varlistentry>\r
        <varlistentry>\r
            <term><parameter>xoffset</parameter></term>\r
            <listitem>\r
                <para>\r
                    The X offset of the region to be invalidated.\r
                </para>\r
            </listitem>\r
        </varlistentry>\r
        <varlistentry>\r
            <term><parameter>yoffset</parameter></term>\r
            <listitem>\r
                <para>\r
                    The Y offset of the region to be invalidated.\r
                </para>\r
            </listitem>\r
        </varlistentry>\r
        <varlistentry>\r
            <term><parameter>zoffset</parameter></term>\r
            <listitem>\r
                <para>\r
                    The Z offset of the region to be invalidated.\r
                </para>\r
            </listitem>\r
        </varlistentry>\r
        <varlistentry>\r
            <term><parameter>width</parameter></term>\r
            <listitem>\r
                <para>\r
                    The width of the region to be invalidated.\r
                </para>\r
            </listitem>\r
        </varlistentry>\r
        <varlistentry>\r
            <term><parameter>height</parameter></term>\r
            <listitem>\r
                <para>\r
                    The height of the region to be invalidated.\r
                </para>\r
            </listitem>\r
        </varlistentry>\r
        <varlistentry>\r
            <term><parameter>depth</parameter></term>\r
            <listitem>\r
                <para>\r
                    The depth of the region to be invalidated.\r
                </para>\r
            </listitem>\r
        </varlistentry>\r
        </variablelist>\r
    </refsect1>\r
    <refsect1 id="description"><title>Description</title>\r
        <para>\r
            <function>glInvalidateTexSubImage</function> invalidates all or part of\r
            a texture image. <parameter>texture</parameter> and <parameter>level</parameter> indicated\r
            which texture image is being invalidated. After this command, data in that subregion have undefined\r
            values. <parameter>xoffset</parameter>, <parameter>yoffset</parameter>, <parameter>zoffset</parameter>, <parameter>width</parameter>, <parameter>height</parameter>, and <parameter>depth</parameter>\r
            are interpreted as they are in <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>. For texture targets that\r
            don't have certain dimensions, this command treats those dimensions as\r
            having a size of 1. For example, to invalidate a portion of a two-\r
            dimensional texture, the application would use <parameter>zoffset</parameter> equal to zero and\r
            <parameter>depth</parameter> equal to one. Cube map textures are treated as an array of six\r
            slices in the z-dimension, where a value of <parameter>zoffset</parameter> is interpreted as\r
            specifying face <constant>TEXTURE_CUBE_MAP_POSITIVE_X</constant> + <parameter>zoffset</parameter>.\r
        </para>\r
        <para>\r
            <parameter>level</parameter> must be greater than or equal to zero and be\r
            less than the base 2 logarithm of the maximum texture width, height, or depth.\r
            <parameter>xoffset</parameter>, <parameter>yoffset</parameter> and <parameter>zoffset</parameter>\r
            must be greater than or equal to zero and be less than the width, height or depth\r
            of the image, respectively. Furthermore, <parameter>xoffset</parameter> + <parameter>width</parameter>,\r
            <parameter>yoffset</parameter> + <parameter>height</parameter>, and\r
            <parameter>zoffset</parameter> + <parameter>depth</parameter> must be less\r
            than or equal to the width, height or depth of the image, respectively.\r
        </para>\r
        <para>\r
            For textures of targets <constant>GL_TEXTURE_RECTANGLE</constant>, <constant>GL_TEXTURE_BUFFER</constant>, <constant>GL_TEXTURE_2D_MULTISAMPLE</constant>, or\r
            <constant>GL_TEXTURE_2D_MULTISAMPLE_ARRAY</constant>, level must be zero.\r
        </para>\r
    </refsect1>\r
    <refsect1 id="errors"><title>Errors</title>\r
        <para>\r
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>xoffset</parameter>,\r
            <parameter>yoffset</parameter> or <parameter>zoffset</parameter> is less than zero,\r
            or if any of them is greater than the size of the image in the corresponding dimension.\r
        </para>\r
        <para>\r
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is\r
            less than zero or if it is greater or equal to the base 2 logarithm of the maximum texture width, height, or depth.\r
        </para>\r
        <para>\r
            <constant>GL_INVALID_VALUE</constant> is generated if the target of <parameter>texture</parameter>\r
            is any of <constant>GL_TEXTURE_RECTANGLE</constant>, <constant>GL_TEXTURE_BUFFER</constant>, <constant>GL_TEXTURE_2D_MULTISAMPLE</constant>, or\r
            <constant>GL_TEXTURE_2D_MULTISAMPLE_ARRAY</constant> and <parameter>level</parameter> is not zero.\r
        </para>\r
        <para>\r
            <constant>GL_INVALID_VALUE</constant> is generated if <parameter>texture</parameter> is not the\r
            name of an existing texture object.\r
        </para>\r
    </refsect1>\r
    <refsect1 id="associatedgets"><title>Associated Gets</title>\r
        <para>\r
            <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_TEXTURE_SIZE</constant>\r
        </para>\r
    </refsect1>\r
    <refsect1 id="seealso"><title>See Also</title>\r
        <para>\r
            <citerefentry><refentrytitle>glInvalidateTexImage</refentrytitle></citerefentry>,,\r
            <citerefentry><refentrytitle>glInvalidateBufferSubData</refentrytitle></citerefentry>,\r
            <citerefentry><refentrytitle>glInvalidateBufferData</refentrytitle></citerefentry>,\r
            <citerefentry><refentrytitle>glInvalidateFramebuffer</refentrytitle></citerefentry>,\r
            <citerefentry><refentrytitle>glInvalidateSubFramebuffer</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="glInvalidateTexSubImage">\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>glInvalidateTexSubImage</refentrytitle>\r
	13	<manvolnum>3G</manvolnum>\r
	14	</refmeta>\r
	15	<refnamediv>\r
	16	<refname>glInvalidateTexSubImage</refname>\r
	17	<refpurpose>invalidate a region of a texture image</refpurpose>\r
	18	</refnamediv>\r
	19	<refsynopsisdiv><title>C Specification</title>\r
	20	<funcsynopsis>\r
	21	<funcprototype>\r
	22	<funcdef>void <function>glInvalidateTexSubImage</function></funcdef>\r
	23	<paramdef>GLuint <parameter>texture</parameter></paramdef>\r
	24	<paramdef>GLint <parameter>level</parameter></paramdef>\r
	25	<paramdef>GLint <parameter>xoffset</parameter></paramdef>\r
	26	<paramdef>GLint <parameter>yoffset</parameter></paramdef>\r
	27	<paramdef>GLint <parameter>zoffset</parameter></paramdef>\r
	28	<paramdef>GLsizei <parameter>width</parameter></paramdef>\r
	29	<paramdef>GLsizei <parameter>height</parameter></paramdef>\r
	30	<paramdef>GLsizei <parameter>depth</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	The name of a texture object a subregion of which to invalidate.\r
	41	</para>\r
	42	</listitem>\r
	43	</varlistentry>\r
	44	<varlistentry>\r
	45	<term><parameter>level</parameter></term>\r
	46	<listitem>\r
	47	<para>\r
	48	The level of detail of the texture object within which the region resides.\r
	49	</para>\r
	50	</listitem>\r
	51	</varlistentry>\r
	52	<varlistentry>\r
	53	<term><parameter>xoffset</parameter></term>\r
	54	<listitem>\r
	55	<para>\r
	56	The X offset of the region to be invalidated.\r
	57	</para>\r
	58	</listitem>\r
	59	</varlistentry>\r
	60	<varlistentry>\r
	61	<term><parameter>yoffset</parameter></term>\r
	62	<listitem>\r
	63	<para>\r
	64	The Y offset of the region to be invalidated.\r
65	</para>\r
66	</listitem>\r
67	</varlistentry>\r
68	<varlistentry>\r
69	<term><parameter>zoffset</parameter></term>\r
70	<listitem>\r
71	<para>\r
72	The Z offset of the region to be invalidated.\r
73	</para>\r
74	</listitem>\r
75	</varlistentry>\r
76	<varlistentry>\r
77	<term><parameter>width</parameter></term>\r
78	<listitem>\r
79	<para>\r
80	The width of the region to be invalidated.\r
81	</para>\r
82	</listitem>\r
83	</varlistentry>\r
84	<varlistentry>\r
85	<term><parameter>height</parameter></term>\r
86	<listitem>\r
87	<para>\r
88	The height of the region to be invalidated.\r
89	</para>\r
90	</listitem>\r
91	</varlistentry>\r
92	<varlistentry>\r
93	<term><parameter>depth</parameter></term>\r
94	<listitem>\r
95	<para>\r
96	The depth of the region to be invalidated.\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>glInvalidateTexSubImage</function> invalidates all or part of\r
105	a texture image. <parameter>texture</parameter> and <parameter>level</parameter> indicated\r
106	which texture image is being invalidated. After this command, data in that subregion have undefined\r
107	values. <parameter>xoffset</parameter>, <parameter>yoffset</parameter>, <parameter>zoffset</parameter>, <parameter>width</parameter>, <parameter>height</parameter>, and <parameter>depth</parameter>\r
108	are interpreted as they are in <citerefentry><refentrytitle>glTexSubImage3D</refentrytitle></citerefentry>. For texture targets that\r
109	don't have certain dimensions, this command treats those dimensions as\r
110	having a size of 1. For example, to invalidate a portion of a two-\r
111	dimensional texture, the application would use <parameter>zoffset</parameter> equal to zero and\r
112	<parameter>depth</parameter> equal to one. Cube map textures are treated as an array of six\r
113	slices in the z-dimension, where a value of <parameter>zoffset</parameter> is interpreted as\r
114	specifying face <constant>TEXTURE_CUBE_MAP_POSITIVE_X</constant> + <parameter>zoffset</parameter>.\r
115	</para>\r
116	<para>\r
117	<parameter>level</parameter> must be greater than or equal to zero and be\r
118	less than the base 2 logarithm of the maximum texture width, height, or depth.\r
119	<parameter>xoffset</parameter>, <parameter>yoffset</parameter> and <parameter>zoffset</parameter>\r
120	must be greater than or equal to zero and be less than the width, height or depth\r
121	of the image, respectively. Furthermore, <parameter>xoffset</parameter> + <parameter>width</parameter>,\r
122	<parameter>yoffset</parameter> + <parameter>height</parameter>, and\r
123	<parameter>zoffset</parameter> + <parameter>depth</parameter> must be less\r
124	than or equal to the width, height or depth of the image, respectively.\r
125	</para>\r
126	<para>\r
127	For textures of targets <constant>GL_TEXTURE_RECTANGLE</constant>, <constant>GL_TEXTURE_BUFFER</constant>, <constant>GL_TEXTURE_2D_MULTISAMPLE</constant>, or\r
128	<constant>GL_TEXTURE_2D_MULTISAMPLE_ARRAY</constant>, level must be zero.\r
129	</para>\r
130	</refsect1>\r
131	<refsect1 id="errors"><title>Errors</title>\r
132	<para>\r
133	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>xoffset</parameter>,\r
134	<parameter>yoffset</parameter> or <parameter>zoffset</parameter> is less than zero,\r
135	or if any of them is greater than the size of the image in the corresponding dimension.\r
136	</para>\r
137	<para>\r
138	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>level</parameter> is\r
139	less than zero or if it is greater or equal to the base 2 logarithm of the maximum texture width, height, or depth.\r
140	</para>\r
141	<para>\r
142	<constant>GL_INVALID_VALUE</constant> is generated if the target of <parameter>texture</parameter>\r
143	is any of <constant>GL_TEXTURE_RECTANGLE</constant>, <constant>GL_TEXTURE_BUFFER</constant>, <constant>GL_TEXTURE_2D_MULTISAMPLE</constant>, or\r
144	<constant>GL_TEXTURE_2D_MULTISAMPLE_ARRAY</constant> and <parameter>level</parameter> is not zero.\r
145	</para>\r
146	<para>\r
147	<constant>GL_INVALID_VALUE</constant> is generated if <parameter>texture</parameter> is not the\r
148	name of an existing texture object.\r
149	</para>\r
150	</refsect1>\r
151	<refsect1 id="associatedgets"><title>Associated Gets</title>\r
152	<para>\r
153	<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with argument <constant>GL_MAX_TEXTURE_SIZE</constant>\r
154	</para>\r
155	</refsect1>\r
156	<refsect1 id="seealso"><title>See Also</title>\r
157	<para>\r
158	<citerefentry><refentrytitle>glInvalidateTexImage</refentrytitle></citerefentry>,,\r
159	<citerefentry><refentrytitle>glInvalidateBufferSubData</refentrytitle></citerefentry>,\r
160	<citerefentry><refentrytitle>glInvalidateBufferData</refentrytitle></citerefentry>,\r
161	<citerefentry><refentrytitle>glInvalidateFramebuffer</refentrytitle></citerefentry>,\r
162	<citerefentry><refentrytitle>glInvalidateSubFramebuffer</refentrytitle></citerefentry>.\r
163	</para>\r
164	</refsect1>\r
165	<refsect1 id="Copyright"><title>Copyright</title>\r
166	<para>\r
167	Copyright <trademark class="copyright"></trademark> 2012 Khronos Group. \r
168	This material may be distributed subject to the terms and conditions set forth in \r
169	the Open Publication License, v 1.0, 8 June 1999.\r
170	<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.\r
171	</para>\r
172	</refsect1>\r
173	</refentry>\r