<div class="refentry" id="glClearTexSubImage">

<div class="titlepage"></div>

<div class="refnamediv">

<h2>Name</h2>

<p>glClearTexSubImage — fills all or part of a texture image with a constant value</p>

</div>

<div class="refsynopsisdiv">

<h2>C Specification</h2>

<div class="funcsynopsis">

<table style="border: 0; cellspacing: 0; cellpadding: 0;" class="funcprototype-table">

<tr>

<td>

<code class="funcdef">void <strong class="fsfunc">glClearTexSubImage</strong>(</code>

</td>

<td>GLuint <var class="pdparam">texture</var>, </td>

</tr>

<tr>

<td> </td>

<td>GLint <var class="pdparam">level</var>, </td>

</tr>

<tr>

<td> </td>

<td>GLint <var class="pdparam">xoffset</var>, </td>

</tr>

<tr>

<td> </td>

<td>GLint <var class="pdparam">yoffset</var>, </td>

</tr>

<tr>

<td> </td>

<td>GLint <var class="pdparam">zoffset</var>, </td>

</tr>

<tr>

<td> </td>

<td>GLsizei <var class="pdparam">width</var>, </td>

</tr>

<tr>

<td> </td>

<td>GLsizei <var class="pdparam">height</var>, </td>

</tr>

<tr>

<td> </td>

<td>GLsizei <var class="pdparam">depth</var>, </td>

</tr>

<tr>

<td> </td>

<td>GLenum <var class="pdparam">format</var>, </td>

</tr>

<tr>

<td> </td>

<td>GLenum <var class="pdparam">type</var>, </td>

</tr>

<tr>

<td> </td>

<td>const void * <var class="pdparam">data</var><code>)</code>;</td>

</tr>

</table>

<div class="funcprototype-spacer"> </div>

</div>

</div>

<div class="refsect1" id="parameters">

<h2>Parameters</h2>

<div class="variablelist">

<dl class="variablelist">

<dt>

<span class="term">

<em class="parameter">

<code>texture</code>

</em>

</span>

</dt>

<dd>

<p>

The name of an existing texture object containing the image to be cleared.

</p>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>level</code>

</em>

</span>

</dt>

<dd>

<p>

The level of <em class="parameter"><code>texture</code></em> containing the region to be cleared.

</p>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>xoffset</code>

</em>

</span>

</dt>

<dd>

<p>

The coordinate of the left edge of the region to be cleared.

</p>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>yoffset</code>

</em>

</span>

</dt>

<dd>

<p>

The coordinate of the lower edge of the region to be cleared.

</p>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>zoffset</code>

</em>

</span>

</dt>

<dd>

<p>

The coordinate of the front of the region to be cleared.

</p>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>width</code>

</em>

</span>

</dt>

<dd>

<p>

The width of the region to be cleared.

</p>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>height</code>

</em>

</span>

</dt>

<dd>

<p>

The height of the region to be cleared.

</p>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>depth</code>

</em>

</span>

</dt>

<dd>

<p>

The depth of the region to be cleared.

</p>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>format</code>

</em>

</span>

</dt>

<dd>

<p>

The format of the data whose address in memory is given by <em class="parameter"><code>data</code></em>.

</p>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>type</code>

</em>

</span>

</dt>

<dd>

<p>

The type of the data whose address in memory is given by <em class="parameter"><code>data</code></em>.

</p>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>data</code>

</em>

</span>

</dt>

<dd>

<p>

The address in memory of the data to be used to clear the specified region.

</p>

</dd>

</dl>

</div>

</div>

<div class="refsect1" id="description">

<h2>Description</h2>

<p>

<code class="function">glClearTexSubImage</code> fills all or part of an image contained in a

texture with an application supplied value. <em class="parameter"><code>texture</code></em> must be

the name of an existing texture. Further, <em class="parameter"><code>texture</code></em> may not be

the name of a buffer texture, nor may its internal format be compressed.

</p>

<p>

Arguments <em class="parameter"><code>xoffset</code></em>, <em class="parameter"><code>yoffset</code></em>, and

<em class="parameter"><code>zoffset</code></em> specify the lower left texel coordinates of

a width-wide by height-high by depth-deep rectangular subregion of the texel array.

</p>

<p>

For one-dimensional array textures, <em class="parameter"><code>yoffset</code></em> is interpreted as the first layer to

