1Name 2 3 ATI_map_object_buffer 4 5Name Strings 6 7 GL_ATI_map_object_buffer 8 9Contact 10 11 Rick Hammerstone, AMD (rick.hammerstone 'at' amd.com) 12 13Status 14 15 Complete. 16 17Version 18 19 0.3 - 11/04/06 20 Updated contact info after ATI/AMD merger. 21 22 0.2 - 01/15/01 23 Modified map call to return a pointer and take a single <buffer> 24 argument. Cleaned up spec. 25 26 0.1 - 11/26/01 27 Initial revision 28 29Number 30 31 288 32 33Dependencies 34 35 This extension is written against the OpenGL 1.2.1 Specification. 36 OpenGL 1.1 is required. ATI_vertex_array_object is required by 37 this extension. 38 39 40Overview 41 42 This extension provides a mechanism for an application to obtain 43 the virtual address of an object buffer. This allows the 44 application to directly update the contents of an object buffer 45 and avoid any intermediate copies. 46 47 48Issues 49 50 Should we use Lock and Unlock terminology? 51 52 UNRESOLVED: This could be confusing. D3D uses "Lock" to mean 53 that something is available for the application to update and 54 won't be changed by the driver. However, in the compiled 55 vertex array extension, "Lock" is used to mean that the 56 application will not be changing the contents of a vertex 57 buffer. 58 59 60New Procedures and Functions 61 62 void *MapObjectBufferATI(uint buffer) 63 64 void UnmapObjectBufferATI(uint buffer) 65 66 67New Tokens 68 69 None 70 71 72Additions to Chapter 2 of the GL Specification (OpenGL Operation) 73 74 Added to the description of Vertex Array Objects: 75 76 The object buffer interface provides a mechanism for an 77 application to store data in persistent memory that can be 78 accessed directly by the graphics hardware. The memory is accessed 79 through handles, and data must be copied into the memory by the 80 driver. This provides a platform-independent mechanism for 81 updating the object buffers, and allows the driver to optimally 82 manage the object buffers. 83 84 However, in cases where object buffers are being frequently 85 updated, the overhead of memory copies can degrade overall 86 application performance. The command 87 88 void *MapObjectBufferATI(uint buffer) 89 90 allows the application to obtain a pointer to the object buffer 91 named <buffer>. If <buffer> is not the name of an existing object 92 buffer, MapObjectBufferATI returns a null pointer. 93 94 The size of the region mapped by MapObjectBufferATI is equal to 95 the size of the object buffer. This size can be queried by calling 96 GetObjectBufferivATI or GetObjectBufferfvATI with the token 97 OBJECT_BUFFER_SIZE_ATI. 98 99 When an application issues a MapObjectBufferATI command, all 100 rendering commands that reference data stored in <buffer> must 101 complete before the call to MapObjectBufferATI returns. When the 102 call returns, the data in <buffer> can be updated immediately. 103 104 If an application desires to update an object buffer using this 105 interface, it should create the object buffer using DYNAMIC_ATI as 106 the usage parameter. Direct updates to object buffers that were 107 created with STATIC_ATI as the usage parameter may operate at 108 reduced performance. 109 110 When an application is finished updating an object buffer, it uses 111 the command 112 113 void UnmapObjectBufferATI(uint buffer) 114 115 to indicate to the driver that it has completed updating the 116 object buffer specified by <buffer>. An application must call 117 UnmapObjectBufferATI before issuing any rendering commands that 118 use the data stored in <buffer>. 119 120 Attempts to update an object buffer by direct memory writes after 121 UnmapObjectBufferATI has been called result in undefined behavior 122 and may generate an error. UpdateObjectBufferATI can be used to 123 update an object buffer at any time, regardless of whether it is 124 mapped or not. 125 126Additions to Chapter 3 of the 1.2.1 Specification (Rasterization) 127 128 None 129 130 131Additions to Chapter 4 of the 1.2.1 Specification (Per-Fragment 132Operations and the Frame Buffer) 133 134 None 135 136 137Additions to Chapter 5 of the 1.2.1 Specification (Special Functions) 138 139 Added to section 5.4, as part of the discussion of what commands 140 are compiled into display lists: 141 142 MapObjectBufferATI and UnmapObjectBufferATI are not included in 143 display lists, but are executed immediately. 144 145 146Additions to Chapter 6 of the 1.2.1 Specification (State and State 147Requests) 148 149 None 150 151Errors 152 153 INVALID_VALUE is generated if the <buffer> argument of 154 MapObjectBuffer or UnmapObjectBuffer does not specify a valid 155 object buffer. 156 157 INVALID_OPERATION may be generated if a rendering command is 158 issued that uses an object buffer that is currently mapped. 159 160New State 161 162 None 163 164 165Implementation Notes 166 167