1Name 2 3 EXT_map_buffer_range 4 5Name Strings 6 7 GL_EXT_map_buffer_range 8 9Contributors 10 11 Contributors to ARB_map_buffer_range desktop OpenGL extension from which 12 this extension borrows heavily 13 14Contact 15 16 Benj Lipchak (lipchak 'at' apple 'dot' com) 17 18Status 19 20 Complete 21 22Version 23 24 Last Modified Date: August 21, 2014 25 Author Revision: 4 26 27Number 28 29 OpenGL ES Extension #121 30 31Dependencies 32 33 OpenGL ES 1.1 or OpenGL ES 2.0 is required. 34 35 OES_mapbuffer is required. 36 37 This specification is written against the OpenGL ES 2.0.25 specification. 38 39Overview 40 41 EXT_map_buffer_range expands the buffer object API to allow greater 42 performance when a client application only needs to write to a sub-range 43 of a buffer object. To that end, this extension introduces two new buffer 44 object features: non-serialized buffer modification and explicit sub-range 45 flushing for mapped buffer objects. 46 47 OpenGL requires that commands occur in a FIFO manner meaning that any 48 changes to buffer objects either block until the data has been processed by 49 the OpenGL pipeline or else create extra copies to avoid such a block. By 50 providing a method to asynchronously modify buffer object data, an 51 application is then able to manage the synchronization points themselves 52 and modify ranges of data contained by a buffer object even though OpenGL 53 might still be using other parts of it. 54 55 This extension also provides a method for explicitly flushing ranges of a 56 mapped buffer object so OpenGL does not have to assume that the entire 57 range may have been modified. Further, it allows the application to more 58 precisely specify its intent with respect to reading, writing, and whether 59 the previous contents of a mapped range of interest need be preserved 60 prior to modification. 61 62New Procedures and Functions 63 64 void *MapBufferRangeEXT(enum target, intptr offset, sizeiptr length, 65 bitfield access); 66 67 void FlushMappedBufferRangeEXT(enum target, intptr offset, 68 sizeiptr length); 69 70 71New Tokens 72 73 Accepted by the <access> parameter of MapBufferRangeEXT: 74 75 MAP_READ_BIT_EXT 0x0001 76 MAP_WRITE_BIT_EXT 0x0002 77 MAP_INVALIDATE_RANGE_BIT_EXT 0x0004 78 MAP_INVALIDATE_BUFFER_BIT_EXT 0x0008 79 MAP_FLUSH_EXPLICIT_BIT_EXT 0x0010 80 MAP_UNSYNCHRONIZED_BIT_EXT 0x0020 81 82 83Additions to Chapter 2 of the OpenGL ES 2.0 Specification (OpenGL ES Operation) 84 85 Add to the end of Section 2.9 "Buffer Objects" (p. 24): 86 87 All or part of the data store of a buffer object may be mapped into the 88 client's address space by calling 89 90 void *MapBufferRangeEXT(enum target, intptr offset, sizeiptr length, 91 bitfield access); 92 93 with <target> set to ARRAY_BUFFER or ELEMENT_ARRAY_BUFFER. 94 <offset> and <length> indicate the range of data in the 95 buffer object that is to be mapped, in terms of basic machine units. 96 <access> is a bitfield containing flags which describe the requested 97 mapping. These flags are described below. 98 99 If no error occurs, a pointer to the beginning of the mapped range is 100 returned once all pending operations on that buffer have completed, and 101 may be used to modify and/or query the corresponding range of the buffer, 102 according to the following flag bits set in <access>: 103 104 * MAP_READ_BIT_EXT indicates that the returned pointer may be used to 105 read buffer object data. No GL error is generated if the pointer is used 106 to query a mapping which excludes this flag, but the result is undefined 107 and system errors (possibly including program termination) may occur. 108 109 * MAP_WRITE_BIT_EXT indicates that the returned pointer may be used to 110 modify buffer object data. No GL error is generated if the pointer is used 111 to modify a mapping which excludes this flag, but the result is undefined 112 and system errors (possibly including program termination) may occur. 113 114 Pointer values returned by MapBufferRangeEXT may not be passed as 115 parameter values to GL commands. For example, they may not be used to 116 specify array pointers, or to specify or query pixel or texture image 117 data; such actions produce undefined results, although implementations 118 may not check for such behavior for performance reasons. 119 120 Mappings to the data stores of buffer objects may have nonstandard 121 performance characteristics. For example, such mappings may be marked as 122 uncacheable regions of memory, and in such cases reading from them may be 123 very slow. To ensure optimal performance, the client should use the 124 mapping in a fashion consistent with the values of BUFFER_USAGE and 125 <access>. Using a mapping in a fashion inconsistent with these values is 126 liable to be multiple orders of magnitude slower than using normal memory. 127 128 The following optional flag bits in <access> may be used to modify the 129 mapping: 130 131 * MAP_INVALIDATE_RANGE_BIT_EXT indicates that the previous contents of 132 the specified range may be discarded. Data within this range are undefined 133 with the exception of subsequently written data. No GL error is generated 134 if subsequent GL operations access unwritten data, but the result is 135 undefined and system errors (possibly including program termination) may 136 occur. This flag may not be used in combination with MAP_READ_BIT_EXT. 137 138 * MAP_INVALIDATE_BUFFER_BIT_EXT indicates that the previous contents of 139 the entire buffer may be discarded. Data within the entire buffer are 140 undefined with the exception of subsequently written data. No GL error is 141 generated if subsequent GL operations access unwritten data, but the 142 result is undefined and system errors (possibly including program 143 termination) may occur. This flag may not be used in combination with 144 MAP_READ_BIT_EXT. 145 146 * MAP_FLUSH_EXPLICIT_BIT_EXT indicates that one or more discrete 147 subranges of the mapping may be modified. When this flag is set, 148 modifications to each subrange must be explicitly flushed by calling 149 FlushMappedBufferRangeEXT. No GL error is set if a subrange of the 150 mapping is modified and not flushed, but data within the corresponding 151 subrange of the buffer is undefined. This flag may only be used in 152 conjunction with MAP_WRITE_BIT_EXT. When this option is selected, 153 flushing is strictly limited to regions that are explicitly indicated 154 with calls to FlushMappedBufferRangeEXT prior to unmap; if this 155 option is not selected UnmapBufferOES will automatically flush the entire 156 mapped range when called. 157 158 * MAP_UNSYNCHRONIZED_BIT_EXT indicates that the GL should not attempt 159 to synchronize pending operations on the buffer prior to returning from 160 MapBufferRangeEXT. No GL error is generated if pending operations which 161 source or modify the buffer overlap the mapped region, but the result of 162 such previous and any subsequent operations is undefined. 163 164 A successful MapBufferRangeEXT sets buffer object state values as shown 165 in table 2.mbr. 166 167 Name Value 168 ------------------- ----- 169 BUFFER_ACCESS_FLAGS <access> 170 BUFFER_MAPPED TRUE 171 BUFFER_MAP_POINTER pointer to the data store 172 BUFFER_MAP_OFFSET <offset> 173 BUFFER_MAP_LENGTH <length> 174 175 Table 2.mbr: Buffer object state set by MapBufferRangeEXT. 176 177 If an error occurs, MapBufferRangeEXT returns a NULL pointer. 178 179 An INVALID_VALUE error is generated if <offset> or <length> is negative, 180 if <offset> + <length> is greater than the value of BUFFER_SIZE, or if 181 <access> has any bits set other than those defined above. 182 183 An INVALID_OPERATION error is generated for any of the following 184 conditions: 185 186 * <length> is zero. 187 * The buffer is already in a mapped state. 188 * Neither MAP_READ_BIT_EXT nor MAP_WRITE_BIT_EXT is set. 189 * MAP_READ_BIT_EXT is set and any of MAP_INVALIDATE_RANGE_BIT_EXT, 190 MAP_INVALIDATE_BUFFER_BIT_EXT, or MAP_UNSYNCHRONIZED_BIT_EXT is set. 191 * MAP_FLUSH_EXPLICIT_BIT_EXT is set and MAP_WRITE_BIT_EXT is not set. 192 193 An OUT_OF_MEMORY error is generated if MapBufferRangeEXT fails because 194 memory for the mapping could not be obtained. 195 196 No error is generated if memory outside the mapped range is modified or 197 queried, but the result is undefined and system errors (possibly including 198 program termination) may occur. 199 200 If a buffer is mapped with the MAP_FLUSH_EXPLICIT_BIT_EXT flag, 201 modifications to the mapped range may be indicated by calling 202 203 void FlushMappedBufferRangeEXT(enum target, intptr offset, 204 sizeiptr length); 205 206 with <target> set to ARRAY_BUFFER or ELEMENT_ARRAY_BUFFER. <offset> and 207 <length> indicate a modified subrange of the mapping, in basic machine 208 units. The specified subrange to flush is relative to the start of the 209 currently mapped range of buffer. FlushMappedBufferRangeEXT may be 210 called multiple times to indicate distinct subranges of the mapping which 211 require flushing. 212 213 An INVALID_VALUE error is generated if <offset> or <length> is negative, 214 or if <offset> + <length> exceeds the size of the mapping. 215 216 An INVALID_OPERATION error is generated if zero is bound to <target>. 217 218 An INVALID_OPERATION error is generated if the buffer bound to <target> 219 is not mapped, or is mapped without the MAP_FLUSH_EXPLICIT_BIT_EXT flag. 220 221New Implementation Dependent State 222 223 None 224 225Usage Examples 226 227 /* bind and initialize a buffer object */ 228 int size = 65536; 229 glBindBuffer(GL_ARRAY_BUFFER, 1); 230 glBufferData(GL_ARRAY_BUFFER, size, NULL, GL_DYNAMIC_DRAW); 231 232/* the following are not meant to be executed as a group, since there are no 233 * unmap calls shown here - they are meant to show different combinations of 234 * map options in conjunction with MapBufferRangeEXT and 235 * FlushMappedBufferRangeEXT. 236 */ 237 238 /* Map the entire buffer with read and write 239 * (identical semantics to MapBufferOES). 240 */ 241 void *ptr = glMapBufferRangeEXT(GL_ARRAY_BUFFER, 0, size, 242 MAP_READ_BIT_EXT | MAP_WRITE_BIT_EXT); 243 244 /* Map the entire buffer as write only. 245 */ 246 void *ptr = glMapBufferRangeEXT(GL_ARRAY_BUFFER, 0, size, 247 MAP_WRITE_BIT_EXT); 248 249 250 /* Map the last 1K bytes of the buffer as write only. 251 */ 252 void *ptr = glMapBufferRangeEXT(GL_ARRAY_BUFFER, size-1024, 1024, 253 MAP_WRITE_BIT_EXT); 254 255 256 /* Map the last 1K bytes of the buffer as write only, and invalidate the 257 * range. Locations within that range can assume undefined values. 258 * Locations written while mapped take on new values as expected. 259 * No changes occur outside the range mapped. 260 */ 261 void *ptr = glMapBufferRangeEXT(GL_ARRAY_BUFFER, size-1024, 1024, 262 MAP_WRITE_BIT_EXT | MAP_INVALIDATE_RANGE_BIT_EXT); 263 264 265 /* Map the first 1K bytes of the buffer as write only, and invalidate the 266 * entire buffer. All locations within the buffer can assume undefined 267 * values. Locations written while mapped take on new values as expected. 268 */ 269 void *ptr = glMapBufferRangeEXT(GL_ARRAY_BUFFER, 0, 1024, 270 MAP_WRITE_BIT_EXT | MAP_INVALIDATE_BUFFER_BIT_EXT); 271 272 273 /* Map the first 32K bytes of the buffer as write only, and invalidate 274 * that range. Indicate that we will explicitly inform GL which ranges are 275 * actually written. Locations within that range can assume undefined 276 * values. Only the locations which are written and subsequently flushed 277 * are guaranteed to take on defined values. 278 * Write data to the first 8KB of the range, then flush it. 279 * Write data to the last 8KB of the range, then flush it. 280 */ 281 void *ptr = glMapBufferRangeEXT(GL_ARRAY_BUFFER, 0, 32768, 282 MAP_WRITE_BIT_EXT | MAP_INVALIDATE_RANGE_BIT_EXT | 283 MAP_FLUSH_EXPLICIT_BIT_EXT); 284 285 memset(ptr, 0x00, 8192); /* write zeroes to first 8KB of range */ 286 glFlushMappedBufferRangeEXT(GL_ARRAY_BUFFER, 0, 8192); 287 288 memset(((char*)ptr)+24576, 0xFF, 8192);/* write FFs to last 8KB of range */ 289 glFlushMappedBufferRangeEXT(GL_ARRAY_BUFFER, 24576, 8192); 290 291 292 /* Map the entire buffer for write - unsynchronized. 293 * GL will not block for prior operations to complete. Application must 294 * use other synchronization techniques to ensure correct operation. 295 */ 296 void *ptr = glMapBufferRangeEXT(GL_ARRAY_BUFFER, 0, size, 297 MAP_WRITE_BIT_EXT | MAP_UNSYNCHRONIZED_BIT_EXT); 298 299 300Revision History 301 302 Version 4, 2014/08/21 - Fix typo OES_map_buffer -> OES_mapbuffer. 303 Version 3, 2012/06/21 - Recast from APPLE to multivendor EXT 304 Version 2, 2012/06/18 - Correct spec to indicate ES 1.1 may also be okay. 305 Version 1, 2012/06/01 - Conversion from ARB_map_buffer_range to 306 APPLE_map_buffer_range for ES. 307