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=
"glInvalidateTexSubImage">
9 <holder>Khronos Group
</holder>
12 <refentrytitle>glInvalidateTexSubImage
</refentrytitle>
13 <manvolnum>3G
</manvolnum>
16 <refname>glInvalidateTexSubImage
</refname>
17 <refpurpose>invalidate a region of a texture image
</refpurpose>
19 <refsynopsisdiv><title>C Specification
</title>
22 <funcdef>void
<function>glInvalidateTexSubImage
</function></funcdef>
23 <paramdef>GLuint
<parameter>texture
</parameter></paramdef>
24 <paramdef>GLint
<parameter>level
</parameter></paramdef>
25 <paramdef>GLint
<parameter>xoffset
</parameter></paramdef>
26 <paramdef>GLint
<parameter>yoffset
</parameter></paramdef>
27 <paramdef>GLint
<parameter>zoffset
</parameter></paramdef>
28 <paramdef>GLsizei
<parameter>width
</parameter></paramdef>
29 <paramdef>GLsizei
<parameter>height
</parameter></paramdef>
30 <paramdef>GLsizei
<parameter>depth
</parameter></paramdef>
34 <refsect1 id=
"parameters"><title>Parameters
</title>
37 <term><parameter>texture
</parameter></term>
40 The name of a texture object a subregion of which to invalidate.
45 <term><parameter>level
</parameter></term>
48 The level of detail of the texture object within which the region resides.
53 <term><parameter>xoffset
</parameter></term>
56 The X offset of the region to be invalidated.
61 <term><parameter>yoffset
</parameter></term>
64 The Y offset of the region to be invalidated.
69 <term><parameter>zoffset
</parameter></term>
72 The Z offset of the region to be invalidated.
77 <term><parameter>width
</parameter></term>
80 The width of the region to be invalidated.
85 <term><parameter>height
</parameter></term>
88 The height of the region to be invalidated.
93 <term><parameter>depth
</parameter></term>
96 The depth of the region to be invalidated.
102 <refsect1 id=
"description"><title>Description
</title>
104 <function>glInvalidateTexSubImage
</function> invalidates all or part of
105 a texture image.
<parameter>texture
</parameter> and
<parameter>level
</parameter> indicated
106 which texture image is being invalidated. After this command, data in that subregion have undefined
107 values.
<parameter>xoffset
</parameter>,
<parameter>yoffset
</parameter>,
<parameter>zoffset
</parameter>,
<parameter>width
</parameter>,
<parameter>height
</parameter>, and
<parameter>depth
</parameter>
108 are interpreted as they are in
<citerefentry><refentrytitle>glTexSubImage3D
</refentrytitle></citerefentry>. For texture targets that
109 don't have certain dimensions, this command treats those dimensions as
110 having a size of
1. For example, to invalidate a portion of a two-
111 dimensional texture, the application would use
<parameter>zoffset
</parameter> equal to zero and
112 <parameter>depth
</parameter> equal to one. Cube map textures are treated as an array of six
113 slices in the z-dimension, where a value of
<parameter>zoffset
</parameter> is interpreted as
114 specifying face
<constant>TEXTURE_CUBE_MAP_POSITIVE_X
</constant> +
<parameter>zoffset
</parameter>.
117 <parameter>level
</parameter> must be greater than or equal to zero and be
118 less than the base
2 logarithm of the maximum texture width, height, or depth.
119 <parameter>xoffset
</parameter>,
<parameter>yoffset
</parameter> and
<parameter>zoffset
</parameter>
120 must be greater than or equal to zero and be less than the width, height or depth
121 of the image, respectively. Furthermore,
<parameter>xoffset
</parameter> +
<parameter>width
</parameter>,
122 <parameter>yoffset
</parameter> +
<parameter>height
</parameter>, and
123 <parameter>zoffset
</parameter> +
<parameter>depth
</parameter> must be less
124 than or equal to the width, height or depth of the image, respectively.
127 For textures of targets
<constant>GL_TEXTURE_RECTANGLE
</constant>,
<constant>GL_TEXTURE_BUFFER
</constant>,
<constant>GL_TEXTURE_2D_MULTISAMPLE
</constant>, or
128 <constant>GL_TEXTURE_2D_MULTISAMPLE_ARRAY
</constant>, level must be zero.
131 <refsect1 id=
"errors"><title>Errors
</title>
133 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>xoffset
</parameter>,
134 <parameter>yoffset
</parameter> or
<parameter>zoffset
</parameter> is less than zero,
135 or if any of them is greater than the size of the image in the corresponding dimension.
138 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>level
</parameter> is
139 less than zero or if it is greater or equal to the base
2 logarithm of the maximum texture width, height, or depth.
142 <constant>GL_INVALID_VALUE
</constant> is generated if the target of
<parameter>texture
</parameter>
143 is any of
<constant>GL_TEXTURE_RECTANGLE
</constant>,
<constant>GL_TEXTURE_BUFFER
</constant>,
<constant>GL_TEXTURE_2D_MULTISAMPLE
</constant>, or
144 <constant>GL_TEXTURE_2D_MULTISAMPLE_ARRAY
</constant> and
<parameter>level
</parameter> is not zero.
147 <constant>GL_INVALID_VALUE
</constant> is generated if
<parameter>texture
</parameter> is not the
148 name of an existing texture object.
151 <refsect1 id=
"associatedgets"><title>Associated Gets
</title>
153 <citerefentry><refentrytitle>glGet
</refentrytitle></citerefentry> with argument
<constant>GL_MAX_TEXTURE_SIZE
</constant>
156 <refsect1 id=
"seealso"><title>See Also
</title>
158 <citerefentry><refentrytitle>glInvalidateTexImage
</refentrytitle></citerefentry>,,
159 <citerefentry><refentrytitle>glInvalidateBufferSubData
</refentrytitle></citerefentry>,
160 <citerefentry><refentrytitle>glInvalidateBufferData
</refentrytitle></citerefentry>,
161 <citerefentry><refentrytitle>glInvalidateFramebuffer
</refentrytitle></citerefentry>,
162 <citerefentry><refentrytitle>glInvalidateSubFramebuffer
</refentrytitle></citerefentry>.
165 <refsect1 id=
"Copyright"><title>Copyright
</title>
167 Copyright
<trademark class=
"copyright"></trademark> 2012 Khronos Group.
168 This material may be distributed subject to the terms and conditions set forth in
169 the Open Publication License, v
1.0,
8 June
1999.
170 <ulink url=
"http://opencontent.org/openpub/">http://opencontent.org/openpub/
</ulink>.