<div class="refentry" id="glBufferStorage">

<div class="titlepage"></div>

<div class="refnamediv">

<h2>Name</h2>

<p>glBufferStorage, glNamedBufferStorage — creates and initializes a buffer object's immutable data

store</p>

</div>

<div class="refsynopsisdiv">

<h2>C Specification</h2>

<div class="funcsynopsis">

<table style="border: 0; cellspacing: 0; cellpadding: 0;" class="funcprototype-table">

<tr>

<td>

<code class="funcdef">void <strong class="fsfunc">glBufferStorage</strong>(</code>

</td>

<td>GLenum <var class="pdparam">target</var>, </td>

</tr>

<tr>

<td> </td>

<td>GLsizeiptr <var class="pdparam">size</var>, </td>

</tr>

<tr>

<td> </td>

<td>const GLvoid * <var class="pdparam">data</var>, </td>

</tr>

<tr>

<td> </td>

<td>GLbitfield <var class="pdparam">flags</var><code>)</code>;</td>

</tr>

</table>

<div class="funcprototype-spacer"> </div>

<table style="border: 0; cellspacing: 0; cellpadding: 0;" class="funcprototype-table">

<tr>

<td>

<code class="funcdef">void <strong class="fsfunc">glNamedBufferStorage</strong>(</code>

</td>

<td>GLuint <var class="pdparam">buffer</var>, </td>

</tr>

<tr>

<td> </td>

<td>GLsizei <var class="pdparam">size</var>, </td>

</tr>

<tr>

<td> </td>

<td>const void *<var class="pdparam">data</var>, </td>

</tr>

<tr>

<td> </td>

<td>GLbitfield <var class="pdparam">flags</var><code>)</code>;</td>

</tr>

</table>

<div class="funcprototype-spacer"> </div>

</div>

</div>

<div class="refsect1" id="parameters">

<h2>Parameters</h2>

<div class="variablelist">

<dl class="variablelist">

<dt>

<span class="term">

<em class="parameter">

<code>target</code>

</em>

</span>

</dt>

<dd>

<p>

Specifies the target to which the buffer object is bound for

<code class="function">glBufferStorage</code>, which must be one of the

buffer binding targets in the following table:

</p>

<div class="informaltable">

<table style="border-collapse: collapse; border-top: 2px solid ; border-bottom: 2px solid ; border-left: 2px solid ; border-right: 2px solid ; ">

<colgroup>

<col style="text-align: left; " class="col1"/>

<col style="text-align: left; " class="col2"/>

</colgroup>

<thead>

<tr>

<th style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold">

<strong>Buffer Binding Target</strong>

</span>

</th>

<th style="text-align: left; border-bottom: 2px solid ; ">

<span class="bold">

<strong>Purpose</strong>

</span>

</th>

</tr>

</thead>

<tbody>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="constant">GL_ARRAY_BUFFER</code>

</td>

<td style="text-align: left; border-bottom: 2px solid ; ">Vertex attributes</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="constant">GL_ATOMIC_COUNTER_BUFFER</code>

</td>

<td style="text-align: left; border-bottom: 2px solid ; ">Atomic counter storage</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="constant">GL_COPY_READ_BUFFER</code>

</td>

<td style="text-align: left; border-bottom: 2px solid ; ">Buffer copy source</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="constant">GL_COPY_WRITE_BUFFER</code>

</td>

<td style="text-align: left; border-bottom: 2px solid ; ">Buffer copy destination</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="constant">GL_DISPATCH_INDIRECT_BUFFER</code>

</td>

<td style="text-align: left; border-bottom: 2px solid ; ">Indirect compute dispatch commands</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="constant">GL_DRAW_INDIRECT_BUFFER</code>

</td>

<td style="text-align: left; border-bottom: 2px solid ; ">Indirect command arguments</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="constant">GL_ELEMENT_ARRAY_BUFFER</code>

</td>

<td style="text-align: left; border-bottom: 2px solid ; ">Vertex array indices</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="constant">GL_PIXEL_PACK_BUFFER</code>

</td>

<td style="text-align: left; border-bottom: 2px solid ; ">Pixel read target</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="constant">GL_PIXEL_UNPACK_BUFFER</code>

</td>

<td style="text-align: left; border-bottom: 2px solid ; ">Texture data source</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="constant">GL_QUERY_BUFFER</code>

</td>

<td style="text-align: left; border-bottom: 2px solid ; ">Query result buffer</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="constant">GL_SHADER_STORAGE_BUFFER</code>

</td>

<td style="text-align: left; border-bottom: 2px solid ; ">Read-write storage for shaders</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="constant">GL_TEXTURE_BUFFER</code>

</td>