be cleared and <em class="parameter"><code>height</code></em> is the number of layers to clear. For two-dimensional array

textures, <em class="parameter"><code>zoffset</code></em> is interpreted as the first layer to be cleared and <em class="parameter"><code>depth</code></em> is the number

of layers to clear. Cube map textures are treated as an array of six slices in the z-dimension,

where the value of <em class="parameter"><code>zoffset</code></em> is interpreted as specifying the cube map face

for the corresponding layer and <em class="parameter"><code>depth</code></em> is the number of faces to clear.

For cube map array textures, <em class="parameter"><code>zoffset</code></em> is the first layer-face to clear,

and <em class="parameter"><code>depth</code></em> is the number of layer-faces to clear. Each layer-face is

translated into an array layer and a cube map face as described in the OpenGL Specification.

</p>

<p>

Negative values of <em class="parameter"><code>xoffset</code></em>, <em class="parameter"><code>yoffset</code></em>, and <em class="parameter"><code>zoffset</code></em> correspond to the coordinates of

border texels. Taking

<math overflow="scroll"><mi mathvariant="italic">ws</mi></math>,

<math overflow="scroll"><mi mathvariant="italic">hs</mi></math>,

<math overflow="scroll"><mi mathvariant="italic">ds</mi></math>,

<math overflow="scroll"><mi mathvariant="italic">wb</mi></math>,

<math overflow="scroll"><mi mathvariant="italic">hb</mi></math>, and

<math overflow="scroll"><mi mathvariant="italic">db</mi></math> to be

the specified <em class="parameter"><code>width</code></em>, <em class="parameter"><code>height</code></em>, <em class="parameter"><code>depth</code></em>, and the border width, border height, and border

depth of the texel array and taking

<math overflow="scroll"><mi mathvariant="italic">x</mi></math>,

<math overflow="scroll"><mi mathvariant="italic">y</mi></math>,

<math overflow="scroll"><mi mathvariant="italic">z</mi></math>,

<math overflow="scroll"><mi mathvariant="italic">w</mi></math>,

<math overflow="scroll"><mi mathvariant="italic">h</mi></math>, and

<math overflow="scroll"><mi mathvariant="italic">d</mi></math>

to be the <em class="parameter"><code>xoffset</code></em>, <em class="parameter"><code>yoffset</code></em>,

<em class="parameter"><code>zoffset</code></em>, <em class="parameter"><code>width</code></em>, <em class="parameter"><code>height</code></em>, and <em class="parameter"><code>depth</code></em> argument values,

any of the following relationships generates a <code class="constant">GL_INVALID_OPERATION</code> error:

</p>

<div class="itemizedlist">

<ul class="itemizedlist" style="list-style-type: disc; ">

<li class="listitem">

<div class="informalequation">

<math overflow="scroll">

<mrow>

<mtext>x</mtext>

<mo>&lt;</mo>

<msub>

<mtext>w</mtext>

<mtext>b</mtext>

</msub>

</mrow>

</math>

</div>

</li>

<li class="listitem">

<div class="informalequation">

<math overflow="scroll">

<mrow>

<mtext mathvariant="italic">x</mtext>

<mo>+</mo>

<mtext mathvariant="italic">w</mtext>

<mo>&gt;</mo>

<msub>

<mtext mathvariant="italic">w</mtext>

<mtext mathvariant="italic">s</mtext>

</msub>

<mo>-</mo>

<msub>

<mtext mathvariant="italic">w</mtext>

<mtext mathvariant="italic">b</mtext>

</msub>

</mrow>

</math>

</div>

</li>

<li class="listitem">

<div class="informalequation">

<math overflow="scroll">

<mrow>

<mtext mathvariant="italic">y</mtext>

<mo>&lt;</mo>

<mo>-</mo>

<msub>

<mtext mathvariant="italic">h</mtext>

<mtext mathvariant="italic">b</mtext>

</msub>

</mrow>

</math>

</div>

</li>

<li class="listitem">

<div class="informalequation">

<math overflow="scroll">

<mrow>

<mtext mathvariant="italic">y</mtext>

<mo>+</mo>

<mtext mathvariant="italic">h</mtext>

<mo>&gt;</mo>

<msub>

<mtext mathvariant="italic">h</mtext>

<mtext mathvariant="italic">s</mtext>

