SGI Developer Toolbox 6.1

home *** CD-ROM | disk | FTP | other *** search

/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 1.iso / toolbox / documents / OpenGL / extensions / spec / texture_object.spec < prev next >

Wrap

Text File | 1996-11-11 | 17.9 KB | 431 lines

Name EXT_texture_object Name Strings GL_EXT_texture_object Version $Date: 1995/09/30 02:33:18 $ $Revision: 1.1 $ 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 be static once they are changed from zero? This might simplify the management of texture memory. What about other properties of a texture? No. Reasoning * Previous proposals overloaded the <target> parameter of many Tex commands with texture names, as well as the original enumerated values. This proposal eliminated such overloading, choosing instead to require an application to bind a texture, and then operate on in 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 <target> parameters now. * Commands to directly set the priority of a texture and to query the resident status of a texture are included. I feel that binding a texture would be an unacceptable burden for these management operations. These commands also allow queries and operations on lists of textures, 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 <pname> parameters of TexParameteri, TexParameterf, TexParameteriv, TexParameterfv, GetTexParameteriv, and GetTexParameterfv: TEXTURE_PRIORITY_EXT 0x8066 Accepted by the <pname> parameters of GetTexParameteriv and GetTexParameterfv: TEXTURE_RESIDENT_EXT 0x8067 Accepted by the <pname> 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 textures. The name space for textures is the unsigned integers, with zero reserved by the GL. A texture is created by simply binding a previously unused texture name to TEXTURE_1D, TEXTURE_2D, or TEXTURE_3D_EXT. This binding is accomplished by calling BindTextureEXT with <target> set to TEXTURE_1D, TEXTURE_2D, or TEXTURE_3D_EXT, and <texture> set to the name of the new texture. When a texture is bound to a target, the previous binding for that target is automatically broken. When a texture is first bound it takes the dimensionality of its target. Thus, a texture first bound to TEXTURE_1D is 1-dimensional; a texture first bound to TEXTURE_2D is 2-dimensional, and a texture first bound to TEXTURE_3D_EXT is 3-dimensional. The state of a 1-dimensional texture 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 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 have no effect on its state. The error INVALID_OPERATION is generated if an attempt is made to bind a texture to a target of different dimensionality. While a texture is bound, GL operations on the target to which it is bound affect the bound texture, and queries of the target to which it is bound return state from the bound texture. If texture mapping of the dimensionality of the target to which a texture is bound is active, the bound texture 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. Named textures are deleted by calling DeleteTexturesEXT with <textures> pointing to a list of <n> texture names to be deleted. After a texture is deleted, it has no contents or dimensionality, and its name is freed. If a texture that is currently bound is deleted, the binding reverts to zero. DeleteTexturesEXT ignores names that do not correspond to textures, including zero. GenTexturesEXT returns <n> texture names in <textures>. 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. The dimensionality of textures created by GenTexturesEXT is indeterminate; such textures assume a dimensionality only when they are first bound. Textures created by GenTexturesEXT are 'used', however, in the sense that they will not be returned by subsequent calls to GenTexturesEXT until they are deleted. An implementation may choose to establish a "working set" of textures on which binding operations are performed with higher performance. A texture that is currently being treated as a part of the working set is said to be resident. AreTexturesResidentEXT returns TRUE if all of the <n> textures named in <textures> are resident, FALSE otherwise. If FALSE is returned, the residence of each texture is returned in <residences>. Otherwise the contents of the <residences> array are not changed. If any of the names in <textures> is not the name of a texture, FALSE is returned, the error INVALID_VALUE is generated, and the contents of <residences> are indeterminate. The resident status of a single bound texture can also be queried by calling GetTexParameteriv or GetTexParameterfv with <target> set to the target to which the texture is bound, and <pname> 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 textures should be resident by specifying a priority for each texture. PrioritizeTexturesEXT sets the priorities of the <n> textures in <textures> to the values in <priorities>. 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 can also be changed by calling TexParameteri, TexParameterf, TexParameteriv, or TexParameterfv with <target> set to the target to which the texture is bound, <pname> set to TEXTURE_PRIORITY_EXT, and <param> or <params> 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 <texture> is the name of a valid texture. If <texture> is zero, or is a non-zero value that is not the name of a texture, 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 currently bound to TEXTURE_1D is returned in <params> when GetIntegerv is called with <pname> set to TEXTURE_1D_BINDING_EXT. If no texture is currently bound to TEXTURE_1D, zero is returned. Likewise, the name of the texture bound to TEXTURE_2D or TEXTURE_3D_EXT is returned in <params> when GetIntegerv is called with <pname> set to TEXTURE_2D_BINDING_EXT or TEXTURE_3D_BINDING_EXT. If no texture 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 textures 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 textures 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 CARD32 return_value 20 unused n LISTofBYTE 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 CARD32 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 <n> is negative. INVALID_VALUE is generated if DeleteTexturesEXT parameter <n> is negative. INVALID_ENUM is generated if BindTextureEXT parameter <target> is not TEXTURE_1D, TEXTURE_2D, or TEXTURE_3D_EXT. INVALID_OPERATION is generated if BindTextureEXT parameter <target> is TEXTURE_1D, and parameter <texture> is not the name of a 1-dimensional texture, the name of an as yet unbound texture, or zero. INVALID_OPERATION is generated if BindTextureEXT parameter <target> is TEXTURE_2D, and parameter <texture> is not the name of a 2-dimensional texture, the name of an as yet unbound texture, or zero. INVALID_OPERATION is generated if BindTextureEXT parameter <target> is TEXTURE_3D_EXT, and parameter <texture> is not the name of a 3-dimensional texture, the name of an as yet unbound texture, or zero. INVALID_VALUE is generated if PrioritizeTexturesEXT parameter <n> negative. INVALID_VALUE is generated if AreTexturesResidentEXT parameter <n> is negative. INVALID_VALUE is generated by AreTexturesResidentEXT if any of the names in <textures> 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