<td style="text-align: left; border-bottom: 2px solid ; ">Texture data buffer</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="constant">GL_TRANSFORM_FEEDBACK_BUFFER</code>

</td>

<td style="text-align: left; border-bottom: 2px solid ; ">Transform feedback buffer</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; ">

<code class="constant">GL_UNIFORM_BUFFER</code>

</td>

<td style="text-align: left; ">Uniform block storage</td>

</tr>

</tbody>

</table>

</div>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>buffer</code>

</em>

</span>

</dt>

<dd>

<p>Specifies the name of the buffer object for

<code class="function">glNamedBufferStorage</code> function.</p>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>size</code>

</em>

</span>

</dt>

<dd>

<p>Specifies the size in bytes of the buffer object's new data

store.</p>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>data</code>

</em>

</span>

</dt>

<dd>

<p>Specifies a pointer to data that will be copied into the data

store for initialization, or <code class="constant">NULL</code> if no data is

to be copied.</p>

</dd>

<dt>

<span class="term">

<em class="parameter">

<code>flags</code>

</em>

</span>

</dt>

<dd>

<p>Specifies the intended usage of the buffer's data store. Must

be a bitwise combination of the following flags.

<code class="constant">GL_DYNAMIC_STORAGE_BIT</code>,

<code class="constant">GL_MAP_READ_BIT</code>

<code class="constant">GL_MAP_WRITE_BIT</code>,

<code class="constant">GL_MAP_PERSISTENT_BIT</code>,

<code class="constant">GL_MAP_COHERENT_BIT</code>, and

<code class="constant">GL_CLIENT_STORAGE_BIT</code>.</p>

</dd>

</dl>

</div>

</div>

<div class="refsect1" id="description">

<h2>Description</h2>

<p><code class="function">glBufferStorage</code> and

<code class="function">glNamedBufferStorage</code> create a new immutable data

store. For <code class="function">glBufferStorage</code>, the buffer object

currently bound to <em class="parameter"><code>target</code></em> will be initialized. For

<code class="function">glNamedBufferStorage</code>, <em class="parameter"><code>buffer</code></em>

is the name of the buffer object that will be configured. The size of the

data store is specified by <em class="parameter"><code>size</code></em>. If an initial data

is available, its address may be supplied in <em class="parameter"><code>data</code></em>.

Otherwise, to create an uninitialized data store,

<em class="parameter"><code>data</code></em> should be <code class="constant">NULL</code>.</p>

<p>The <em class="parameter"><code>flags</code></em> parameters specifies the intended

usage of the buffer's data store. It must be a bitwise combination of a

subset of the following flags: </p>

<div class="variablelist">

<dl class="variablelist">

<dt>

<span class="term">

<code class="constant">GL_DYNAMIC_STORAGE_BIT</code>

</span>

</dt>

<dd>

<p>The contents of the data store may be updated after creation

through calls to <a class="citerefentry" href="glBufferSubData"><span class="citerefentry"><span class="refentrytitle">glBufferSubData</span></span></a>. If this bit is not set, the buffer content may

not be directly updated by the client. The data argument may be

used to specify the initial content of the buffer's data store

regardless of the presence of the

<code class="constant">GL_DYNAMIC_STORAGE_BIT</code>. Regardless of the

presence of this bit, buffers may always be updated with

server-side calls such as <a class="citerefentry" href="glCopyBufferSubData"><span class="citerefentry"><span class="refentrytitle">glCopyBufferSubData</span></span></a> and <a class="citerefentry" href="glClearBufferSubData"><span class="citerefentry"><span class="refentrytitle">glClearBufferSubData</span></span></a>.</p>

</dd>

<dt>

<span class="term">

<code class="constant">GL_MAP_READ_BIT</code>

</span>

</dt>

<dd>

<p>The data store may be mapped by the client for read access

and a pointer in the client's address space obtained that may be

read from.</p>

</dd>

<dt>

<span class="term">

<code class="constant">GL_MAP_WRITE_BIT</code>

</span>

</dt>

<dd>

<p>The data store may be mapped by the client for write access

and a pointer in the client's address space obtained that may be

written through.</p>

</dd>

<dt>

<span class="term">

<code class="constant">GL_MAP_PERSISTENT_BIT</code>

</span>

</dt>

<dd>

<p>The client may request that the server read from or write to

the buffer while it is mapped. The client's pointer to the data

store remains valid so long as the data store is mapped, even

during execution of drawing or dispatch commands.</p>

</dd>

<dt>

<span class="term">

<code class="constant">GL_MAP_COHERENT_BIT</code>

</span>

</dt>

<dd>

<p>Shared access to buffers that are simultaneously mapped for

client access and are used by the server will be coherent, so long

