1Name 2 3 AMD_pinned_memory 4 5Name Strings 6 7 GL_AMD_pinned_memory 8 9Contributors 10 11 Pierre Boudier 12 Graham Sellers 13 14Contact 15 16 Pierre Boudier, AMD (pierre.boudier 'at' amd.com) 17 18IP Status 19 20 None. 21 22Status 23 24 Shipping 25 26Version 27 28 Last Modified Date: June 4, 2013 29 Revision: 2.0 30 31Number 32 33 411 34 35Dependencies 36 37 This specification is written against the OpenGL 4.2 (Core) Specification, 38 dated August 8, 2011. 39 40Overview 41 42 This extension defines an interface that allows improved control 43 of the physical memory used by the graphics device. 44 45 It allows an existing page of system memory allocated by the application 46 to be used as memory directly accessible to the graphics processor. One 47 example application of this functionality would be to be able to avoid an 48 explicit synchronous copy with sub-system of the application; for instance 49 it is possible to directly draw from a system memory copy of a video 50 image. 51 52New Procedures and Functions 53 54 None 55 56New Tokens 57 58 Accepted by the <target> parameters of BindBuffer, BufferData, 59 BufferSubData, MapBuffer, UnmapBuffer, GetBufferSubData, 60 GetBufferParameteriv, GetBufferPointerv, MapBufferRange: 61 62 EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD 0x9160 63 64Additions to Chapter 2 of the OpenGL 4.2 (Core Profile) Specification 65(OpenGL Operation) 66 67 Additions to the table Table 2.8: Buffer object binding targets. 68 69 +-------------------------------------+---------------------------------+-------------------------+ 70 | Target name | Purpose | Described in section(s) | 71 +-------------------------------------+---------------------------------+-------------------------+ 72 | EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD | Application-owned memory buffer | 2.9.2 | 73 +-------------------------------------+---------------------------------+-------------------------+ 74 75 Modifications to Section 2.9.2, "Creating Buffer Object Data Stores" 76 77 2.9.2 Creating Buffer Object Data Stores 78 79 The data store of a buffer object is created and initialized by calling 80 81 void BufferData( enum target, sizeiptr size, const void *data, enum usage ); 82 83 with <target> set to one of the targets listed in table 2.8, <size> set to 84 the size of the data store in basic machine units, and data pointing to the 85 source data in client memory. If <target> is not 86 EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD, then if <data> is non-null, the source 87 data is copied to the buffer object's data store. If <data> is null, then 88 the contents of the buffer object's data store are undefined. If <target> 89 is EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD, then the client's memory is used 90 directly by the GL for all subsequent operations on the buffer object's 91 data store. In this case, the application must guarantee the existence of 92 the buffer for the lifetime of the buffer object, or until its data store 93 is re-specified by another call to BufferData. <usage> is specified as one 94 of nine enumerated values, indicating the expected application usage 95 pattern of the data store. The values are: ... 96 97Additions to Chapter 3 of the OpenGL 4.2 (Core Profile) Specification 98(Rasterization) 99 100 None. 101 102Additions to Chapter 4 of the OpenGL 4.2 (Core Profile) Specification 103(Per-Fragment Operations and the Framebuffer) 104 105 None. 106 107Additions to Chapter 5 of the OpenGL 4.2 (Core Profile) Specification 108(Special Functions) 109 110 None. 111 112Additions to Chapter 6 of the OpenGL 4.2 (Core Profile) Specification 113(State and State Requests) 114 115 None. 116 117Errors 118 119 INVALID_OPERATION is generated by BufferData if <target> is 120 EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD, and the store cannot be mapped to the 121 GPU address space. 122 123Issues 124 125 1) When a system memory is shared with the GL, do we need extra 126 synchronization for the application to update the content? 127 128 RESOLVED: NO. once the memory page has been shared with the GL, 129 then all the regular OpenGL commands can be used to ensure 130 proper synchronization. the newly created buffer object is 131 no different from the ones that were allocated by GL, except 132 that the physical pages cannot be changed (but virtual mapping 133 can change). 134 135 2) Can the application still use the buffer using the CPU address? 136 137 RESOLVED: YES. However, this access would be completely 138 non synchronized to the OpenGL pipeline, unless explicit 139 synchronization is being used (for example, through glFinish or by using 140 sync objects). 141 142 3) Can the application free the memory? 143 144 RESOLVED: YES. However, the underlying buffer object should 145 have been deleted from the OpenGL to prevent any access by 146 the GPU, or the result is undefined, including program or even system 147 termination. 148 149 4) Is glMapBuffer on a shared buffer guaranteed to return the same system 150 address which was specified at creation time? 151 152 RESOLVED: NO. The GL implementation might return a different virtual 153 mapping of that memory, although the same physical page will be used. 154 155 5) Is there any limitation on offset/size? 156 157 RESOLVED: YES. Since the pinning of system memory is eventually handled 158 by the OS, there might be different restriction. It is recommended to 159 align the offset/size to the underlying page size (4k seems to be 160 widespread). 161 162 6) What happens if you use this extension on two separate buffers which are 163 sharing the same underlying physical page? 164 165 RESOLVED: The behavior is undefined. some OS will not refcount how 166 many times a physical page is locked for GPU access, and may therefore 167 either fail to lock, or fail to properly unlock. 168 169 7) Should there be a query for the alignment value of offset/size? 170 171 RESOLVED: NO. on the same system, it is possible to have several 172 different page sizes. 173 174 8) Why is the error produced for failure to pin memory INVALID_OPERATION? 175 Why not OUT_OF_MEMORY? 176 177 OUT_OF_MEMORY invalidates OpenGL context state. Failure to pin memory 178 does not upset the state of the context, and so an error that does not 179 have this semantic was chosen. The exact cause of the failure may be 180 reported by a debug context. 181 182Example Usage 183 184 The GL_EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD target is used simply for the 185 purposes of allocation through BufferData. It is otherwise not referenced 186 by the GL (much like GL_COPY_READ_BUFFER, for example). Once the buffer's 187 data store has been associated with client memory, that memory may be used 188 for any purpose such as vertex attributes (GL_ARRAY_BUFFER), TBO 189 (GL_TEXTURE_BUFFER), pixel reads and writes (GL_PIXEL_UNPACK_BUFFER, 190 GL_PIXEL_PACK_BUFFER) or transform feedback (GL_TRANSFORM_FEEDBACK_BUFFER). 191 192 As an example, consider the following example, which performs an 193 asynchronous pixel readback to client memory: 194 195 GLuint buffer; 196 glGenBuffers(1, &buffer); 197 glBindBuffer(GL_EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD, buffer); 198 199 void * memory = malloc(1024 * 1024 * 4); 200 glBufferData(GL_EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD, 1024 * 1024 * 4, GL_STREAM_COPY, memory); 201 202 glBindBuffer(GL_EXTERNAL_VIRTUAL_MEMORY_BUFFER_AMD, 0); 203 glBindBuffer(GL_PIXEL_PACK_BUFFER_AMD, buffer); 204 glReadPixels(0, 0, 1024, 1024, GL_RGBA, GL_UNSIGNED_BYTE, 0); 205 206 GLsync s = glFenceSync(GL_SYNC_GPU_COMMANDS_COMPLETE, 0); 207 208 // Data will eventually end up in 'memory'. Other processing may occur 209 // during the transfer time. 210 211 glClientWaitSync(s, GL_SYNC_FLUSH_COMMANDS_BIT, ~0ull); 212 213 // It is now safe to use 'memory' 214 215Revision History 216 217 Rev. Date Author Changes 218 ---- -------- -------- ----------------------------------------- 219 220 2 04/05/2013 gsellers Fixed a couple of typos. 221 1 11/30/2011 gsellers Cleanup and minor updates. 222 xx 03/22/2011 pboudier Initial draft. 223 224