[clinton/guile-figl.git] / upstream-doc / man4 / xhtml / glMapBuffer.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
<!-- saved from url=(0013)about:internet -->
<?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><link rel="stylesheet" type="text/css" href="opengl-man.css" /><title>glMapBuffer - OpenGL 4 Reference Pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.1" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glMapBuffer"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glMapBuffer — map a buffer object's data store</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void * <b class="fsfunc">glMapBuffer</b>(</code></td><td>GLenum  </td><td><var class="pdparam">target</var>, </td></tr><tr><td> </td><td>GLenum  </td><td><var class="pdparam">access</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>
                    Specifies the target buffer object being mapped.
                    The symbolic constant must be
                    <code class="constant">GL_ARRAY_BUFFER</code>,
                    <code class="constant">GL_ATOMIC_COUNTER_BUFFER</code>,
                    <code class="constant">GL_COPY_READ_BUFFER</code>,
                    <code class="constant">GL_COPY_WRITE_BUFFER</code>,
                    <code class="constant">GL_DRAW_INDIRECT_BUFFER</code>,
                    <code class="constant">GL_DISPATCH_INDIRECT_BUFFER</code>,
                    <code class="constant">GL_ELEMENT_ARRAY_BUFFER</code>,
                    <code class="constant">GL_PIXEL_PACK_BUFFER</code>,
                    <code class="constant">GL_PIXEL_UNPACK_BUFFER</code>,
                    <code class="constant">GL_SHADER_STORAGE_BUFFER</code>,
                    <code class="constant">GL_TEXTURE_BUFFER</code>,
                    <code class="constant">GL_TRANSFORM_FEEDBACK_BUFFER</code> or
                    <code class="constant">GL_UNIFORM_BUFFER</code>.
                </p></dd><dt><span class="term"><em class="parameter"><code>access</code></em></span></dt><dd><p>
                    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
                    <code class="constant">GL_READ_ONLY</code>, <code class="constant">GL_WRITE_ONLY</code>, or <code class="constant">GL_READ_WRITE</code>.
                </p></dd></dl></div></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><p><code class="funcdef">GLboolean <b class="fsfunc">glUnmapBuffer</b>(</code>GLenum <var class="pdparam">target</var><code>)</code>;</p></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters2"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>
                    Specifies the target buffer object being unmapped.
                    The symbolic constant must be
                    <code class="constant">GL_ARRAY_BUFFER</code>,
                    <code class="constant">GL_ATOMIC_COUNTER_BUFFER</code>,
                    <code class="constant">GL_COPY_READ_BUFFER</code>,
                    <code class="constant">GL_COPY_WRITE_BUFFER</code>,
                    <code class="constant">GL_DRAW_INDIRECT_BUFFER</code>,
                    <code class="constant">GL_DISPATCH_INDIRECT_BUFFER</code>,
                    <code class="constant">GL_ELEMENT_ARRAY_BUFFER</code>,
                    <code class="constant">GL_PIXEL_PACK_BUFFER</code>,
                    <code class="constant">GL_PIXEL_UNPACK_BUFFER</code>,
                    <code class="constant">GL_SHADER_STORAGE_BUFFER</code>,
                    <code class="constant">GL_TEXTURE_BUFFER</code>,
                    <code class="constant">GL_TRANSFORM_FEEDBACK_BUFFER</code> or
                    <code class="constant">GL_UNIFORM_BUFFER</code>.
                </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
            <code class="function">glMapBuffer</code> maps to the client's address space the entire data store of the buffer object 
            currently bound to <em class="parameter"><code>target</code></em>. The data can then be directly read and/or written relative to 
            the returned pointer, depending on the specified <em class="parameter"><code>access</code></em> policy. If the GL is unable to
            map the buffer object's data store, <code class="function">glMapBuffer</code> generates an error and returns 
            <code class="constant">NULL</code>. This may occur for system-specific reasons, such as low virtual memory availability.
            If no error occurs, the returned pointer will have an alignment of at least <code class="constant">GL_MIN_MAP_BUFFER_ALIGNMENT</code>
            basic machine units. The value of <code class="constant">GL_MIN_MAP_BUFFER_ALIGNMENT</code> can be retrieved by calling
            <a href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with <em class="parameter"><code>pname</code></em> set to
            <code class="constant">GL_MIN_MAP_BUFFER_ALIGNMENT</code> and must be a power of two that is at least 64.
        </p><p>
            If a mapped data store is accessed in a way inconsistent with the specified <em class="parameter"><code>access</code></em> policy,
            no error is generated, but performance may be negatively impacted and system errors, including program 
            termination, may result. Unlike the <em class="parameter"><code>usage</code></em> parameter of <code class="function">glBufferData</code>, 
            <em class="parameter"><code>access</code></em> 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 <em class="parameter"><code>usage</code></em> and 
            <em class="parameter"><code>access</code></em> parameters.
        </p><p>
            A mapped data store must be unmapped with <code class="function">glUnmapBuffer</code> 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. <code class="function">glUnmapBuffer</code>
            returns <code class="constant">GL_TRUE</code> 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, <code class="constant">GL_FALSE</code> is returned and the
            data store contents are undefined. An application must detect this rare condition and reinitialize the data store.
        </p><p>
            A buffer object's mapped data store is automatically unmapped when the buffer object is deleted or its data store 
            is recreated with <code class="function">glBufferData</code>.
        </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
            If an error is generated, <code class="function">glMapBuffer</code> returns <code class="constant">NULL</code>, and
            <code class="function">glUnmapBuffer</code> returns <code class="constant">GL_FALSE</code>.
        </p><p>
            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.
        </p><p>
            Alignment of the returned pointer is guaranteed only if the version
            of the GL version is 4.2 or greater. Also, the <code class="constant">GL_ATOMIC_COUNTER_BUFFER</code>
            target is accepted only if the GL version is 4.2 or greater.
        </p><p>
            The <code class="constant">GL_DISPATCH_INDIRECT_BUFFER</code> and <code class="constant">GL_SHADER_STORAGE_BUFFER</code> targets are available only if the GL version
            is 4.3 or greater.
        </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
            <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>target</code></em> is not
            one of the accepted targets.
        </p><p>
            <code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>access</code></em> is not 
            <code class="constant">GL_READ_ONLY</code>, <code class="constant">GL_WRITE_ONLY</code>, or <code class="constant">GL_READ_WRITE</code>.
        </p><p>
            <code class="constant">GL_OUT_OF_MEMORY</code> is generated when <code class="function">glMapBuffer</code> 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.
        </p><p>
            <code class="constant">GL_INVALID_OPERATION</code> is generated if the reserved buffer object name 0 is bound to <em class="parameter"><code>target</code></em>.
        </p><p>
            <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glMapBuffer</code> is executed for
            a buffer object whose data store is already mapped.
        </p><p>
            <code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glUnmapBuffer</code> is executed for
            a buffer object whose data store is not currently mapped.
        </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
            <a href="glGetBufferPointerv.xml"><span class="citerefentry"><span class="refentrytitle">glGetBufferPointerv</span></span></a> with argument <code class="constant">GL_BUFFER_MAP_POINTER</code>
        </p><p>
            <a href="glGetBufferParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetBufferParameter</span></span></a> with argument <code class="constant">GL_BUFFER_MAPPED</code>,  <code class="constant">GL_BUFFER_ACCESS</code>, or <code class="constant">GL_BUFFER_USAGE</code>
        </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
            <a href="glBindBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glBindBuffer</span></span></a>,
            <a href="glBindBufferBase.xml"><span class="citerefentry"><span class="refentrytitle">glBindBufferBase</span></span></a>,
            <a href="glBindBufferRange.xml"><span class="citerefentry"><span class="refentrytitle">glBindBufferRange</span></span></a>,
            <a href="glBufferData.xml"><span class="citerefentry"><span class="refentrytitle">glBufferData</span></span></a>,
            <a href="glBufferSubData.xml"><span class="citerefentry"><span class="refentrytitle">glBufferSubData</span></span></a>,
            <a href="glDeleteBuffers.xml"><span class="citerefentry"><span class="refentrytitle">glDeleteBuffers</span></span></a>
        </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
            Copyright <span class="trademark"></span>© 2005 Addison-Wesley.
            Copyright <span class="trademark"></span>© 2010-2011 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.
            <a href="http://opencontent.org/openpub/" target="_top">http://opencontent.org/openpub/</a>.
        </p></div></div></body></html>