as that mapping is performed using <a class="citerefentry" href="glMapBufferRange"><span class="citerefentry"><span class="refentrytitle">glMapBufferRange</span></span></a>. That is, data written to the store by either

the client or server will be immediately visible to the other with

no further action taken by the application. In particular,</p>

<div class="itemizedlist">

<ul style="list-style-type: disc; " class="itemizedlist">

<li class="listitem">

<p>If <code class="constant">GL_MAP_COHERENT_BIT</code> is not set

and the client performs a write followed by a call to the

<a class="citerefentry" href="glMemoryBarrier"><span class="citerefentry"><span class="refentrytitle">glMemoryBarrier</span></span></a> command with the

<code class="constant">GL_CLIENT_MAPPED_BUFFER_BARRIER_BIT</code> set,

then in subsequent commands the server will see the

writes.</p>

</li>

<li class="listitem">

<p>If <code class="constant">GL_MAP_COHERENT_BIT</code> is set and

the client performs a write, then in subsequent commands the

server will see the writes.</p>

</li>

<li class="listitem">

<p>If <code class="constant">GL_MAP_COHERENT_BIT</code> is not set

and the server performs a write, the application must call

<a class="citerefentry" href="glMemoryBarrier"><span class="citerefentry"><span class="refentrytitle">glMemoryBarrier</span></span></a> with the

<code class="constant">GL_CLIENT_MAPPED_BUFFER_BARRIER_BIT</code> set

and then call <a class="citerefentry" href="glFenceSync"><span class="citerefentry"><span class="refentrytitle">glFenceSync</span></span></a> with

<code class="constant">GL_SYNC_GPU_COMMANDS_COMPLETE</code> (or

<code class="function">glFinish</code>). Then the CPU will see the

writes after the sync is complete.</p>

</li>

<li class="listitem">

<p>If <code class="constant">GL_MAP_COHERENT_BIT</code> is set and

the server does a write, the app must call FenceSync with

<code class="constant">GL_SYNC_GPU_COMMANDS_COMPLETE</code> (or

<a class="citerefentry" href="glFinish"><span class="citerefentry"><span class="refentrytitle">glFinish</span></span></a>). Then the CPU will see the writes after the

sync is complete.</p>

</li>

</ul>

</div>

</dd>

<dt>

<span class="term">

<code class="constant">GL_CLIENT_STORAGE_BIT</code>

</span>

</dt>

<dd>

<p>When all other criteria for the buffer storage allocation

are met, this bit may be used by an implementation to determine

whether to use storage that is local to the server or to the

client to serve as the backing store for the buffer.</p>

</dd>

</dl>

</div>

<p>The allowed combinations of flags are subject to certain

restrictions. They are as follows: </p>

<div class="itemizedlist">

<ul class="itemizedlist" style="list-style-type: disc; ">

<li class="listitem">

<p>If <em class="parameter"><code>flags</code></em> contains

<code class="constant">GL_MAP_PERSISTENT_BIT</code>, it must also contain at

least one of <code class="constant">GL_MAP_READ_BIT</code> or

<code class="constant">GL_MAP_WRITE_BIT</code>.</p>

</li>

<li class="listitem">

<p>If <em class="parameter"><code>flags</code></em> contains

<code class="constant">GL_MAP_COHERENT_BIT</code>, it must also contain

<code class="constant">GL_MAP_PERSISTENT_BIT</code>.</p>

</li>

</ul>

</div>

</div>

<div class="refsect1" id="notes">

<h2>Notes</h2>

<p><code class="function">glBufferStorage</code> is available only if the GL

version is 4.4 or greater.</p>

<p><code class="function">glNamedBufferStorage</code> is available only if the

GL version is 4.5 or greater.</p>

<p>If <em class="parameter"><code>data</code></em> is <code class="constant">NULL</code>, a data

store of the specified size is still created, but its contents remain

uninitialized and thus undefined.</p>

</div>

<div class="refsect1" id="errors">

<h2>Errors</h2>

<p><code class="constant">GL_INVALID_ENUM</code> is generated by

<code class="function">glBufferStorage</code> if <em class="parameter"><code>target</code></em> is

not one of the accepted buffer targets.</p>

<p><code class="constant">GL_INVALID_OPERATION</code> is generated by

<code class="function">glNamedBufferStorage</code> if buffer is not the name of an

existing buffer object.</p>

<p><code class="constant">GL_INVALID_VALUE</code> is generated if

<em class="parameter"><code>size</code></em> is less than or equal to zero.</p>

<p><code class="constant">GL_INVALID_OPERATION</code> is generated by

<code class="function">glBufferStorage</code> if the reserved buffer object name 0

