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