1Name
2
3    NV_copy_buffer
4
5Name Strings
6
7    GL_NV_copy_buffer
8
9Contact
10
11    Mathias Heyer, NVIDIA Corporation (mheyer 'at' nvidia.com)
12
13Contributors
14
15    From ARB_copy_buffer:
16    Rob Barris, Blizzard Entertainment
17    Bruce Merry, ARM
18    Eric Werness, NVIDIA
19    Greg Roth, NVIDIA
20    Daniel Koch, NVIDIA
21
22Status
23
24    Shipping on Tegra
25
26Version
27
28    Last Modified Date: September 20, 2013
29    Author Revision: 3
30
31Number
32
33    OpenGL ES Extension #158
34
35Dependencies
36
37    Written based on the wording of the OpenGL ES 2.0.25 (Nov, 2010)
38    specification.
39    
40    OES_mapbuffer extension affects the definition of this extension.
41
42Overview
43
44    This extension provides a mechanism to do an accelerated copy from one
45    buffer object to another. This may be useful to load buffer objects
46    in a "loading thread" while minimizing cost and synchronization effort
47    in the "rendering thread."
48
49New Tokens
50
51    Accepted by the target parameters of BindBuffer, BufferData,
52    BufferSubData, MapBufferOES, UnmapBufferOES, 
53    GetBufferPointervOES, GetBufferParameteriv and CopyBufferSubDataNV:
54
55    COPY_READ_BUFFER_NV                    0x8F36
56    COPY_WRITE_BUFFER_NV                   0x8F37
57
58New Procedures and Functions
59
60    void CopyBufferSubDataNV(enum readtarget, enum writetarget,
61                             intptr readoffset, intptr writeoffset,
62                             sizeiptr size);
63
64Additions to Chapter 2 of the OpenGL ES 2.0 Specification (Rasterization)
65
66    Add a new subsection "Copying Between Buffers" to section 2.9:
67
68    All or part of one buffer object's data store may be copied to the
69    data store of another buffer object by calling
70
71    void CopyBufferSubDataNV(enum readtarget, enum writetarget,
72                             intptr readoffset, intptr writeoffset,
73                             sizeiptr size);
74
75    with readtarget and writetarget each set to one of the targets
76    ARRAY_BUFFER, COPY_READ_BUFFER_NV, COPY_WRITE_BUFFER_NV or
77    ELEMENT_ARRAY_BUFFER. While any of these targets may be used,
78    the COPY_READ_BUFFER_NV and COPY_WRITE_BUFFER_NV targets are
79    provided specifically for copies, so that they can be done without
80    affecting other buffer binding targets that may be in use.
81    writeoffset and size specify the range of data in the buffer object
82    bound to writetarget that is to be replaced, in terms of basic machine
83    units. readoffset and size specify the range of data in the buffer
84    object bound to readtarget that is to be copied to the corresponding
85    region of writetarget.
86    
87    A buffer object is bound to COPY_READ_BUFFER_NV or COPY_WRITE_BUFFER_NV
88    by calling BindBuffer with target set to COPY_READ_BUFFER_NV or
89    COPY_WRITE_BUFFER_NV and buffer set to the name of the buffer object.
90    If no corresponding buffer object exists, one is initialized as
91    defined in section 2.9.
92    
93    The commands BufferData, BufferSubData, MapBufferOES, UnmapBufferOES, 
94    GetBufferPointervOES, GetBufferParameteriv (section 6.1.3)  may be used
95    with target set to COPY_READ_BUFFER_NV or COPY_WRITE_BUFFER_NV. In such
96    event, these commands operate in the same fashion as described in section
97    2.9 and 6.3.1 but on the buffer currently bound to target
98    COPY_READ_BUFFER_NV or COPY_WRITE_BUFFER_NV respectively.
99
100    An INVALID_VALUE error is generated if any of readoffset,
101    writeoffset, or size are negative, if readoffset+size exceeds the
102    size of the buffer object bound to readtarget, or if
103    writeoffset+size exceeds the size of the buffer object bound to
104    writetarget.
105
106    An INVALID_VALUE error is generated if the same buffer object is
107    bound to both readtarget and writetarget, and the ranges
108    [readoffset, readoffset+size) and [writeoffset, writeoffset+size)
109    overlap.
110
111    An INVALID_OPERATION error is generated if zero is bound to
112    readtarget or writetarget.
113    
114    An INVALID_OPERATION error is generated if the buffer objects
115    bound to either readtarget or writetarget are mapped.
116
117Additions to the AGL/EGL/GLX/WGL Specifications
118
119    None
120
121Errors
122
123    The error INVALID_VALUE is generated by CopyBufferSubDataNV if
124    readoffset, writeoffset, or size are less than zero, or if
125    readoffset+size is greater than the value of BUFFER_SIZE of
126    readtarget/readBuffer, or if writeoffset+size is greater than the
127    value of BUFFER_SIZE of writetarget/writeBuffer.
128    
129    The error INVALID_OPERATION is generated by CopyBufferSubDataNV if
130    either readtarget/readBuffer or writetarget/writeBuffer are mapped.
131
132    The error INVALID_VALUE is generated by CopyBufferSubDataNV if
133    readtarget/readBuffer and writetarget/writeBuffer are the same
134    buffer object, and the ranges [readoffset, readoffset+size) and
135    [writeoffset, writeoffset+size) overlap.
136
137New State
138
139    (add to table 6.2, Vertex Array State)
140
141                                            Initial
142    Get Value              Type    Get Command Value   Description                 Sec.    
143    ----------------       ----    ----------- ------- --------------------------- ------  
144    COPY_READ_BUFFER_NV    Z+      GetIntegerv 0       Buffer object bound to the  2.9     
145                                                       copy buffer "read" binding
146                                                       point
147    COPY_WRITE_BUFFER_NV   Z+      GetIntegerv 0       Buffer object bound to the  2.9     
148                                                       copy buffer "write"
149                                                       binding point
150
151Issues
152
153    1) How is this extension useful?
154        
155    This can be a desirable replacement to BufferSubData if there are
156    large updates that will pollute the CPU cache. If generating the data
157    can be offloaded to another thread, then the CPU cost of the update
158    in the rendering thread can be very small.
159
160    Finally, if an implementation supports concurrent data transfers in
161    one context/thread while doing rendering in another context/thread,
162    this extension may be used to move data from system memory to video
163    memory in preparation for copying it into another buffer in the
164    rendering thread.
165       
166
167Dependencies on OES_mapbuffer
168
169    If OES_mapbuffer is not present, references to MapBufferOES and
170    UnmapBufferOES should be ignored and language referring to mapped
171    buffer objects should be removed.
172    
173Revision History
174
175    Revision 3, 2013/08/20
176    - minor edits for publishing
177    Revision 2, 2012/04/19
178    - Added explicit interaction with BufferData, BufferSubData, MapBufferOES,
179      UnmapBufferOES, GetBufferPointervOES and GetBufferParameteriv
180    Revision 1, 2012/04/18
181     - Initial draft by starting with a copy of ARB_copy_buffer and stripping
182       it to ES
183
184