upstream-doc/man4/glMapBuffer.xml

   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="glMapBuffer">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>2005</year>
   9                 <holder>Sams Publishing</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glMapBuffer</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glMapBuffer</refname>
  17         <refpurpose>map a buffer object's data store</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void * <function>glMapBuffer</function></funcdef>
  23                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  24                 <paramdef>GLenum <parameter>access</parameter></paramdef>
  25             </funcprototype>
  26         </funcsynopsis>
  27     </refsynopsisdiv>
  28     <refsect1 id="parameters"><title>Parameters</title>
  29         <variablelist>
  30         <varlistentry>
  31             <term><parameter>target</parameter></term>
  32             <listitem>
  33                 <para>
  34                     Specifies the target buffer object being mapped.
  35                     The symbolic constant must be
  36                     <constant>GL_ARRAY_BUFFER</constant>,
  37                     <constant>GL_ATOMIC_COUNTER_BUFFER</constant>,
  38                     <constant>GL_COPY_READ_BUFFER</constant>,
  39                     <constant>GL_COPY_WRITE_BUFFER</constant>,
  40                     <constant>GL_DRAW_INDIRECT_BUFFER</constant>,
  41                     <constant>GL_DISPATCH_INDIRECT_BUFFER</constant>,
  42                     <constant>GL_ELEMENT_ARRAY_BUFFER</constant>,
  43                     <constant>GL_PIXEL_PACK_BUFFER</constant>,
  44                     <constant>GL_PIXEL_UNPACK_BUFFER</constant>,
  45                     <constant>GL_SHADER_STORAGE_BUFFER</constant>,
  46                     <constant>GL_TEXTURE_BUFFER</constant>,
  47                     <constant>GL_TRANSFORM_FEEDBACK_BUFFER</constant> or
  48                     <constant>GL_UNIFORM_BUFFER</constant>.
  49                 </para>
  50             </listitem>
  51         </varlistentry>
  52         <varlistentry>
  53             <term><parameter>access</parameter></term>
  54             <listitem>
  55                 <para>
  56                     Specifies the access policy, indicating whether it will be possible to read from, write to,
  57                     or both read from and write to the buffer object's mapped data store. The symbolic constant must be
  58                     <constant>GL_READ_ONLY</constant>, <constant>GL_WRITE_ONLY</constant>, or <constant>GL_READ_WRITE</constant>.
  59                 </para>
  60             </listitem>
  61         </varlistentry>
  62         </variablelist>
  63     </refsect1>
  64     <refsynopsisdiv><title>C Specification</title>
  65         <funcsynopsis>
  66             <funcprototype>
  67                 <funcdef>GLboolean <function>glUnmapBuffer</function></funcdef>
  68                 <paramdef>GLenum <parameter>target</parameter></paramdef>
  69             </funcprototype>
  70         </funcsynopsis>
  71     </refsynopsisdiv>
  72     <!-- eqn: ignoring delim $$ -->
  73     <refsect1 id="parameters2"><title>Parameters</title>
  74         <variablelist>
  75         <varlistentry>
  76             <term><parameter>target</parameter></term>
  77             <listitem>
  78                 <para>
  79                     Specifies the target buffer object being unmapped.
  80                     The symbolic constant must be
  81                     <constant>GL_ARRAY_BUFFER</constant>,
  82                     <constant>GL_ATOMIC_COUNTER_BUFFER</constant>,
  83                     <constant>GL_COPY_READ_BUFFER</constant>,
  84                     <constant>GL_COPY_WRITE_BUFFER</constant>,
  85                     <constant>GL_DRAW_INDIRECT_BUFFER</constant>,
  86                     <constant>GL_DISPATCH_INDIRECT_BUFFER</constant>,
  87                     <constant>GL_ELEMENT_ARRAY_BUFFER</constant>,
  88                     <constant>GL_PIXEL_PACK_BUFFER</constant>,
  89                     <constant>GL_PIXEL_UNPACK_BUFFER</constant>,
  90                     <constant>GL_SHADER_STORAGE_BUFFER</constant>,
  91                     <constant>GL_TEXTURE_BUFFER</constant>,
  92                     <constant>GL_TRANSFORM_FEEDBACK_BUFFER</constant> or
  93                     <constant>GL_UNIFORM_BUFFER</constant>.
  94                 </para>
  95             </listitem>
  96         </varlistentry>
  97         </variablelist>
  98     </refsect1>
  99     <refsect1 id="description"><title>Description</title>
 100         <para>
 101             <function>glMapBuffer</function> maps to the client's address space the entire data store of the buffer object
 102             currently bound to <parameter>target</parameter>. The data can then be directly read and/or written relative to
 103             the returned pointer, depending on the specified <parameter>access</parameter> policy. If the GL is unable to
 104             map the buffer object's data store, <function>glMapBuffer</function> generates an error and returns
 105             <constant>NULL</constant>. This may occur for system-specific reasons, such as low virtual memory availability.
 106             If no error occurs, the returned pointer will have an alignment of at least <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant>
 107             basic machine units. The value of <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant> can be retrieved by calling
 108             <citerefentry><refentrytitle>glGet</refentrytitle></citerefentry> with <parameter>pname</parameter> set to
 109             <constant>GL_MIN_MAP_BUFFER_ALIGNMENT</constant> and must be a power of two that is at least 64.
 110         </para>
 111         <para>
 112             If a mapped data store is accessed in a way inconsistent with the specified <parameter>access</parameter> policy,
 113             no error is generated, but performance may be negatively impacted and system errors, including program
 114             termination, may result. Unlike the <parameter>usage</parameter> parameter of <function>glBufferData</function>,
 115             <parameter>access</parameter> is not a hint, and does in fact constrain the usage of the mapped data store on
 116             some GL implementations. In order to achieve the highest performance available, a buffer object's data store
 117             should be used in ways consistent with both its specified <parameter>usage</parameter> and
 118             <parameter>access</parameter> parameters.
 119         </para>
 120         <para>
 121             A mapped data store must be unmapped with <function>glUnmapBuffer</function> before its buffer object is used.
 122             Otherwise an error will be generated by any GL command that attempts to dereference the buffer object's data store.
 123             When a data store is unmapped, the pointer to its data store becomes invalid. <function>glUnmapBuffer</function>
 124             returns <constant>GL_TRUE</constant> unless the data store contents have become corrupt during the time
 125             the data store was mapped. This can occur for system-specific reasons that affect the availability of graphics
 126             memory, such as screen mode changes. In such situations, <constant>GL_FALSE</constant> is returned and the
 127             data store contents are undefined. An application must detect this rare condition and reinitialize the data store.
 128         </para>
 129         <para>
 130             A buffer object's mapped data store is automatically unmapped when the buffer object is deleted or its data store
 131             is recreated with <function>glBufferData</function>.
 132         </para>
 133     </refsect1>
 134     <refsect1 id="notes"><title>Notes</title>
 135         <para>
 136             If an error is generated, <function>glMapBuffer</function> returns <constant>NULL</constant>, and
 137             <function>glUnmapBuffer</function> returns <constant>GL_FALSE</constant>.
 138         </para>
 139         <para>
 140             Parameter values passed to GL commands may not be sourced from the returned pointer. No error will be generated,
 141             but results will be undefined and will likely vary across GL implementations.
 142         </para>
 143         <para>
 144             Alignment of the returned pointer is guaranteed only if the version
 145             of the GL version is 4.2 or greater. Also, the <constant>GL_ATOMIC_COUNTER_BUFFER</constant>
 146             target is accepted only if the GL version is 4.2 or greater.
 147         </para>
 148         <para>
 149             The <constant>GL_DISPATCH_INDIRECT_BUFFER</constant> and <constant>GL_SHADER_STORAGE_BUFFER</constant> targets are available only if the GL version
 150             is 4.3 or greater.
 151         </para>
 152     </refsect1>
 153     <refsect1 id="errors"><title>Errors</title>
 154         <para>
 155             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>target</parameter> is not
 156             one of the accepted targets.
 157         </para>
 158         <para>
 159             <constant>GL_INVALID_ENUM</constant> is generated if <parameter>access</parameter> is not
 160             <constant>GL_READ_ONLY</constant>, <constant>GL_WRITE_ONLY</constant>, or <constant>GL_READ_WRITE</constant>.
 161         </para>
 162         <para>
 163             <constant>GL_OUT_OF_MEMORY</constant> is generated when <function>glMapBuffer</function> is executed
 164             if the GL is unable to map the buffer object's data store. This may occur for a variety of system-specific
 165             reasons, such as the absence of sufficient remaining virtual memory.
 166         </para>
 167         <para>
 168             <constant>GL_INVALID_OPERATION</constant> is generated if the reserved buffer object name 0 is bound to <parameter>target</parameter>.
 169         </para>
 170         <para>
 171             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glMapBuffer</function> is executed for
 172             a buffer object whose data store is already mapped.
 173         </para>
 174         <para>
 175             <constant>GL_INVALID_OPERATION</constant> is generated if <function>glUnmapBuffer</function> is executed for
 176             a buffer object whose data store is not currently mapped.
 177         </para>
 178     </refsect1>
 179     <refsect1 id="associatedgets"><title>Associated Gets</title>
 180         <para>
 181             <citerefentry><refentrytitle>glGetBufferPointerv</refentrytitle></citerefentry> with argument <constant>GL_BUFFER_MAP_POINTER</constant>
 182         </para>
 183         <para>
 184             <citerefentry><refentrytitle>glGetBufferParameter</refentrytitle></citerefentry> with argument <constant>GL_BUFFER_MAPPED</constant>,  <constant>GL_BUFFER_ACCESS</constant>, or <constant>GL_BUFFER_USAGE</constant>
 185         </para>
 186     </refsect1>
 187     <refsect1 id="seealso"><title>See Also</title>
 188         <para>
 189             <citerefentry><refentrytitle>glBindBuffer</refentrytitle></citerefentry>,
 190             <citerefentry><refentrytitle>glBindBufferBase</refentrytitle></citerefentry>,
 191             <citerefentry><refentrytitle>glBindBufferRange</refentrytitle></citerefentry>,
 192             <citerefentry><refentrytitle>glBufferData</refentrytitle></citerefentry>,
 193             <citerefentry><refentrytitle>glBufferSubData</refentrytitle></citerefentry>,
 194             <citerefentry><refentrytitle>glDeleteBuffers</refentrytitle></citerefentry>
 195         </para>
 196     </refsect1>
 197     <refsect1 id="Copyright"><title>Copyright</title>
 198         <para>
 199             Copyright <trademark class="copyright"></trademark> 2005 Addison-Wesley.
 200             Copyright <trademark class="copyright"></trademark> 2010-2011 Khronos Group.
 201             This material may be distributed subject to the terms and conditions set forth in
 202             the Open Publication License, v 1.0, 8 June 1999.
 203             <ulink url="http://opencontent.org/openpub/">http://opencontent.org/openpub/</ulink>.
 204         </para>
 205     </refsect1>
 206 </refentry>