1<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglCreatePlatformPixmapSurface"> 2 <info> 3 <copyright> 4 <year>2003-2018</year> 5 <holder>The Khronos Group Inc.</holder> 6 </copyright> 7 </info> 8 <refmeta> 9 <refentrytitle>eglCreatePlatformPixmapSurface</refentrytitle> 10 <manvolnum>3G</manvolnum> 11 </refmeta> 12 <refnamediv> 13 <refname>eglCreatePlatformPixmapSurface</refname> 14 <refpurpose> 15 create a new <acronym>EGL</acronym> offscreen surface 16 </refpurpose> 17 </refnamediv> 18 <refsynopsisdiv> 19 <title>C Specification</title> 20 <funcsynopsis> 21 <funcprototype> 22 <funcdef>EGLSurface <function>eglCreatePlatformPixmapSurface</function></funcdef> 23 <paramdef>EGLDisplay <parameter>display</parameter></paramdef> 24 <paramdef>EGLConfig <parameter>config</parameter></paramdef> 25 <paramdef>void * <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>eglCreatePlatformPixmapSurface</function> creates an 60 off-screen <acronym>EGL</acronym> pixmap surface and returns 61 a handle to it. 62 </para> 63 <para> 64 If <function>eglCreatePlatformPixmapSurface</function> fails to 65 create a pixmap surface, <constant>EGL_NO_SURFACE</constant> is 66 returned. 67 </para> 68 <para> 69 <parameter>native_pixmap</parameter> must belong to the same 70 platform as <parameter>display</parameter>, and EGL considers 71 the returned <type>EGLSurface</type> as belonging to that same 72 platform. The EGL extension that defines the platform to which 73 <parameter>display</parameter> belongs also defines the 74 requirements for the <parameter>native_pixmap</parameter> 75 parameter. 76 </para> 77 <para> 78 Surface attributes are specified as a list of 79 attribute-value pairs, terminated with 80 <constant>EGL_NONE</constant>. Accepted attributes 81 are: 82 </para> 83 <variablelist> 84 <varlistentry> 85 <term><constant>EGL_GL_COLORSPACE</constant></term> 86 <listitem> 87 <para> 88 Specifies the color space used by OpenGL and OpenGL ES 89 when rendering to the surface. If its value is 90 <constant>EGL_GL_COLORSPACE_SRGB</constant>, then a 91 non-linear, perceptually uniform color space is assumed, 92 with a corresponding 93 <constant>GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING</constant> 94 value of <constant>GL_SRGB</constant>. If its value is 95 <constant>EGL_GL_COLORSPACE_LINEAR</constant>, then a 96 linear color space is assumed, with a corresponding 97 <constant>GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING</constant> 98 value of <constant>GL_LINEAR</constant>. The default 99 value of <constant>EGL_GL_COLORSPACE</constant> is 100 <constant>EGL_GL_COLORSPACE_SRGB</constant>. 101 </para> 102 <para> 103 Note that the <constant>EGL_GL_COLORSPACE</constant> 104 attribute is used only by OpenGL and OpenGL ES contexts 105 supporting sRGB framebuffers. EGL itself does not 106 distinguish multiple colorspace models. Refer to the 107 ``sRGB Conversion'' sections of the OpenGL 4.6 and 108 OpenGL ES 3.2 Specifications for more information. 109 </para> 110 </listitem> 111 </varlistentry> 112 <varlistentry> 113 <term><constant>EGL_VG_ALPHA_FORMAT</constant></term> 114 <listitem> 115 <para> 116 Specifies how alpha values are interpreted by OpenVG 117 when rendering to the surface. If its value is 118 <constant>EGL_VG_ALPHA_FORMAT_NONPRE</constant>, 119 then alpha values are not premultipled. If its value 120 is <constant>EGL_VG_ALPHA_FORMAT_PRE</constant>, 121 then alpha values are premultiplied. The default 122 value of <constant>EGL_VG_ALPHA_FORMAT</constant> is 123 <constant>EGL_VG_ALPHA_FORMAT_NONPRE</constant>. 124 </para> 125 </listitem> 126 </varlistentry> 127 <varlistentry> 128 <term><constant>EGL_VG_COLORSPACE</constant></term> 129 <listitem> 130 <para> 131 Specifies the color space used by OpenVG when 132 rendering to the surface. If its value is 133 <constant>EGL_VG_COLORSPACE_sRGB</constant>, then a 134 non-linear, perceptually uniform color space is 135 assumed, with a corresponding 136 <type>VGImageFormat</type> of form 137 <constant>VG_s*</constant>. If its value is 138 <constant>EGL_VG_COLORSPACE_LINEAR</constant>, then 139 a linear color space is assumed, with a 140 corresponding <type>VGImageFormat</type> of form 141 <constant>VG_l*</constant>. The default value of 142 <constant>EGL_VG_COLORSPACE</constant> is 143 <constant>EGL_VG_COLORSPACE_sRGB</constant>. 144 </para> 145 </listitem> 146 </varlistentry> 147 </variablelist> 148 <para> 149 Any EGL rendering context that was created with respect to 150 <parameter>config</parameter> can be used to render into the 151 surface. Use 152 <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry> 153 to attach an EGL rendering context to the surface. 154 </para> 155 <para> 156 Use 157 <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry> 158 to retrieve the ID of <parameter>config</parameter>. 159 </para> 160 <para> 161 Use <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry> 162 to destroy the surface. 163 </para> 164 </refsect1> 165 <refsect1 xml:id="notes"><title>Notes</title> 166 <para> 167 The <constant>EGL_MATCH_NATIVE_PIXMAP</constant> attribute 168 of 169 <citerefentry><refentrytitle>eglChooseConfig</refentrytitle></citerefentry> 170 can be used to select a frame buffer configuration matching 171 a specified native pixmap. 172 </para> 173 <para> 174 Attribute <constant>EGL_GL_COLORSPACE</constant> is supported 175 only if the EGL version is 1.5 or greater. 176 </para> 177 <para> 178 Attributes 179 <constant>EGL_VG_ALPHA_FORMAT</constant> and 180 <constant>EGL_VG_COLORSPACE</constant>, and the 181 corresponding attribute values, are supported only if the 182 EGL version is 1.2 or greater. 183 </para> 184 <!-- Might want to mention aliasing of EGL_VG_* -> EGL_* that occurred in EGL 1.3 --> 185 <para> 186 The <constant>EGL_VG_ALPHA_FORMAT</constant> and 187 <constant>EGL_VG_COLORSPACE</constant> attributes are used only 188 by OpenVG and EGL itself. Refer to section 11.2 of the OpenVG 189 1.0 specification for more information. The platform's use and 190 interpretation of alpha values is outside the scope of EGL. 191 However, the preferred behavior is for the window system to 192 ignore the value of <constant>EGL_VG_ALPHA_FORMAT</constant>. 193 </para> 194 </refsect1> 195 <refsect1 xml:id="errors"><title>Errors</title> 196 <para> 197 If <parameter>display</parameter> and 198 <parameter>native_pixmap</parameter> do not belong to the same 199 platform, then undefined behavior occurs. 200 </para> 201 <para> 202 <constant>EGL_NO_SURFACE</constant> is returned if creation of 203 the surface fails. 204 </para> 205 <para> 206 <constant>EGL_BAD_DISPLAY</constant> is generated if 207 <parameter>display</parameter> is not an EGL display connection. 208 </para> 209 <para> 210 <constant>EGL_NOT_INITIALIZED</constant> is generated if 211 <parameter>display</parameter> has not been initialized. 212 </para> 213 <para> 214 <constant>EGL_BAD_CONFIG</constant> is generated if 215 <parameter>config</parameter> is not an EGL config. 216 </para> 217 <para> 218 <constant>EGL_BAD_NATIVE_PIXMAP</constant> may be generated if 219 <parameter>native_pixmap</parameter> is not a valid native pixmap. 220 </para> 221 <para> 222 <constant>EGL_BAD_ATTRIBUTE</constant> is generated if 223 <parameter>attrib_list</parameter> contains an invalid pixmap attribute 224 or if an attribute value is not recognized or out of range. 225 </para> 226 <para> 227 <constant>EGL_BAD_ALLOC</constant> is generated if there is 228 already an <type>EGLSurface</type> associated with 229 <parameter>native_pixmap</parameter> (as a result of a previous 230 <function>eglCreatePlatformPixmapSurface</function> call). 231 </para> 232 <para> 233 <constant>EGL_BAD_ALLOC</constant> is generated if the 234 implementation cannot allocate resources for the new EGL window. 235 </para> 236 <para> 237 <constant>EGL_BAD_MATCH</constant> is generated if the attributes of 238 <parameter>native_pixmap</parameter> do not correspond to 239 <parameter>config</parameter> or if 240 <parameter>config</parameter> does not support rendering to pixmaps 241 (the <constant>EGL_SURFACE_TYPE</constant> attribute does not contain 242 <constant>EGL_PIXMAP_BIT</constant>). 243 </para> 244 <para> 245 <constant>EGL_BAD_MATCH</constant> is generated if 246 <parameter>config</parameter> does not support the specified 247 OpenVG alpha format attribute (the value of 248 <constant>EGL_VG_ALPHA_FORMAT</constant> is 249 <constant>EGL_VG_ALPHA_FORMAT_PRE</constant> and the 250 <constant>EGL_VG_ALPHA_FORMAT_PRE_BIT</constant> is not set 251 in the <constant>EGL_SURFACE_TYPE</constant> attribute of 252 <parameter>config</parameter>) or colorspace attribute (the 253 value of <constant>EGL_VG_COLORSPACE</constant> is 254 <constant>EGL_VG_COLORSPACE_LINEAR</constant> and the 255 <constant>EGL_VG_COLORSPACE_LINEAR_IT</constant> is not set 256 in the <constant>EGL_SURFACE_TYPE</constant> attribute of 257 <parameter>config</parameter>). 258 </para> 259 </refsect1> 260 <refsect1 xml:id="seealso"><title>See Also</title> 261 <para> 262 <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry>, 263 <citerefentry><refentrytitle>eglChooseConfig</refentrytitle></citerefentry>, 264 <citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry>, 265 <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry>, 266 <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry> 267 </para> 268 </refsect1> 269 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/> 270</refentry> 271