1Name 2 3 EXT_external_buffer 4 5Name Strings 6 7 GL_EXT_external_buffer 8 9Contact 10 11 Jeff Leger (jleger 'at' qti.qualcomm.com) 12 13Contributors 14 15 Sam Holmes 16 Maurice Ribble 17 Matt Netsch 18 Jeremy Gebben 19 John Bates 20 Craig Donner 21 Jeff Leger 22 Rob VanReenen 23 Tom Kneeland 24 Jesse Hall 25 Jan-Harald Fredriksen 26 Daniel Koch 27 Mathias Heyer 28 29Status 30 31 Complete 32 33Version 34 35 Last Modified Date: May 29, 2017 36 Revision: 1.0 37 38Number 39 40 OpenGL ES Extension #284 41 OpenGL Extension #508 42 43Dependencies 44 45 OpenGL ES 3.1 and EXT_buffer_storage are required for OpenGL ES 46 implementations. 47 48 OpenGL 4.4 is required for OpenGL implementations. 49 50 This extension is written against the OpenGL ES 3.1 (June 4, 2014) 51 Specification. 52 53 This extension is written against version 3 of EXT_buffer_storage. 54 55 The definition of this extension is affected by the presence of 56 GL_EXT_direct_state_access, GL_ARB_direct_state_access, or OpenGL 4.5. 57 58 59Overview 60 61 Extension EXT_buffer_storage introduced immutable storage buffers to 62 OpenGL ES. This extension allows the data store for an immutable buffer to 63 be sourced from an external EGLClientBuffer, allowing sharing of EGL client 64 buffers across APIs, across processes, and across different processing 65 cores such as the GPU, CPU, and DSP. 66 67 Operations can then be performed on the external buffer using standard 68 GL buffer object procedures. The data in the allocation is not copied to 69 the buffer object's data store; the external allocation represents a single 70 memory allocation that can be shared across multiple GL objects -- this 71 aspect is similar to EGL external images. On the other hand, the external 72 buffer does not provide lifetime guarantees including orphaning and sibling 73 behavior as provided by EGL external images. 74 75 The EGLClientBuffer must be allocated in a way which permits this shared 76 access. For example, on Android via a shareable Android hardware buffer. 77 This extension does not enable support for arbitrary EGLClientBuffers to be 78 used as an external buffer. 79 80 It is the application's responsibility to ensure synchronization between 81 operations performed by separate components (DSP / CPU / GPU) and processes 82 on the external buffer. Additionally the application is responsible for 83 avoiding violating existing GL spec requirements. For example, mapping a 84 single shared allocation to two GL buffer objects and then performing 85 CopyBufferSubData such that the read and write regions overlap would 86 violate the existing CopyBufferSubData spec regarding copies performed 87 with the same buffer set for source and destination. 88 89 The application must take any steps necessary to ensure memory access to 90 the external buffer behaves as required by the application. For example, 91 preventing compilation differences in data padding from causing data to be 92 inadvertently corrupted by using defined structure alignment methods such 93 as the std140 layout qualifier. The application is responsible for 94 managing the lifetime of the external buffer, ensuring that the external 95 buffer is not deleted as long as there are any GL buffer objects referring 96 to it. 97 98New Types 99 100 /* 101 * GLeglClientBufferEXT is an opaque handle to an EGLClientBuffer 102 */ 103 typedef void* GLeglClientBufferEXT; 104 105New Procedures and Functions 106 107 void BufferStorageExternalEXT(enum target, 108 intptr offset, 109 sizeiptr size, 110 eglClientBufferEXT clientBuffer, 111 bitfield flags); 112 113 [[ The following is only added if GL_EXT_direct_state_access, 114 GL_ARB_direct_state_access, or OpenGL 4.5 is supported. ]] 115 116 void NamedBufferStorageExternalEXT(uint buffer, 117 intptr offset, 118 sizeiptr size, 119 eglClientBufferEXT clientBuffer, 120 bitfield flags); 121 122New Tokens 123 124 None 125 126Additions to Chapter 6 of the OpenGL ES 3.1 Specification (Buffer Objects) 127 128Modify Section 6.2, (Creating and Modifying Buffer Object Data Stores). After 129the section describing BufferStorageEXT, insert the following: 130 131 The command 132 133 void BufferStorageExternalEXT(enum target, intptr offset, 134 sizeiptr size, eglClientBufferEXT clientBuffer, 135 bitfield flags); 136 137 behaves similar to BufferStorageEXT, but rather than allocate an immutable 138 data store, the specified client buffer is referenced as the immutable 139 data store. Such a store may not be modified through further calls to 140 BufferStorageExternalEXT, BufferStorageEXT, or BufferData. 141 142 <target> Specifies the target buffer object. The symbolic constant must be 143 one of the targets listed in table 6.1. <offset> and <size> specify, in 144 basic machine units, the range of the client buffer to be bound to the data 145 store. <offset> must be zero. 146 147 <clientBuffer> Is the handle of a valid EGLClientBuffer resource (cast 148 into type eglClientBufferEXT). The EGLClientBuffer must be allocated in a 149 platform-specific way which permits shared access. For example, on Android 150 via a sharable Android hardware buffer (struct AHardwareBuffer), converted 151 into EGLClientBuffer via extension EGL_ANDROID_get_native_client_buffer. 152 Other platforms would require a similar mechanism. This extension does not 153 enable support for arbitrary EGLClientBuffers to be used as a shared buffer. 154 <flags> is the bitwise OR of flags describing the intended usage of the buffer 155 object's external data store by the application. Valid flags and their 156 meanings are as described for BufferStorageEXT. 157 158 The values of the buffer object's state variables will match those for other 159 *BufferStorageEXT calls, as specified in table 6.3. 160 161 The behavior follows other immutable buffers; BufferStorageExternalEXT sets the 162 created buffer's BUFFER_IMMUTABLE_STORAGE_EXT to TRUE. 163 164 [[ The following is only added if GL_EXT_direct_state_access, 165 GL_ARB_direct_state_access, or OpenGL 4.5 is supported. ]] 166 167 The command 168 169 void NamedBufferStorageExternalEXT(uint buffer, intptr offset, 170 sizeiptr size, eglClientBufferEXT clientBuffer, 171 bitfield flags); 172 173 behaves similarly to BufferStorageExternalEXT, except that the buffer whose 174 storage is to be defined is specified by <buffer> rather than by the current 175 binding to <target>. 176 177 178Errors 179 180 INVALID_OPERATION is generated by BufferStorageExternalEXT if zero is bound to 181 <target>. 182 183 INVALID_OPERATION is generated by BufferStorageExternalEXT, if the 184 BUFFER_IMMUTABLE_STORAGE flag of the buffer bound to <target> is TRUE. 185 186 INVALID_VALUE is generated by BufferStorageExternalEXT if <offset> is not 0. 187 188 INVALID_VALUE is generated by BufferStorageExternalEXT if <size> is 0 189 or negative. 190 191 INVALID_VALUE is generated by BufferStorageExternalEXT if <offset> + <size> 192 exceeds the size of the EGLClientBuffer. 193 194 INVALID_VALUE is generated by BufferStorageExternalEXT if <flags> has any 195 bits set other than those defined above. 196 197 INVALID_VALUE is generated by BufferStorageExternalEXT if <flags> contains 198 MAP_PERSISTENT_BIT_EXT but does not contain at least one of MAP_READ_BIT or 199 MAP_WRITE_BIT. 200 201 INVALID_VALUE is generated by BufferStorageExternalEXT if <flags> contains 202 MAP_COHERENT_BIT_EXT, but does not also contain MAP_PERSISTENT_BIT_EXT. 203 204 INVALID_ENUM is generated by BufferStorageExternalEXT if <target> is not one 205 of the accepted buffer targets. 206 207 INVALID_OPERATION is generated by BufferStorageExternalEXT if the shared 208 buffer is not allocated in a way which permits shared access by the GPU. 209 210 [[ The following is only added if GL_EXT_direct_state_access or 211 GL_ARB_direct_state_access is supported. ]] 212 213 An INVALID_OPERATION error is generated by NamedBufferStorageExternalEXT if 214 the BUFFER_IMMUTABLE_STORAGE_EXT flag of <buffer> is set to TRUE. 215 216Interactions with GL_EXT_direct_state_access, GL_ARB_direct_state_access and 217OpenGL 4.5 218 219 If none of GL_EXT_direct_state_access, GL_ARB_direct_state_access, or 220 OpenGL 4.5, the NamedBufferStorageExternalEXT entry-point is not 221 added and all references to it should be ignored. 222 223Issues 224 225 1. How are possible GPU cache interactions handled? 226 227 The application is responsible for synchronizing writes to the shared buffer 228 by other processing cores (e.g. DSP), and making those available to CPU 229 reads for the processing of client-side GL commands (e.g., BufferSubData). 230 The GL implementation should guarantee that available writes by other cores 231 (e.g., DSP) are visible to the GPU when server-side commands read from the 232 shared buffer. 233 234 PROPOSED: The exact granularity with which available writes from other cores 235 e.g., DSP) become visible to the CPU and GPU is implementation dependent. 236 237 2. Should EGLClientBuffers, be directly referenced by the GL API? 238 239 For images, a set of EGL and client API extensions provide import/export 240 of EGLImages from client APIs and native buffers. The EGLImage also provides 241 lifetime guarantees including orphaning and sibling behavior. This extension 242 is more narrowly focused, specifically targeted to the import of EGLClientBuffers 243 as GL buffers, and requiring the application to manage the resource lifetime. 244 As such, it may not warrant a new EGL object or EGL extension. 245 246 RESOLVED: A corresponding EGL object and extension is not required. When 247 using this extension, applications are expected to cast EGLClientBuffer as 248 GLeglClientBufferEXT. 249 250Revision History 251 252 Rev. Date Author Changes 253 ---- ---------- -------- ----------------------------------------- 254 0.1 04/18/2017 sholmes Initial version. Based on QCOM_shared_buffer. 255 0.2 05/16/2017 jleger Renamed the extension and reworked it to to 256 be an extension to EXT_buffer_storage. 257 0.3 05/24/2017 jleger Add offset parameter and other cleanup. 258 0.4 05/25/2017 jleger Add DSA entrypoint and minor cleanup. 259 1.0 05/29/2017 dgkoch Add interactions with GL, minor cleanup. 260