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