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