256 lines
15 KiB
XML
256 lines
15 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
|
|
"http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
|
|
<refentry id="glMapBufferRange">
|
|
<refentryinfo>
|
|
<copyright>
|
|
<year>2013</year>
|
|
<holder>Khronos Group</holder>
|
|
</copyright>
|
|
</refentryinfo>
|
|
<refmeta>
|
|
<refentrytitle>glMapBufferRange</refentrytitle>
|
|
<manvolnum>3G</manvolnum>
|
|
</refmeta>
|
|
<refnamediv>
|
|
<refname>glMapBufferRange</refname>
|
|
<refpurpose>map a section of a buffer object's data store</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv><title>C Specification</title>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void *<function>glMapBufferRange</function></funcdef>
|
|
<paramdef>GLenum <parameter>target</parameter></paramdef>
|
|
<paramdef>GLintptr <parameter>offset</parameter></paramdef>
|
|
<paramdef>GLsizeiptr <parameter>length</parameter></paramdef>
|
|
<paramdef>GLbitfield <parameter>access</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</refsynopsisdiv>
|
|
<refsect1 id="parameters"><title>Parameters</title>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>target</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a binding to which the target buffer is bound.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>offset</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a the starting offset within the buffer of the range to be mapped.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>length</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a length of the range to be mapped.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>access</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
Specifies a combination of access flags indicating the desired access to the range.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
<refsect1 id="description"><title>Description</title>
|
|
<para>
|
|
<function>glMapBufferRange</function> maps all or part of the data store of a buffer object into the client's address
|
|
space. <parameter>target</parameter> specifies the target to which the buffer is bound and must be one of <constant>GL_ARRAY_BUFFER</constant>,
|
|
<constant>GL_ATOMIC_COUNTER_BUFFER</constant>,
|
|
<constant>GL_COPY_READ_BUFFER</constant>, <constant>GL_COPY_WRITE_BUFFER</constant>, <constant>GL_DRAW_INDIRECT_BUFFER</constant>,
|
|
<constant>GL_DISPATCH_INDIRECT_BUFFER</constant>, <constant>GL_ELEMENT_ARRAY_BUFFER</constant>,
|
|
<constant>GL_PIXEL_PACK_BUFFER</constant>, <constant>GL_PIXEL_UNPACK_BUFFER</constant>, <constant>GL_QUERY_BUFFER</constant>, <constant>GL_TEXTURE_BUFFER</constant>,
|
|
<constant>GL_TRANSFORM_FEEDBACK_BUFFER</constant>, <constant>GL_UNIFORM_BUFFER</constant> or <constant>GL_SHADER_STORAGE_BUFFER</constant>. <parameter>offset</parameter> and
|
|
<parameter>length</parameter> indicate the range of data in the buffer object htat is to be mapped, in terms of basic machine units.
|
|
<parameter>access</parameter> is a bitfield containing flags which describe the requested mapping. These flags are described below.
|
|
</para>
|
|
<para>
|
|
If no error occurs, a pointer to the beginning of the mapped range is returned once all pending operations on that buffer have
|
|
completed, and may be used to modify and/or query the corresponding range of the buffer, according to the following flag bits set
|
|
in <parameter>access</parameter>:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<constant>GL_MAP_READ_BIT</constant> indicates that the returned pointer may be used to read
|
|
buffer object data. No GL error is generated if the pointer is used to query
|
|
a mapping which excludes this flag, but the result is undefined and system
|
|
errors (possibly including program termination) may occur.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<constant>GL_MAP_WRITE_BIT</constant> indicates that the returned pointer may be used to modify
|
|
buffer object data. No GL error is generated if the pointer is used to modify
|
|
a mapping which excludes this flag, but the result is undefined and system
|
|
errors (possibly including program termination) may occur.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
Furthermore, the following <emphasis>optional</emphasis> flag bits in <parameter>access</parameter> may be used to modify the mapping:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<constant>GL_MAP_INVALIDATE_RANGE_BIT</constant> indicates that the previous contents of the
|
|
specified range may be discarded. Data within this range are undefined with
|
|
the exception of subsequently written data. No GL error is generated if sub-
|
|
sequent GL operations access unwritten data, but the result is undefined and
|
|
system errors (possibly including program termination) may occur. This flag
|
|
may not be used in combination with <constant>GL_MAP_READ_BIT</constant>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<constant>GL_MAP_INVALIDATE_BUFFER_BIT</constant> indicates that the previous contents of the
|
|
entire buffer may be discarded. Data within the entire buffer are undefined
|
|
with the exception of subsequently written data. No GL error is generated if
|
|
subsequent GL operations access unwritten data, but the result is undefined
|
|
and system errors (possibly including program termination) may occur. This
|
|
flag may not be used in combination with <constant>GL_MAP_READ_BIT</constant>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<constant>GL_MAP_FLUSH_EXPLICIT_BIT</constant> indicates that one or more discrete subranges
|
|
of the mapping may be modified. When this flag is set, modifications to
|
|
each subrange must be explicitly flushed by calling <citerefentry><refentrytitle>glFlushMappedBufferRange</refentrytitle></citerefentry>.
|
|
No GL error is set if a subrange of the mapping is modified and
|
|
not flushed, but data within the corresponding subrange of the buffer are undefined.
|
|
This flag may only be used in conjunction with <constant>GL_MAP_WRITE_BIT</constant>.
|
|
When this option is selected, flushing is strictly limited to regions that are
|
|
explicitly indicated with calls to <citerefentry><refentrytitle>glFlushMappedBufferRange</refentrytitle></citerefentry>
|
|
prior to unmap; if this option is not selected <citerefentry><refentrytitle>glUnmapBuffer</refentrytitle></citerefentry>
|
|
will automatically flush the entire mapped range when called.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<constant>GL_MAP_UNSYNCHRONIZED_BIT</constant> indicates that the GL should not attempt to
|
|
synchronize pending operations on the buffer prior to returning from <function>glMapBufferRange</function>.
|
|
No GL error is generated if pending operations which source or modify the buffer overlap the mapped region,
|
|
but the result of such previous and any subsequent operations is undefined.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<constant>GL_MAP_PERSISTENT_BIT</constant> indicates that the mapping is to be made in a persistent
|
|
fassion and that the client intends to hold and use the returned pointer during subsequent GL operation. It is not
|
|
an error to call drawing commands (render) while buffers are mapped using this flag. It is an error to
|
|
specify this flag if the buffer's data store was not allocated through a call to the <citerefentry><refentrytitle>glBufferStorage</refentrytitle></citerefentry>
|
|
command in which the <constant>GL_MAP_PERSISTENT_BIT</constant> was also set.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<constant>GL_MAP_COHERENT_BIT</constant> indicates that a persistent mapping is also to be coherent.
|
|
Coherent maps guarantee that the effect of writes to a buffer's data store by either the client or server will
|
|
eventually become visible to the other without further intervention from the application. In the absence
|
|
of this bit, persistent mappings are not coherent and modified ranges of the buffer store must be explicitly
|
|
communicated to the GL, either by unmapping the buffer, or through a call to
|
|
<citerefentry><refentrytitle>glFlushMappedBufferRange</refentrytitle></citerefentry> or <citerefentry><refentrytitle>glMemoryBarrier</refentrytitle></citerefentry>.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
If an error occurs, <function>glMapBufferRange</function> returns a <code>NULL</code> pointer.
|
|
If no error occurs, the returned pointer will reflect an alignment of at least <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant>
|
|
basic machine units. The value of <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant> can be retrieved by calling
|
|
<citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with <parameter>pname</parameter> set to
|
|
<constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant> and must be a power of two that is at least 64. Subtracting <parameter>offset</parameter>
|
|
from this returned pointed will always produce a multiple of <constant>GL_MIN_MAP_BUFFER_ALINMENT</constant>.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="notes"><title>Notes</title>
|
|
<para>
|
|
Alignment of the returned pointer is guaranteed only if the version
|
|
of the GL version is 4.2 or greater. Also, the <constant>GL_ATOMIC_COUNTER_BUFFER</constant>
|
|
target is accepted 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 accepted 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>
|
|
<para>
|
|
The <constant>GL_MAP_PERSISTENT_BIT</constant> and <constant>GL_MAP_COHERENT_BIT</constant> flags are available
|
|
only if the GL version is 4.4 or greater.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="errors"><title>Errors</title>
|
|
<para>
|
|
<constant>GL_INVALID_VALUE</constant> is generated if either of <parameter>offset</parameter> or <parameter>length</parameter> is negative,
|
|
or if <parameter>offset</parameter> + <parameter>length</parameter> is greater than the value of <constant>GL_BUFFER_SIZE</constant>.
|
|
</para>
|
|
<para>
|
|
<constant>GL_INVALID_VALUE</constant> is generated if <parameter>access</parameter> has any bits set other than those defined above.
|
|
</para>
|
|
<para>
|
|
<constant>GL_INVALID_OPERATION</constant> is generated for any of the following conditions:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
The buffer is already in a mapped state.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Neither <constant>GL_MAP_READ_BIT</constant> or <constant>GL_MAP_WRITE_BIT</constant> is set.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<constant>GL_MAP_READ_BIT</constant> is set and any of <constant>GL_MAP_INVALIDATE_RANGE_BIT</constant>,
|
|
<constant>GL_MAP_INVALIDATE_BUFFER_BIT</constant>, or <constant>GL_MAP_UNSYNCHRONIZED_BIT</constant> is set.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<constant>GL_MAP_FLUSH_EXPLICIT_BIT</constant> is set and <constant>GL_MAP_WRITE_BIT</constant> is not set.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Any of <constant>GL_MAP_READ_BIT</constant>, <constant>GL_MAP_WRITE_BIT</constant>, <constant>GL_MAP_PERSISTENT_BIT</constant>,
|
|
or <constant>GL_MAP_COHERENT_BIT</constant> are included in <parameter>access</parameter>, but the same bit
|
|
is not included in the buffer's storage flags.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
<constant>GL_OUT_OF_MEMORY</constant> is generated if <function>glMapBufferRange</function> fails because memory for the
|
|
mapping could not be obtained.
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="seealso"><title>See Also</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>glMapBuffer</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glFlushMappedBufferRange</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>,
|
|
<citerefentry><refentrytitle>glBufferStorage</refentrytitle></citerefentry>
|
|
</para>
|
|
</refsect1>
|
|
<refsect1 id="Copyright"><title>Copyright</title>
|
|
<para>
|
|
Copyright <trademark class="copyright"></trademark> 2010-2013 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.
|
|
<ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
|
|
</para>
|
|
</refsect1>
|
|
</refentry>
|