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