[clinton/guile-figl.git] / upstream-doc / man2 / glXCreatePbuffer.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="glXCreatePbuffer">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glXCreatePbuffer</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glXCreatePbuffer</refname>
        <refpurpose>create an off-screen rendering area</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>GLXPbuffer <function>glXCreatePbuffer</function></funcdef>
                <paramdef>Display * <parameter>dpy</parameter></paramdef>
                <paramdef>GLXFBConfig <parameter>config</parameter></paramdef>
                <paramdef>const int * <parameter>attrib_list</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <!-- eqn: ignoring delim $$ -->
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>dpy</parameter></term>
            <listitem>
                <para>
                    Specifies the connection to the X server.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>config</parameter></term>
            <listitem>
                <para>
                    Specifies a GLXFBConfig structure with the desired attributes for the
                    window.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>attrib_list</parameter></term>
            <listitem>
                <para>
                    Specifies a list of attribute value pairs, which must be terminated with
                    <constant>None</constant> or <constant>NULL</constant>. Accepted attributes are
                    <constant>GLX_PBUFFER_WIDTH</constant>, <constant>GLX_PBUFFER_HEIGHT</constant>, 
                    <constant>GLX_PRESERVED_CONTENTS</constant>, and <constant>GLX_LARGEST_PBUFFER</constant>.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glXCreatePbuffer</function> creates an off-screen rendering area and returns its XID.
            Any GLX rendering context that was created with respect to <parameter>config</parameter>
            can be used to render into this window.
            Use <citerefentry><refentrytitle>glXMakeContextCurrent</refentrytitle></citerefentry> to associate the rendering area with a GLX
            rendering context.
        </para>
        <para>
            The accepted attributes for a GLXPbuffer are:
        </para>
        <variablelist>
            <varlistentry>
                <term><constant>GLX_PBUFFER_WIDTH</constant></term>
                <listitem>
                    <para>
                        Specify the pixel width of the requested GLXPbuffer. The default value
                        is 0.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_PBUFFER_HEIGHT</constant></term>
                <listitem>
                    <para>
                        Specify the pixel height of the requested GLXPbuffer. The default value
                        is 0.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_LARGEST_PBUFFER</constant></term>
                <listitem>
                    <para>
                        Specify to obtain the largest available pixel buffer, if the requested
                        allocation would have failed. The width and height of the allocated
                        pixel buffer will never exceed the specified <constant>GLX_PBUFFER_WIDTH</constant> or
                        <constant>GLX_PBUFFER_HEIGHT</constant>, respectively.  Use <citerefentry><refentrytitle>glXQueryDrawable</refentrytitle></citerefentry> to
                        retrieve the dimensions of the allocated pixel buffer. The default value is
                        <constant>False</constant>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term><constant>GLX_PRESERVED_CONTENTS</constant></term>
                <listitem>
                    <para>
                        Specify if the contents of the pixel buffer should be preserved when a
                        resource conflict occurs.  If set to <constant>False</constant>, the contents of the 
                        pixel buffer may be lost at any time.  If set to <constant>True</constant>, or not
                        specified in <parameter>attrib_list</parameter>, then the contents of the pixel buffer will be preserved 
                        (most likely by copying the contents into main system memory from the
                        frame buffer).  In either case, the client can register (using
                        <citerefentry><refentrytitle>glXSelectEvent</refentrytitle></citerefentry>, to receive
                        pixel buffer clobber events that are generated when the pbuffer contents have
                        been preserved or damaged.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            GLXPbuffers contain the color and ancillary buffers specified by
            <parameter>config</parameter>.  It is possible to create a pixel buffer with back buffers and
            to swap those buffers using <citerefentry><refentrytitle>glXSwapBuffers</refentrytitle></citerefentry>.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            <function>glXCreatePbuffer</function> is available only if the GLX version is 1.3 or greater.
        </para>
        <para>
            If the GLX version is 1.1 or 1.0, the GL version must be 1.0.
            If the GLX version is 1.2, then the GL version must be 1.1.
            If the GLX version is 1.3, then the GL version must be 1.2.
        </para>
        <para>
            GLXPbuffers are allocated from frame buffer resources; applications
            should consider deallocating them when they are not in use.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>BadAlloc</constant> is generated if there are insufficient resources to
            allocate the requested GLXPbuffer.
        </para>
        <para>
            <constant>GLXBadFBConfig</constant> is generated if <parameter>config</parameter> is not a valid
            GLXFBConfig.
        </para>
        <para>
            <constant>BadMatch</constant> is generated if <parameter>config</parameter> does not support rendering to
            pixel buffers (e.g., <constant>GLX_DRAWABLE_TYPE</constant> does not contain
            <constant>GLX_PBUFFER_BIT</constant>).
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glXChooseFBConfig</refentrytitle></citerefentry>,
            <function>glXCreatePbuffer</function>,
            <citerefentry><refentrytitle>glXMakeContextCurrent</refentrytitle></citerefentry>,
            <citerefentry><refentrytitle>glXSelectEvent</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 1991-2006
            Silicon Graphics, Inc. This document is licensed under the SGI
            Free Software B License. For details, see
            <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</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="glXCreatePbuffer">
	5	<refmeta>
	6	<refmetainfo>
	7	<copyright>
	8	<year>1991-2006</year>
	9	<holder>Silicon Graphics, Inc.</holder>
	10	</copyright>
	11	</refmetainfo>
	12	<refentrytitle>glXCreatePbuffer</refentrytitle>
	13	<manvolnum>3G</manvolnum>
	14	</refmeta>
	15	<refnamediv>
	16	<refname>glXCreatePbuffer</refname>
	17	<refpurpose>create an off-screen rendering area</refpurpose>
	18	</refnamediv>
	19	<refsynopsisdiv><title>C Specification</title>
	20	<funcsynopsis>
	21	<funcprototype>
	22	<funcdef>GLXPbuffer <function>glXCreatePbuffer</function></funcdef>
	23	<paramdef>Display * <parameter>dpy</parameter></paramdef>
	24	<paramdef>GLXFBConfig <parameter>config</parameter></paramdef>
	25	<paramdef>const int * <parameter>attrib_list</parameter></paramdef>
	26	</funcprototype>
	27	</funcsynopsis>
	28	</refsynopsisdiv>
	29	<!-- eqn: ignoring delim $$ -->
	30	<refsect1 id="parameters"><title>Parameters</title>
	31	<variablelist>
	32	<varlistentry>
	33	<term><parameter>dpy</parameter></term>
	34	<listitem>
	35	<para>
	36	Specifies the connection to the X server.
	37	</para>
	38	</listitem>
	39	</varlistentry>
	40	<varlistentry>
	41	<term><parameter>config</parameter></term>
	42	<listitem>
	43	<para>
	44	Specifies a GLXFBConfig structure with the desired attributes for the
	45	window.
	46	</para>
	47	</listitem>
	48	</varlistentry>
	49	<varlistentry>
	50	<term><parameter>attrib_list</parameter></term>
	51	<listitem>
	52	<para>
	53	Specifies a list of attribute value pairs, which must be terminated with
	54	<constant>None</constant> or <constant>NULL</constant>. Accepted attributes are
	55	<constant>GLX_PBUFFER_WIDTH</constant>, <constant>GLX_PBUFFER_HEIGHT</constant>,
	56	<constant>GLX_PRESERVED_CONTENTS</constant>, and <constant>GLX_LARGEST_PBUFFER</constant>.
	57	</para>
	58	</listitem>
	59	</varlistentry>
	60	</variablelist>
	61	</refsect1>
	62	<refsect1 id="description"><title>Description</title>
	63	<para>
	64	<function>glXCreatePbuffer</function> creates an off-screen rendering area and returns its XID.
65	Any GLX rendering context that was created with respect to <parameter>config</parameter>
66	can be used to render into this window.
67	Use <citerefentry><refentrytitle>glXMakeContextCurrent</refentrytitle></citerefentry> to associate the rendering area with a GLX
68	rendering context.
69	</para>
70	<para>
71	The accepted attributes for a GLXPbuffer are:
72	</para>
73	<variablelist>
74	<varlistentry>
75	<term><constant>GLX_PBUFFER_WIDTH</constant></term>
76	<listitem>
77	<para>
78	Specify the pixel width of the requested GLXPbuffer. The default value
79	is 0.
80	</para>
81	</listitem>
82	</varlistentry>
83	<varlistentry>
84	<term><constant>GLX_PBUFFER_HEIGHT</constant></term>
85	<listitem>
86	<para>
87	Specify the pixel height of the requested GLXPbuffer. The default value
88	is 0.
89	</para>
90	</listitem>
91	</varlistentry>
92	<varlistentry>
93	<term><constant>GLX_LARGEST_PBUFFER</constant></term>
94	<listitem>
95	<para>
96	Specify to obtain the largest available pixel buffer, if the requested
97	allocation would have failed. The width and height of the allocated
98	pixel buffer will never exceed the specified <constant>GLX_PBUFFER_WIDTH</constant> or
99	<constant>GLX_PBUFFER_HEIGHT</constant>, respectively. Use <citerefentry><refentrytitle>glXQueryDrawable</refentrytitle></citerefentry> to
100	retrieve the dimensions of the allocated pixel buffer. The default value is
101	<constant>False</constant>.
102	</para>
103	</listitem>
104	</varlistentry>
105	<varlistentry>
106	<term><constant>GLX_PRESERVED_CONTENTS</constant></term>
107	<listitem>
108	<para>
109	Specify if the contents of the pixel buffer should be preserved when a
110	resource conflict occurs. If set to <constant>False</constant>, the contents of the
111	pixel buffer may be lost at any time. If set to <constant>True</constant>, or not
112	specified in <parameter>attrib_list</parameter>, then the contents of the pixel buffer will be preserved
113	(most likely by copying the contents into main system memory from the
114	frame buffer). In either case, the client can register (using
115	<citerefentry><refentrytitle>glXSelectEvent</refentrytitle></citerefentry>, to receive
116	pixel buffer clobber events that are generated when the pbuffer contents have
117	been preserved or damaged.
118	</para>
119	</listitem>
120	</varlistentry>
121	</variablelist>
122	<para>
123	GLXPbuffers contain the color and ancillary buffers specified by
124	<parameter>config</parameter>. It is possible to create a pixel buffer with back buffers and
125	to swap those buffers using <citerefentry><refentrytitle>glXSwapBuffers</refentrytitle></citerefentry>.
126	</para>
127	</refsect1>
128	<refsect1 id="notes"><title>Notes</title>
129	<para>
130	<function>glXCreatePbuffer</function> is available only if the GLX version is 1.3 or greater.
131	</para>
132	<para>
133	If the GLX version is 1.1 or 1.0, the GL version must be 1.0.
134	If the GLX version is 1.2, then the GL version must be 1.1.
135	If the GLX version is 1.3, then the GL version must be 1.2.
136	</para>
137	<para>
138	GLXPbuffers are allocated from frame buffer resources; applications
139	should consider deallocating them when they are not in use.
140	</para>
141	</refsect1>
142	<refsect1 id="errors"><title>Errors</title>
143	<para>
144	<constant>BadAlloc</constant> is generated if there are insufficient resources to
145	allocate the requested GLXPbuffer.
146	</para>
147	<para>
148	<constant>GLXBadFBConfig</constant> is generated if <parameter>config</parameter> is not a valid
149	GLXFBConfig.
150	</para>
151	<para>
152	<constant>BadMatch</constant> is generated if <parameter>config</parameter> does not support rendering to
153	pixel buffers (e.g., <constant>GLX_DRAWABLE_TYPE</constant> does not contain
154	<constant>GLX_PBUFFER_BIT</constant>).
155	</para>
156	</refsect1>
157	<refsect1 id="seealso"><title>See Also</title>
158	<para>
159	<citerefentry><refentrytitle>glXChooseFBConfig</refentrytitle></citerefentry>,
160	<function>glXCreatePbuffer</function>,
161	<citerefentry><refentrytitle>glXMakeContextCurrent</refentrytitle></citerefentry>,
162	<citerefentry><refentrytitle>glXSelectEvent</refentrytitle></citerefentry>
163	</para>
164	</refsect1>
165	<refsect1 id="Copyright"><title>Copyright</title>
166	<para>
167	Copyright <trademark class="copyright"></trademark> 1991-2006
168	Silicon Graphics, Inc. This document is licensed under the SGI
169	Free Software B License. For details, see
170	<ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
171	</para>
172	</refsect1>
173	</refentry>