is bound to <em class="parameter"><code>target</code></em>.</p>

<p><code class="constant">GL_OUT_OF_MEMORY</code> is generated if the GL is

unable to create a data store with the properties requested in

<em class="parameter"><code>flags</code></em>.</p>

<p><code class="constant">GL_INVALID_VALUE</code> is generated if

<em class="parameter"><code>flags</code></em> has any bits set other than those defined

above.</p>

<p><code class="constant">GL_INVALID_VALUE</code> error is generated if

<em class="parameter"><code>flags</code></em> contains

<code class="constant">GL_MAP_PERSISTENT_BIT</code> but does not contain at least

one of <code class="constant">GL_MAP_READ_BIT</code> or

<code class="constant">GL_MAP_WRITE_BIT</code>.</p>

<p><code class="constant">GL_INVALID_VALUE</code> is generated if

<em class="parameter"><code>flags</code></em> contains

<code class="constant">GL_MAP_COHERENT_BIT</code>, but does not also contain

<code class="constant">GL_MAP_PERSISTENT_BIT</code>.</p>

<p><code class="constant">GL_INVALID_OPERATION</code> is generated by

<code class="function">glBufferStorage</code> if the

<code class="constant">GL_BUFFER_IMMUTABLE_STORAGE</code> flag of the buffer bound

to <em class="parameter"><code>target</code></em> is <code class="constant">GL_TRUE</code>.</p>

</div>

<div class="refsect1" id="associatedgets">

<h2>Associated Gets</h2>

<p>

<a class="citerefentry" href="glGetBufferSubData">

<span class="citerefentry">

<span class="refentrytitle">glGetBufferSubData</span>

</span>

</a>

</p>

<p><a class="citerefentry" href="glGetBufferParameter"><span class="citerefentry"><span class="refentrytitle">glGetBufferParameter</span></span></a> with argument <code class="constant">GL_BUFFER_SIZE</code> or

<code class="constant">GL_BUFFER_USAGE</code></p>

</div>

{$pipelinestall}{$examples}

<div class="refsect1" id="versions">

<h2>Version Support</h2>

<div class="informaltable">

<table style="border-collapse: collapse; border-top: 2px solid ; border-bottom: 2px solid ; border-left: 2px solid ; border-right: 2px solid ; ">

<colgroup>

<col style="text-align: left; "/>

<col style="text-align: center; " class="firstvers"/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; "/>

<col style="text-align: center; " class="lastvers"/>

</colgroup>

<thead>

<tr>

<th style="text-align: left; border-right: 2px solid ; ">

</th>

<th style="text-align: center; border-bottom: 2px solid ; " colspan="12">

<span class="bold"><strong>OpenGL Version</strong></span>

</th>

</tr>

<tr>

<th style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>Function / Feature Name</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>2.0</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>2.1</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>3.0</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>3.1</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>3.2</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>3.3</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>4.0</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>4.1</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>4.2</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>4.3</strong></span>

</th>

<th style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">

<span class="bold"><strong>4.4</strong></span>

</th>

<th style="text-align: center; border-bottom: 2px solid ; ">

<span class="bold"><strong>4.5</strong></span>

</th>

</tr>

</thead>

<tbody>

<tr>

<td style="text-align: left; border-right: 2px solid ; border-bottom: 2px solid ; ">

<code class="function">glBufferStorage</code>

</td>

<td style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; border-bottom: 2px solid ; ">✔</td>

<td style="text-align: center; border-bottom: 2px solid ; ">✔</td>

</tr>

<tr>

<td style="text-align: left; border-right: 2px solid ; ">

<code class="function">glNamedBufferStorage</code>

</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; border-right: 2px solid ; ">-</td>

<td style="text-align: center; ">✔</td>

</tr>

</tbody>

</table>

</div>

</div>

<div class="refsect1" id="seealso">

<h2>See Also</h2>

<p><a class="citerefentry" href="glBindBuffer"><span class="citerefentry"><span class="refentrytitle">glBindBuffer</span></span></a>, <a class="citerefentry" href="glBufferSubData"><span class="citerefentry"><span class="refentrytitle">glBufferSubData</span></span></a>, <a class="citerefentry" href="glMapBuffer"><span class="citerefentry"><span class="refentrytitle">glMapBuffer</span></span></a>, <a class="citerefentry" href="glUnmapBuffer"><span class="citerefentry"><span class="refentrytitle">glUnmapBuffer</span></span></a></p>

</div>

<div class="refsect1" id="Copyright">

<h2>Copyright</h2>

<p>

Copyright © 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.

<a class="link" href="https://opencontent.org/openpub/" target="_top">https://opencontent.org/openpub/</a>.

</p>

</div>

</div>