--- name: "glTexSubImage2D" section: "3x" platform: "linux" package: "xlibmesa-gl-dev" version: "4.3.0.dfsg.1-14sarge7" release: "Debian 3.1 (Sarge)" platforms: ["linux"] url: "https://new.carta.tech/glTexSubImage2D" --- # glTexSubImage2D(3x) specify a two-dimensional texture subimage ## NAME **glTexSubImage2D** - specify a two-dimensional texture subimage ## C SPECIFICATION void **glTexSubImage2D**( GLenum *target*, ``` GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLsizei height, GLenum format, GLenum type, const GLvoid *pixels ) ``` delim $$ ## PARAMETERS - *target* Specifies the target texture. Must be **GL\_TEXTURE\_2D**. - *level* Specifies the level-of-detail number. Level 0 is the base image level. Level *n* is the *n*th mipmap reduction image. - *xoffset* Specifies a texel offset in the x direction within the texture array. - *yoffset* Specifies a texel offset in the y direction within the texture array. - *width* Specifies the width of the texture subimage. - *height* Specifies the height of the texture subimage. - *format* Specifies the of the pixel data. The following symbolic values are accepted: **GL\_COLOR\_INDEX**, **GL\_RED**, **GL\_GREEN**, **GL\_BLUE**, **GL\_ALPHA**, **GL\_RGB**, **GL\_BGR**, **GL\_RGBA**, **GL\_BGRA**, **GL\_LUMINANCE**, and **GL\_LUMINANCE\_ALPHA**. - *type* Specifies the data type of the pixel data. The following symbolic values are accepted: **GL\_UNSIGNED\_BYTE**, **GL\_BYTE**, **GL\_BITMAP**, **GL\_UNSIGNED\_SHORT**, **GL\_SHORT**, **GL\_UNSIGNED\_INT**, **GL\_INT**, **GL\_FLOAT**, **GL\_UNSIGNED\_BYTE\_3\_3\_2**, **GL\_UNSIGNED\_BYTE\_2\_3\_3\_REV**, **GL\_UNSIGNED\_SHORT\_5\_6\_5**, **GL\_UNSIGNED\_SHORT\_5\_6\_5\_REV**, **GL\_UNSIGNED\_SHORT\_4\_4\_4\_4**, **GL\_UNSIGNED\_SHORT\_4\_4\_4\_4\_REV**, **GL\_UNSIGNED\_SHORT\_5\_5\_5\_1**, **GL\_UNSIGNED\_SHORT\_1\_5\_5\_5\_REV**, **GL\_UNSIGNED\_INT\_8\_8\_8\_8**, **GL\_UNSIGNED\_INT\_8\_8\_8\_8\_REV**, **GL\_UNSIGNED\_INT\_10\_10\_10\_2**, and **GL\_UNSIGNED\_INT\_2\_10\_10\_10\_REV**. - *pixels* 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 two-dimensional texturing, call **glEnable** and **glDisable** with argument **GL\_TEXTURE\_2D**. **glTexSubImage2D** redefines a contiguous subregion of an existing two-dimensional texture image. The texels referenced by *pixels* replace the portion of the existing texture array with x indices *xoffset* and $"xoffset"~+~"width"~-~1$, inclusive, and y indices *yoffset* and $"yoffset"~+~"height"~-~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 or height, but such a specification has no effect. ## NOTES **glTexSubImage2D** is available only if the GL version is 1.1 or greater. Texturing has no effect in color index mode. **glPixelStore** and **glPixelTransfer** modes affect texture images in exactly the way they affect **glDrawPixels**. Formats **GL\_BGR**, and **GL\_BGRA** and types **GL\_UNSIGNED\_BYTE\_3\_3\_2**, **GL\_UNSIGNED\_BYTE\_2\_3\_3\_REV**, **GL\_UNSIGNED\_SHORT\_5\_6\_5**, **GL\_UNSIGNED\_SHORT\_5\_6\_5\_REV**, **GL\_UNSIGNED\_SHORT\_4\_4\_4\_4**, **GL\_UNSIGNED\_SHORT\_4\_4\_4\_4\_REV**, **GL\_UNSIGNED\_SHORT\_5\_5\_5\_1**, **GL\_UNSIGNED\_SHORT\_1\_5\_5\_5\_REV**, **GL\_UNSIGNED\_INT\_8\_8\_8\_8**, **GL\_UNSIGNED\_INT\_8\_8\_8\_8\_REV**, **GL\_UNSIGNED\_INT\_10\_10\_10\_2**, and **GL\_UNSIGNED\_INT\_2\_10\_10\_10\_REV** are available only if the GL version is 1.2 or greater. When the **GL\_ARB\_multitexture** extension is supported, **glTexSubImage2D** specifies a two-dimensional sub texture for the current texture unit, specified with **glActiveTextureARB**. When the **GL\_ARB\_imaging** extension is supported, the RGBA components specified in *pixels* may be processed by the imaging pipeline. See **glTexImage1D** for specific details. ## ERRORS **GL\_INVALID\_ENUM** is generated if *target* is not **GL\_TEXTURE\_2D**. **GL\_INVALID\_OPERATION** is generated if the texture array has not been defined by a previous **glTexImage2D** operation. **GL\_INVALID\_VALUE** is generated if *level* is less than 0. **GL\_INVALID\_VALUE** may be generated if *level* is greater than $log sub 2$*max*, where *max* is the returned value of **GL\_MAX\_TEXTURE\_SIZE**. **GL\_INVALID\_VALUE** is generated if $"xoffset" ~\<~ ~-b$, $("xoffset"~+~"width") ~\>~ (w~-~b)$, $"yoffset" ~\<~ ~-b$, or $("yoffset" ~+~ "height") ~\>~ (h~-~b)$, where $w$ is the **GL\_TEXTURE\_WIDTH**, $h$ is the **GL\_TEXTURE\_HEIGHT**, and $b$ is the border width of the texture image being modified. Note that $w$ and $h$ include twice the border width. **GL\_INVALID\_VALUE** is generated if *width* or *height* is less than 0. **GL\_INVALID\_ENUM** is generated if *format* is not an accepted\ constant. **GL\_INVALID\_ENUM** is generated if *type* is not a type constant. **GL\_INVALID\_ENUM** is generated if *type* is **GL\_BITMAP** and *format* is not **GL\_COLOR\_INDEX**. **GL\_INVALID\_OPERATION** is generated if **glTexSubImage2D** is executed between the execution of **glBegin** and the corresponding execution of **glEnd**. **GL\_INVALID\_OPERATION** is generated if *type* is one of **GL\_UNSIGNED\_BYTE\_3\_3\_2**, **GL\_UNSIGNED\_BYTE\_2\_3\_3\_REV**, **GL\_UNSIGNED\_SHORT\_5\_6\_5**, or **GL\_UNSIGNED\_SHORT\_5\_6\_5\_REV** and *format* is not **GL\_RGB**. **GL\_INVALID\_OPERATION** is generated if *type* is one of **GL\_UNSIGNED\_SHORT\_4\_4\_4\_4**, **GL\_UNSIGNED\_SHORT\_4\_4\_4\_4\_REV**, **GL\_UNSIGNED\_SHORT\_5\_5\_5\_1**, **GL\_UNSIGNED\_SHORT\_1\_5\_5\_5\_REV**, **GL\_UNSIGNED\_INT\_8\_8\_8\_8**, **GL\_UNSIGNED\_INT\_8\_8\_8\_8\_REV**, **GL\_UNSIGNED\_INT\_10\_10\_10\_2**, or **GL\_UNSIGNED\_INT\_2\_10\_10\_10\_REV** and *format* is neither **GL\_RGBA** nor **GL\_BGRA**. ## ASSOCIATED GETS **glGetTexImage**\ **glIsEnabled** with argument **GL\_TEXTURE\_2D** ## SEE ALSO **glActiveTextureARB(3G)**, **glCopyTexImage1D(3G)**, **glCopyTexImage2D(3G)**, **glCopyTexSubImage1D(3G)**, **glCopyTexSubImage2D(3G)**, **glCopyTexSubImage3D(3G)**, **glDrawPixels(3G)**, **glPixelStore(3G)**, **glPixelTransfer(3G)**, **glTexEnv(3G)**, **glTexGen(3G)**, **glTexImage1D(3G)**, **glTexImage2D(3G)**, **glTexImage3D(3G)**, **glTexSubImage1D(3G)**, **glTexSubImage3D(3G)**, **glTexParameter(3G)**