Name EXT_texture_object Name Strings GL_EXT_texture_object Version $Date: 1995/10/03 05:39:56 $ $Revision: 1.27 $ Number 20 Dependencies EXT_texture3D affects the definition of this extension Overview This extension introduces named texture objects. The only way to name a texture in GL 1.0 is by defining it as a single display list. Because display lists cannot be edited, these objects are static. Yet it is important to be able to change the images and parameters of a texture. Issues * Should the dimensions of a texture object be static once they are changed from zero? This might simplify the management of texture memory. What about other properties of a texture object? No. Reasoning * Previous proposals overloaded the parameter of many Tex commands with texture object names, as well as the original enumerated values. This proposal eliminated such overloading, choosing instead to require an application to bind a texture object, and then operate on it through the binding reference. If this constraint ultimately proves to be unacceptable, we can always extend the extension with additional binding points for editing and querying only, but if we expect to do this, we might choose to bite the bullet and overload the parameters now. * Commands to directly set the priority of a texture object and to query the resident status of a texture object are included. I feel that binding a texture object would be an unacceptable burden for these management operations. These commands also allow queries and operations on lists of texture objects, which should improve efficiency. * GenTexturesEXT does not return a success/failure boolean because it should never fail in practice. New Procedures and Functions void GenTexturesEXT(sizei n, uint* textures); void DeleteTexturesEXT(sizei n, const uint* textures); void BindTextureEXT(enum target, uint texture); void PrioritizeTexturesEXT(sizei n, const uint* textures, const clampf* priorities); boolean AreTexturesResidentEXT(sizei n, const uint* textures, boolean* residences); boolean IsTextureEXT(uint texture); New Tokens Accepted by the parameters of TexParameteri, TexParameterf, TexParameteriv, TexParameterfv, GetTexParameteriv, and GetTexParameterfv: TEXTURE_PRIORITY_EXT 0x8066 Accepted by the parameters of GetTexParameteriv and GetTexParameterfv: TEXTURE_RESIDENT_EXT 0x8067 Accepted by the parameters of GetBooleanv, GetIntegerv, GetFloatv, and GetDoublev: TEXTURE_1D_BINDING_EXT 0x8068 TEXTURE_2D_BINDING_EXT 0x8069 TEXTURE_3D_BINDING_EXT 0x806A Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation) None Additions to Chapter 3 of the 1.0 Specification (Rasterization) Add the following discussion to section 3.8 (Texturing). In addition to the default textures TEXTURE_1D, TEXTURE_2D, and TEXTURE_3D_EXT, it is possible to create named 1, 2, and 3-dimensional texture objects. The name space for texture objects is the unsigned integers, with zero reserved by the GL. A texture object is created by binding an unused name to TEXTURE_1D, TEXTURE_2D, or TEXTURE_3D_EXT. This binding is accomplished by calling BindTextureEXT with set to TEXTURE_1D, TEXTURE_2D, or TEXTURE_3D_EXT, and set to the name of the new texture object. When a texture object is bound to a target, the previous binding for that target is automatically broken. When a texture object is first bound it takes the dimensionality of its target. Thus, a texture object first bound to TEXTURE_1D is 1-dimensional; a texture object first bound to TEXTURE_2D is 2-dimensional, and a texture object first bound to TEXTURE_3D_EXT is 3-dimensional. The state of a 1-dimensional texture object immediately after it is first bound is equivalent to the state of the default TEXTURE_1D at GL initialization. Likewise, the state of a 2-dimensional or 3-dimensional texture object immediately after it is first bound is equivalent to the state of the default TEXTURE_2D or TEXTURE_3D_EXT at GL initialization. Subsequent bindings of a texture object have no effect on its state. The error INVALID_OPERATION is generated if an attempt is made to bind a texture object to a target of different dimensionality. While a texture object is bound, GL operations on the target to which it is bound affect the bound texture object, and queries of the target to which it is bound return state from the bound texture object. If texture mapping of the dimensionality of the target to which a texture object is bound is active, the bound texture object is used. By default when an OpenGL context is created, TEXTURE_1D, TEXTURE_2D, and TEXTURE_3D_EXT have 1, 2, and 3-dimensional textures associated with them. In order that access to these default textures not be lost, this extension treats them as though their names were all zero. Thus the default 1-dimensional texture is operated on, queried, and applied as TEXTURE_1D while zero is bound to TEXTURE_1D. Likewise, the default 2-dimensional texture is operated on, queried, and applied as TEXTURE_2D while zero is bound to TEXTURE_2D, and the default 3-dimensional texture is operated on, queried, and applied as TEXTURE_3D_EXT while zero is bound to TEXTURE_3D_EXT. Texture objects are deleted by calling DeleteTexturesEXT with pointing to a list of names of texture object to be deleted. After a texture object is deleted, it has no contents or dimensionality, and its name is freed. If a texture object that is currently bound is deleted, the binding reverts to zero. DeleteTexturesEXT ignores names that do not correspond to textures objects, including zero. GenTexturesEXT returns texture object names in . These names are chosen in an unspecified manner, the only condition being that only names that were not in use immediately prior to the call to GenTexturesEXT are considered. Names returned by GenTexturesEXT are marked as used (so that they are not returned by subsequent calls to GenTexturesEXT), but they are associated with a texture object only after they are first bound (just as if the name were unused). An implementation may choose to establish a working set of texture objects on which binding operations are performed with higher performance. A texture object that is currently being treated as a part of the working set is said to be resident. AreTexturesResidentEXT returns TRUE if all of the texture objects named in are resident, FALSE otherwise. If FALSE is returned, the residence of each texture object is returned in . Otherwise the contents of the array are not changed. If any of the names in is not the name of a texture object, FALSE is returned, the error INVALID_VALUE is generated, and the contents of are indeterminate. The resident status of a single bound texture object can also be queried by calling GetTexParameteriv or GetTexParameterfv with set to the target to which the texture object is bound, and set to TEXTURE_RESIDENT_EXT. This is the only way that the resident status of a default texture can be queried. Applications guide the OpenGL implementation in determining which texture objects should be resident by specifying a priority for each texture object. PrioritizeTexturesEXT sets the priorities of the texture objects in to the values in . Each priority value is clamped to the range [0.0, 1.0] before it is assigned. Zero indicates the lowest priority, and hence the least likelihood of being resident. One indicates the highest priority, and hence the greatest likelihood of being resident. The priority of a single bound texture object can also be changed by calling TexParameteri, TexParameterf, TexParameteriv, or TexParameterfv with set to the target to which the texture object is bound, set to TEXTURE_PRIORITY_EXT, and or specifying the new priority value (which is clamped to [0.0,1.0] before being assigned). This is the only way that the priority of a default texture can be specified. (PrioritizeTexturesEXT silently ignores attempts to prioritize nontextures, and texture zero.) Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations and the Frame Buffer) None Additions to Chapter 5 of the 1.0 Specification (Special Functions) BindTextureEXT and PrioritizeTexturesEXT are included in display lists. All other commands defined by this extension are not included in display lists. Additions to Chapter 6 of the 1.0 Specification (State and State Requests) IsTextureEXT returns TRUE if is the name of a valid texture object. If is zero, or is a non-zero value that is not the name of a texture object, or if an error condition occurs, IsTextureEXT returns FALSE. Because the query values of TEXTURE_1D, TEXTURE_2D, and TEXTURE_3D_EXT are already defined as booleans indicating whether these textures are enabled or disabled, another mechanism is required to query the binding associated with each of these texture targets. The name of the texture object currently bound to TEXTURE_1D is returned in when GetIntegerv is called with set to TEXTURE_1D_BINDING_EXT. If no texture object is currently bound to TEXTURE_1D, zero is returned. Likewise, the name of the texture object bound to TEXTURE_2D or TEXTURE_3D_EXT is returned in when GetIntegerv is called with set to TEXTURE_2D_BINDING_EXT or TEXTURE_3D_BINDING_EXT. If no texture object is currently bound to TEXTURE_2D or to TEXTURE_3D_EXT, zero is returned. A texture object comprises the image arrays, priority, border color, filter modes, and wrap modes that are associated with that object. More explicitly, the state list TEXTURE, TEXTURE_PRIORITY_EXT TEXTURE_RED_SIZE, TEXTURE_GREEN_SIZE, TEXTURE_BLUE_SIZE, TEXTURE_ALPHA_SIZE, TEXTURE_LUMINANCE_SIZE, TEXTURE_INTENSITY_SIZE, TEXTURE_WIDTH, TEXTURE_HEIGHT, TEXTURE_DEPTH_EXT, TEXTURE_BORDER, TEXTURE_COMPONENTS, TEXTURE_BORDER_COLOR, TEXTURE_MIN_FILTER, TEXTURE_MAG_FILTER, TEXTURE_WRAP_S, TEXTURE_WRAP_T, TEXTURE_WRAP_R_EXT composes a single texture object. When PushAttrib is called with TEXTURE_BIT enabled, the priorities, border colors, filter modes, and wrap modes of the currently bound texture objects are pushed, as well as the current texture bindings and enables. When an attribute set that includes texture information is popped, the bindings and enables are first restored to their pushed values, then the bound texture objects have their priorities, border colors, filter modes, and wrap modes restored to their pushed values. Additions to the GLX Specification Texture objects are shared between GLX rendering contexts if and only if the rendering contexts share display lists. No change is made to the GLX API. GLX Protocol Six new GL commands are added. The following rendering command is sent to the server as part of a glXRender request: BindTextureEXT 2 12 rendering command length 2 4117 rendering command opcode 4 ENUM target 4 CARD32 texture The following rendering command can be sent to the server as part of a glXRender request or as part of a glXRenderLarge request: PrioritizeTexturesEXT 2 8+(n*8) rendering command length 2 4118 rendering command opcode 4 INT32 n n*4 LISTofCARD32 textures n*4 LISTofFLOAT32 priorities If the command is encoded in a glXRenderLarge request, the command opcode and command length fields above are expanded to 4 bytes each: 4 12+(n*8) rendering command length 4 4118 rendering command opcode The remaining commands are non-rendering commands. These commands are sent separately (i.e., not as part of a glXRender or glXRenderLarge request), using either the glXVendorPrivate request or the glXVendorPrivateWithReply request: DeleteTexturesEXT 1 CARD8 opcode (X assigned) 1 16 GLX opcode (glXVendorPrivate) 2 4+n request length 4 12 vendor specific opcode 4 GLX_CONTEXT_TAG context tag 4 INT32 n n*4 CARD32 textures GenTexturesEXT 1 CARD8 opcode (X assigned) 1 17 GLX opcode (glXVendorPrivateWithReply) 2 4 request length 4 13 vendor specific opcode 4 GLX_CONTEXT_TAG context tag 4 INT32 n => 1 1 reply 1 unused 2 CARD16 sequence number 4 n reply length 24 unused 4*n LISTofCARD32 textures AreTexturesResidentEXT 1 CARD8 opcode (X assigned) 1 17 GLX opcode (glXVendorPrivateWithReply) 2 4+n request length 4 11 vendor specific opcode 4 GLX_CONTEXT_TAG context tag 4 INT32 n 4*n LISTofCARD32 textures => 1 1 reply 1 unused 2 CARD16 sequence number 4 (n+p)/4 reply length 4 BOOL32 return_value 20 unused n LISTofBOOL residences p unused, p=pad(n) IsTextureEXT 1 CARD8 opcode (X assigned) 1 17 GLX opcode (glXVendorPrivateWithReply) 2 4 request length 4 14 vendor specific opcode 4 GLX_CONTEXT_TAG context tag 4 CARD32 textures => 1 1 reply 1 unused 2 CARD16 sequence number 4 0 reply length 4 BOOL32 return_value 20 unused Dependencies on EXT_texture3D If EXT_texture3D is not supported, then all references to 3D textures in this specification are invalid. Errors INVALID_VALUE is generated if GenTexturesEXT parameter is negative. INVALID_VALUE is generated if DeleteTexturesEXT parameter is negative. INVALID_ENUM is generated if BindTextureEXT parameter is not TEXTURE_1D, TEXTURE_2D, or TEXTURE_3D_EXT. INVALID_OPERATION is generated if BindTextureEXT parameter is TEXTURE_1D, and parameter is the name of a 2-dimensional or 3-dimensional texture object. INVALID_OPERATION is generated if BindTextureEXT parameter is TEXTURE_2D, and parameter is the name of a 1-dimensional or 3-dimensional texture object. INVALID_OPERATION is generated if BindTextureEXT parameter is TEXTURE_3D_EXT, and parameter is the name of a 1-dimensional or 2-dimensional texture object. INVALID_VALUE is generated if PrioritizeTexturesEXT parameter negative. INVALID_VALUE is generated if AreTexturesResidentEXT parameter is negative. INVALID_VALUE is generated by AreTexturesResidentEXT if any of the names in is zero, or is not the name of a texture. INVALID_OPERATION is generated if any of the commands defined in this extension is executed between the execution of Begin and the corresponding execution of End. New State Get Value Get Command Type Initial Value Attribute --------- ----------- ---- ------------- --------- TEXTURE_1D IsEnabled B FALSE texture/enable TEXTURE_2D IsEnabled B FALSE texture/enable TEXTURE_3D_EXT IsEnabled B FALSE texture/enable TEXTURE_1D_BINDING_EXT GetIntegerv Z+ 0 texture TEXTURE_2D_BINDING_EXT GetIntegerv Z+ 0 texture TEXTURE_3D_BINDING_EXT GetIntegerv Z+ 0 texture TEXTURE_PRIORITY_EXT GetTexParameterfv n x Z+ 1 texture TEXTURE_RESIDENT_EXT AreTexturesResidentEXT n x B unknown - TEXTURE GetTexImage n x levels x I null - TEXTURE_RED_SIZE_EXT GetTexLevelParameteriv n x levels x Z+ 0 - TEXTURE_GREEN_SIZE_EXT GetTexLevelParameteriv n x levels x Z+ 0 - TEXTURE_BLUE_SIZE_EXT GetTexLevelParameteriv n x levels x Z+ 0 - TEXTURE_ALPHA_SIZE_EXT GetTexLevelParameteriv n x levels x Z+ 0 - TEXTURE_LUMINANCE_SIZE_EXT GetTexLevelParameteriv n x levels x Z+ 0 - TEXTURE_INTENSITY_SIZE_EXT GetTexLevelParameteriv n x levels x Z+ 0 - TEXTURE_WIDTH GetTexLevelParameteriv n x levels x Z+ 0 - TEXTURE_HEIGHT GetTexLevelParameteriv n x levels x Z+ 0 - TEXTURE_DEPTH_EXT GetTexLevelParameteriv n x levels x Z+ 0 - TEXTURE_4DSIZE_SGIS GetTexLevelParameteriv n x levels x Z+ 0 - TEXTURE_BORDER GetTexLevelParameteriv n x levels x Z+ 0 - TEXTURE_COMPONENTS (1D and 2D) GetTexLevelParameteriv n x levels x Z42 1 - TEXTURE_COMPONENTS (3D and 4D) GetTexLevelParameteriv n x levels x Z38 LUMINANCE - TEXTURE_BORDER_COLOR GetTexParameteriv n x C 0, 0, 0, 0 texture TEXTURE_MIN_FILTER GetTexParameteriv n x Z7 NEAREST_MIPMAP_LINEAR texture TEXTURE_MAG_FILTER GetTexParameteriv n x Z3 LINEAR texture TEXTURE_WRAP_S GetTexParameteriv n x Z2 REPEAT texture TEXTURE_WRAP_T GetTexParameteriv n x Z2 REPEAT texture TEXTURE_WRAP_R_EXT GetTexParameteriv n x Z2 REPEAT texture TEXTURE_WRAP_Q_SGIS GetTexParameteriv n x Z2 REPEAT texture New Implementation Dependent State None