NAME

glTexSubImage3D - specify a three-dimensional texture subimage

C SPECIFICATION

void ggllTTeexxSSuubbIImmaaggee33DD( 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,
                      GLsizei _w_i_d_t_h,
                      GLsizei _h_e_i_g_h_t,
                      GLsizei _d_e_p_t_h,
                      GLenum _f_o_r_m_a_t,
                      GLenum _t_y_p_e,
                      const GLvoid _*_p_i_x_e_l_s )

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.
_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.
_d_e_p_t_h
Specifies the depth of the texture subimage.
_f_o_r_m_a_t
Specifies the of the pixel data. The following symbolic values are accepted: GGLL__CCOOLLOORR__IINNDDEEXX, GGLL__RREEDD, GGLL__GGRREEEENN, GGLL__BBLLUUEE, GGLL__AALLPPHHAA, GGLL__RRGGBB, GGLL__BBGGRR, GGLL__RRGGBBAA, GGLL__BBGGRRAA, GGLL__LLUUMMIINNAANNCCEE, and GGLL__LLUUMMIINNAANNCCEE__AALLPPHHAA.
_t_y_p_e
Specifies the data type of the pixel data. The following symbolic values are accepted: GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE, GGLL__BBYYTTEE, GGLL__BBIITTMMAAPP, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT, GGLL__SSHHOORRTT, GGLL__UUNNSSIIGGNNEEDD__IINNTT, GGLL__IINNTT, GGLL__FFLLOOAATT, GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__33__33__22, GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__22__33__33__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__55__55__11, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__11__55__55__55__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__1100__1100__1100__22, and GGLL__UUNNSSIIGGNNEEDD__IINNTT__22__1100__1100__1100__RREEVV.
_p_i_x_e_l_s
Specifies a pointer to the image data in memory.

DESCRIPTION

Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. To enable and disable three-dimensional texturing, call ggllEEnnaabbllee and ggllDDiissaabbllee with argument GGLL__TTEEXXTTUURREE__33DD.

ggllTTeexxSSuubbIImmaaggee33DD redefines a contiguous subregion of an existing three-dimensional texture image. The texels referenced by _p_i_x_e_l_s replace the portion of the existing texture array with x indices _x_o_f_f_s_e_t and $"xoffset" ~+~ "width" ~-~ 1$, inclusive, y indices _y_o_f_f_s_e_t and $"yoffset" ~+~ "height" ~-~ 1$, inclusive, and z indices _z_o_f_f_s_e_t and $"zoffset" ~+~ "depth" ~-~ 1$, inclusive. This region may not include any texels outside the range of the texture array as it was originally specified. It is not an error to specify a subtexture with zero width, height, or depth but such a specification has no effect.

NOTES

ggllTTeexxSSuubbIImmaaggee33DD 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.

Formats GGLL__BBGGRR, and GGLL__BBGGRRAA and types GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__33__33__22, GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__22__33__33__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__55__55__11, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__11__55__55__55__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__1100__1100__1100__22, and GGLL__UUNNSSIIGGNNEEDD__IINNTT__22__1100__1100__1100__RREEVV are available only if the GL version is 1.2 or greater.

When the GGLL__AARRBB__mmuullttiitteexxttuurree extension is supported, ggllTTeexxSSuubbIImmaaggee33DD specifies a three-dimensional sub texture for the current texture unit, specified with ggllAAccttiivveeTTeexxttuurreeAARRBB.

When the GGLL__AARRBB__iimmaaggiinngg extension is supported, the RGBA components specified in _p_i_x_e_l_s may be processed by the imaging pipeline. See ggllTTeexxIImmaaggee33DD 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 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$_m_a_x, where _m_a_x is the returned value of GGLL__MMAAXX__TTEEXXTTUURREE__SSIIZZEE.

GGLL__IINNVVAALLIIDD__VVAALLUUEE is generated if $"xoffset" ~<~ ~-b$, $("xoffset" ~+~ "width") ~>~ (w~-~b)$, $"yoffset" ~<~ ~-b$, or $("yoffset" ~+~ "height") ~>~ (h~-~b)$, or $"zoffset" ~<~ ~-b$, or $("zoffset" ~+~ "depth") ~>~ (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 border width of the texture image being modified. Note that $w$, $h$, and $d$ include twice the border width.

GGLL__IINNVVAALLIIDD__VVAALLUUEE is generated if _w_i_d_t_h, _h_e_i_g_h_t, or _d_e_p_t_h is less than 0.

GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _f_o_r_m_a_t is not an accepted constant.

GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _t_y_p_e is not a type constant.

GGLL__IINNVVAALLIIDD__EENNUUMM is generated if _t_y_p_e is GGLL__BBIITTMMAAPP and _f_o_r_m_a_t is not GGLL__CCOOLLOORR__IINNDDEEXX.

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

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if _t_y_p_e is one of GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__33__33__22, GGLL__UUNNSSIIGGNNEEDD__BBYYTTEE__22__33__33__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55, or GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__66__55__RREEVV and _f_o_r_m_a_t is not GGLL__RRGGBB.

GGLL__IINNVVAALLIIDD__OOPPEERRAATTIIOONN is generated if _t_y_p_e is one of GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__44__44__44__44__RREEVV, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__55__55__55__11, GGLL__UUNNSSIIGGNNEEDD__SSHHOORRTT__11__55__55__55__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88, GGLL__UUNNSSIIGGNNEEDD__IINNTT__88__88__88__88__RREEVV, GGLL__UUNNSSIIGGNNEEDD__IINNTT__1100__1100__1100__22, or GGLL__UUNNSSIIGGNNEEDD__IINNTT__22__1100__1100__1100__RREEVV and _f_o_r_m_a_t is neither GGLL__RRGGBBAA nor GGLL__BBGGRRAA.

ASSOCIATED GETS

ggllGGeettTTeexxIImmaaggee
ggllIIssEEnnaabblleedd with argument GGLL__TTEEXXTTUURREE__33DD

SEE ALSO

ggllAAccttiivveeTTeexxttuurreeAARRBB((33GG)), ggllCCooppyyTTeexxIImmaaggee11DD((33GG)), ggllCCooppyyTTeexxIImmaaggee22DD((33GG)), ggllCCooppyyTTeexxSSuubbIImmaaggee11DD((33GG)), ggllCCooppyyTTeexxSSuubbIImmaaggee22DD((33GG)), ggllCCooppyyTTeexxSSuubbIImmaaggee33DD((33GG)), ggllDDrraawwPPiixxeellss((33GG)), ggllPPiixxeellSSttoorree((33GG)), ggllPPiixxeellTTrraannssffeerr((33GG)), ggllTTeexxEEnnvv((33GG)), ggllTTeexxGGeenn((33GG)), ggllTTeexxIImmaaggee11DD((33GG)), ggllTTeexxIImmaaggee22DD((33GG)), ggllTTeexxIImmaaggee33DD((33GG)), ggllTTeexxSSuubbIImmaaggee11DD((33GG)), ggllTTeexxSSuubbIImmaaggee22DD((33GG)), ggllTTeexxPPaarraammeetteerr((33GG))