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">eglCreatePlatformWindowSurface - 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="eglCreatePlatformWindowSurface"> 11 <div class="titlepage"/> 12 <div class="refnamediv"> 13 <h2>Name</h2> 14 <p>eglCreatePlatformWindowSurface — 15 create a new <abbr class="acronym">EGL</abbr> on-screen rendering 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">eglCreatePlatformWindowSurface</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_window</var>, </td> 35 </tr> 36 <tr> 37 <td> </td> 38 <td>EGLAttrib 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>Specifies the EGL frame buffer configuration that defines the 67 frame buffer resource available to the surface.</p> 68 </dd> 69 <dt> 70 <span class="term"> 71 <em class="parameter"> 72 <code>native_window</code> 73 </em> 74 </span> 75 </dt> 76 <dd> 77 <p>Specifies the native window.</p> 78 </dd> 79 <dt> 80 <span class="term"> 81 <em class="parameter"> 82 <code>attrib_list</code> 83 </em> 84 </span> 85 </dt> 86 <dd> 87 <p> 88 Specifies a list of attributes for the window surface. 89 May be <code class="constant">NULL</code> or empty 90 (first attribute is <code class="constant">EGL_NONE</code>). 91 </p> 92 </dd> 93 </dl> 94 </div> 95 </div> 96 <div class="refsect1" id="description"> 97 <h2>Description</h2> 98 <p> 99 <code class="function">eglCreatePlatformWindowSurface</code> creates an 100 on-screen EGL window surface and returns a handle to it. Any EGL 101 context created with a compatible <span class="type">EGLConfig</span> can be 102 used to render into this surface. 103 </p> 104 <p> 105 If <code class="function">eglCreatePlatformWindowSurface</code> fails to 106 create a window surface, <code class="constant">EGL_NO_SURFACE</code> is 107 returned. 108 </p> 109 <p> 110 <em class="parameter"><code>native_window</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_window</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_LINEAR</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_RENDER_BUFFER</code> 159 </span> 160 </dt> 161 <dd> 162 <p> 163 Specifies which buffer should be used for client API 164 rendering to the window. If its value is 165 <code class="constant">EGL_SINGLE_BUFFER</code>, then client 166 APIs should render directly into the visible window. 167 If its value is 168 <code class="constant">EGL_BACK_BUFFER</code>, then client 169 APIs should render into the back buffer. The default 170 value of <code class="constant">EGL_RENDER_BUFFER</code> is 171 <code class="constant">EGL_BACK_BUFFER</code>. 172 </p> 173 <p> 174 Client APIs may not be able to respect the requested 175 rendering buffer. To determine the actual buffer 176 being rendered to by a context, call 177 <a class="citerefentry" href="eglQueryContext.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQueryContext</span></span></a>. 178 </p> 179 </dd> 180 <dt> 181 <span class="term"> 182 <code class="constant">EGL_VG_ALPHA_FORMAT</code> 183 </span> 184 </dt> 185 <dd> 186 <p> 187 Specifies how alpha values are interpreted by OpenVG 188 when rendering to the surface. If its value is 189 <code class="constant">EGL_VG_ALPHA_FORMAT_NONPRE</code>, 190 then alpha values are not premultipled. If its value 191 is <code class="constant">EGL_VG_ALPHA_FORMAT_PRE</code>, 192 then alpha values are premultiplied. The default 193 value of <code class="constant">EGL_VG_ALPHA_FORMAT</code> is 194 <code class="constant">EGL_VG_ALPHA_FORMAT_NONPRE</code>. 195 </p> 196 </dd> 197 <dt> 198 <span class="term"> 199 <code class="constant">EGL_VG_COLORSPACE</code> 200 </span> 201 </dt> 202 <dd> 203 <p> 204 Specifies the color space used by OpenVG when 205 rendering to the surface. If its value is 206 <code class="constant">EGL_VG_COLORSPACE_sRGB</code>, then a 207 non-linear, perceptually uniform color space is 208 assumed, with a corresponding 209 <span class="type">VGImageFormat</span> of form 210 <code class="constant">VG_s*</code>. If its value is 211 <code class="constant">EGL_VG_COLORSPACE_LINEAR</code>, then 212 a linear color space is assumed, with a 213 corresponding <span class="type">VGImageFormat</span> of form 214 <code class="constant">VG_l*</code>. The default value of 215 <code class="constant">EGL_VG_COLORSPACE</code> is 216 <code class="constant">EGL_VG_COLORSPACE_sRGB</code>. 217 </p> 218 </dd> 219 </dl> 220 </div> 221 <p> 222 Any EGL rendering context that was created with respect to 223 <em class="parameter"><code>config</code></em> can be used to render into the 224 surface. Use 225 <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a> 226 to attach an EGL rendering context to the surface. 227 </p> 228 <p> 229 Use 230 <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> 231 to retrieve the ID of <em class="parameter"><code>config</code></em>. 232 </p> 233 <p> 234 Use 235 <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a> 236 to destroy the surface. 237 </p> 238 </div> 239 <div class="refsect1" id="notes"> 240 <h2>Notes</h2> 241 <p> 242 Attribute <code class="constant">EGL_GL_COLORSPACE</code> is supported 243 only if the EGL version is 1.5 or greater. 244 </p> 245 <p> 246 Attributes <code class="constant">EGL_RENDER_BUFFER</code>, 247 <code class="constant">EGL_VG_ALPHA_FORMAT</code>, and 248 <code class="constant">EGL_VG_COLORSPACE</code>, and the 249 corresponding attribute values, are supported only if the 250 EGL version is 1.2 or greater. 251 </p> 252 <p> 253 The <code class="constant">EGL_VG_ALPHA_FORMAT</code> and 254 <code class="constant">EGL_VG_COLORSPACE</code> attributes are used only 255 by OpenVG and EGL itself. Refer to section 11.2 of the OpenVG 256 1.0 specification for more information. The platform's use and 257 interpretation of alpha values is outside the scope of EGL. 258 However, the preferred behavior is for platforms to ignore the 259 value of <code class="constant">EGL_VG_ALPHA_FORMAT</code> when 260 compositing window surfaces. 261 </p> 262 </div> 263 <div class="refsect1" id="errors"> 264 <h2>Errors</h2> 265 <p> 266 If <em class="parameter"><code>display</code></em> and 267 <em class="parameter"><code>native_window</code></em> do not belong to the same 268 platform, then undefined behavior occurs. 269 </p> 270 <p> 271 <code class="constant">EGL_NO_SURFACE</code> is returned if creation of 272 the surface fails. 273 </p> 274 <p> 275 <code class="constant">EGL_BAD_DISPLAY</code> is generated if 276 <em class="parameter"><code>display</code></em> is not an EGL display connection. 277 </p> 278 <p> 279 <code class="constant">EGL_NOT_INITIALIZED</code> is generated if 280 <em class="parameter"><code>display</code></em> has not been initialized. 281 </p> 282 <p> 283 <code class="constant">EGL_BAD_CONFIG</code> is generated if 284 <em class="parameter"><code>config</code></em> is not a valid EGL frame buffer 285 configuration. 286 </p> 287 <p> 288 <code class="constant">EGL_BAD_NATIVE_WINDOW</code> may be generated if 289 <em class="parameter"><code>native_window</code></em> is not a valid native 290 window for the same platform as <em class="parameter"><code>display</code></em>. 291 </p> 292 <p> 293 <code class="constant">EGL_BAD_ATTRIBUTE</code> is generated if 294 <em class="parameter"><code>attrib_list</code></em> contains an invalid window attribute 295 or if an attribute value is not recognized or is out of range. 296 </p> 297 <p> 298 <code class="constant">EGL_BAD_ALLOC</code> is generated if there is 299 already an <span class="type">EGLSurface</span> associated with 300 <em class="parameter"><code>native_window</code></em> (as a result of a previous 301 <code class="function">eglCreatePlatformWindowSurface</code> call). 302 </p> 303 <p> 304 <code class="constant">EGL_BAD_ALLOC</code> is generated if the 305 implementation cannot allocate resources for the new EGL window. 306 </p> 307 <p> 308 <code class="constant">EGL_BAD_MATCH</code> is generated if the pixel 309 format of <em class="parameter"><code>native_window</code></em> does not 310 correspond to the format, type, and size of the color buffers 311 required by <em class="parameter"><code>config</code></em>. 312 <code class="constant">EGL_BAD_MATCH</code> is generated if the pixel 313 </p> 314 <p> 315 <code class="constant">EGL_BAD_MATCH</code> is generated if 316 <em class="parameter"><code>config</code></em> does not support rendering to 317 windows (the <code class="constant">EGL_SURFACE_TYPE</code> attribute 318 does not contain <code class="constant">EGL_WINDOW_BIT</code>). 319 </p> 320 <p> 321 <code class="constant">EGL_BAD_MATCH</code> is generated if 322 <em class="parameter"><code>config</code></em> does not support the specified 323 OpenVG alpha format attribute (the value of 324 <code class="constant">EGL_VG_ALPHA_FORMAT</code> is 325 <code class="constant">EGL_VG_ALPHA_FORMAT_PRE</code> and the 326 <code class="constant">EGL_VG_ALPHA_FORMAT_PRE_BIT</code> is not set 327 in the <code class="constant">EGL_SURFACE_TYPE</code> attribute of 328 <em class="parameter"><code>config</code></em>) or colorspace attribute (the 329 value of <code class="constant">EGL_VG_COLORSPACE</code> is 330 <code class="constant">EGL_VG_COLORSPACE_LINEAR</code> and the 331 <code class="constant">EGL_VG_COLORSPACE_LINEAR_IT</code> is not set 332 in the <code class="constant">EGL_SURFACE_TYPE</code> attribute of 333 <em class="parameter"><code>config</code></em>). 334 </p> 335 </div> 336 <div class="refsect1" id="seealso"> 337 <h2>See Also</h2> 338 <p> 339 <a class="citerefentry" href="eglCreateWindowSurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglCreateWindowSurface</span></span></a>, 340 <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a>, 341 <a class="citerefentry" href="eglChooseConfig.xhtml"><span class="citerefentry"><span class="refentrytitle">eglChooseConfig</span></span></a>, 342 <a class="citerefentry" href="eglGetConfigs.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetConfigs</span></span></a>, 343 <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a>, 344 <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> 345 </p> 346 </div> 347 <p> 348 </p> 349 <div class="refsect3" id="copyright"> 350 <img src="KhronosLogo.jpg"/> 351 <p> 352 Copyright © 2003-2014 The Khronos Group Inc. 353 Permission is hereby granted, free of charge, to any person obtaining a 354 copy of this software and/or associated documentation files (the 355 "Materials"), to deal in the Materials without restriction, including 356 without limitation the rights to use, copy, modify, merge, publish, 357 distribute, sublicense, and/or sell copies of the Materials, and to 358 permit persons to whom the Materials are furnished to do so, subject to 359 the condition that this copyright notice and permission notice shall be included 360 in all copies or substantial portions of the Materials. 361 </p> 362 </div> 363 <p> 364</p> 365 </div> 366 <footer/> 367 </body> 368</html> 369
