1Name 2 3 ARB_clear_buffer_object 4 5Name Strings 6 7 GL_ARB_clear_buffer_object 8 9Contact 10 11 Graham Sellers (graham.sellers 'at' amd.com) 12 13Contributors 14 15 Jon Leech 16 Piers Daniell, NVIDIA 17 Mark Kilgard, NVIDIA 18 19Notice 20 21 Copyright (c) 2012-2014 The Khronos Group Inc. Copyright terms at 22 http://www.khronos.org/registry/speccopyright.html 23 24Specification Update Policy 25 26 Khronos-approved extension specifications are updated in response to 27 issues and bugs prioritized by the Khronos OpenGL Working Group. For 28 extensions which have been promoted to a core Specification, fixes will 29 first appear in the latest version of that core Specification, and will 30 eventually be backported to the extension document. This policy is 31 described in more detail at 32 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 33 34Status 35 36 Complete. 37 Approved by the ARB on 2012/06/12. 38 39Version 40 41 Last Modified Date: February 18, 2014 42 Version: 13 43 44Number 45 46 ARB Extension #121 47 48Dependencies 49 50 OpenGL 1.5 is required. 51 52 The definition of this extension is dependent on EXT_direct_state_access. 53 54 This extension is written against the OpenGL 4.2 (Core) Specification. 55 56Overview 57 58 Buffer objects are fundamental to the operation of OpenGL. Buffers are used 59 as a source of data for vertices and indices, read through buffer textures 60 in shaders, used to transfer texture and image data into and out of 61 textures and framebuffers, and may be written to by operations such as 62 transform feedback. OpenGL contains mechanisms to copy sections of buffers 63 from one to another, but it has no mechanism to initialize the content 64 of a buffer to a known value. In effect, it has memcpy, but not memset. 65 66 This extension adds such a mechanism and has several use cases. Examples 67 include clearing a pixel unpack buffer before transferring data to 68 a texture or resetting buffer data to a known value before sparse updates 69 through shader image stores or transform feedback. 70 71IP Status 72 73 No known IP claims. 74 75New Procedures and Functions 76 77 void ClearBufferData(enum target, 78 enum internalformat, 79 enum format, 80 enum type, 81 const void * data); 82 83 void ClearBufferSubData(enum target, 84 enum internalformat, 85 intptr offset, 86 sizeiptr size, 87 enum format, 88 enum type, 89 const void * data); 90 91 When EXT_direct_state_access is present: 92 93 void ClearNamedBufferDataEXT(uint buffer, 94 enum internalformat, 95 enum format, 96 enum type, 97 const void * data); 98 99 void ClearNamedBufferSubDataEXT(uint buffer, 100 enum internalformat, 101 intptr offset, 102 sizeiptr size, 103 enum format, 104 enum type, 105 const void * data); 106 107New Tokens 108 109 None. 110 111Additions to Chapter 2 of the OpenGL 4.2 (Core Profile) Specification 112(OpenGL Operation) 113 114Append to the end of Section 2.9.2, "Creating Buffer Object Stores" 115 116 To fill all or part of an existing buffer object's data store with a 117 constant value, call 118 119 void ClearBufferSubData(enum target, 120 enum internalformat, 121 sizeiptr offset, 122 sizeiptr size, 123 enum format, 124 enum type, 125 const void * data); 126 127 with <target> set to the target to which the destination buffer is bound. 128 <target> must be one of the targets listed in Table 2.8. 129 <internalformat> must be set to one of the format tokens listed in Table 130 3.15, "Internal formats for buffer textures". <format> and <type> specify 131 the format and type of the source data and are interpreted as described in 132 Section 3.7.2. <offset> set to the offset, measured in basic 133 machine units, into the buffer object's data store from which to begin 134 filling, and <size> set to the size, also in basic machine units, of the 135 range to fill. Both <offset> and <range> must be multiples of the number 136 of basic machine units per-element for that internal format specified by 137 <internalformat>, otherwise the error INVALID_VALUE is generated. 138 <data> is a pointer to an array of between one and four components 139 containing the data to be used as the source of the constant fill value. 140 The elements of <data> are converted by the GL into the format specified by 141 <internalformat> in the manner described in section 2.3.1, and then used to 142 fill the specified range of the destination buffer. If <data> is NULL, then 143 the pointer is ignored and the sub-range of the buffer is filled with zeros. 144 145 If <offset> or <size> is less than zero, or if <offset> + <size> is 146 greater than the value of BUFFER_SIZE for the buffer bound to <target> 147 then the error INVALID_VALUE is generated. The command 148 149 An INVALID_OPERATION error is generated if any part of the specified 150 range of the buffer bound to <target> is currently mapped. 151 152 void ClearBufferData(enum target, 153 enum internalformat, 154 enum format, 155 enum type, 156 const void * data); 157 158 is equivalent to calling ClearBufferSubData with <target>, 159 <internalformat> and <data> as specified, with <offset> set to zero, 160 and <size> set to the value of BUFFER_SIZE for the buffer bound to 161 <target>. 162 163 The commands: 164 165 void ClearNamedBufferDataEXT(uint buffer, 166 enum internalformat, 167 enum format, 168 enum type, 169 const void * data); 170 171 and 172 173 void ClearNamedBufferSubDataEXT(uint buffer, 174 enum internalformat, 175 sizeiptr offset, 176 sizeiptr size, 177 enum format, 178 enum type, 179 const void * data); 180 181 are equivalent to calling ClearBufferData and ClearBufferSubData, 182 respectively, except that the buffer object to be accessed is specified 183 in the <buffer> parameter rather than being derived from the <target> 184 buffer binding point. 185 186Additions to Chapter 3 of the OpenGL 4.2 (Core Profile) Specification 187(Rasterization) 188 189 None. 190 191Additions to Chapter 4 of the OpenGL 4.2 (Core Profile) Specification 192(Per-Fragment Operations and the Frame Buffer) 193 194 None. 195 196Additions to Chapter 5 of the OpenGL 4.2 (Core Profile) Specification 197(Special Functions) 198 199 None. 200 201Additions to Chapter 6 of the OpenGL 4.2 (Core Profile) Specification 202(State and State Requests) 203 204 None. 205 206Errors 207 208 INVALID_ENUM is generated by ClearBufferSubData if <internalformat> 209 is not one of the sized internal format identifiers listed in Table 3.15. 210 211 INVAILD_ENUM is generated by ClearBufferSubData <target> is not a legal 212 buffer binding point. 213 214 INVALID_ENUM is generated by ClearBufferSubData if <format> or <type> is 215 not one of the supported format or type tokens. 216 217 INVALID_VALUE is generated by ClearBufferSubData if <offset> 218 or <size> is less than zero. 219 220 INVALID_VALUE is generated by ClearBufferSubData if no buffer is bound 221 to the binding point indicated by <target>. 222 223 INVALID_VALUE is generated by ClearBufferSubData if <offset> + 224 <size> is greater than the value of BUFFER_SIZE for the buffer bound to 225 <target>. 226 227 INVALID_VALUE is generated by ClearBufferSubData if <offset> or <size> 228 is not an integer multiple of the element size indicated by 229 <internalformat>. The element size is the number of components for 230 <internalformat> from table 3.15 multiplied by the size of the base type 231 for <internalformat> in that table. 232 233 INVALID_OPERATION is generated by ClearBufferSubData if any part of the 234 specified range of the buffer bound to <target> is currently mapped. 235 236New State 237 238 None. 239 240Dependencies on EXT_direct_state_access 241 242 If EXT_direct_state_access is not supported, then remove all references to 243 ClearNamedBufferDataEXT and ClearNamedBufferSubDataEXT. 244 245Conformance Tests 246 247 TBD 248 249Issues 250 251 1) Do we need to have restrictions on the alignment of <offset> and/or 252 <size> for ClearBufferSubData 253 254 RESOLVED: Yes, we restrict both <offset> and <size> to be integer 255 multiples of the element size for the format indicated by 256 <internalformat>. 257 258 2) Should the ClearBufferObject take int/float/uint types, or take 259 format + type poarameters more like glTexImage2D etc.? 260 261 RESOLVED: ClearBufferSubData takes an <internalformat> parameter 262 to indicate the internal storage format for the buffer, and 263 a <format> and <type> parameter for the application-supplied data. 264 This is consistent with APIs such as TexSubImagenD. 265 266 3) Currently, the legal tokens for <internalformat> are taken from the 267 texture internal format types in table 3.12. Is this sufficient? 268 Do we need to also allow other formats such as those in table 3.22 269 (image formats), or table 3.2 (packed pixel formats). 270 271 RESOLVED: Updated in revision 4 to use table 3.15, which is actually 272 more concise than 3.12. However, it represents the complete list 273 of formats that are reasonably easily filled by existing hardware. 274 If the application bit-packs other formats, this should be sufficient 275 for the intended use-cases of this extension. 276 277 4) Do we want DSA-style ClearNamedBufferSubData, ClearNamedBufferData? 278 279 RESOLVED: Yes. Documented dependency on EXT_dsa. 280 281 5) How do we specify data formats that are not supported for buffer 282 textures - for example, R3_G3_B2 or RGB10_A2? 283 284 RESOLVED: It is the application's responsibility to bit-pack the 285 components of the source data into a number of native types (unsigned 286 bytes, shorts or ints), and then pass them using a supported internal 287 format. 288 289Revision History 290 291 Rev. Date Author Changes 292 ---- ---------- -------- --------------------------------------------- 293 13 02/18/2014 Jon Leech Change order of ClearBufferSubData arguments 294 in spec body to be consistent with New 295 Procedures declaration ((offset,size,format, 296 type) instead of the erroneous (format,type, 297 offset,size)) (Public Bug 1122). 298 299 12 12/12/2013 Jon Leech Change order of ClearNamedBufferSubDataEXT 300 arguments in spec body to be consistent with 301 New Procedures declaration ((offset, 302 size,format,type) instead of the erroneous 303 (format,type,offset,size)) (Bug 11378). 304 305 11 08/07/2013 mjk Better indicate DSA entrypoints 306 307 10 09/12/2012 Jon Leech Modify error condition when the target buffer 308 is mapped to only be generated when the 309 mapped region intersects the region being 310 cleared (bug 9343). 311 312 9 07/25/2012 Jon Leech Fix typos from bug 8935. 313 314 8 07/23/2012 Jon Leech Clarify offset/alignment constraints as 315 based on the total size of a texel in 316 <internalformat>. 317 318 7 06/28/2012 pdaniell Modify the parameter order of the *SubData 319 functions to match the ordering of 320 TexSubImage parameters. Also change the 321 <offset> parameter to intptr. 322 323 6 05/29/2012 Jon Leech Fix capitalization of <internalformat>. 324 325 5 05/15/2012 Jon Leech Fix typo in error condition. 326 327 4 04/26/2012 gsellers Add interaction with EXT_dsa, resolve issue 4. 328 Document <format> and <type> parameters. 329 Correct reference to Table 3.15 (Internal 330 formats for buffer textures). 331 Resolve issue 3. Add issue 5. 332 Change behavior of NULL for <data> to fill the 333 buffer subrange with zeros. 334 3 04/02/2012 gsellers Delete 'either/or' approach. 335 Change API to texture-like ClearBufferSubData. 336 Resolve issues (1) + (2). 337 Address feedback from bug 8132. 338 Add issues (3) and (4). 339 2 12/19/2011 gsellers Rename to ARB. Strip suffixes from APIs. 340 Add format + type versions of APIs for 341 consideration. Allow NULL for <data> in 342 ClearBufferRange. 343 1 09/27/2011 gsellers Initial draft 344