1Name 2 3 EXT_subtexture 4 5Name Strings 6 7 GL_EXT_subtexture 8 9Version 10 11 $Date: 1995/10/03 05:39:55 $ $Revision: 1.17 $ 12 13Number 14 15 9 16 17Dependencies 18 19 EXT_abgr affects the definition of this extension 20 EXT_texture is required 21 EXT_texture3D affects the definition of this extension 22 23Overview 24 25 This extension allows a contiguous portion of an already-existing 26 texture image to be redefined, without affecting the remaining portion 27 of the image, or any of the other state that describe the texture. No 28 provision is made to query a subregion of a texture. 29 30 Semantics for null image pointers are defined for TexImage1D, 31 TexImage2D, and TexImage3DEXT. Null image pointers can be used by 32 applications to effectively support texture arrays whose dimensions 33 are not a power of 2. 34 35New Procedures and Functions 36 37 void TexSubImage1DEXT(enum target, 38 int level, 39 int xoffset, 40 sizei width, 41 enum format, 42 enum type, 43 const void* pixels); 44 45 void TexSubImage2DEXT(enum target, 46 int level, 47 int xoffset, 48 int yoffset, 49 sizei width, 50 sizei height, 51 enum format, 52 enum type, 53 const void* pixels); 54 55 void TexSubImage3DEXT(enum target, 56 int level, 57 int xoffset, 58 int yoffset, 59 int zoffset, 60 sizei width, 61 sizei height, 62 sizei depth, 63 enum format, 64 enum type, 65 const void* pixels); 66 67New Tokens 68 69 None 70 71Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation) 72 73 None 74 75Additions to Chapter 3 of the 1.0 Specification (Rasterization) 76 77 This extension makes no changes or additions to the texture operations 78 defined in the GL Specification. Its sole purpose is to extend the 79 semantics of texture specification. 80 81 TexSubImage1DEXT, TexSubImage2DEXT, and TexSubImage3DEXT redefine a 82 contiguous subregion of an existing texture image. Their <target> 83 parameters must be TEXTURE_1D, TEXTURE_2D, and TEXTURE_3D_EXT 84 respectively. (The proxy targets defined by EXT_texture are not 85 accepted by the subtexture commands.) <level>, <width>, <height>, 86 <depth>, <format>, <type>, and <pixels> correspond precisely to the 87 corresponding arguments of TexImage1D, TexImage2D, and TexImage3DEXT. 88 <xoffset>, <yoffset>, and <zoffset> specify texel offsets in the x, y, 89 and z directions within the texture array being modified. The new 90 image replaces the portion of the texture array indexed with 91 92 xoffset <= i < (xoffset + width), 93 yoffset <= j < (yoffset + height), 94 zoffset <= k < (zoffset + depth), 95 96 where i, j, and k are indexes as described in Figure 3.10 of the GL 97 Specification. It is an error for this region to include any texels 98 outside the range of the texture array as it was originally specified. 99 Specifically, the error INVALID_VALUE results if any of the following 100 conditions are met: 101 102 xoffset < -TEXTURE_BORDER 103 (xoffset + width) > (TEXTURE_WIDTH - TEXTURE_BORDER) 104 yoffset < -TEXTURE_BORDER 105 (yoffset + height) > (TEXTURE_HEIGHT - TEXTURE_BORDER) 106 zoffset < -TEXTURE_BORDER 107 (zoffset + depth) > (TEXTURE_DEPTH_EXT - TEXTURE_BORDER) 108 109 and TEXTURE_WIDTH, TEXTURE_HEIGHT, TEXTURE_DEPTH_EXT, and TEXTURE_BORDER 110 are the state values of the texture array that is being modified. Note 111 that TEXTURE_WIDTH, TEXTURE_HEIGHT, and TEXTURE_DEPTH_EXT include twice 112 the border width. 113 114 It is not an error to specify a subtexture with zero width, height, or 115 depth. Such a specification has no effect, however. 116 117 Counting from zero, each Nth pixel is assigned internal integer 118 coordinates [i,j,k], where 119 120 i = xoffset + (N mod width), 1D, 2D, and 3D textures 121 122 j = yoffset + ((N div width) mod height), 2D and 3D textures only 123 124 k = zoffset + ((N div (width * height)) mod depth), 3D textures only 125 126 and the div operator performs integer division with truncation. 127 128 Null images 129 ----------- 130 131 It is sometimes useful to define the parameters of a texture image 132 without actually initializing the contents of that image. In 133 particular, this capability is expected to be used in conjunction with 134 the TexSubImage commands that are defined in this extension. If 135 EXT_subtexture is implemented, and TexImage1D, TexImage2D, or 136 TexImage3DEXT is called with <pixels> equal to the null pointer 137 (a pointer to location zero in the C language), then the specified 138 texture is created as it would otherwise be, but no pixels are 139 processed, so the contents of the resulting texture image are undefined. 140 It is permissible to use such an uninitialized texture image, the 141 resulting color buffer contents being undefined only due to the random 142 color values of the texture image. 143 144Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations 145and the Framebuffer) 146 147 None 148 149Additions to Chapter 5 of the 1.0 Specification (Special Functions) 150 151 None 152 153Additions to Chapter 6 of the 1.0 Specification (State and State Requests) 154 155 None. No provision is made to query a subregion of a texture image. 156 157Additions to the GLX Specification 158 159 None 160 161GLX Protocol 162 163 Several new GL rendering commands are added. All of these commands have pixel 164 data; thus they are sent to the server either as part of a glXRender request or 165 a glXRenderLarge request: 166 167 TexSubImage1DEXT 168 2 60+n+p rendering command length 169 2 4099 170 1 BOOL swap_bytes 171 1 BOOL lsb_first 172 2 unused 173 4 CARD32 row_length 174 4 CARD32 skip_rows 175 4 CARD32 skip_pixels 176 4 CARD32 alignment 177 4 ENUM target 178 4 INT32 level 179 4 INT32 xoffset 180 4 INT32 yoffset 181 4 INT32 width 182 4 INT32 height 183 4 ENUM format 184 4 ENUM type 185 4 CARD32 unused 186 n LISTofBYTE image 187 p unused, p=pad(n) 188 189 If the command is encoded in a glXRenderLarge request, the command 190 opcode and command length fields above are expanded to 4 bytes each: 191 192 4 64+n+p rendering command length 193 4 4099 rendering command opcode 194 195 If <width> < 0, <format> is invalid or <type> is invalid, then the command is 196 erroneous and n=0. The <yoffset> and <height> parameters in this request are 197 ignored. 198 199 The structure of <pixels> is described in Appendix A of the GLX Protocol 200 Specification, "Pixel Data", using the parameters <swap_bytes>, <lsb_first>, 201 <row_length>, <skip_rows>, <skip_pixels>, <alignment>, <width>, <format>, and 202 <type> as given in the request and height = 1. 203 204 205 TexSubImage2DEXT 206 2 60+n+p rendering command length 207 2 4100 rendering command opcode 208 1 BOOL swap_bytes 209 1 BOOL lsb_first 210 2 unused 211 4 CARD32 row_length 212 4 CARD32 skip_rows 213 4 CARD32 skip_pixels 214 4 CARD32 alignment 215 4 ENUM target 216 4 INT32 level 217 4 INT32 xoffset 218 4 INT32 yoffset 219 4 INT32 width 220 4 INT32 height 221 4 ENUM format 222 4 ENUM type 223 4 CARD32 unused 224 n LISTofBYTE image 225 p unused, p=pad(n) 226 227 If the command is encoded in a glXRenderLarge request, the command 228 opcode and command length fields above are expanded to 4 bytes each: 229 230 4 64+n+p rendering command length 231 4 4100 rendering command opcode 232 233 If <width> < 0, <height> < 0, <format> is invalid or <type> is invalid, then 234 the command is erroneous and n=0. 235 236 The structure of <pixels> is described in Appendix A of the GLX Protocol 237 Specification, "Pixel Data", using the parameters <swap_bytes>, <lsb_first>, 238 <row_length>, <skip_rows>, <skip_pixels>, <alignment>, <width>, <height>, 239 <format>, and <type> as given in the request. 240 241 242 TexSubImage3DEXT 243 2 88+n+p rendering command length 244 2 4115 rendering command opcode 245 1 BOOL swap_bytes 246 1 BOOL lsb_first 247 2 unused 248 4 CARD32 row_length 249 4 CARD32 image_height 250 4 CARD32 image_depth 251 4 CARD32 skip_rows 252 4 CARD32 skip_images 253 4 CARD32 skip_volumes 254 4 CARD32 skip_pixels 255 4 CARD32 alignment 256 4 ENUM target 257 4 INT32 level 258 4 INT32 xoffset 259 4 INT32 yoffset 260 4 INT32 zoffset 261 4 INT32 woffset 262 4 INT32 width 263 4 INT32 height 264 4 INT32 depth 265 4 INT32 size4d 266 4 ENUM format 267 4 ENUM type 268 4 CARD32 unused 269 n LISTofBYTE image 270 p unused, p=pad(n) 271 272 If the command is encoded in a glXRenderLarge request, the command 273 opcode and command length fields above are expanded to 4 bytes each: 274 275 4 92+n+p rendering command length 276 4 4115 rendering command opcode 277 278 If <width> < 0, <height> < 0, <depth> < 0, <format> is invalid or <type> is 279 invalid, then the command is erroneous and n=0. The <woffset>, <size4d>, 280 <image_depth>, and <skip_volumes> parameters in this request are ignored. 281 282 <pixels> is arranged as a sequence of adjacent rectangles. Each rectangle is a 283 2-dimensional image, whose structure is determined by the image height and the 284 parameters <swap_bytes>, <lsb_first>, <row_length>, <skip_rows>, <skip_pixels>, 285 <alignment>, <width>, <format>, and <type> given in the request. If <image_height> 286 is not positive then the number of rows (i.e., the image height) is <height>; 287 otherwise the number of rows is <image_height>. 288 289 <skip_images> allows a sub-volume of the 3-dimensional image to be selected. 290 If <skip_images> is positive, then the pointer is advanced by <skip_images> 291 times the number of elements in one 2-dimensional image. Then <depth> 292 2-dimensional images are read, each having a subimage extracted in the 293 manner described in Appendix A of the GLX Protocol Specification. 294 295Dependencies on EXT_abgr 296 297 If EXT_abgr is supported, the <format> parameters of TexSubImage1DEXT, 298 TexSubImage2DEXT, and TexSubImage3DEXT accept ABGR_EXT. Otherwise they 299 do not. 300 301Dependencies on EXT_texture 302 303 EXT_texture is required. This extension builds on the notion of 304 internal image format, which is defined by EXT_texture. 305 306Dependencies on EXT_texture3D 307 308 If EXT_texture3D is not supported, then TexSubImage3DEXT is not defined 309 by this extension. In this case, none of the description of 310 3-dimensional texture mapping in this extension document is valid. The 311 descriptions of TexSubImage1DEXT and TexSubImage2DEXT remain valid, 312 however. 313 314Errors 315 316 INVALID_ENUM is generated by TexSubImage1DEXT if its <target> parameter 317 is not TEXTURE_1D. 318 319 INVALID_ENUM is generated by TexSubImage2DEXT if its <target> parameter 320 is not TEXTURE_2D. 321 322 INVALID_ENUM is generated by TexSubImage3DEXT if its <target> parameter 323 is not TEXTURE_3D_EXT. 324 325 INVALID_OPERATION is generated by TexSubImage1DEXT if the specified 326 texture array has not been defined by a previous TexImage1D operation. 327 328 INVALID_OPERATION is generated by TexSubImage2DEXT if the specified 329 texture array has not been defined by a previous TexImage2D operation. 330 331 INVALID_OPERATION is generated by TexSubImage3DEXT if the specified 332 texture array has not been defined by a previous TexImage3DEXT 333 operation. 334 335 INVALID_VALUE is generated if <level> is less than zero 336 337 INVALID_VALUE is generated if <width>, <height>, or <depth> is negative. 338 339 INVALID_VALUE is generated if <xoffset>, <yoffset>, or <zoffset> is 340 less than -TEXTURE_BORDER. 341 342 INVALID_VALUE is generated if 343 (xoffset + width) > (TEXTURE_WIDTH - TEXTURE_BORDER), or if 344 (yoffset + height) > (TEXTURE_HEIGHT - TEXTURE_BORDER), or if 345 (zoffset + depth) > (TEXTURE_DEPTH_EXT - TEXTURE_BORDER). 346 347 INVALID_ENUM is generated if <format> is not COLOR_INDEX, RED, GREEN, 348 BLUE, ALPHA, RGB, RGBA, LUMINANCE, or LUMINANCE_ALPHA (or ABGR_EXT if 349 EXT_abgr is supported). 350 351 INVALID_ENUM is generated if <type> is not UNSIGNED_BYTE, BYTE, 352 UNSIGNED_SHORT, SHORT, UNSIGNED_INT, INT, or FLOAT. 353 354 INVALID_OPERATION is generated if TexSubImage1DEXT, TexSubImage2DEXT, 355 or TexSubImage3DEXT is called between execution of Begin and the 356 corresponding execution of End. 357 358New State 359 360 None 361 362New Implementation Dependent State 363 364 None 365