1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
<!DOCTYPE refentry [ <!ENTITY % mathent SYSTEM "math.ent"> %mathent; ]>
<!-- Converted by db4-upgrade version 1.1 -->
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="glBufferSubData">
<info>
<copyright>
<year>2005</year>
<holder>Sams Publishing</holder>
</copyright>
<copyright>
<year>2010-2014</year>
<holder>Khronos Group</holder>
</copyright>
</info>
<refmeta>
<refentrytitle>glBufferSubData</refentrytitle>
<manvolnum>3G</manvolnum>
</refmeta>
<refnamediv>
<refname>glBufferSubData</refname>
<refname>glNamedBufferSubData</refname>
<refpurpose>updates a subset of a buffer object's data store</refpurpose>
</refnamediv>
<refsynopsisdiv><title>C Specification</title>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>glBufferSubData</function></funcdef>
<paramdef>GLenum <parameter>target</parameter></paramdef>
<paramdef>GLintptr <parameter>offset</parameter></paramdef>
<paramdef>GLsizeiptr <parameter>size</parameter></paramdef>
<paramdef>const GLvoid * <parameter>data</parameter></paramdef>
</funcprototype>
<funcprototype>
<funcdef>void <function>glNamedBufferSubData</function></funcdef>
<paramdef>GLuint <parameter>buffer</parameter></paramdef>
<paramdef>GLintptr <parameter>offset</parameter></paramdef>
<paramdef>GLsizei <parameter>size</parameter></paramdef>
<paramdef>const void *<parameter>data</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</refsynopsisdiv>
<refsect1 xml:id="parameters"><title>Parameters</title>
<variablelist>
<varlistentry>
<term><parameter>target</parameter></term>
<listitem>
<para>
Specifies the target to which the buffer object is bound
for <function>glBufferSubData</function>, which must be
one of the buffer binding targets in the following
table:
</para>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="bufferbindings.xml"/>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>buffer</parameter></term>
<listitem>
<para>
Specifies the name of the buffer object
for <function>glNamedBufferSubData</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>offset</parameter></term>
<listitem>
<para>
Specifies the offset into the buffer object's data store
where data replacement will begin, measured in bytes.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>size</parameter></term>
<listitem>
<para>
Specifies the size in bytes of the data store region
being replaced.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>data</parameter></term>
<listitem>
<para>
Specifies a pointer to the new data that will be copied
into the data store.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 xml:id="description"><title>Description</title>
<para>
<function>glBufferSubData</function> and
<function>glNamedBufferSubData</function> redefine some or all
of the data store for the specified buffer object. Data starting
at byte offset <parameter>offset</parameter> and extending for
<parameter>size</parameter> bytes is copied to the data store
from the memory pointed to by <parameter>data</parameter>.
<parameter>offset</parameter> and <parameter>size</parameter>
must define a range lying entirely within the buffer object's
data store.
</para>
</refsect1>
<refsect1 xml:id="notes"><title>Notes</title>
<para>
When replacing the entire data store, consider using
<function>glBufferSubData</function> rather than completely
recreating the data store with
<function>glBufferData</function>. This avoids the cost of
reallocating the data store.
</para>
<para>
Consider using multiple buffer objects to avoid stalling the
rendering pipeline during data store updates. If any rendering
in the pipeline makes reference to data in the buffer object
being updated by <function>glBufferSubData</function>,
especially from the specific region being updated, that
rendering must drain from the pipeline before the data store can
be updated.
</para>
<para>
Clients must align data elements consistent with the
requirements of the client platform, with an additional
base-level requirement that an offset within a buffer to a datum
comprising $N$ bytes be a multiple of $N$.
</para>
<para>
The <constant>GL_ATOMIC_COUNTER_BUFFER</constant> target is
available only if the GL version is 4.2 or greater.
</para>
<para>
The <constant>GL_DISPATCH_INDIRECT_BUFFER</constant> and
<constant>GL_SHADER_STORAGE_BUFFER</constant> targets are
available only if the GL version is 4.3 or greater.
</para>
<para>
The <constant>GL_QUERY_BUFFER</constant> target is available
only if the GL version is 4.4 or greater.
</para>
</refsect1>
<refsect1 xml:id="errors"><title>Errors</title>
<para>
<constant>GL_INVALID_ENUM</constant> is generated by
<function>glBufferSubData</function> if
<parameter>target</parameter> is not one of the accepted buffer
targets.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated by
<function>glBufferSubData</function> if zero is bound to
<parameter>target</parameter>.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated by
<function>glNamedBufferSubData</function> if
<parameter>buffer</parameter> is not the name of an existing
buffer object.
</para>
<para>
<constant>GL_INVALID_VALUE</constant> is generated if
<parameter>offset</parameter> or <parameter>size</parameter> is
negative, or if $offset + size$ is greater than the value of
<constant>GL_BUFFER_SIZE</constant> for the specified buffer
object.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if any
part of the specified range of the buffer object is mapped with
<citerefentry><refentrytitle>glMapBufferRange</refentrytitle></citerefentry>
or
<citerefentry><refentrytitle>glMapBuffer</refentrytitle></citerefentry>,
unless it was mapped with the
<constant>GL_MAP_PERSISTENT_BIT</constant> bit set in the
<function>glMapBufferRange</function>
<parameter>access</parameter> flags.
</para>
<para>
<constant>GL_INVALID_OPERATION</constant> is generated if the
value of the <constant>GL_BUFFER_IMMUTABLE_STORAGE</constant>
flag of the buffer object is <constant>GL_TRUE</constant> and
the value of <constant>GL_BUFFER_STORAGE_FLAGS</constant> for
the buffer object does not have the
<constant>GL_DYNAMIC_STORAGE_BIT</constant> bit set.
</para>
</refsect1>
<refsect1 xml:id="associatedgets"><title>Associated Gets</title>
<para>
<citerefentry><refentrytitle>glGetBufferSubData</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 xml:id="versions"><title>Version Support</title>
<informaltable>
<tgroup cols="13" align="left">
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apifunchead.xml" xpointer="xpointer(/*/*)"/>
<tbody>
<row>
<entry><function>glBufferSubData</function></entry>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apiversion.xml" xpointer="xpointer(/*/*[@role='20']/*)"/>
</row>
<row>
<entry><function>glNamedBufferSubData</function></entry>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="apiversion.xml" xpointer="xpointer(/*/*[@role='45']/*)"/>
</row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 xml:id="seealso"><title>See Also</title>
<para>
<citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glBufferData</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMapBuffer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glMapBufferRange</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>glUnmapBuffer</refentrytitle></citerefentry>
</para>
</refsect1>
<refsect1 xml:id="Copyright"><title>Copyright</title>
<para>
Copyright <trademark class="copyright"/> 2005 Addison-Wesley.
Copyright <trademark class="copyright"/> 2010-2014 Khronos Group.
This material may be distributed subject to the terms and conditions set forth in
the Open Publication License, v 1.0, 8 June 1999.
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://opencontent.org/openpub/">http://opencontent.org/openpub/</link>.
</para>
</refsect1>
</refentry>
|
