1<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglCreatePixmapSurface">
2    <info>
3         <copyright>
4             <year>2003-2014</year>
5             <holder>The Khronos Group Inc.</holder>
6         </copyright>
7    </info>
8    <refmeta>
9        <refentrytitle>eglCreatePixmapSurface</refentrytitle>
10        <manvolnum>3G</manvolnum>
11    </refmeta>
12    <refnamediv>
13        <refname>eglCreatePixmapSurface</refname>
14        <refpurpose>
15            create a new <acronym>EGL</acronym> pixmap surface
16        </refpurpose>
17    </refnamediv>
18    <refsynopsisdiv>
19        <title>C Specification</title>
20        <funcsynopsis>
21            <funcprototype>
22                <funcdef>EGLSurface <function>eglCreatePixmapSurface</function></funcdef>
23                <paramdef>EGLDisplay <parameter>display</parameter></paramdef>
24                <paramdef>EGLConfig <parameter>config</parameter></paramdef>
25                <paramdef>NativePixmapType <parameter>native_pixmap</parameter></paramdef>
26                <paramdef>EGLint const * <parameter>attrib_list</parameter></paramdef>
27            </funcprototype>
28        </funcsynopsis>
29    </refsynopsisdiv>
30    <refsect1 xml:id="parameters"><title>Parameters</title>
31        <variablelist>
32            <varlistentry>
33                <term><parameter>display</parameter></term>
34                <listitem><para>Specifies the EGL display connection.</para></listitem>
35            </varlistentry>
36            <varlistentry>
37                <term><parameter>config</parameter></term>
38                <listitem><para>
39                    Specifies the EGL frame buffer configuration that defines the
40                    frame buffer resource available to the surface.</para>
41                </listitem>
42            </varlistentry>
43            <varlistentry>
44                <term><parameter>native_pixmap</parameter></term>
45                <listitem><para>Specifies the native pixmap.</para></listitem>
46            </varlistentry>
47            <varlistentry>
48                <term><parameter>attrib_list</parameter></term>
49                <listitem><para>
50                    Specifies pixmap surface attributes.
51                    May be <constant>NULL</constant> or empty
52                    (first attribute is <constant>EGL_NONE</constant>).
53                </para></listitem>
54            </varlistentry>
55        </variablelist>
56    </refsect1>
57    <refsect1 xml:id="description"><title>Description</title>
58        <para>
59            <function>eglCreatePixmapSurface</function> creates an
60            off-screen <acronym>EGL</acronym> pixmap surface and returns
61            its handle. If <function>eglCreatePixmapSurface</function>
62            fails to create a pixmap surface,
63            <constant>EGL_NO_SURFACE</constant> is returned.
64        </para>
65        <para>
66            Surface attributes are specified as a list of
67            attribute-value pairs, terminated with
68            <constant>EGL_NONE</constant>. Accepted attributes
69            are:
70        </para>
71        <variablelist>
72            <varlistentry>
73                <term><constant>EGL_VG_ALPHA_FORMAT</constant></term>
74                <listitem>
75                <para>
76                    Specifies how alpha values are interpreted by OpenVG
77                    when rendering to the surface. If its value is
78                    <constant>EGL_VG_ALPHA_FORMAT_NONPRE</constant>,
79                    then alpha values are not premultipled. If its value
80                    is <constant>EGL_VG_ALPHA_FORMAT_PRE</constant>,
81                    then alpha values are premultiplied. The default
82                    value of <constant>EGL_VG_ALPHA_FORMAT</constant> is
83                    <constant>EGL_VG_ALPHA_FORMAT_NONPRE</constant>.
84                </para>
85                </listitem>
86            </varlistentry>
87            <varlistentry>
88                <term><constant>EGL_VG_COLORSPACE</constant></term>
89                <listitem>
90                <para>
91                    Specifies the color space used by OpenVG when
92                    rendering to the surface. If its value is
93                    <constant>EGL_VG_COLORSPACE_sRGB</constant>, then a
94                    non-linear, perceptually uniform color space is
95                    assumed, with a corresponding
96                    <type>VGImageFormat</type> of form
97                    <constant>VG_s*</constant>. If its value is
98                    <constant>EGL_VG_COLORSPACE_LINEAR</constant>, then
99                    a linear color space is assumed, with a
100                    corresponding <type>VGImageFormat</type> of form
101                    <constant>VG_l*</constant>. The default value of
102                    <constant>EGL_VG_COLORSPACE</constant> is
103                    <constant>EGL_VG_COLORSPACE_sRGB</constant>.
104                </para>
105                </listitem>
106            </varlistentry>
107        </variablelist>
108        <para>
109            Any EGL rendering context that was created with respect to
110            <parameter>config</parameter> can be used to render into the
111            surface. Use
112            <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry>
113            to attach an EGL rendering context to the surface.
114        </para>
115        <para>
116            Use
117            <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry>
118            to retrieve the ID of <parameter>config</parameter>.
119        </para>
120        <para>
121            Use <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry>
122            to destroy the surface.
123        </para>
124    </refsect1>
125    <refsect1 xml:id="notes"><title>Notes</title>
126        <para>
127            The <constant>EGL_MATCH_NATIVE_PIXMAP</constant> attribute
128            of
129            <citerefentry><refentrytitle>eglChooseConfig</refentrytitle></citerefentry>
130            can be used to select a frame buffer configuration matching
131            a specified native pixmap.
132        </para>
133        <para>
134            Attributes
135            <constant>EGL_VG_ALPHA_FORMAT</constant> and
136            <constant>EGL_VG_COLORSPACE</constant>, and the
137            corresponding attribute values, are supported only if the
138            EGL version is 1.2 or greater.
139        </para>
140        <!-- Might want to mention aliasing of EGL_VG_* -> EGL_* that occurred in EGL 1.3 -->
141        <para>
142            The <constant>EGL_VG_ALPHA_FORMAT</constant> and
143            <constant>EGL_VG_COLORSPACE</constant> attributes are used
144            only by OpenVG. EGL itself, and other client APIs such as
145            OpenGL and OpenGL ES , do not distinguish multiple
146            colorspace models. Refer to section 11.2 of the OpenVG 1.0
147            specification for more information. The native window
148            system's use and interpretation of alpha values is outside
149            the scope of EGL, although the preferred behavior is for the
150            window system to ignore the value of
151            <constant>EGL_VG_ALPHA_FORMAT</constant>.
152        </para>
153    </refsect1>
154    <refsect1 xml:id="errors"><title>Errors</title>
155        <para>
156            <constant>EGL_NO_SURFACE</constant> is returned if creation of
157            the context fails.
158        </para>
159        <para>
160            <constant>EGL_BAD_DISPLAY</constant> is generated if
161            <parameter>display</parameter> is not an EGL display connection.
162        </para>
163        <para>
164            <constant>EGL_NOT_INITIALIZED</constant> is generated if
165            <parameter>display</parameter> has not been initialized.
166        </para>
167        <para>
168            <constant>EGL_BAD_CONFIG</constant> is generated if
169            <parameter>config</parameter> is not an EGL config.
170        </para>
171        <para>
172            <constant>EGL_BAD_NATIVE_PIXMAP</constant> may be generated if
173            <parameter>native_pixmap</parameter> is not a valid native pixmap.
174        </para>
175        <para>
176            <constant>EGL_BAD_ATTRIBUTE</constant> is generated if
177            <parameter>attrib_list</parameter> contains an invalid pixmap attribute
178            or if an attribute value is not recognized or out of range.
179        </para>
180        <para>
181            <constant>EGL_BAD_ALLOC</constant> is generated if there are not
182            enough resources to allocate the new surface.
183        </para>
184        <para>
185            <constant>EGL_BAD_MATCH</constant> is generated if the attributes of
186            <parameter>native_pixmap</parameter> do not correspond to
187            <parameter>config</parameter> or if
188            <parameter>config</parameter> does not support rendering to pixmaps
189            (the <constant>EGL_SURFACE_TYPE</constant> attribute does not contain
190            <constant>EGL_PIXMAP_BIT</constant>).
191        </para>
192        <para>
193            <constant>EGL_BAD_MATCH</constant> is generated if
194            <parameter>config</parameter> does not support the specified
195            OpenVG alpha format attribute (the value of
196            <constant>EGL_VG_ALPHA_FORMAT</constant> is
197            <constant>EGL_VG_ALPHA_FORMAT_PRE</constant> and the
198            <constant>EGL_VG_ALPHA_FORMAT_PRE_BIT</constant> is not set
199            in the <constant>EGL_SURFACE_TYPE</constant> attribute of
200            <parameter>config</parameter>) or colorspace attribute (the
201            value of <constant>EGL_VG_COLORSPACE</constant> is
202            <constant>EGL_VG_COLORSPACE_LINEAR</constant> and the
203            <constant>EGL_VG_COLORSPACE_LINEAR_IT</constant> is not set
204            in the <constant>EGL_SURFACE_TYPE</constant> attribute of
205            <parameter>config</parameter>).
206        </para>
207    </refsect1>
208    <refsect1 xml:id="seealso"><title>See Also</title>
209        <para>
210            <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry>,
211            <citerefentry><refentrytitle>eglChooseConfig</refentrytitle></citerefentry>,
212            <citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry>,
213            <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry>,
214            <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry>
215        </para>
216    </refsect1>
217    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/>
218</refentry>
219