Name AMD_name_gen_delete Name Strings GL_AMD_name_gen_delete Contributors Balaji Calidas Mark Young Murat Balci Benedikt Kessler Contact Mark Young (mark.young 'at' amd.com) Status In Progress. Version Last Modified Date: February 10, 2010 Author Revision: 1 Number 394 Dependencies OpenGL 2.1 is required. ARB_framebuffer_object affects this spec. ARB_vertex_array_object affects this spec. EXT_transform_feedback affects this spec. EXT_transform_feedback2 affects this spec. AMD_performance_monitor affects this spec ARB_sampler_objects affects this spec Overview This extension simply creates 2 new entry-points that name generic creation and deletion of names. The intent is to go away from API functionality that provides a create/delete function for each specific object. For example: glGenTextures/glDeleteTextures/glIsTexture glGenBuffers/glDeleteBuffers/IsBuffer glGenFramebuffers/glDeleteFramebuffers/IsFramebuffer Instead, everything is created using one entry-point GenNamesAMD and everything is now deleted with another entry-point DeleteNamesAMD with the appropriate identifier set. In addition, everything can now be queried with IsNameAMD. This alleviates the problem we may eventually encounter where we have many Gen/Delete/Is functions where 3 might suffice. All that is needed in the new case is to add a valid identifier to the accepted parameters list. IP Status No known IP claims. New Procedures and Functions void GenNamesAMD(enum identifier, uint num, uint *names); void DeleteNamesAMD(enum identifier, uint num, const uint *names); boolean IsNameAMD(enum identifier, uint name); New Types None. New Tokens Accepted as the parameter of GenNamesAMD and DeleteNamesAMD: DATA_BUFFER_AMD 0x9151 PERFORMANCE_MONITOR_AMD 0x9152 QUERY_OBJECT_AMD 0x9153 VERTEX_ARRAY_OBJECT_AMD 0x9154 SAMPLER_OBJECT_AMD 0x9155 Additions to Chapter 2 of the OpenGL 2.1 Specification (OpenGL Operation) Insert a new section before section 2.9 "Buffer Objects" titled "Object Name Handling" ---------------------------------------------------------------- 2.x Object Name Handling 2.x.1 Name Generation Objects in OpenGL are created, modified, and deleted using names. These names are unique per object type, but can be common across multiple types. For example, a texture and a query object may both be named 127, but two query different query objects cannot have the name 127 in the same context. These names are generated using each types own specific GenXXX command, but can also be created using the more generic command void GenNamesAMD( enum identifier, sizei n, uint *names ); where indicates the type of object that is to be created, is used to indicate how many objects to create, and is a previously allocated array that the new generated names will be supplied in. These names for marked as used for the purposes of the type of object specified by (and their own individual GenXXX command), but they do not typically acquire any state until they are first bound, just as if they were unused. Valid values for currently are: - DATA_BUFFER_AMD (For ARRAY_BUFFER, ELEMENT_ARRAY_BUFFER, PIXEL_PACK_BUFFER, and PIXEL_UNPACK_BUFFER) - FRAMEBUFFER - RENDERBUFFER - TEXTURE - TRANSFORM_FEEDBACK_EXT - VERTEX_ARRAY_OBJECT_AMD (For VAOs instead of VERTEX_ARRAY_BINDING) - QUERY_OBJECT_AMD (For query objects) - PERFORMANCE_MONITOR_AMD (For a performance monitor object) - SAMPLER_OBJECT_AMD (For a sampler object) If is not one of these valid values, the error INVALID_ENUM will be triggered. If is a number zero or is NULL, the error INVALID_VALUE is triggered. 2.x.2 Name Deletion Object names can be deleted when they are no longer needed using the command void DeleteNamesAMD( enum identifier, sizei n, const uint *names ); where indicates one of the above valid types, and indicates how many object names are provided in the array. Similar to GenNamesAMD, each object type also has its own DeleteXXX command. DeleteNamesAMD with a given object type behaves in the same way that the object types specific DeleteXXX command does. If is not one of these valid values, the error INVALID_ENUM will be triggered. If is a number zero or is NULL, the error INVALID_VALUE is triggered. 2.x.3 Name Querying Object names can be queried to make sure that an object of the given type exists using the command boolean IsNameAMD( enum identifier, uint name ); where indicates one of the above valid types, and is the name that is being identified as a valid name for that object type. Similar to GenNamesAMD and DeleteNamesAMD, each object type also has its own IsXXX command. IsNameAMD with a given object type behaves in the same way that the object types specific IsXXX command does. If is not one of these valid values, the error INVALID_ENUM will be triggered. 2.x.4 Name Binding Objects are typically enabled for usage through a Bind call or something similar. The process for binding objects for usage is handled differently per object type. For further information on how to use each object, refer to its section later in this spec. Modify section 2.9 "Buffer Objects", page 33. ---------------------------------------------------------------- After the paragraphs talking about 'DeleteBuffers' insert: ---------------------------------------------------------------- Calling the command void DeleteNamesAMD( enum identifier, sizei n, const uint *names ); with set to DATA_BUFFER_AMD behaves the same as using the DeleteBuffers command. Modify the paragraphs talking about 'GenBuffers': ---------------------------------------------------------------- The commands void GenBuffers( sizei n, uint *buffers ); returns previously unused buffer object names in . These names are marked as used, for the purposes of GenBuffers and GenNamesAMD when used with set to DATA_BUFFER_AMD only, but they acquire buffer state only when they are first bound, just as if they were unused. Calling the command void GenNamesAMD( enum identifier, sizei n, uint *names ); with set to DATA_BUFFER_AMD behaves the same as using the GenBuffers command. While a buffer object is bound, any GL operations on that object affect any other bindings of that object. If a buffer object is deleted while it is bound, all bindings to that object in the current context (i.e. in the thread that called DeleteBuffers or DeleteNamesAMD with set to DATA_BUFFER_AMD) are reset to zero. Bindings to that buffer in other contexts and other threads are not affected, but attempting to use a deleted buffer in another thread... Modify the new section 2.y "Vertex Array Objects". Added by ARB_vertex_array_object ---------------------------------------------------------------- Modify the paragraphs talking about 'GenVertexArrays': ---------------------------------------------------------------- The commands void GenVertexArrays( sizei n, uint *arrays ); returns previous unused vertex array object names in . These names are marked as used, for the purposes of GenVertexArrays and GenNamesAMD (when is set to VERTEX_ARRAY_OBJECT_AMD) only, and are initialized with the state listed in tables 6.6 (except for the CLIENT_ACTIVE_TEXTURE selector state), 6.7 and 6.8. Calling the command void GenNamesAMD( enum identifier, sizei n, uint *names ); with set to VERTEX_ARRAY_OBJECT_AMD behaves the same as using the GenVertexArrays command. After the paragraphs talking about 'DeleteVertexArrays' insert: ---------------------------------------------------------------- Calling the command void DeleteNamesAMD( enum identifier, sizei n, const uint *names ); with set to VERTEX_ARRAY_OBJECT_AMD behaves the same as using the DeleteVertexArrays command. Modify the paragraph that starts with 'BindVertexArray fails and an INVALID_OPERATION error'... to: ---------------------------------------------------------------- BindVertexArray fails and an INVALID_OPERATION error is generated if array is not a name returned from a previous call to GenVertexArrays (or GenNamesAMD with set to VERTEX_ARRAY_OBJECT), or if such a name has since been deleted with either DeleteVertexArrays or DeleteNamesAMD (with set to VERTEX_ARRAY_OBJECT). An INVALID_OPERATION error is generated if VertexAttribPointer or VertexAttribIPointer is called while a non-zero vertex array object is bound and zero is bound to the ARRAY_BUFFER buffer object binding point[fn]. Modify the new section 2.z.1 "Transform Feedback Objects" Added by EXT_transform_feedback2 ---------------------------------------------------------------- Add after the paragraphs talking about 'DeleteTransformFeedbacksEXT': ---------------------------------------------------------------- Calling the command void DeleteNamesAMD( enum identifier, sizei n, const uint *names ); with set to TRANSFORM_FEEDBACK_EXT behaves the same as using the DeleteTransformFeedbacksEXT command. Modify the paragraphs talking about 'GenTransformFeedbacksEXT': ---------------------------------------------------------------- The command void GenTransformFeedbacksEXT(sizei n, uint *ids) returns previously unused transform feedback object names in . These names are marked as used, for the purposes of GenTransformFeedbacksEXT and GenNamesAMD (when is set to TRANSFORM_FEEDBACK_EXT) only, but they acquire transform feedback state only when they are first bound, just as if they were unused. Calling the command void GenNamesAMD( enum identifier, sizei n, uint *names ); with set to TRANSFORM_FEEDBACK_EXT behaves the same as using the GenTransformFeedbacksEXT command. Modify the paragraph that starts with 'BindVertexArray fails and an INVALID_OPERATION error'... to: ---------------------------------------------------------------- BindVertexArray fails and an INVALID_OPERATION error is generated if array is not a name returned from a previous call to GenVertexArrays (or GenNamesAMD with set to VERTEX_ARRAY_OBJECT), or if such a name has since been deleted with either DeleteVertexArrays or DeleteNamesAMD (with set to VERTEX_ARRAY_OBJECT). An INVALID_OPERATION error is generated if VertexAttribPointer or VertexAttribIPointer is called while a non-zero vertex array object is bound and zero is bound to the ARRAY_BUFFER buffer object binding point[fn]. Additions to Chapter 3 of the OpenGL 2.1 Specification (Rasterization) Modify section 3.8.12 "Texture Objects", page 182. ---------------------------------------------------------------- After the paragraphs talking about 'DeleteTextures' insert: ---------------------------------------------------------------- Calling the command void DeleteNamesAMD( enum identifier, sizei n, const uint *names ); with set to TEXTURE behaves the same as using the DeleteTextures command. Modify the paragraphs talking about 'GenTextures': ---------------------------------------------------------------- The commands void GenTextures( sizei n, uint *textures ); returns previously unused texture object names in . These names are marked as used, for the purposes of GenTextures and GenNamesAMD when used with set to TEXTURE only, but they acquire texture state and dimensionality only when they are first bound, just as if they were unused. Calling the command void GenNamesAMD( enum identifier, sizei n, uint *names ); with set to TEXTURE behaves the same as using the GenBuffers command. Modify section 3.9.2 "Sampler Objects". ---------------------------------------------------------------- After the paragraphs talking about 'GenSamplers' insert: ---------------------------------------------------------------- Calling the command void GenNamesAMD( enum identifier, sizei n, uint *names ); with set to SAMPLER_OBJECT_AMD behaves the same as using the GenSamplers command. After the paragraphs talking about 'DeleteSamplers' insert: ---------------------------------------------------------------- Calling the command void DeleteNamesAMD( enum identifier, sizei n, const uint *names ); with set to SAMPLER_OBJECT_AMD behaves the same as using the DeleteSamplers command. Additions to Chapter 4 of the OpenGL 2.1 Specification (Per-Fragment Operations and the Framebuffer) Modify section 4.1.7 "Occlusion Queries", page 207. ---------------------------------------------------------------- Insert after the paragraph talking about 'GenQueries': ---------------------------------------------------------------- Calling the command void GenNamesAMD( enum identifier, sizei n, uint *names ); with set to QUERY_OBJECT_AMD behaves the same as using the GenQueries command. After the paragraphs talking about 'DeleteQueries' insert: ---------------------------------------------------------------- Calling the command void DeleteNamesAMD( enum identifier, sizei n, const uint *names ); with set to QUERY_OBJECT_AMD behaves the same as using the DeleteTextures command. Modify the paragraph that talks about GenQueries and DeleteQueries errors after that: ---------------------------------------------------------------- Calling either GenQueries, DeleteQueries, GenNamesAMD(QUERY_OBJECT_AMD), or DeleteNamesAMD(QUERY_OBJECT_AMD), while any query of any target is active causes an INVALID OPERATION error to be generated. Modify section 4.4.1 "Binding and Managing Framebuffer Objects" ---------------------------------------------------------------- Modify the 2nd paragraph to read: ---------------------------------------------------------------- A framebuffer object is created by binding a name returned by GenFramebuffers or GenNamesAMD (see below) to DRAW_FRAMEBUFFER or READ_FRAMEBUFFER. The binding is effected by calling Modify the 5th paragraph to read: ---------------------------------------------------------------- BindFramebuffer fails and an INVALID_OPERATION error is generated if is not zero or a name returned from a previous call to GenFramebuffers or GenNamesAMD, or if such a name has since been deleted with DeleteFramebuffers or DeleteNamesAMD. After the paragraphs talking about 'DeleteFramebuffers' insert: ---------------------------------------------------------------- Calling the command void DeleteNamesAMD( enum identifier, sizei n, const uint *names ); with set to FRAMEBUFFER behaves the same as using the DeleteFramebuffers command. After the paragraphs talking about 'GenFramebuffers' insert: ---------------------------------------------------------------- Calling the command void GenNamesAMD( enum identifier, sizei n, uint *names ); with set to FRAMEBUFFER behaves the same as using the GenFramebuffers command. Modify section 4.4.2.1 "Renderbuffer Objects" ---------------------------------------------------------------- Modify the 2nd paragraph to read: ---------------------------------------------------------------- The name space for renderbuffer objects is the unsigned integers, with zero reserved for the GL. A renderbuffer object is created by binding a name returned by GenRenderbuffers or GenNamesAMD (see below) to RENDERBUFFER. The binding is effected by calling Modify the 9th paragraph to read: ---------------------------------------------------------------- BindRenderbuffer fails and an INVALID_OPERATION error is generated if is not a name returned from a previous call to GenRenderbuffers or GenNamesAMD, or if such a name has since been deleted with DeleteRenderbuffers or DeleteNamesAMD. After the paragraphs talking about 'DeleteRenderbuffers' insert: ---------------------------------------------------------------- Calling the command void DeleteNamesAMD( enum identifier, sizei n, const uint *names ); with set to RENDERBUFFER behaves the same as using the DeleteFramebuffers command. After the paragraphs talking about 'GenRenderbuffers' insert: ---------------------------------------------------------------- Calling the command void GenNamesAMD( enum identifier, sizei n, uint *names ); with set to RENDERBUFFER behaves the same as using the GenFramebuffers command. Additions to Chapter 5 of the OpenGL 2.1 Specification (Special Functions) Modify section 5.4 "Display Lists", page 240. ---------------------------------------------------------------- Add the following to the list of things not allowed inside of a display list: ---------------------------------------------------------------- Name generation: GenNamesAMD and DeleteNamesAMD Additions to Chapter 6 of the OpenGL 2.1 Specification (State and State Requests) Modify section 6.1.4 "Texture Queries" ---------------------------------------------------------------- After the paragraphs talking about 'IsTexture' insert: ---------------------------------------------------------------- Calling the command void IsNameAMD( enum identifier, uint name ); with set to TEXTURE behaves the same as using the IsTexture command. Modify section 6.1.12 "Occlusion Queries" ---------------------------------------------------------------- After the paragraphs talking about 'IsQuery' insert: ---------------------------------------------------------------- Calling the command void IsNameAMD( enum identifier, uint name ); with set to QUERY_OBJECT_AMD behaves differently from calling IsQuery. IsQuery only returns if an object is a query once it has been used. However, IsName returns TRUE if a QUERY_OBJECT_AMD object had been created either through GenQueries or GenNamesAMD. Modify section 6.1.13 "Buffer Object Queries" ---------------------------------------------------------------- After the paragraphs talking about 'IsBuffer' insert: ---------------------------------------------------------------- Calling the command void IsNameAMD( enum identifier, uint name ); with set to DATA_BUFFER_AMD behaves the same as using the IsBuffer command. Additions to new section for Performance Monitoring (added by AMD_performance_monitor) After the paragraphs talking about 'GenPerfMonitorsAMD' insert: ---------------------------------------------------------------- Calling the command void GenNamesAMD( enum identifier, sizei n, uint *names ); with set to PERFORMANCE_MONITOR_AMD behaves the same as using the GenPerfMonitorsAMD command. Modify the paragraphs talking about 'DeletePerfMonitorsAMD' to: ---------------------------------------------------------------- The command void DeletePerfMonitorsAMD(sizei n, uint *monitors) is used to delete the list of monitors created by a previous call to GenPerfMonitors or GenNamesAMD (with set to PERFORMANCE_MONITOR_AMD). If a monitor ID in the list does not reference a previously generated performance monitor, an INVALID_VALUE error is generated. Calling the command void DeleteNamesAMD( enum identifier, sizei n, const uint *names ); with set to PERFORMANCE_MONITOR_AMD behaves the same as using the DeletePerfMonitors command. Modify the paragraph after the protoype for SelectPerfMonitorCountersAMD to read: ---------------------------------------------------------------- is used to enable or disable a list of counters from a group to be monitored as identified by . The argument determines whether the counters should be enabled or disabled. specifies the group ID under which counters will be enabled or disabled. The argument gives the number of counters to be selected from the list . If is not a valid monitor created by either GenPerfMonitorsAMD or GneNamesAMD (with set to PERFORMANCE_MONITOR_AMD), then INVALID_VALUE error will be generated. If is not a valid group, the INVALID_VALUE error will be generated. If is less than 0, an INVALID_VALUE error will be generated. Additions to the OpenGL / GLX / GLX Protocol Specifications None. Additions to the WGL Specification None. Errors The error INVALID_ENUM is generated by GenNamesAMD, DeleteNamesAMD, or IsNameAMD if is not one of: - DATA_BUFFER_AMD (For ARRAY_BUFFER, ELEMENT_ARRAY_BUFFER, PIXEL_PACK_BUFFER, and PIXEL_UNPACK_BUFFER) - FRAMEBUFFER - RENDERBUFFER - TEXTURE - TRANSFORM_FEEDBACK_EXT - VERTEX_ARRAY_OBJECT_AMD (For VAOs instead of VERTEX_ARRAY_BINDING) - QUERY_OBJECT_AMD (For query objects) - PERFORMANCE_MONITOR_AMD (For a performance monitor object) - SAMPLER_OBJECT_AMD (For a sampler object) The error INVALID_VALUE is generated by GenNamesAMD or DeleteNamesAMD if is 0. The error INVALID_VALUE is generated by GenNamesAMD or DeleteNamesAMD if is NULL. New State None New Implementation Dependent State If ARB_vertex_array_object is not present, remove any reference to VERTEX_ARRAY or VERTEX_ARRAY_BINDING and VAOs. Sample Code glGenTextures/glDeleteTextures Before: GLuint texID[12]; glGenTextures(12, &texID[0]); ... // Use textures ... glDeleteTextures(12, &texID[0]); After: GLuint texID[12]; glGenNames(GL_TEXTURE, 12, &texID[0]); ... // Use textures ... glDeleteNames(GL_TEXTURE, 12, &texID[0]); Issues 01) What is the main benefit of these new entry-points? To reduce the requirement of new entry-points for generating and deleting names. 02) Do we want to use VERTEX_ARRAY_BINDING for a vertex array object? RECOMMENDATION - I suggest using a new variable called VERTEX_ARRAY_OBJECT_AMD. This makes it clear what's being generated. 03) What do we want the generic buffer object name to be called RESOLVED - Use DATA_BUFFER_AMD. 04) Do we want to include display list generation? RECOMMENDATION - No. There is additional restrictions on display list name generation specifically items being consecutively generated. 05) Should DeleteNamesAMD verify that the names exist and throw an error if not? RECOMMENDATION - I think not since it might cause issues with multi- context multi-thread cases where sharing is enabled and one context deletes them follwed by another context deleting items. Revision History 1) September 11, 2009: myoung - Initial revision of AMDX extension 2) February 10, 2010: myoung - Change from AMDX to AMD extension 2) February 12, 2010: myoung - Add in IsNameAMD functionality requested by Benedikt