Commit	Line	Data
7faf1d71 AW	1	<?xml version="1.0" encoding="UTF-8"?>
	2	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
	3	<!-- saved from url=(0013)about:internet -->
	4	<?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><link rel="stylesheet" type="text/css" href="opengl-man.css" /><title>glMapBuffer - OpenGL 4 Reference Pages</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.1" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glMapBuffer"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glMapBuffer — map a buffer object's data store</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">void * <b class="fsfunc">glMapBuffer</b>(</code></td><td>GLenum </td><td><var class="pdparam">target</var>, </td></tr><tr><td> </td><td>GLenum </td><td><var class="pdparam">access</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>
	5	Specifies the target buffer object being mapped.
	6	The symbolic constant must be
	7	<code class="constant">GL_ARRAY_BUFFER</code>,
	8	<code class="constant">GL_ATOMIC_COUNTER_BUFFER</code>,
	9	<code class="constant">GL_COPY_READ_BUFFER</code>,
	10	<code class="constant">GL_COPY_WRITE_BUFFER</code>,
	11	<code class="constant">GL_DRAW_INDIRECT_BUFFER</code>,
	12	<code class="constant">GL_DISPATCH_INDIRECT_BUFFER</code>,
	13	<code class="constant">GL_ELEMENT_ARRAY_BUFFER</code>,
	14	<code class="constant">GL_PIXEL_PACK_BUFFER</code>,
	15	<code class="constant">GL_PIXEL_UNPACK_BUFFER</code>,
	16	<code class="constant">GL_SHADER_STORAGE_BUFFER</code>,
	17	<code class="constant">GL_TEXTURE_BUFFER</code>,
	18	<code class="constant">GL_TRANSFORM_FEEDBACK_BUFFER</code> or
	19	<code class="constant">GL_UNIFORM_BUFFER</code>.
	20	</p></dd><dt><span class="term"><em class="parameter"><code>access</code></em></span></dt><dd><p>
	21	Specifies the access policy, indicating whether it will be possible to read from, write to,
	22	or both read from and write to the buffer object's mapped data store. The symbolic constant must be
	23	<code class="constant">GL_READ_ONLY</code>, <code class="constant">GL_WRITE_ONLY</code>, or <code class="constant">GL_READ_WRITE</code>.
	24	</p></dd></dl></div></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><p><code class="funcdef">GLboolean <b class="fsfunc">glUnmapBuffer</b>(</code>GLenum <var class="pdparam">target</var><code>)</code>;</p></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters2"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>target</code></em></span></dt><dd><p>
	25	Specifies the target buffer object being unmapped.
	26	The symbolic constant must be
	27	<code class="constant">GL_ARRAY_BUFFER</code>,
	28	<code class="constant">GL_ATOMIC_COUNTER_BUFFER</code>,
	29	<code class="constant">GL_COPY_READ_BUFFER</code>,
	30	<code class="constant">GL_COPY_WRITE_BUFFER</code>,
	31	<code class="constant">GL_DRAW_INDIRECT_BUFFER</code>,
	32	<code class="constant">GL_DISPATCH_INDIRECT_BUFFER</code>,
	33	<code class="constant">GL_ELEMENT_ARRAY_BUFFER</code>,
	34	<code class="constant">GL_PIXEL_PACK_BUFFER</code>,
	35	<code class="constant">GL_PIXEL_UNPACK_BUFFER</code>,
	36	<code class="constant">GL_SHADER_STORAGE_BUFFER</code>,
	37	<code class="constant">GL_TEXTURE_BUFFER</code>,
	38	<code class="constant">GL_TRANSFORM_FEEDBACK_BUFFER</code> or
	39	<code class="constant">GL_UNIFORM_BUFFER</code>.
	40	</p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
	41	<code class="function">glMapBuffer</code> maps to the client's address space the entire data store of the buffer object
	42	currently bound to <em class="parameter"><code>target</code></em>. The data can then be directly read and/or written relative to
	43	the returned pointer, depending on the specified <em class="parameter"><code>access</code></em> policy. If the GL is unable to
	44	map the buffer object's data store, <code class="function">glMapBuffer</code> generates an error and returns
	45	<code class="constant">NULL</code>. This may occur for system-specific reasons, such as low virtual memory availability.
	46	If no error occurs, the returned pointer will have an alignment of at least <code class="constant">GL_MIN_MAP_BUFFER_ALIGNMENT</code>
	47	basic machine units. The value of <code class="constant">GL_MIN_MAP_BUFFER_ALIGNMENT</code> can be retrieved by calling
	48	<a href="glGet.xml"><span class="citerefentry"><span class="refentrytitle">glGet</span></span></a> with <em class="parameter"><code>pname</code></em> set to
	49	<code class="constant">GL_MIN_MAP_BUFFER_ALIGNMENT</code> and must be a power of two that is at least 64.
	50	</p><p>
	51	If a mapped data store is accessed in a way inconsistent with the specified <em class="parameter"><code>access</code></em> policy,
	52	no error is generated, but performance may be negatively impacted and system errors, including program
	53	termination, may result. Unlike the <em class="parameter"><code>usage</code></em> parameter of <code class="function">glBufferData</code>,
	54	<em class="parameter"><code>access</code></em> is not a hint, and does in fact constrain the usage of the mapped data store on
	55	some GL implementations. In order to achieve the highest performance available, a buffer object's data store
	56	should be used in ways consistent with both its specified <em class="parameter"><code>usage</code></em> and
	57	<em class="parameter"><code>access</code></em> parameters.
	58	</p><p>
	59	A mapped data store must be unmapped with <code class="function">glUnmapBuffer</code> before its buffer object is used.
	60	Otherwise an error will be generated by any GL command that attempts to dereference the buffer object's data store.
	61	When a data store is unmapped, the pointer to its data store becomes invalid. <code class="function">glUnmapBuffer</code>
	62	returns <code class="constant">GL_TRUE</code> unless the data store contents have become corrupt during the time
	63	the data store was mapped. This can occur for system-specific reasons that affect the availability of graphics
	64	memory, such as screen mode changes. In such situations, <code class="constant">GL_FALSE</code> is returned and the
