mirror of
https://github.com/Ryujinx/Opentk.git
synced 2024-12-26 07:35:31 +00:00
205 lines
11 KiB
XML
205 lines
11 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">
|
||
|
|
<refmeta>
|
||
|
|
<refmetainfo>
|
||
|
|
<copyright>
|
||
|
|
<year>2010</year>
|
||
|
|
<holder>Khronos Group</holder>
|
||
|
|
</copyright>
|
||
|
|
</refmetainfo>
|
||
|
|
<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_COPY_READ_BUFFER</constant>, <constant>GL_COPY_WRITE_BUFFER</constant>, <constant>GL_ELEMENT_ARRAY_BUFFER</constant>,
|
||
|
|
<constant>GL_PIXEL_PACK_BUFFER</constant>, <constant>GL_PIXEL_UNPACK_BUFFER</constant>, <constant>GL_TEXTURE_BUFFER</constant>,
|
||
|
|
<constant>GL_TRANSFORM_FEEDBACK_BUFFER</constant>, or <constant>GL_UNIFORM_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>
|
||
|
|
</itemizedlist>
|
||
|
|
</para>
|
||
|
|
<para>
|
||
|
|
If an error occurs, <function>glMapBufferRange</function> returns a <code>NULL</code> pointer.
|
||
|
|
</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>
|
||
|
|
</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>
|
||
|
|
</para>
|
||
|
|
</refsect1>
|
||
|
|
<refsect1 id="Copyright"><title>Copyright</title>
|
||
|
|
<para>
|
||
|
|
Copyright <trademark class="copyright"></trademark> 2010 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>
|