1Name 2 3 ARB_copy_buffer 4 5Name Strings 6 7 GL_ARB_copy_buffer 8 9Contact 10 11 Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com) 12 13Contributors 14 15 Rob Barris, Blizzard Entertainment 16 Bruce Merry, ARM 17 Eric Werness, NVIDIA 18 Greg Roth, NVIDIA 19 20Notice 21 22 Copyright (c) 2009-2013 The Khronos Group Inc. Copyright terms at 23 http://www.khronos.org/registry/speccopyright.html 24 25Specification Update Policy 26 27 Khronos-approved extension specifications are updated in response to 28 issues and bugs prioritized by the Khronos OpenGL Working Group. For 29 extensions which have been promoted to a core Specification, fixes will 30 first appear in the latest version of that core Specification, and will 31 eventually be backported to the extension document. This policy is 32 described in more detail at 33 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 34 35Status 36 37 Complete. Approved by the ARB on March 19, 2009. 38 39Version 40 41 Last Modified Date: September 6, 2017 42 Author Revision: 7 43 44Number 45 46 ARB Extension #59 47 48Dependencies 49 50 Written based on the wording of the OpenGL 3.0 (August 11, 2008 draft) 51 specification. 52 53Overview 54 55 This extension provides a mechanism to do an accelerated copy from one 56 buffer object to another. This may be useful to load buffer objects 57 in a "loading thread" while minimizing cost and synchronization effort 58 in the "rendering thread." 59 60IP Status 61 62 No known IP claims. 63 64New Tokens 65 66 Accepted by the target parameters of BindBuffer, BufferData, 67 BufferSubData, MapBuffer, UnmapBuffer, GetBufferSubData, 68 GetBufferPointerv, MapBufferRange, FlushMappedBufferRange, 69 GetBufferParameteriv, BindBufferRange, BindBufferBase, 70 and CopyBufferSubData: 71 72 COPY_READ_BUFFER 0x8F36 73 COPY_WRITE_BUFFER 0x8F37 74 75New Procedures and Functions 76 77 void CopyBufferSubData(enum readtarget, enum writetarget, 78 intptr readoffset, intptr writeoffset, 79 sizeiptr size); 80 81Additions to Chapter 2 of the OpenGL 3.0 Specification (Rasterization) 82 83 Add a new subsection "Copying Between Buffers" to section 2.9: 84 85 All or part of one buffer object's data store may be copied to the 86 data store of another buffer object by calling 87 88 void CopyBufferSubData(enum readtarget, enum writetarget, 89 intptr readoffset, intptr writeoffset, 90 sizeiptr size); 91 92 with readtarget and writetarget each set to one of the targets 93 ARRAY_BUFFER, COPY_READ_BUFFER, COPY_WRITE_BUFFER, 94 ELEMENT_ARRAY_BUFFER, PIXEL_PACK_BUFFER, PIXEL_UNPACK_BUFFER, 95 TEXTURE_BUFFER, TRANSFORM_FEEDBACK_BUFFER, or UNIFORM_BUFFER. While 96 any of these targets may be used, the COPY_READ_BUFFER and 97 COPY_WRITE_BUFFER targets are provided specifically for copies, so 98 that they can be done without affecting other buffer binding targets 99 that may be in use. writeoffset and size specify the range of data 100 in the buffer object bound to writetarget that is to be replaced, in 101 terms of basic machine units. readoffset and size specify the range 102 of data in the buffer object bound to readtarget that is to be 103 copied to the corresponding region of writetarget. 104 105 An INVALID_VALUE error is generated if any of readoffset, 106 writeoffset, or size are negative, if readoffset+size exceeds the 107 size of the buffer object bound to readtarget, or if 108 writeoffset+size exceeds the size of the buffer object bound to 109 writetarget. 110 111 An INVALID_VALUE error is generated if the same buffer object is 112 bound to both readtarget and writetarget, and the ranges 113 [readoffset, readoffset+size) and [writeoffset, writeoffset+size) 114 overlap. 115 116 An INVALID_OPERATION error is generated if zero is bound to 117 readtarget or writetarget. 118 119 An INVALID_OPERATION error is generated if the buffer objects bound 120 to either readtarget or writetarget are mapped. 121 122Additions to Chapter 5 of the OpenGL 3.0 Specification (Special Functions) 123 124 Add to the list (page 310) of "Vertex Buffer Objects" commands "not 125 compiled into the display list but are executed immediately": 126 127 CopyBufferSubData 128 129Additions to the AGL/EGL/GLX/WGL Specifications 130 131 None 132 133GLX Protocol 134 135 The following single command is sent to the server as 136 a glxsingle request: 137 138 CopyBufferSubData 139 140 1 CARD8 opcode 141 1 221 GLX opcode 142 2 10 request length 143 4 GLX_CONTEXT_TAG context tag 144 8 CARD64 readoffset 145 8 CARD64 writeoffset 146 8 CARD64 size 147 4 ENUM readtarget 148 4 ENUM writetarget 149 150Errors 151 152 The error INVALID_VALUE is generated by CopyBufferSubData if 153 readoffset, writeoffset, or size are less than zero, or if 154 readoffset+size is greater than the value of BUFFER_SIZE of 155 readtarget/readBuffer, or if writeoffset+size is greater than the 156 value of BUFFER_SIZE of writetarget/writeBuffer. 157 158 The error INVALID_OPERATION is generated by CopyBufferSubData if 159 either readtarget/readBuffer or writetarget/writeBuffer are mapped. 160 161 The error INVALID_VALUE is generated by CopyBufferSubData if 162 readtarget/readBuffer and writetarget/writeBuffer are the same 163 buffer object, and the ranges [readoffset, readoffset+size) and 164 [writeoffset, writeoffset+size) overlap. 165 166New State 167 168 (add to table 6.52, Miscellaneous State, p. 390) 169 170 Initial 171 Get Value Type Get Command Value Description Sec. Attribute 172 ---------------- ---- ----------- ------- --------------------------- ------ --------- 173 COPY_READ_BUFFER Z+ GetIntegerv 0 Buffer object bound to the 2.9 none 174 copy buffer "read" binding 175 point 176 COPY_WRITE_BUFFE Z+ GetIntegerv 0 Buffer object bound to the 2.9 none 177 copy buffer "write" 178 binding point 179 180Usage Examples 181 182 Replace BufferSubData with a non-cache-polluting update: 183 184 BindBuffer(COPY_READ_BUFFER, tempBuffer); 185 BufferData(COPY_READ_BUFFER, updateSize, NULL, STREAM_DRAW); 186 // this may return a WriteCombined mapping! 187 ptr = MapBuffer(COPY_READ_BUFFER, WRITE_ONLY); 188 // fill ptr 189 UnmapBuffer(COPY_READ_BUFFER); 190 191 BindBuffer(COPY_WRITE_BUFFER, vtxBuffer); 192 // this copy ideally requires no CPU work on the data itself. 193 CopyBufferSubData(COPY_READ_BUFFER, COPY_WRITE_BUFFER, 194 0, writeoffset, updateSize); 195 196Issues 197 198 1) What should the new targets and parameters be named? READ/WRITE? 199 SOURCE/DEST? Something else? 200 201 RESOLVED: READ and WRITE, because it's consistent with the <access> 202 parameters and state. 203 204 2) How is this extension useful? 205 206 This can be a desirable replacement to BufferSubData if there are 207 large updates that will pollute the CPU cache. If generating the data 208 can be offloaded to another thread, then the CPU cost of the update 209 in the rendering thread can be very small. 210 211 This can also be an alternate mechanism to MapBufferRange with the 212 MAP_UNSYNCHRONIZED_BIT, by allowing the CPU to write into a temp 213 buffer and then scheduling the update to be in-band with the 214 rendering. MAP_UNSYNCHRONIZED_BIT can lead to hard-to-detect 215 synchronization bugs if the GPU hasn't finished consuming the data 216 that is overwritten (Write After Read hazard). Also, mapping a buffer 217 may, on some implementations, require forcing the data store into a 218 memory space more local to the CPU than to the GPU, which can adversely 219 affect rendering performance. 220 221 Finally, if an implementation supports concurrent data transfers in 222 one context/thread while doing rendering in another context/thread, 223 this extension may be used to move data from system memory to video 224 memory in preparation for copying it into another buffer, or texture, 225 etc., in the rendering thread. 226 227 (3) Why don't the new tokens and entry points in this extension have 228 "ARB" suffixes like other ARB extensions? 229 230 RESOLVED: Unlike most ARB extensions, this is a strict subset of 231 functionality already approved in OpenGL 3.1. This extension 232 exists only to support that functionality on older hardware that 233 cannot implement a full OpenGL 3.1 driver. Since there are no 234 possible behavior changes between the ARB extension and core 235 features, source code compatibility is improved by not using 236 suffixes on the extension. 237 238Revision History 239 240 Revision 1, 2008/09/09 241 - Initial draft 242 Revision 2, 2008/09/26 243 - Make EXT_direct_state_access interaction explicit. 244 Revision 3, 2008/10/10 245 - Fix missing entry points for the new targets. 246 Revision 4, 2009/03/13 247 - Move Named* entry point to EXT_direct_state_access. 248 Revision 5, 2009/03/19 249 - ARBify and remove ARB suffix from entry points and tokens. 250 Revision 6, 2009/06/03 251 - Add buffer target list and fix capitalization differences on 252 parameter names per feedback from Jonathan Knispel 253 Revision 7, 2017/09/06 254 - Add GLX protocol. 255