65	data store contents are undefined. An application must detect this rare condition and reinitialize the data store.
66	</p><p>
67	A buffer object's mapped data store is automatically unmapped when the buffer object is deleted or its data store
68	is recreated with <code class="function">glBufferData</code>.
69	</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
70	If an error is generated, <code class="function">glMapBuffer</code> returns <code class="constant">NULL</code>, and
71	<code class="function">glUnmapBuffer</code> returns <code class="constant">GL_FALSE</code>.
72	</p><p>
73	Parameter values passed to GL commands may not be sourced from the returned pointer. No error will be generated,
74	but results will be undefined and will likely vary across GL implementations.
75	</p><p>
76	Alignment of the returned pointer is guaranteed only if the version
77	of the GL version is 4.2 or greater. Also, the <code class="constant">GL_ATOMIC_COUNTER_BUFFER</code>
78	target is accepted only if the GL version is 4.2 or greater.
79	</p><p>
80	The <code class="constant">GL_DISPATCH_INDIRECT_BUFFER</code> and <code class="constant">GL_SHADER_STORAGE_BUFFER</code> targets are available only if the GL version
81	is 4.3 or greater.
82	</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
83	<code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>target</code></em> is not
84	one of the accepted targets.
85	</p><p>
86	<code class="constant">GL_INVALID_ENUM</code> is generated if <em class="parameter"><code>access</code></em> is not
87	<code class="constant">GL_READ_ONLY</code>, <code class="constant">GL_WRITE_ONLY</code>, or <code class="constant">GL_READ_WRITE</code>.
88	</p><p>
89	<code class="constant">GL_OUT_OF_MEMORY</code> is generated when <code class="function">glMapBuffer</code> is executed
90	if the GL is unable to map the buffer object's data store. This may occur for a variety of system-specific
91	reasons, such as the absence of sufficient remaining virtual memory.
92	</p><p>
93	<code class="constant">GL_INVALID_OPERATION</code> is generated if the reserved buffer object name 0 is bound to <em class="parameter"><code>target</code></em>.
94	</p><p>
95	<code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glMapBuffer</code> is executed for
96	a buffer object whose data store is already mapped.
97	</p><p>
98	<code class="constant">GL_INVALID_OPERATION</code> is generated if <code class="function">glUnmapBuffer</code> is executed for
99	a buffer object whose data store is not currently mapped.
100	</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="associatedgets"></a><h2>Associated Gets</h2><p>
101	<a href="glGetBufferPointerv.xml"><span class="citerefentry"><span class="refentrytitle">glGetBufferPointerv</span></span></a> with argument <code class="constant">GL_BUFFER_MAP_POINTER</code>
102	</p><p>
103	<a href="glGetBufferParameter.xml"><span class="citerefentry"><span class="refentrytitle">glGetBufferParameter</span></span></a> with argument <code class="constant">GL_BUFFER_MAPPED</code>, <code class="constant">GL_BUFFER_ACCESS</code>, or <code class="constant">GL_BUFFER_USAGE</code>
104	</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
105	<a href="glBindBuffer.xml"><span class="citerefentry"><span class="refentrytitle">glBindBuffer</span></span></a>,
106	<a href="glBindBufferBase.xml"><span class="citerefentry"><span class="refentrytitle">glBindBufferBase</span></span></a>,
107	<a href="glBindBufferRange.xml"><span class="citerefentry"><span class="refentrytitle">glBindBufferRange</span></span></a>,
108	<a href="glBufferData.xml"><span class="citerefentry"><span class="refentrytitle">glBufferData</span></span></a>,
109	<a href="glBufferSubData.xml"><span class="citerefentry"><span class="refentrytitle">glBufferSubData</span></span></a>,
110	<a href="glDeleteBuffers.xml"><span class="citerefentry"><span class="refentrytitle">glDeleteBuffers</span></span></a>
111	</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
112	Copyright <span class="trademark"></span>© 2005 Addison-Wesley.
113	Copyright <span class="trademark"></span>© 2010-2011 Khronos Group.
114	This material may be distributed subject to the terms and conditions set forth in
115	the Open Publication License, v 1.0, 8 June 1999.
116	<a href="http://opencontent.org/openpub/" target="_top">http://opencontent.org/openpub/</a>.
117	</p></div></div></body></html>