| 1 | <?xml version="1.0" encoding="UTF-8"?> |
| 2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN" |
| 3 | "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd"> |
| 4 | <refentry id="glMapBufferRange"> |
| 5 | <refmeta> |
| 6 | <refmetainfo> |
| 7 | <copyright> |
| 8 | <year>2012</year> |
| 9 | <holder>Khronos Group</holder> |
| 10 | </copyright> |
| 11 | </refmetainfo> |
| 12 | <refentrytitle>glMapBufferRange</refentrytitle> |
| 13 | <manvolnum>3G</manvolnum> |
| 14 | </refmeta> |
| 15 | <refnamediv> |
| 16 | <refname>glMapBufferRange</refname> |
| 17 | <refpurpose>map a section of a buffer object's data store</refpurpose> |
| 18 | </refnamediv> |
| 19 | <refsynopsisdiv><title>C Specification</title> |
| 20 | <funcsynopsis> |
| 21 | <funcprototype> |
| 22 | <funcdef>void *<function>glMapBufferRange</function></funcdef> |
| 23 | <paramdef>GLenum <parameter>target</parameter></paramdef> |
| 24 | <paramdef>GLintptr <parameter>offset</parameter></paramdef> |
| 25 | <paramdef>GLsizeiptr <parameter>length</parameter></paramdef> |
| 26 | <paramdef>GLbitfield <parameter>access</parameter></paramdef> |
| 27 | </funcprototype> |
| 28 | </funcsynopsis> |
| 29 | </refsynopsisdiv> |
| 30 | <refsect1 id="parameters"><title>Parameters</title> |
| 31 | <variablelist> |
| 32 | <varlistentry> |
| 33 | <term><parameter>target</parameter></term> |
| 34 | <listitem> |
| 35 | <para> |
| 36 | Specifies a binding to which the target buffer is bound. |
| 37 | </para> |
| 38 | </listitem> |
| 39 | </varlistentry> |
| 40 | <varlistentry> |
| 41 | <term><parameter>offset</parameter></term> |
| 42 | <listitem> |
| 43 | <para> |
| 44 | Specifies a the starting offset within the buffer of the range to be mapped. |
| 45 | </para> |
| 46 | </listitem> |
| 47 | </varlistentry> |
| 48 | <varlistentry> |
| 49 | <term><parameter>length</parameter></term> |
| 50 | <listitem> |
| 51 | <para> |
| 52 | Specifies a length of the range to be mapped. |
| 53 | </para> |
| 54 | </listitem> |
| 55 | </varlistentry> |
| 56 | <varlistentry> |
| 57 | <term><parameter>access</parameter></term> |
| 58 | <listitem> |
| 59 | <para> |
| 60 | Specifies a combination of access flags indicating the desired access to the range. |
| 61 | </para> |
| 62 | </listitem> |
| 63 | </varlistentry> |
| 64 | </variablelist> |
| 65 | </refsect1> |
| 66 | <refsect1 id="description"><title>Description</title> |
| 67 | <para> |
| 68 | <function>glMapBufferRange</function> maps all or part of the data store of a buffer object into the client's address |
| 69 | space. <parameter>target</parameter> specifies the target to which the buffer is bound and must be one of <constant>GL_ARRAY_BUFFER</constant>, |
| 70 | <constant>GL_ATOMIC_COUNTER_BUFFER</constant>, |
| 71 | <constant>GL_COPY_READ_BUFFER</constant>, <constant>GL_COPY_WRITE_BUFFER</constant>, <constant>GL_DRAW_INDIRECT_BUFFER</constant>, |
| 72 | <constant>GL_DISPATCH_INDIRECT_BUFFER</constant>, <constant>GL_ELEMENT_ARRAY_BUFFER</constant>, |
| 73 | <constant>GL_PIXEL_PACK_BUFFER</constant>, <constant>GL_PIXEL_UNPACK_BUFFER</constant>, <constant>GL_TEXTURE_BUFFER</constant>, |
| 74 | <constant>GL_TRANSFORM_FEEDBACK_BUFFER</constant>, <constant>GL_UNIFORM_BUFFER</constant> or <constant>GL_SHADER_STORAGE_BUFFER</constant>. <parameter>offset</parameter> and |
| 75 | <parameter>length</parameter> indicate the range of data in the buffer object htat is to be mapped, in terms of basic machine units. |
| 76 | <parameter>access</parameter> is a bitfield containing flags which describe the requested mapping. These flags are described below. |
| 77 | </para> |
| 78 | <para> |
| 79 | If no error occurs, a pointer to the beginning of the mapped range is returned once all pending operations on that buffer have |
| 80 | completed, and may be used to modify and/or query the corresponding range of the buffer, according to the following flag bits set |
| 81 | in <parameter>access</parameter>: |
| 82 | <itemizedlist> |
| 83 | <listitem> |
| 84 | <para> |
| 85 | <constant>GL_MAP_READ_BIT</constant> indicates that the returned pointer may be used to read |
| 86 | buffer object data. No GL error is generated if the pointer is used to query |
| 87 | a mapping which excludes this flag, but the result is undefined and system |
| 88 | errors (possibly including program termination) may occur. |
| 89 | </para> |
| 90 | </listitem> |
| 91 | <listitem> |
| 92 | <para> |
| 93 | <constant>GL_MAP_WRITE_BIT</constant> indicates that the returned pointer may be used to modify |
| 94 | buffer object data. No GL error is generated if the pointer is used to modify |
| 95 | a mapping which excludes this flag, but the result is undefined and system |
| 96 | errors (possibly including program termination) may occur. |
| 97 | </para> |
| 98 | </listitem> |
| 99 | </itemizedlist> |
| 100 | </para> |
| 101 | <para> |
| 102 | Furthermore, the following <emphasis>optional</emphasis> flag bits in <parameter>access</parameter> may be used to modify the mapping: |
| 103 | <itemizedlist> |
| 104 | <listitem> |
| 105 | <para> |
| 106 | <constant>GL_MAP_INVALIDATE_RANGE_BIT</constant> indicates that the previous contents of the |
| 107 | specified range may be discarded. Data within this range are undefined with |
| 108 | the exception of subsequently written data. No GL error is generated if sub- |
| 109 | sequent GL operations access unwritten data, but the result is undefined and |
| 110 | system errors (possibly including program termination) may occur. This flag |
| 111 | may not be used in combination with <constant>GL_MAP_READ_BIT</constant>. |
| 112 | </para> |
| 113 | </listitem> |
| 114 | <listitem> |
| 115 | <para> |
| 116 | <constant>GL_MAP_INVALIDATE_BUFFER_BIT</constant> indicates that the previous contents of the |
| 117 | entire buffer may be discarded. Data within the entire buffer are undefined |
| 118 | with the exception of subsequently written data. No GL error is generated if |
| 119 | subsequent GL operations access unwritten data, but the result is undefined |
| 120 | and system errors (possibly including program termination) may occur. This |
| 121 | flag may not be used in combination with <constant>GL_MAP_READ_BIT</constant>. |
| 122 | </para> |
| 123 | </listitem> |
| 124 | <listitem> |
| 125 | <para> |
| 126 | <constant>GL_MAP_FLUSH_EXPLICIT_BIT</constant> indicates that one or more discrete subranges |
| 127 | of the mapping may be modified. When this flag is set, modifications to |
| 128 | each subrange must be explicitly flushed by calling <citerefentry><refentrytitle>glFlushMappedBufferRange</refentrytitle></citerefentry>. |
| 129 | No GL error is set if a subrange of the mapping is modified and |
| 130 | not flushed, but data within the corresponding subrange of the buffer are undefined. |
| 131 | This flag may only be used in conjunction with <constant>GL_MAP_WRITE_BIT</constant>. |
| 132 | When this option is selected, flushing is strictly limited to regions that are |
| 133 | explicitly indicated with calls to <citerefentry><refentrytitle>glFlushMappedBufferRange</refentrytitle></citerefentry> |
| 134 | prior to unmap; if this option is not selected <citerefentry><refentrytitle>glUnmapBuffer</refentrytitle></citerefentry> |
| 135 | will automatically flush the entire mapped range when called. |
| 136 | </para> |
| 137 | </listitem> |
| 138 | <listitem> |
| 139 | <para> |
| 140 | <constant>GL_MAP_UNSYNCHRONIZED_BIT</constant> indicates that the GL should not attempt to |
| 141 | synchronize pending operations on the buffer prior to returning from <function>glMapBufferRange</function>. |
| 142 | No GL error is generated if pending operations which source or modify the buffer overlap the mapped region, |
| 143 | but the result of such previous and any subsequent operations is undefined. |
| 144 | </para> |
| 145 | </listitem> |
| 146 | </itemizedlist> |
| 147 | </para> |
| 148 | <para> |
| 149 | If an error occurs, <function>glMapBufferRange</function> returns a <code>NULL</code> pointer. |
| 150 | If no error occurs, the returned pointer will reflect an alignment of at least <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant> |
| 151 | basic machine units. The value of <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant> can be retrieved by calling |
| 152 | <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with <parameter>pname</parameter> set to |
| 153 | <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant> and must be a power of two that is at least 64. Subtracting <parameter>offset</parameter> |
| 154 | from this returned pointed will always produce a multiple of <constant>GL_MIN_MAP_BUFFER_ALINMENT</constant>. |
| 155 | </para> |
| 156 | </refsect1> |
| 157 | <refsect1 id="notes"><title>Notes</title> |
| 158 | <para> |
| 159 | Alignment of the returned pointer is guaranteed only if the version |
| 160 | of the GL version is 4.2 or greater. Also, the <constant>GL_ATOMIC_COUNTER_BUFFER</constant> |
| 161 | target is accepted only if the GL version is 4.2 or greater. |
| 162 | </para> |
| 163 | <para> |
| 164 | The <constant>GL_DISPATCH_INDIRECT_BUFFER</constant> and <constant>GL_SHADER_STORAGE_BUFFER</constant> targets are accepted only if the |
| 165 | GL version is 4.3 or greater. |
| 166 | </para> |
| 167 | </refsect1> |
| 168 | <refsect1 id="errors"><title>Errors</title> |
| 169 | <para> |
| 170 | <constant>GL_INVALID_VALUE</constant> is generated if either of <parameter>offset</parameter> or <parameter>length</parameter> is negative, |
| 171 | or if <parameter>offset</parameter> + <parameter>length</parameter> is greater than the value of <constant>GL_BUFFER_SIZE</constant>. |
| 172 | </para> |
| 173 | <para> |
| 174 | <constant>GL_INVALID_VALUE</constant> is generated if <parameter>access</parameter> has any bits set other than those defined above. |
| 175 | </para> |
| 176 | <para> |
| 177 | <constant>GL_INVALID_OPERATION</constant> is generated for any of the following conditions: |
| 178 | <itemizedlist> |
| 179 | <listitem> |
| 180 | <para> |
| 181 | The buffer is already in a mapped state. |
| 182 | </para> |
| 183 | </listitem> |
| 184 | <listitem> |
| 185 | <para> |
| 186 | Neither <constant>GL_MAP_READ_BIT</constant> or <constant>GL_MAP_WRITE_BIT</constant> is set. |
| 187 | </para> |
| 188 | </listitem> |
| 189 | <listitem> |
| 190 | <para> |
| 191 | <constant>GL_MAP_READ_BIT</constant> is set and any of <constant>GL_MAP_INVALIDATE_RANGE_BIT</constant>, |
| 192 | <constant>GL_MAP_INVALIDATE_BUFFER_BIT</constant>, or <constant>GL_MAP_UNSYNCHRONIZED_BIT</constant> is set. |
| 193 | </para> |
| 194 | </listitem> |
| 195 | <listitem> |
| 196 | <para> |
| 197 | <constant>GL_MAP_FLUSH_EXPLICIT_BIT</constant> is set and <constant>GL_MAP_WRITE_BIT</constant> is not set. |
| 198 | </para> |
| 199 | </listitem> |
| 200 | </itemizedlist> |
| 201 | </para> |
| 202 | <para> |
| 203 | <constant>GL_OUT_OF_MEMORY</constant> is generated if <function>glMapBufferRange</function> fails because memory for the |
| 204 | mapping could not be obtained. |
| 205 | </para> |
| 206 | </refsect1> |
| 207 | <refsect1 id="seealso"><title>See Also</title> |
| 208 | <para> |
| 209 | <citerefentry><refentrytitle>glMapBuffer</refentrytitle></citerefentry>, |
| 210 | <citerefentry><refentrytitle>glFlushMappedBufferRange</refentrytitle></citerefentry>, |
| 211 | <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry> |
| 212 | </para> |
| 213 | </refsect1> |
| 214 | <refsect1 id="Copyright"><title>Copyright</title> |
| 215 | <para> |
| 216 | Copyright <trademark class="copyright"></trademark> 2010-2012 Khronos Group. |
| 217 | This material may be distributed subject to the terms and conditions set forth in |
| 218 | the Open Publication License, v 1.0, 8 June 1999. |
| 219 | <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>. |
| 220 | </para> |
| 221 | </refsect1> |
| 222 | </refentry> |