| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <title xmlns:xlink="http://www.w3.org/1999/xlink">eglCreatePlatformWindowSurface - EGL Reference Pages</title> |
| <link rel="stylesheet" type="text/css" href="khronos-man.css"/> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"/> |
| </head> |
| <body> |
| <header/> |
| <div class="refentry" id="eglCreatePlatformWindowSurface"> |
| <div class="titlepage"/> |
| <div class="refnamediv"> |
| <h2>Name</h2> |
| <p>eglCreatePlatformWindowSurface — |
| create a new <abbr class="acronym">EGL</abbr> on-screen rendering surface |
| </p> |
| </div> |
| <div class="refsynopsisdiv"> |
| <h2>C Specification</h2> |
| <div class="funcsynopsis"> |
| <table style="border: 0; cellspacing: 0; cellpadding: 0;" class="funcprototype-table"> |
| <tr> |
| <td> |
| <code class="funcdef">EGLSurface <strong class="fsfunc">eglCreatePlatformWindowSurface</strong>(</code> |
| </td> |
| <td>EGLDisplay <var class="pdparam">display</var>, </td> |
| </tr> |
| <tr> |
| <td> </td> |
| <td>EGLConfig <var class="pdparam">config</var>, </td> |
| </tr> |
| <tr> |
| <td> </td> |
| <td>void * <var class="pdparam">native_window</var>, </td> |
| </tr> |
| <tr> |
| <td> </td> |
| <td>EGLAttrib const * <var class="pdparam">attrib_list</var><code>)</code>;</td> |
| </tr> |
| </table> |
| <div class="funcprototype-spacer"> </div> |
| </div> |
| </div> |
| <div class="refsect1" id="parameters"> |
| <h2>Parameters</h2> |
| <div class="variablelist"> |
| <dl class="variablelist"> |
| <dt> |
| <span class="term"> |
| <em class="parameter"> |
| <code>display</code> |
| </em> |
| </span> |
| </dt> |
| <dd> |
| <p>Specifies the EGL display connection.</p> |
| </dd> |
| <dt> |
| <span class="term"> |
| <em class="parameter"> |
| <code>config</code> |
| </em> |
| </span> |
| </dt> |
| <dd> |
| <p>Specifies the EGL frame buffer configuration that defines the |
| frame buffer resource available to the surface.</p> |
| </dd> |
| <dt> |
| <span class="term"> |
| <em class="parameter"> |
| <code>native_window</code> |
| </em> |
| </span> |
| </dt> |
| <dd> |
| <p>Specifies the native window.</p> |
| </dd> |
| <dt> |
| <span class="term"> |
| <em class="parameter"> |
| <code>attrib_list</code> |
| </em> |
| </span> |
| </dt> |
| <dd> |
| <p> |
| Specifies a list of attributes for the window surface. |
| May be <code class="constant">NULL</code> or empty |
| (first attribute is <code class="constant">EGL_NONE</code>). |
| </p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="refsect1" id="description"> |
| <h2>Description</h2> |
| <p> |
| <code class="function">eglCreatePlatformWindowSurface</code> creates an |
| on-screen EGL window surface and returns a handle to it. Any EGL |
| context created with a compatible <span class="type">EGLConfig</span> can be |
| used to render into this surface. |
| </p> |
| <p> |
| If <code class="function">eglCreatePlatformWindowSurface</code> fails to |
| create a window surface, <code class="constant">EGL_NO_SURFACE</code> is |
| returned. |
| </p> |
| <p> |
| <em class="parameter"><code>native_window</code></em> must belong to the same |
| platform as <em class="parameter"><code>display</code></em>, and EGL considers |
| the returned <span class="type">EGLSurface</span> as belonging to that same |
| platform. The EGL extension that defines the platform to which |
| <em class="parameter"><code>display</code></em> belongs also defines the |
| requirements for the <em class="parameter"><code>native_window</code></em> |
| parameter. |
| </p> |
| <p> |
| Surface attributes are specified as a list of |
| attribute-value pairs, terminated with |
| <code class="constant">EGL_NONE</code>. Accepted attributes |
| are: |
| </p> |
| <div class="variablelist"> |
| <dl class="variablelist"> |
| <dt> |
| <span class="term"> |
| <code class="constant">EGL_GL_COLORSPACE</code> |
| </span> |
| </dt> |
| <dd> |
| <p> |
| Specifies the color space used by OpenGL and OpenGL ES |
| when rendering to the surface. If its value is |
| <code class="constant">EGL_GL_COLORSPACE_SRGB</code>, then a |
| non-linear, perceptually uniform color space is assumed, |
| with a corresponding |
| <code class="constant">GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING</code> |
| value of <code class="constant">GL_SRGB</code>. If its value is |
| <code class="constant">EGL_GL_COLORSPACE_LINEAR</code>, then a |
| linear color space is assumed, with a corresponding |
| <code class="constant">GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING</code> |
| value of <code class="constant">GL_LINEAR</code>. The default |
| value of <code class="constant">EGL_GL_COLORSPACE</code> is |
| <code class="constant">EGL_GL_COLORSPACE_LINEAR</code>. |
| </p> |
| <p> |
| Note that the <code class="constant">EGL_GL_COLORSPACE</code> |
| attribute is used only by OpenGL and OpenGL ES contexts |
| supporting sRGB framebuffers. EGL itself does not |
| distinguish multiple colorspace models. Refer to the |
| ``sRGB Conversion'' sections of the OpenGL 4.6 and |
| OpenGL ES 3.2 Specifications for more information. |
| </p> |
| </dd> |
| <dt> |
| <span class="term"> |
| <code class="constant">EGL_RENDER_BUFFER</code> |
| </span> |
| </dt> |
| <dd> |
| <p> |
| Specifies which buffer should be used for client API |
| rendering to the window. If its value is |
| <code class="constant">EGL_SINGLE_BUFFER</code>, then client |
| APIs should render directly into the visible window. |
| If its value is |
| <code class="constant">EGL_BACK_BUFFER</code>, then client |
| APIs should render into the back buffer. The default |
| value of <code class="constant">EGL_RENDER_BUFFER</code> is |
| <code class="constant">EGL_BACK_BUFFER</code>. |
| </p> |
| <p> |
| Client APIs may not be able to respect the requested |
| rendering buffer. To determine the actual buffer |
| being rendered to by a context, call |
| <a class="citerefentry" href="eglQueryContext.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQueryContext</span></span></a>. |
| </p> |
| </dd> |
| <dt> |
| <span class="term"> |
| <code class="constant">EGL_VG_ALPHA_FORMAT</code> |
| </span> |
| </dt> |
| <dd> |
| <p> |
| Specifies how alpha values are interpreted by OpenVG |
| when rendering to the surface. If its value is |
| <code class="constant">EGL_VG_ALPHA_FORMAT_NONPRE</code>, |
| then alpha values are not premultipled. If its value |
| is <code class="constant">EGL_VG_ALPHA_FORMAT_PRE</code>, |
| then alpha values are premultiplied. The default |
| value of <code class="constant">EGL_VG_ALPHA_FORMAT</code> is |
| <code class="constant">EGL_VG_ALPHA_FORMAT_NONPRE</code>. |
| </p> |
| </dd> |
| <dt> |
| <span class="term"> |
| <code class="constant">EGL_VG_COLORSPACE</code> |
| </span> |
| </dt> |
| <dd> |
| <p> |
| Specifies the color space used by OpenVG when |
| rendering to the surface. If its value is |
| <code class="constant">EGL_VG_COLORSPACE_sRGB</code>, then a |
| non-linear, perceptually uniform color space is |
| assumed, with a corresponding |
| <span class="type">VGImageFormat</span> of form |
| <code class="constant">VG_s*</code>. If its value is |
| <code class="constant">EGL_VG_COLORSPACE_LINEAR</code>, then |
| a linear color space is assumed, with a |
| corresponding <span class="type">VGImageFormat</span> of form |
| <code class="constant">VG_l*</code>. The default value of |
| <code class="constant">EGL_VG_COLORSPACE</code> is |
| <code class="constant">EGL_VG_COLORSPACE_sRGB</code>. |
| </p> |
| </dd> |
| </dl> |
| </div> |
| <p> |
| Any EGL rendering context that was created with respect to |
| <em class="parameter"><code>config</code></em> can be used to render into the |
| surface. Use |
| <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a> |
| to attach an EGL rendering context to the surface. |
| </p> |
| <p> |
| Use |
| <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> |
| to retrieve the ID of <em class="parameter"><code>config</code></em>. |
| </p> |
| <p> |
| Use |
| <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a> |
| to destroy the surface. |
| </p> |
| </div> |
| <div class="refsect1" id="notes"> |
| <h2>Notes</h2> |
| <p> |
| Attribute <code class="constant">EGL_GL_COLORSPACE</code> is supported |
| only if the EGL version is 1.5 or greater. |
| </p> |
| <p> |
| Attributes <code class="constant">EGL_RENDER_BUFFER</code>, |
| <code class="constant">EGL_VG_ALPHA_FORMAT</code>, and |
| <code class="constant">EGL_VG_COLORSPACE</code>, and the |
| corresponding attribute values, are supported only if the |
| EGL version is 1.2 or greater. |
| </p> |
| <p> |
| The <code class="constant">EGL_VG_ALPHA_FORMAT</code> and |
| <code class="constant">EGL_VG_COLORSPACE</code> attributes are used only |
| by OpenVG and EGL itself. Refer to section 11.2 of the OpenVG |
| 1.0 specification for more information. The platform's use and |
| interpretation of alpha values is outside the scope of EGL. |
| However, the preferred behavior is for platforms to ignore the |
| value of <code class="constant">EGL_VG_ALPHA_FORMAT</code> when |
| compositing window surfaces. |
| </p> |
| </div> |
| <div class="refsect1" id="errors"> |
| <h2>Errors</h2> |
| <p> |
| If <em class="parameter"><code>display</code></em> and |
| <em class="parameter"><code>native_window</code></em> do not belong to the same |
| platform, then undefined behavior occurs. |
| </p> |
| <p> |
| <code class="constant">EGL_NO_SURFACE</code> is returned if creation of |
| the surface fails. |
| </p> |
| <p> |
| <code class="constant">EGL_BAD_DISPLAY</code> is generated if |
| <em class="parameter"><code>display</code></em> is not an EGL display connection. |
| </p> |
| <p> |
| <code class="constant">EGL_NOT_INITIALIZED</code> is generated if |
| <em class="parameter"><code>display</code></em> has not been initialized. |
| </p> |
| <p> |
| <code class="constant">EGL_BAD_CONFIG</code> is generated if |
| <em class="parameter"><code>config</code></em> is not a valid EGL frame buffer |
| configuration. |
| </p> |
| <p> |
| <code class="constant">EGL_BAD_NATIVE_WINDOW</code> may be generated if |
| <em class="parameter"><code>native_window</code></em> is not a valid native |
| window for the same platform as <em class="parameter"><code>display</code></em>. |
| </p> |
| <p> |
| <code class="constant">EGL_BAD_ATTRIBUTE</code> is generated if |
| <em class="parameter"><code>attrib_list</code></em> contains an invalid window attribute |
| or if an attribute value is not recognized or is out of range. |
| </p> |
| <p> |
| <code class="constant">EGL_BAD_ALLOC</code> is generated if there is |
| already an <span class="type">EGLSurface</span> associated with |
| <em class="parameter"><code>native_window</code></em> (as a result of a previous |
| <code class="function">eglCreatePlatformWindowSurface</code> call). |
| </p> |
| <p> |
| <code class="constant">EGL_BAD_ALLOC</code> is generated if the |
| implementation cannot allocate resources for the new EGL window. |
| </p> |
| <p> |
| <code class="constant">EGL_BAD_MATCH</code> is generated if the pixel |
| format of <em class="parameter"><code>native_window</code></em> does not |
| correspond to the format, type, and size of the color buffers |
| required by <em class="parameter"><code>config</code></em>. |
| <code class="constant">EGL_BAD_MATCH</code> is generated if the pixel |
| </p> |
| <p> |
| <code class="constant">EGL_BAD_MATCH</code> is generated if |
| <em class="parameter"><code>config</code></em> does not support rendering to |
| windows (the <code class="constant">EGL_SURFACE_TYPE</code> attribute |
| does not contain <code class="constant">EGL_WINDOW_BIT</code>). |
| </p> |
| <p> |
| <code class="constant">EGL_BAD_MATCH</code> is generated if |
| <em class="parameter"><code>config</code></em> does not support the specified |
| OpenVG alpha format attribute (the value of |
| <code class="constant">EGL_VG_ALPHA_FORMAT</code> is |
| <code class="constant">EGL_VG_ALPHA_FORMAT_PRE</code> and the |
| <code class="constant">EGL_VG_ALPHA_FORMAT_PRE_BIT</code> is not set |
| in the <code class="constant">EGL_SURFACE_TYPE</code> attribute of |
| <em class="parameter"><code>config</code></em>) or colorspace attribute (the |
| value of <code class="constant">EGL_VG_COLORSPACE</code> is |
| <code class="constant">EGL_VG_COLORSPACE_LINEAR</code> and the |
| <code class="constant">EGL_VG_COLORSPACE_LINEAR_IT</code> is not set |
| in the <code class="constant">EGL_SURFACE_TYPE</code> attribute of |
| <em class="parameter"><code>config</code></em>). |
| </p> |
| </div> |
| <div class="refsect1" id="seealso"> |
| <h2>See Also</h2> |
| <p> |
| <a class="citerefentry" href="eglCreateWindowSurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglCreateWindowSurface</span></span></a>, |
| <a class="citerefentry" href="eglDestroySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglDestroySurface</span></span></a>, |
| <a class="citerefentry" href="eglChooseConfig.xhtml"><span class="citerefentry"><span class="refentrytitle">eglChooseConfig</span></span></a>, |
| <a class="citerefentry" href="eglGetConfigs.xhtml"><span class="citerefentry"><span class="refentrytitle">eglGetConfigs</span></span></a>, |
| <a class="citerefentry" href="eglMakeCurrent.xhtml"><span class="citerefentry"><span class="refentrytitle">eglMakeCurrent</span></span></a>, |
| <a class="citerefentry" href="eglQuerySurface.xhtml"><span class="citerefentry"><span class="refentrytitle">eglQuerySurface</span></span></a> |
| </p> |
| </div> |
| <p> |
| </p> |
| <div class="refsect3" id="copyright"> |
| <img src="KhronosLogo.jpg"/> |
| <p> |
| Copyright © 2003-2014 The Khronos Group Inc. |
| Permission is hereby granted, free of charge, to any person obtaining a |
| copy of this software and/or associated documentation files (the |
| "Materials"), to deal in the Materials without restriction, including |
| without limitation the rights to use, copy, modify, merge, publish, |
| distribute, sublicense, and/or sell copies of the Materials, and to |
| permit persons to whom the Materials are furnished to do so, subject to |
| the condition that this copyright notice and permission notice shall be included |
| in all copies or substantial portions of the Materials. |
| </p> |
| </div> |
| <p> |
| </p> |
| </div> |
| <footer/> |
| </body> |
| </html> |