</msub>

<mo>-</mo>

<msub>

<mtext mathvariant="italic">h</mtext>

<mtext mathvariant="italic">b</mtext>

</msub>

</mrow>

</math>

</div>

</li>

<li class="listitem">

<div class="informalequation">

<math overflow="scroll">

<mrow>

<mtext mathvariant="italic">z</mtext>

<mo>&lt;</mo>

<mo>-</mo>

<msub>

<mtext mathvariant="italic">d</mtext>

<mtext mathvariant="italic">b</mtext>

</msub>

</mrow>

</math>

</div>

</li>

<li class="listitem">

<div class="informalequation">

<math overflow="scroll">

<mrow>

<mtext mathvariant="italic">z</mtext>

<mo>+</mo>

<mtext mathvariant="italic">d</mtext>

<mo>&gt;</mo>

<msub>

<mtext mathvariant="italic">d</mtext>

<mtext mathvariant="italic">s</mtext>

</msub>

<mo>-</mo>

<msub>

<mtext mathvariant="italic">d</mtext>

<mtext mathvariant="italic">b</mtext>

</msub>

</mrow>

</math>

</div>

</li>

</ul>

</div>

<p>

</p>

<p>

For texture types that do not have certain dimensions, this command treats those

dimensions as having a size of 1. For example, to clear a portion of a two-dimensional

texture, use <em class="parameter"><code>zoffset</code></em> equal to zero and <em class="parameter"><code>depth</code></em> equal to one.

</p>

<p>

<em class="parameter"><code>format</code></em> and <em class="parameter"><code>type</code></em> specify the format and type of the

source data and are interpreted as they are for <a class="citerefentry" href="glTexImage3D"><span class="citerefentry"><span class="refentrytitle">glTexImage3D</span></span></a>.

Textures with a base internal format of <code class="constant">GL_DEPTH_COMPONENT</code>, <code class="constant">GL_STENCIL_INDEX</code>, or <code class="constant">GL_DEPTH_STENCIL</code>

require depth component, stencil, or depth-stencil component data respectively.

Textures with other base internal formats require RGBA formats. Textures with integer

internal formats require integer data.

</p>

<p>

<em class="parameter"><code>data</code></em> is a pointer to an array of between one and four components of texel

data that will be used as the source for the constant fill value. The elements of

data are converted by the GL into the internal format of the texture image (that

was specified when the level was defined by any of the <code class="function">glTexImage*</code>, <code class="function">glTexStorage*</code>

or <code class="function">glCopyTexImage*</code> commands), and then

used to fill the specified range of the destination texture level. If <em class="parameter"><code>data</code></em> is <code class="constant">NULL</code>, then

the pointer is ignored and the sub-range of the texture image is filled with zeros. If

texture is a multisample texture, all the samples in a texel are cleared to the value

specified by data.

</p>

</div>

<div class="refsect1" id="notes">

<h2>Notes</h2>

<p>

<code class="function">glClearTexSubImage</code> is available only if the GL version is 4.4 or greater.

</p>

</div>

<div class="refsect1" id="errors">

<h2>Errors</h2>

<p>

<code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>texture</code></em> is zero or not the

name of an existing texture object.

</p>

<p>

<code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>texture</code></em> is a buffer texture.

</p>

<p>

<code class="constant">GL_INVALID_OPERATION</code> is generated if <em class="parameter"><code>texture</code></em> has a compressed

internal format.

</p>

<p>

<code class="constant">GL_INVALID_OPERATION</code> is generated if the base internal format is

<code class="constant">GL_DEPTH_COMPONENT</code> and <em class="parameter"><code>format</code></em> is not <code class="constant">GL_DEPTH_COMPONENT</code>.

</p>

<p>

<code class="constant">GL_INVALID_OPERATION</code> is generated if the base internal format is

<code class="constant">GL_DEPTH_STENCIL</code> and <em class="parameter"><code>format</code></em> is not <code class="constant">GL_DEPTH_STENCIL</code>.

</p>

<p>

<code class="constant">GL_INVALID_OPERATION</code> is generated if the base internal format is

<code class="constant">GL_STENCIL_INDEX</code> and <em class="parameter"><code>format</code></em> is not <code class="constant">GL_STENCIL_INDEX</code>.

</p>

<p>

<code class="constant">GL_INVALID_OPERATION</code> is generated if the base internal format is

