NAME

glCopyTexSubImage3D - copy a three-dimensional texture subimage

C SPECIFICATION

void ggllCCooppyyTTeexxSSuubbIImmaaggee33DD( GLenum _t_a_r_g_e_t,
                          GLint _l_e_v_e_l,
                          GLint _x_o_f_f_s_e_t,
                          GLint _y_o_f_f_s_e_t,
                          GLint _z_o_f_f_s_e_t,
                          GLint _x,
                          GLint _y,
                          GLsizei _w_i_d_t_h,
                          GLsizei _h_e_i_g_h_t )

delim $$

PARAMETERS

_t_a_r_g_e_t
Specifies the target texture. Must be GGLL__TTEEXXTTUURREE__33DD
_l_e_v_e_l
Specifies the level-of-detail number. Level 0 is the base image level. Level _n is the _nth mipmap reduction image.
_x_o_f_f_s_e_t
Specifies a texel offset in the x direction within the texture array.
_y_o_f_f_s_e_t
Specifies a texel offset in the y direction within the texture array.
_z_o_f_f_s_e_t
Specifies a texel offset in the z direction within the texture array.
_x, _y
Specify the window coordinates of the lower left corner of the rectangular region of pixels to be copied.
_w_i_d_t_h
Specifies the width of the texture subimage.
_h_e_i_g_h_t
Specifies the height of the texture subimage.

DESCRIPTION

ggllCCooppyyTTeexxSSuubbIImmaaggee33DD replaces a rectangular portion of a three-dimensional texture image with pixels from the current GGLL__RREEAADD__BBUUFFFFEERR (rather than from main memory, as is the case for ggllTTeexxSSuubbIImmaaggee33DD).

The screen-aligned pixel rectangle with lower left corner at (_x, _y) and with width _w_i_d_t_h and height _h_e_i_g_h_t replaces the portion of the texture array with x indices _x_o_f_f_s_e_t through _x_o_f_f_s_e_t$~+~$_w_i_d_t_h$~-~$1, inclusive, and y indices _y_o_f_f_s_e_t through _y_o_f_f_s_e_t$~+~$_h_e_i_g_h_t$~-~$1, inclusive, at z index _z_o_f_f_s_e_t and at the mipmap level specified by _l_e_v_e_l.

The pixels in the rectangle are processed exactly as if ggllCCooppyyPPiixxeellss had been called, but the process stops just before final conversion. At this point, all pixel component values are clamped to the range [0, 1] and then converted to the texture's internal for storage in the texel array.

The destination rectangle in the texture array may not include any texels outside the texture array as it was originally specified. It is not an error to specify a subtexture with zero width or height, but such a specification has no effect.

If any of the pixels within the specified rectangle of the current GGLL__RREEAADD__BBUUFFFFEERR are outside the read window associated with the current rendering context, then the values obtained for those pixels are undefined.

No change is made to the _i_n_t_e_r_n_a_l_f_o_r_m_a_t, _w_i_d_t_h, _h_e_i_g_h_t, _d_e_p_t_h, or _b_o_r_d_e_r parameters of the specified texture array or to texel values outside the specified subregion.

NOTES

ggllCCooppyyTTeexxSSuubbIImmaaggee33DD is available only if the GL version is 1.2 or greater.

Texturing has no effect in color index mode.

ggllPPiixxeellSSttoorree and ggllPPiixxeellTTrraannssffeerr modes affect texture images in exactly the way they affect ggllDDrraawwPPiixxeellss.

When the GGLL__AARRBB__iimmaaggiinngg extension is supported, the RGBA components copied from the framebuffer may be processed by the imaging pipeline, as if they were a two-dimensional texture. See ggllTTeexxIImmaaggee22DD for specific details.

ERRORS

GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _t_a_r_g_e_t is not GGLL__TTEEXXTTUURREE__33DD.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if the texture array has not been defined by a previous ggllTTeexxIImmaaggee33DD or ggllCCooppyyTTeexxIImmaaggee33DD operation.

GGLL__IINNVVAALLIIDD__VVAALLUUEE is generated if _l_e_v_e_l is less than 0.

GGLL__IINNVVAALLIIDD__VVAALLUUEE may be generated if _l_e_v_e_l is greater than $log sub 2^max$, where $max$ is the returned value of GGLL__MMAAXX__33DD__TTEEXXTTUURREE__SSIIZZEE.

GGLL__IINNVVAALLIIDD__VVAALLUUEE is generated if _x$ ~<~ ~-b$ or if _y$ ~<~ ~-b$, where $b$ is the border width of the texture array.

GGLL__IINNVVAALLIIDD__VVAALLUUEE is generated if $"xoffset" ~<~ -b$, (_x_o_f_f_s_e_t$~+~$_w_i_d_t_h)$~>~(w ~-~b)$, _y_o_f_f_s_e_t$~<~ ~-b$, (_y_o_f_f_s_e_t$~+~$_h_e_i_g_h_t)$~>~(h ~-~b)$, _z_o_f_f_s_e_t$~<~ ~-b$, or _z_o_f_f_s_e_t$~>~(d ~-~b)$, where $w$ is the GGLL__TTEEXXTTUURREE__WWIIDDTTHH, $h$ is the GGLL__TTEEXXTTUURREE__HHEEIIGGHHTT, $d$ is the GGLL__TTEEXXTTUURREE__DDEEPPTTHH, and $b$ is the GGLL__TTEEXXTTUURREE__BBOORRDDEERR of the texture image being modified. Note that $w$, $h$, and $d$ include twice the border width.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if ggllCCooppyyTTeexxSSuubbIImmaaggee33DD is executed between the execution of ggllBBeeggiinn and the corresponding execution of ggllEEnndd.

ASSOCIATED GETS

ggllGGeettTTeexxIImmaaggee
ggllIIssEEnnaabblleedd with argument GGLL__TTEEXXTTUURREE__33DD

SEE ALSO

ggllCCooppyyPPiixxeellss((33GG)), ggllCCooppyyTTeexxIImmaaggee11DD((33GG)), ggllCCooppyyTTeexxIImmaaggee22DD((33GG)), ggllCCooppyyTTeexxSSuubbIImmaaggee11DD((33GG)), ggllCCooppyyTTeexxSSuubbIImmaaggee22DD((33GG)), ggllPPiixxeellSSttoorree((33GG)), ggllPPiixxeellTTrraannssffeerr((33GG)), ggllRReeaaddBBuuffffeerr((33GG)), ggllTTeexxEEnnvv((33GG)), ggllTTeexxGGeenn((33GG)), ggllTTeexxIImmaaggee11DD((33GG)), ggllTTeexxIImmaaggee22DD((33GG)), ggllTTeexxIImmaaggee33DD((33GG)), ggllTTeexxPPaarraammeetteerr((33GG)), ggllTTeexxSSuubbIImmaaggee11DD((33GG)), ggllTTeexxSSuubbIImmaaggee22DD((33GG)), ggllTTeexxSSuubbIImmaaggee33DD((33GG))