1Name 2 3 EXT_texture_object 4 5Name Strings 6 7 GL_EXT_texture_object 8 9Version 10 11 $Date: 1995/10/03 05:39:56 $ $Revision: 1.27 $ 12 13Number 14 15 20 16 17Dependencies 18 19 EXT_texture3D affects the definition of this extension 20 21Overview 22 23 This extension introduces named texture objects. The only way to name 24 a texture in GL 1.0 is by defining it as a single display list. Because 25 display lists cannot be edited, these objects are static. Yet it is 26 important to be able to change the images and parameters of a texture. 27 28Issues 29 30 * Should the dimensions of a texture object be static once they are 31 changed from zero? This might simplify the management of texture 32 memory. What about other properties of a texture object? 33 34 No. 35 36Reasoning 37 38 * Previous proposals overloaded the <target> parameter of many Tex 39 commands with texture object names, as well as the original 40 enumerated values. This proposal eliminated such overloading, 41 choosing instead to require an application to bind a texture object, 42 and then operate on it through the binding reference. If this 43 constraint ultimately proves to be unacceptable, we can always 44 extend the extension with additional binding points for editing and 45 querying only, but if we expect to do this, we might choose to bite 46 the bullet and overload the <target> parameters now. 47 48 * Commands to directly set the priority of a texture object and to 49 query the resident status of a texture object are included. I feel 50 that binding a texture object would be an unacceptable burden for 51 these management operations. These commands also allow queries and 52 operations on lists of texture objects, which should improve 53 efficiency. 54 55 * GenTexturesEXT does not return a success/failure boolean because 56 it should never fail in practice. 57 58New Procedures and Functions 59 60 void GenTexturesEXT(sizei n, 61 uint* textures); 62 63 void DeleteTexturesEXT(sizei n, 64 const uint* textures); 65 66 void BindTextureEXT(enum target, 67 uint texture); 68 69 void PrioritizeTexturesEXT(sizei n, 70 const uint* textures, 71 const clampf* priorities); 72 73 boolean AreTexturesResidentEXT(sizei n, 74 const uint* textures, 75 boolean* residences); 76 77 boolean IsTextureEXT(uint texture); 78 79New Tokens 80 81 Accepted by the <pname> parameters of TexParameteri, TexParameterf, 82 TexParameteriv, TexParameterfv, GetTexParameteriv, and GetTexParameterfv: 83 84 TEXTURE_PRIORITY_EXT 0x8066 85 86 Accepted by the <pname> parameters of GetTexParameteriv and 87 GetTexParameterfv: 88 89 TEXTURE_RESIDENT_EXT 0x8067 90 91 Accepted by the <pname> parameters of GetBooleanv, GetIntegerv, 92 GetFloatv, and GetDoublev: 93 94 TEXTURE_1D_BINDING_EXT 0x8068 95 TEXTURE_2D_BINDING_EXT 0x8069 96 TEXTURE_3D_BINDING_EXT 0x806A 97 98Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation) 99 100 None 101 102Additions to Chapter 3 of the 1.0 Specification (Rasterization) 103 104 Add the following discussion to section 3.8 (Texturing). In addition 105 to the default textures TEXTURE_1D, TEXTURE_2D, and TEXTURE_3D_EXT, it 106 is possible to create named 1, 2, and 3-dimensional texture objects. 107 The name space for texture objects is the unsigned integers, with zero 108 reserved by the GL. 109 110 A texture object is created by binding an unused name to TEXTURE_1D, 111 TEXTURE_2D, or TEXTURE_3D_EXT. This binding is accomplished by calling 112 BindTextureEXT with <target> set to TEXTURE_1D, TEXTURE_2D, or 113 TEXTURE_3D_EXT, and <texture> set to the name of the new texture object. 114 When a texture object is bound to a target, the previous binding for 115 that target is automatically broken. 116 117 When a texture object is first bound it takes the dimensionality of its 118 target. Thus, a texture object first bound to TEXTURE_1D is 119 1-dimensional; a texture object first bound to TEXTURE_2D is 120 2-dimensional, and a texture object first bound to TEXTURE_3D_EXT is 121 3-dimensional. The state of a 1-dimensional texture object 122 immediately after it is first bound is equivalent to the state of the 123 default TEXTURE_1D at GL initialization. Likewise, the state of a 124 2-dimensional or 3-dimensional texture object immediately after it is 125 first bound is equivalent to the state of the default TEXTURE_2D or 126 TEXTURE_3D_EXT at GL initialization. Subsequent bindings of a texture 127 object have no effect on its state. The error INVALID_OPERATION is 128 generated if an attempt is made to bind a texture object to a target of 129 different dimensionality. 130 131 While a texture object is bound, GL operations on the target to which it 132 is bound affect the bound texture object, and queries of the target to 133 which it is bound return state from the bound texture object. If 134 texture mapping of the dimensionality of the target to which a texture 135 object is bound is active, the bound texture object is used. 136 137 By default when an OpenGL context is created, TEXTURE_1D, TEXTURE_2D, 138 and TEXTURE_3D_EXT have 1, 2, and 3-dimensional textures associated 139 with them. In order that access to these default textures not be 140 lost, this extension treats them as though their names were all zero. 141 Thus the default 1-dimensional texture is operated on, queried, and 142 applied as TEXTURE_1D while zero is bound to TEXTURE_1D. Likewise, 143 the default 2-dimensional texture is operated on, queried, and applied 144 as TEXTURE_2D while zero is bound to TEXTURE_2D, and the default 145 3-dimensional texture is operated on, queried, and applied as 146 TEXTURE_3D_EXT while zero is bound to TEXTURE_3D_EXT. 147 148 Texture objects are deleted by calling DeleteTexturesEXT with <textures> 149 pointing to a list of <n> names of texture object to be deleted. After 150 a texture object is deleted, it has no contents or dimensionality, and 151 its name is freed. If a texture object that is currently bound is 152 deleted, the binding reverts to zero. DeleteTexturesEXT ignores names 153 that do not correspond to textures objects, including zero. 154 155 GenTexturesEXT returns <n> texture object names in <textures>. These 156 names are chosen in an unspecified manner, the only condition being that 157 only names that were not in use immediately prior to the call to 158 GenTexturesEXT are considered. Names returned by GenTexturesEXT are 159 marked as used (so that they are not returned by subsequent calls to 160 GenTexturesEXT), but they are associated with a texture object only 161 after they are first bound (just as if the name were unused). 162 163 An implementation may choose to establish a working set of texture 164 objects on which binding operations are performed with higher 165 performance. A texture object that is currently being treated as a 166 part of the working set is said to be resident. AreTexturesResidentEXT 167 returns TRUE if all of the <n> texture objects named in <textures> are 168 resident, FALSE otherwise. If FALSE is returned, the residence of each 169 texture object is returned in <residences>. Otherwise the contents of 170 the <residences> array are not changed. If any of the names in 171 <textures> is not the name of a texture object, FALSE is returned, the 172 error INVALID_VALUE is generated, and the contents of <residences> are 173 indeterminate. The resident status of a single bound texture object 174 can also be queried by calling GetTexParameteriv or GetTexParameterfv 175 with <target> set to the target to which the texture object is bound, 176 and <pname> set to TEXTURE_RESIDENT_EXT. This is the only way that the 177 resident status of a default texture can be queried. 178 179 Applications guide the OpenGL implementation in determining which 180 texture objects should be resident by specifying a priority for each 181 texture object. PrioritizeTexturesEXT sets the priorities of the <n> 182 texture objects in <textures> to the values in <priorities>. Each 183 priority value is clamped to the range [0.0, 1.0] before it is 184 assigned. Zero indicates the lowest priority, and hence the least 185 likelihood of being resident. One indicates the highest priority, and 186 hence the greatest likelihood of being resident. The priority of a 187 single bound texture object can also be changed by calling 188 TexParameteri, TexParameterf, TexParameteriv, or TexParameterfv with 189 <target> set to the target to which the texture object is bound, <pname> 190 set to TEXTURE_PRIORITY_EXT, and <param> or <params> specifying the new 191 priority value (which is clamped to [0.0,1.0] before being assigned). 192 This is the only way that the priority of a default texture can be 193 specified. (PrioritizeTexturesEXT silently ignores attempts to 194 prioritize nontextures, and texture zero.) 195 196Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations 197and the Frame Buffer) 198 199 None 200 201Additions to Chapter 5 of the 1.0 Specification (Special Functions) 202 203 BindTextureEXT and PrioritizeTexturesEXT are included in display lists. 204 All other commands defined by this extension are not included in display 205 lists. 206 207Additions to Chapter 6 of the 1.0 Specification (State and State Requests) 208 209 IsTextureEXT returns TRUE if <texture> is the name of a valid texture 210 object. If <texture> is zero, or is a non-zero value that is not the 211 name of a texture object, or if an error condition occurs, IsTextureEXT 212 returns FALSE. 213 214 Because the query values of TEXTURE_1D, TEXTURE_2D, and TEXTURE_3D_EXT 215 are already defined as booleans indicating whether these textures are 216 enabled or disabled, another mechanism is required to query the 217 binding associated with each of these texture targets. The name 218 of the texture object currently bound to TEXTURE_1D is returned in 219 <params> when GetIntegerv is called with <pname> set to 220 TEXTURE_1D_BINDING_EXT. If no texture object is currently bound to 221 TEXTURE_1D, zero is returned. Likewise, the name of the texture object 222 bound to TEXTURE_2D or TEXTURE_3D_EXT is returned in <params> when 223 GetIntegerv is called with <pname> set to TEXTURE_2D_BINDING_EXT or 224 TEXTURE_3D_BINDING_EXT. If no texture object is currently bound to 225 TEXTURE_2D or to TEXTURE_3D_EXT, zero is returned. 226 227 A texture object comprises the image arrays, priority, border color, 228 filter modes, and wrap modes that are associated with that object. More 229 explicitly, the state list 230 231 TEXTURE, 232 TEXTURE_PRIORITY_EXT 233 TEXTURE_RED_SIZE, 234 TEXTURE_GREEN_SIZE, 235 TEXTURE_BLUE_SIZE, 236 TEXTURE_ALPHA_SIZE, 237 TEXTURE_LUMINANCE_SIZE, 238 TEXTURE_INTENSITY_SIZE, 239 TEXTURE_WIDTH, 240 TEXTURE_HEIGHT, 241 TEXTURE_DEPTH_EXT, 242 TEXTURE_BORDER, 243 TEXTURE_COMPONENTS, 244 TEXTURE_BORDER_COLOR, 245 TEXTURE_MIN_FILTER, 246 TEXTURE_MAG_FILTER, 247 TEXTURE_WRAP_S, 248 TEXTURE_WRAP_T, 249 TEXTURE_WRAP_R_EXT 250 251 composes a single texture object. 252 253 When PushAttrib is called with TEXTURE_BIT enabled, the priorities, 254 border colors, filter modes, and wrap modes of the currently bound 255 texture objects are pushed, as well as the current texture bindings and 256 enables. When an attribute set that includes texture information is 257 popped, the bindings and enables are first restored to their pushed 258 values, then the bound texture objects have their priorities, border 259 colors, filter modes, and wrap modes restored to their pushed values. 260 261Additions to the GLX Specification 262 263 Texture objects are shared between GLX rendering contexts if and only 264 if the rendering contexts share display lists. No change is made to 265 the GLX API. 266 267GLX Protocol 268 269 Six new GL commands are added. 270 271 The following rendering command is sent to the server as part of a 272 glXRender request: 273 274 BindTextureEXT 275 2 12 rendering command length 276 2 4117 rendering command opcode 277 4 ENUM target 278 4 CARD32 texture 279 280 The following rendering command can be sent to the server as part of a 281 glXRender request or as part of a glXRenderLarge request: 282 283 PrioritizeTexturesEXT 284 2 8+(n*8) rendering command length 285 2 4118 rendering command opcode 286 4 INT32 n 287 n*4 LISTofCARD32 textures 288 n*4 LISTofFLOAT32 priorities 289 290 If the command is encoded in a glXRenderLarge request, the 291 command opcode and command length fields above are expanded to 292 4 bytes each: 293 294 4 12+(n*8) rendering command length 295 4 4118 rendering command opcode 296 297 The remaining commands are non-rendering commands. These commands are 298 sent separately (i.e., not as part of a glXRender or glXRenderLarge 299 request), using either the glXVendorPrivate request or the 300 glXVendorPrivateWithReply request: 301 302 DeleteTexturesEXT 303 1 CARD8 opcode (X assigned) 304 1 16 GLX opcode (glXVendorPrivate) 305 2 4+n request length 306 4 12 vendor specific opcode 307 4 GLX_CONTEXT_TAG context tag 308 4 INT32 n 309 n*4 CARD32 textures 310 311 GenTexturesEXT 312 1 CARD8 opcode (X assigned) 313 1 17 GLX opcode (glXVendorPrivateWithReply) 314 2 4 request length 315 4 13 vendor specific opcode 316 4 GLX_CONTEXT_TAG context tag 317 4 INT32 n 318 => 319 1 1 reply 320 1 unused 321 2 CARD16 sequence number 322 4 n reply length 323 24 unused 324 4*n LISTofCARD32 textures 325 326 AreTexturesResidentEXT 327 1 CARD8 opcode (X assigned) 328 1 17 GLX opcode (glXVendorPrivateWithReply) 329 2 4+n request length 330 4 11 vendor specific opcode 331 4 GLX_CONTEXT_TAG context tag 332 4 INT32 n 333 4*n LISTofCARD32 textures 334 => 335 1 1 reply 336 1 unused 337 2 CARD16 sequence number 338 4 (n+p)/4 reply length 339 4 BOOL32 return_value 340 20 unused 341 n LISTofBOOL residences 342 p unused, p=pad(n) 343 344 IsTextureEXT 345 1 CARD8 opcode (X assigned) 346 1 17 GLX opcode (glXVendorPrivateWithReply) 347 2 4 request length 348 4 14 vendor specific opcode 349 4 GLX_CONTEXT_TAG context tag 350 4 CARD32 textures 351 => 352 1 1 reply 353 1 unused 354 2 CARD16 sequence number 355 4 0 reply length 356 4 BOOL32 return_value 357 20 unused 358 359Dependencies on EXT_texture3D 360 361 If EXT_texture3D is not supported, then all references to 3D textures 362 in this specification are invalid. 363 364Errors 365 366 INVALID_VALUE is generated if GenTexturesEXT parameter <n> is negative. 367 368 INVALID_VALUE is generated if DeleteTexturesEXT parameter <n> is 369 negative. 370 371 INVALID_ENUM is generated if BindTextureEXT parameter <target> is not 372 TEXTURE_1D, TEXTURE_2D, or TEXTURE_3D_EXT. 373 374 INVALID_OPERATION is generated if BindTextureEXT parameter <target> is 375 TEXTURE_1D, and parameter <texture> is the name of a 2-dimensional or 376 3-dimensional texture object. 377 378 INVALID_OPERATION is generated if BindTextureEXT parameter <target> is 379 TEXTURE_2D, and parameter <texture> is the name of a 1-dimensional or 380 3-dimensional texture object. 381 382 INVALID_OPERATION is generated if BindTextureEXT parameter <target> is 383 TEXTURE_3D_EXT, and parameter <texture> is the name of a 1-dimensional 384 or 2-dimensional texture object. 385 386 INVALID_VALUE is generated if PrioritizeTexturesEXT parameter <n> 387 negative. 388 389 INVALID_VALUE is generated if AreTexturesResidentEXT parameter <n> 390 is negative. 391 392 INVALID_VALUE is generated by AreTexturesResidentEXT if any of the 393 names in <textures> is zero, or is not the name of a texture. 394 395 INVALID_OPERATION is generated if any of the commands defined in this 396 extension is executed between the execution of Begin and the 397 corresponding execution of End. 398 399New State 400 401 402 Get Value Get Command Type Initial Value Attribute 403 --------- ----------- ---- ------------- --------- 404 TEXTURE_1D IsEnabled B FALSE texture/enable 405 TEXTURE_2D IsEnabled B FALSE texture/enable 406 TEXTURE_3D_EXT IsEnabled B FALSE texture/enable 407 TEXTURE_1D_BINDING_EXT GetIntegerv Z+ 0 texture 408 TEXTURE_2D_BINDING_EXT GetIntegerv Z+ 0 texture 409 TEXTURE_3D_BINDING_EXT GetIntegerv Z+ 0 texture 410 TEXTURE_PRIORITY_EXT GetTexParameterfv n x Z+ 1 texture 411 TEXTURE_RESIDENT_EXT AreTexturesResidentEXT n x B unknown - 412 413 TEXTURE GetTexImage n x levels x I null - 414 TEXTURE_RED_SIZE_EXT GetTexLevelParameteriv n x levels x Z+ 0 - 415 TEXTURE_GREEN_SIZE_EXT GetTexLevelParameteriv n x levels x Z+ 0 - 416 TEXTURE_BLUE_SIZE_EXT GetTexLevelParameteriv n x levels x Z+ 0 - 417 TEXTURE_ALPHA_SIZE_EXT GetTexLevelParameteriv n x levels x Z+ 0 - 418 TEXTURE_LUMINANCE_SIZE_EXT GetTexLevelParameteriv n x levels x Z+ 0 - 419 TEXTURE_INTENSITY_SIZE_EXT GetTexLevelParameteriv n x levels x Z+ 0 - 420 TEXTURE_WIDTH GetTexLevelParameteriv n x levels x Z+ 0 - 421 TEXTURE_HEIGHT GetTexLevelParameteriv n x levels x Z+ 0 - 422 TEXTURE_DEPTH_EXT GetTexLevelParameteriv n x levels x Z+ 0 - 423 TEXTURE_4DSIZE_SGIS GetTexLevelParameteriv n x levels x Z+ 0 - 424 TEXTURE_BORDER GetTexLevelParameteriv n x levels x Z+ 0 - 425 TEXTURE_COMPONENTS (1D and 2D) GetTexLevelParameteriv n x levels x Z42 1 - 426 TEXTURE_COMPONENTS (3D and 4D) GetTexLevelParameteriv n x levels x Z38 LUMINANCE - 427 TEXTURE_BORDER_COLOR GetTexParameteriv n x C 0, 0, 0, 0 texture 428 TEXTURE_MIN_FILTER GetTexParameteriv n x Z7 NEAREST_MIPMAP_LINEAR texture 429 TEXTURE_MAG_FILTER GetTexParameteriv n x Z3 LINEAR texture 430 TEXTURE_WRAP_S GetTexParameteriv n x Z2 REPEAT texture 431 TEXTURE_WRAP_T GetTexParameteriv n x Z2 REPEAT texture 432 TEXTURE_WRAP_R_EXT GetTexParameteriv n x Z2 REPEAT texture 433 TEXTURE_WRAP_Q_SGIS GetTexParameteriv n x Z2 REPEAT texture 434 435New Implementation Dependent State 436 437 None 438