1Name 2 3 ARB_sparse_buffer 4 5Name Strings 6 7 GL_ARB_sparse_buffer 8 9Contact 10 11 Graham Sellers (graham.sellers 'at' amd.com) 12 13Contributors 14 15 Graham Sellers, AMD 16 Christophe Riccio, Unity 17 18Notice 19 20 Copyright (c) 2014 The Khronos Group Inc. Copyright terms at 21 http://www.khronos.org/registry/speccopyright.html 22 23Specification Update Policy 24 25 Khronos-approved extension specifications are updated in response to 26 issues and bugs prioritized by the Khronos OpenGL Working Group. For 27 extensions which have been promoted to a core Specification, fixes will 28 first appear in the latest version of that core Specification, and will 29 eventually be backported to the extension document. This policy is 30 described in more detail at 31 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 32 33Status 34 35 Complete. 36 Approved by the ARB on June 26, 2014. 37 Ratified by the Khronos Board of Promoters on August 7, 2014. 38 39Version 40 41 Last Modified Date: 5/31/2016 42 Author Revision: 4 43 44Number 45 46 ARB Extension #172 47 48Dependencies 49 50 OpenGL 4.4 is required. 51 52 This extension interacts with EXT_direct_state_access. 53 54 This extension interacts with ARB_direct_state_access. 55 56 This extension is written against the OpenGL 4.4 (core) specification. 57 58Overview 59 60 The ARB_sparse_texture extension adds to GL a mechanism to decouple the 61 virtual and physical storage requirements of textures and allows an 62 application to create partially populated textures that would 63 over-subscribe available graphics memory if made fully resident. This 64 extension provides like functionality for buffer objects, allowing 65 applications to manage buffer object storage in a similar manner. 66 67New Procedures and Functions 68 69 void BufferPageCommitmentARB(enum target, 70 intptr offset, 71 sizeiptr size, 72 boolean commit); 73 74New Tokens 75 76 Accepted as part of the the <flags> parameter to BufferStorage 77 78 SPARSE_STORAGE_BIT_ARB 0x0400 79 80 Accepted by the <pname> parameter of GetBooleanv, GetDoublev, GetFloatv, 81 GetIntegerv, and GetInteger64v: 82 83 SPARSE_BUFFER_PAGE_SIZE_ARB 0x82F8 84 85Additions to Chapter 6 of the OpenGL 4.4 (core) Specification (Buffer Objects) 86 87 In Section 6.2, "Creating and Modifying Buffer Object Data Stores", add 88 the following to the list of flags accepted by the <flags> parameter 89 to BufferStorage: 90 91 SPARSE_STORAGE_BIT_ARB The data store of the buffer object is sparse, 92 consisting only of a virtual allocation. Physical storage for buffer 93 contents may be later allocated and assigned using 94 BufferPageCommitmentARB. Initially, the entire data store is 95 uncommitted. As a side effect, the data specified in the <data> 96 parameter is discarded, although the GL may still acces the client's 97 address space within the specified region. 98 99 If <flags> contains SPARSE_STORAGE_BIT_ARB, then it may not also 100 contain any combination of MAP_READ_BIT or MAP_WRITE_BIT. 101 102 Add the following to the end of the description of BufferSubData. 103 104 If the target of the operation is sparse and the range specified by 105 <offset> and <size> includes uncommited regions, data destined for those 106 regions is silently discarded. 107 108 Add the following introduction and description of BufferPageCommitmentARB: 109 110 The command 111 112 void BufferPageCommitmentARB(enum target, 113 intptr offset, 114 sizeiptr size, 115 boolean commit); 116 117 may be used to commit and de-commit regions of sparse buffer storage. 118 <target> is set to one of the targets listed in table 6.1. <offset> and 119 <size> indicate the range of the data store's virtual allocation to commit. 120 <offset> must be an integer multiple of the implementation dependent 121 constant SPARSE_BUFFER_PAGE_SIZE_ARB, and <size> must either be a multiple 122 of SPARSE_BUFFER_PAGE_SIZE_ARB, or extend to the end of the buffer's 123 data store. If <commit> is TRUE, then pages contained in the specified 124 range become committed and become physically backed. If <commit> is 125 FALSE, then physical storage associated with the data store in the 126 specified region may be freed and those pages become uncommitted. Newly 127 committed pages have undefined content. However, redundantly committing 128 pages does not alter their content. 129 130 Additionally, the commands 131 132 void NamedBufferPageCommitmentEXT(uint buffer, 133 intptr offset, 134 sizeiptr size, 135 boolean commit); 136 137 void NamedBufferPageCommitmentARB(uint buffer, 138 intptr offset, 139 sizeiptr size, 140 boolean commit); 141 142 behaves similarly to BufferPageCommitmentARB except that the target of 143 the operation is the buffer whose name is specified by <buffer>. 144 145 Add subsection 6.4.1 "Effects of Accessing Uncommitted Regions of Sparse 146 Buffers" 147 148 When a buffer object's SPARSE_STORAGE_BIT_ARB is TRUE, it may be 149 fully or partially uncommitted. Unless otherwise noted, reads from 150 uncommitted regions of a sparse buffer, whether through fixed-function 151 logic or shader access return undefined values, but otherwise do not 152 negatively affect GL operation. Further, unless otherwise noted, attempts 153 to write to such regions are silently ignored. Exceptions to this behavior 154 are noted in the relevant sections of this specification. 155 156Additions to the AGL/GLX/WGL Specifications 157 158 None. 159 160GLX Protocol 161 162 TBD. 163 164Errors 165 166 INVALID_ENUM is generated by BufferPageCommitmentARB if <target> is not one 167 of the accepted buffer targets. 168 169 INVALID_VALUE is generated by BufferStorage if <flags> contains 170 SPARSE_STORAGE_BIT_ARB and <flags> also contains any combination of 171 MAP_READ_BIT or MAP_WRITE_BIT. 172 173 INVALID_OPERATION is generated by BufferPageCommitmentARB if the 174 SPARSE_STORAGE_BIT_ARB of the buffer bound to <target> is FALSE. 175 176 INVALID_VALUE is generated by BufferPageCommitmentARB if <offset> is not 177 an integer multiple of SPARSE_BUFFER_PAGE_SIZE_ARB, or if <size> is not 178 an integer multiple of SPARSE_BUFFER_PAGE_SIZE_ARB and does not extend 179 to the end of the buffer's data store. 180 181 INVALID_VALUE is generated by BufferPageCommitmentARB if either of 182 <offset> or <size> is negative, or if <offset> + <size> is greater than the 183 value of BUFFER_SIZE for the buffer bound to <target>. 184 185New State 186 187 None. 188 189New Implementation Dependent State 190 191 Append to Table 23.55, Implementation Dependent Values 192 193 +-----------------------------------+-------+----------------+----------------+-----------------------------------------+------+ 194 | Get Value | Type | Get Command | Minimum Value | Description | Sec. | 195 +-----------------------------------+-------+----------------+----------------+-----------------------------------------+------+ 196 | SPARSE_BUFFER_PAGE_SIZE_ARB | Z+ | GetIntegerv | 65536 ** | Page size of sparse buffers in bytes. | 6.2 | 197 +-----------------------------------+-------+----------------+----------------+-----------------------------------------+------+ 198 199 ** The value of SPARSE_BUFFER_PAGE_SIZE_ARB is the largest allowed value. 200 Smaller values are permitted and it is recommended to implementors that it 201 be a power of two. 202 203Usage Examples 204 205 TBD 206 207Dependencies on GL_EXT_direct_state_access 208 209 If GL_EXT_direct_state_access is not supported, remove references to 210 NamedBufferPageCommitmentEXT. 211 212 213Dependencies on GL_ARB_direct_state_access 214 215 If GL_ARB_direct_state_access is not supported, remove references to 216 NamedBufferPageCommitmentARB. 217 218 219Issues 220 221 1) What is the effect of reading from or writing to an uncommitted region 222 of a buffer's data store. 223 224 RESOLVED: This is defined (or undefined) on a case-by case basis. If it 225 is not defined in this specification, then reads return undefined data, 226 but never interrupt the GL, and writes are silently ignored. Atomics 227 with return constitute a read-modify-write cycle, where the read 228 produces undefined results and the write is discarded. 229 230 2) Should mapping a sparse buffer be allowed? What is the defined content 231 as seen for the client for unmapped parts of the buffer? 232 233 RESOLVED: No, it's not possible to map a sparse buffer at all. Such 234 functionality could always be added by a future extension. In this 235 extension, we disallow creation of a mappable sparse buffer, which in 236 turns will cause MapBuffer{Range} to fail if a mapping attempt is 237 made. 238 239Revision History 240 241 Rev. Date Author Changes 242 ---- -------- -------- --------------------------------------------- 243 4 5/31/2016 Jon Leech Change dependency from GL 1.5 + ARB_vbo to 244 GL 4.4 (Bug 14117). 245 3 5/16/2014 criccio Added interactions with 246 GL_ARB_direct_state_access 247 2 4/17/2014 gsellers Make it illegal to create a mappable sparse 248 buffer. Add DSA entry point. Change name of 249 SPARSE_BUFFER_PAGE_SIZE_ARB. Allow <size> in 250 BufferPageCommitmentARB to go to the end of 251 the buffer. 252 1 1/1/2014 gsellers Initial revision 253