<code class="constant">GL_RGBA</code> and <em class="parameter"><code>format</code></em> is <code class="constant">GL_DEPTH_COMPONENT</code>, <code class="constant">GL_STENCIL_INDEX</code>, or <code class="constant">GL_DEPTH_STENCIL</code>.

</p>

<p>

<code class="constant">GL_INVALID_OPERATION</code> is generated if the internal format is integer and <em class="parameter"><code>format</code></em> does not specify integer data.

</p>

<p>

<code class="constant">GL_INVALID_OPERATION</code> is generated if the internal format is not

integer and <em class="parameter"><code>format</code></em> specifies integer data.

</p>

<p>

<code class="constant">GL_INVALID_OPERATION</code> error is generated if the <em class="parameter"><code>xoffset</code></em>, <em class="parameter"><code>yoffset</code></em>, <em class="parameter"><code>zoffset</code></em>,

<em class="parameter"><code>width</code></em>, <em class="parameter"><code>height</code></em>, and <em class="parameter"><code>depth</code></em> parameters (or combinations thereof) specify a region that falls outside the

defined texture image array (including border, if any).

</p>

</div>

<div class="refsect1" id="associatedgets">

<h2>Associated Gets</h2>

<p>

<a class="citerefentry" href="glGetTexImage"><span class="citerefentry"><span class="refentrytitle">glGetTexImage</span></span></a>, <a class="citerefentry" href="glGetInternalformat"><span class="citerefentry"><span class="refentrytitle">glGetInternalformat</span></span></a>

</p>

</div>

{$pipelinestall}{$examples}

<div class="refsect1" id="versions">

<h2>Version Support</h2>

<div class="informaltable">

<table style="border-collapse: collapse; border-top: 2px solid ; border-bottom: 2px solid ; border-left: 2px solid ; border-right: 2px solid ; ">

<colgroup>

<col style="text-align: left; "/>

<col style="text-align: center; " class="firstvers"/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; " class="lastvers"/>

</colgroup>

<thead>

<tr>

<th style="text-align: left; border-right: 2px solid ; ">

</th>

<th style="text-align: center; border-bottom: 2px solid ; " colspan="12">

<span class="bold"><strong>OpenGL Version</strong></span>

</th>

</tr>

<tr>

<th style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>Function / Feature Name</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>2.0</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>2.1</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>3.0</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>3.1</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>3.2</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>3.3</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>4.0</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>4.1</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>4.2</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>4.3</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>4.4</strong></span>

</th>

<th style="text-align: center; border-bottom: 2px solid ; ">

<span class="bold"><strong>4.5</strong></span>

</th>

</tr>

</thead>

<tbody>

<tr>

<td style="text-align: left; border-right: 2px solid ; ">

<code class="function">glClearTexSubImage</code>

</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">✔</td>

<td style="text-align: center; ">✔</td>

</tr>

</tbody>

</table>

</div>

</div>

<div class="refsect1" id="seealso">

<h2>See Also</h2>

<p>

<a class="citerefentry" href="glClearTexImage"><span class="citerefentry"><span class="refentrytitle">glClearTexImage</span></span></a>,

<a class="citerefentry" href="glTexStorage1D"><span class="citerefentry"><span class="refentrytitle">glTexStorage1D</span></span></a>,

<a class="citerefentry" href="glTexStorage2D"><span class="citerefentry"><span class="refentrytitle">glTexStorage2D</span></span></a>,

<a class="citerefentry" href="glTexStorage3D"><span class="citerefentry"><span class="refentrytitle">glTexStorage3D</span></span></a>,

<a class="citerefentry" href="glTexImage1D"><span class="citerefentry"><span class="refentrytitle">glTexImage1D</span></span></a>,

<a class="citerefentry" href="glTexImage2D"><span class="citerefentry"><span class="refentrytitle">glTexImage2D</span></span></a>,

<a class="citerefentry" href="glTexImage3D"><span class="citerefentry"><span class="refentrytitle">glTexImage3D</span></span></a>

</p>

</div>

<div class="refsect1" id="Copyright">

<h2>Copyright</h2>

<p>

Copyright © 2013-2014 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.

<a class="link" href="https://opencontent.org/openpub/" target="_top">https://opencontent.org/openpub/</a>.

</p>

</div>

</div>