1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"> 3 <head> 4 <title xmlns:xlink="http://www.w3.org/1999/xlink">eglCreatePlatformPixmapSurface - EGL Reference Pages</title> 5 <link rel="stylesheet" type="text/css" href="khronos-man.css"/> 6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"/> 7 </head> 8 <body> 9 <header/> 10 <div class="refentry" id="eglCreatePlatformPixmapSurface"> 11 <div class="titlepage"/> 12 <div class="refnamediv"> 13 <h2>Name</h2> 14 <p>eglCreatePlatformPixmapSurface — 15 create a new <abbr class="acronym">EGL</abbr> offscreen surface 16 </p> 17 </div> 18 <div class="refsynopsisdiv"> 19 <h2>C Specification</h2> 20 <div class="funcsynopsis"> 21 <table style="border: 0; cellspacing: 0; cellpadding: 0;" class="funcprototype-table"> 22 <tr> 23 <td> 24 <code class="funcdef">EGLSurface <strong class="fsfunc">eglCreatePlatformPixmapSurface</strong>(</code> 25 </td> 26 <td>EGLDisplay <var class="pdparam">display</var>, </td> 27 </tr> 28 <tr> 29 <td> </td> 30 <td>EGLConfig <var class="pdparam">config</var>, </td> 31 </tr> 32 <tr> 33 <td> </td> 34 <td>void * <var class="pdparam">native_pixmap</var>, </td> 35 </tr> 36 <tr> 37 <td> </td> 38 <td>EGLint const * <var class="pdparam">attrib_list</var><code>)</code>;</td> 39 </tr> 40 </table> 41 <div class="funcprototype-spacer"> </div> 42 </div> 43 </div> 44 <div class="refsect1" id="parameters"> 45 <h2>Parameters</h2> 46 <div class="variablelist"> 47 <dl class="variablelist"> 48 <dt> 49 <span class="term"> 50 <em class="parameter"> 51 <code>display</code> 52 </em> 53 </span> 54 </dt> 55 <dd> 56 <p>Specifies the EGL display connection.</p> 57 </dd> 58 <dt> 59 <span class="term"> 60 <em class="parameter"> 61 <code>config</code> 62 </em> 63 </span> 64 </dt> 65 <dd> 66 <p> 67 Specifies the EGL frame buffer configuration that defines the 68 frame buffer resource available to the surface.</p> 69 </dd> 70 <dt> 71 <span class="term"> 72 <em class="parameter"> 73 <code>native_pixmap</code> 74 </em> 75 </span> 76 </dt> 77 <dd> 78 <p>Specifies the native pixmap.</p> 79 </dd> 80 <dt> 81 <span class="term"> 82 <em class="parameter"> 83 <code>attrib_list</code> 84 </em> 85 </span> 86 </dt> 87 <dd> 88 <p> 89 Specifies pixmap surface attributes. 90 May be <code class="constant">NULL</code> or empty 91 (first attribute is <code class="constant">EGL_NONE</code>). 92 </p> 93 </dd> 94 </dl> 95 </div> 96 </div> 97 <div class="refsect1" id="description"> 98 <h2>Description</h2> 99 <p> 100 <code class="function">eglCreatePlatformPixmapSurface</code> creates an 101 off-screen <abbr class="acronym">EGL</abbr> pixmap surface and returns 102 a handle to it. 103 </p> 104 <p> 105 If <code class="function">eglCreatePlatformPixmapSurface</code> fails to 106 create a pixmap surface, <code class="constant">EGL_NO_SURFACE</code> is 107 returned. 108 </p> 109 <p> 110 <em class="parameter"><code>native_pixmap</code></em> must belong to the same 111 platform as <em class="parameter"><code>display</code></em>, and EGL considers 112 the returned <span class="type">EGLSurface</span> as belonging to that same 113 platform. The EGL extension that defines the platform to which 114 <em class="parameter"><code>display</code></em> belongs also defines the 115 requirements for the <em class="parameter"><code>native_pixmap</code></em> 116 parameter. 117 </p> 118 <p> 119 Surface attributes are specified as a list of 120 attribute-value pairs, terminated with 121 <code class="constant">EGL_NONE</code>. Accepted attributes 122 are: 123 </p> 124 <div class="variablelist"> 125 <dl class="variablelist"> 126 <dt> 127 <span class="term"> 128 <code class="constant">EGL_GL_COLORSPACE</code> 129 </span> 130 </dt> 131 <dd> 132 <p> 133 Specifies the color space used by OpenGL and OpenGL ES 134 when rendering to the surface. If its value is 135 <code class="constant">EGL_GL_COLORSPACE_SRGB</code>, then a 136 non-linear, perceptually uniform color space is assumed, 137 with a corresponding 138 <code class="constant">GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING</code> 139 value of <code class="constant">GL_SRGB</code>. If its value is 140 <code class="constant">EGL_GL_COLORSPACE_LINEAR</code>, then a 141 linear color space is assumed, with a corresponding 142 <code class="constant">GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING</code> 143 value of <code class="constant">GL_LINEAR</code>. The default 144 value of <code class="constant">EGL_GL_COLORSPACE</code> is 145 <code class="constant">EGL_GL_COLORSPACE_SRGB</code>. 146 </p> 147 <p> 148 Note that the <code class="constant">EGL_GL_COLORSPACE</code> 149 attribute is used only by OpenGL and OpenGL ES contexts 150 supporting sRGB framebuffers. EGL itself does not 151 distinguish multiple colorspace models. Refer to the 152 ``sRGB Conversion'' sections of the OpenGL 4.6 and 153 OpenGL ES 3.2 Specifications for more information. 154 </p> 155 </dd> 156 <dt> 157 <span class="term"> 158 <code class="constant">EGL_VG_ALPHA_FORMAT</code> 159 </span> 160 </dt> 161 <dd> 162 <p> 163 Specifies how alpha values are interpreted by OpenVG 164 when rendering to the surface. If its value is 165 <code class="constant">EGL_VG_ALPHA_FORMAT_NONPRE</code>, 166 then alpha values are not premultipled. If its value 167 is <code class="constant">EGL_VG_ALPHA_FORMAT_PRE</code>, 168 then alpha values are premultiplied. The default 169 value of <code class="constant">EGL_VG_ALPHA_FORMAT</code> is 170 <code class="constant">EGL_VG_ALPHA_FORMAT_NONPRE</code>. 171 </p> 172 </dd> 173 <dt> 174 <span class="term"> 175 <code class="constant">EGL_VG_COLORSPACE</code> 176 </span> 177 </dt> 178 <dd> 179 <p> 180 Specifies the color space used by OpenVG when 181 rendering to the surface. If its value is 182 <code class="constant">EGL_VG_COLORSPACE_sRGB</code>, then a 183 non-linear, perceptually uniform color space is 184 assumed, with a corresponding 185 <span class="type">VGImageFormat</span> of form 186 <code class="constant">VG_s*</code>. If its value is 187 <code class="constant">EGL_VG_COLORSPACE_LINEAR</code>, then 188 a linear color space is assumed, with a 189 corresponding <span class="type">VGImageFormat</span> of form 190 <code class="constant">VG_l*</code>. The default value of 191 <code class="constant">EGL_VG_COLORSPACE</code> is 192 <code class="constant">EGL_VG_COLORSPACE_sRGB</code>. 193 </p> 194 </dd> 195 </dl> 196 </div> 197 <p> 198 Any EGL rendering context that was created with respect to 199 <em class="parameter"><code>config</code></em> can be used to render into the 200 surface. Use 201 <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a> 202 to attach an EGL rendering context to the surface. 203 </p> 204 <p> 205 Use 206 <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> 207 to retrieve the ID of <em class="parameter"><code>config</code></em>. 208 </p> 209 <p> 210 Use <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a> 211 to destroy the surface. 212 </p> 213 </div> 214 <div class="refsect1" id="notes"> 215 <h2>Notes</h2> 216 <p> 217 The <code class="constant">EGL_MATCH_NATIVE_PIXMAP</code> attribute 218 of 219 <a class="citerefentry" href="eglChooseConfig.xhtml"><span class="citerefentry"><span class="refentrytitle">eglChooseConfig</span></span></a> 220 can be used to select a frame buffer configuration matching 221 a specified native pixmap. 222 </p> 223 <p> 224 Attribute <code class="constant">EGL_GL_COLORSPACE</code> is supported 225 only if the EGL version is 1.5 or greater. 226 </p> 227 <p> 228 Attributes 229 <code class="constant">EGL_VG_ALPHA_FORMAT</code> and 230 <code class="constant">EGL_VG_COLORSPACE</code>, and the 231 corresponding attribute values, are supported only if the 232 EGL version is 1.2 or greater. 233 </p> 234 <p> 235 The <code class="constant">EGL_VG_ALPHA_FORMAT</code> and 236 <code class="constant">EGL_VG_COLORSPACE</code> attributes are used only 237 by OpenVG and EGL itself. Refer to section 11.2 of the OpenVG 238 1.0 specification for more information. The platform's use and 239 interpretation of alpha values is outside the scope of EGL. 240 However, the preferred behavior is for the window system to 241 ignore the value of <code class="constant">EGL_VG_ALPHA_FORMAT</code>. 242 </p> 243 </div> 244 <div class="refsect1" id="errors"> 245 <h2>Errors</h2> 246 <p> 247 If <em class="parameter"><code>display</code></em> and 248 <em class="parameter"><code>native_pixmap</code></em> do not belong to the same 249 platform, then undefined behavior occurs. 250 </p> 251 <p> 252 <code class="constant">EGL_NO_SURFACE</code> is returned if creation of 253 the surface fails. 254 </p> 255 <p> 256 <code class="constant">EGL_BAD_DISPLAY</code> is generated if 257 <em class="parameter"><code>display</code></em> is not an EGL display connection. 258 </p> 259 <p> 260 <code class="constant">EGL_NOT_INITIALIZED</code> is generated if 261 <em class="parameter"><code>display</code></em> has not been initialized. 262 </p> 263 <p> 264 <code class="constant">EGL_BAD_CONFIG</code> is generated if 265 <em class="parameter"><code>config</code></em> is not an EGL config. 266 </p> 267 <p> 268 <code class="constant">EGL_BAD_NATIVE_PIXMAP</code> may be generated if 269 <em class="parameter"><code>native_pixmap</code></em> is not a valid native pixmap. 270 </p> 271 <p> 272 <code class="constant">EGL_BAD_ATTRIBUTE</code> is generated if 273 <em class="parameter"><code>attrib_list</code></em> contains an invalid pixmap attribute 274 or if an attribute value is not recognized or out of range. 275 </p> 276 <p> 277 <code class="constant">EGL_BAD_ALLOC</code> is generated if there is 278 already an <span class="type">EGLSurface</span> associated with 279 <em class="parameter"><code>native_pixmap</code></em> (as a result of a previous 280 <code class="function">eglCreatePlatformPixmapSurface</code> call). 281 </p> 282 <p> 283 <code class="constant">EGL_BAD_ALLOC</code> is generated if the 284 implementation cannot allocate resources for the new EGL window. 285 </p> 286 <p> 287 <code class="constant">EGL_BAD_MATCH</code> is generated if the attributes of 288 <em class="parameter"><code>native_pixmap</code></em> do not correspond to 289 <em class="parameter"><code>config</code></em> or if 290 <em class="parameter"><code>config</code></em> does not support rendering to pixmaps 291 (the <code class="constant">EGL_SURFACE_TYPE</code> attribute does not contain 292 <code class="constant">EGL_PIXMAP_BIT</code>). 293 </p> 294 <p> 295 <code class="constant">EGL_BAD_MATCH</code> is generated if 296 <em class="parameter"><code>config</code></em> does not support the specified 297 OpenVG alpha format attribute (the value of 298 <code class="constant">EGL_VG_ALPHA_FORMAT</code> is 299 <code class="constant">EGL_VG_ALPHA_FORMAT_PRE</code> and the 300 <code class="constant">EGL_VG_ALPHA_FORMAT_PRE_BIT</code> is not set 301 in the <code class="constant">EGL_SURFACE_TYPE</code> attribute of 302 <em class="parameter"><code>config</code></em>) or colorspace attribute (the 303 value of <code class="constant">EGL_VG_COLORSPACE</code> is 304 <code class="constant">EGL_VG_COLORSPACE_LINEAR</code> and the 305 <code class="constant">EGL_VG_COLORSPACE_LINEAR_IT</code> is not set 306 in the <code class="constant">EGL_SURFACE_TYPE</code> attribute of 307 <em class="parameter"><code>config</code></em>). 308 </p> 309 </div> 310 <div class="refsect1" id="seealso"> 311 <h2>See Also</h2> 312 <p> 313 <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a>, 314 <a class="citerefentry" href="eglChooseConfig.xhtml"><span class="citerefentry"><span class="refentrytitle">eglChooseConfig</span></span></a>, 315 <a class="citerefentry" href="eglGetConfigs.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetConfigs</span></span></a>, 316 <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a>, 317 <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> 318 </p> 319 </div> 320 <p> 321 </p> 322 <div class="refsect3" id="copyright"> 323 <img src="KhronosLogo.jpg"/> 324 <p> 325 Copyright © 2003-2014 The Khronos Group Inc. 326 Permission is hereby granted, free of charge, to any person obtaining a 327 copy of this software and/or associated documentation files (the 328 "Materials"), to deal in the Materials without restriction, including 329 without limitation the rights to use, copy, modify, merge, publish, 330 distribute, sublicense, and/or sell copies of the Materials, and to 331 permit persons to whom the Materials are furnished to do so, subject to 332 the condition that this copyright notice and permission notice shall be included 333 in all copies or substantial portions of the Materials. 334 </p> 335 </div> 336 <p> 337</p> 338 </div> 339 <footer/> 340 </body> 341</html> 342
