1<?xml version="1.0" encoding="UTF-8"?> 2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN" 3 "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd"> 4<refentry xml:base="" id="eglCreateWindowSurface"> 5 <refentryinfo> 6 <copyright> 7 <year>2003-2014</year> 8 <holder>The Khronos Group Inc.</holder> 9 </copyright> 10 </refentryinfo> 11 <refmeta> 12 <refentrytitle>eglCreateWindowSurface</refentrytitle> 13 <manvolnum>3G</manvolnum> 14 </refmeta> 15 <refnamediv> 16 <refname>eglCreateWindowSurface</refname> 17 <refpurpose> 18 create a new <acronym>EGL</acronym> window surface 19 </refpurpose> 20 </refnamediv> 21 <refsynopsisdiv> 22 <title>C Specification</title> 23 <funcsynopsis> 24 <funcprototype> 25 <funcdef>EGLSurface <function>eglCreateWindowSurface</function></funcdef> 26 <paramdef>EGLDisplay <parameter>display</parameter></paramdef> 27 <paramdef>EGLConfig <parameter>config</parameter></paramdef> 28 <paramdef>NativeWindowType <parameter>native_window</parameter></paramdef> 29 <paramdef>EGLint const * <parameter>attrib_list</parameter></paramdef> 30 </funcprototype> 31 </funcsynopsis> 32 </refsynopsisdiv> 33 <refsect1 id="parameters"><title>Parameters</title> 34 <variablelist> 35 <varlistentry> 36 <term><parameter>display</parameter></term> 37 <listitem><para>Specifies the EGL display connection.</para></listitem> 38 </varlistentry> 39 <varlistentry> 40 <term><parameter>config</parameter></term> 41 <listitem> 42 <para>Specifies the EGL frame buffer configuration that defines the 43 frame buffer resource available to the surface.</para> 44 </listitem> 45 </varlistentry> 46 <varlistentry> 47 <term><parameter>native_window</parameter></term> 48 <listitem><para>Specifies the native window.</para></listitem> 49 </varlistentry> 50 <varlistentry> 51 <term><parameter>attrib_list</parameter></term> 52 <listitem><para> 53 Specifies window surface attributes. 54 May be <constant>NULL</constant> or empty 55 (first attribute is <constant>EGL_NONE</constant>). 56 </para></listitem> 57 </varlistentry> 58 </variablelist> 59 </refsect1> 60 <refsect1 id="description"><title>Description</title> 61 <para> 62 <function>eglCreateWindowSurface</function> creates an EGL 63 window surface and returns its handle. If 64 <function>eglCreateWindowSurface</function> fails to create 65 a window surface, <constant>EGL_NO_SURFACE</constant> is 66 returned. 67 </para> 68 <para> 69 Surface attributes are specified as a list of 70 attribute-value pairs, terminated with 71 <constant>EGL_NONE</constant>. Accepted attributes 72 are: 73 </para> 74 <variablelist> 75 <varlistentry> 76 <term><constant>EGL_RENDER_BUFFER</constant></term> 77 <listitem> 78 <para> 79 Specifies which buffer should be used for client API 80 rendering to the window. If its value is 81 <constant>EGL_SINGLE_BUFFER</constant>, then client 82 APIs should render directly into the visible window. 83 If its value is 84 <constant>EGL_BACK_BUFFER</constant>, then client 85 APIs should render into the back buffer. The default 86 value of <constant>EGL_RENDER_BUFFER</constant> is 87 <constant>EGL_BACK_BUFFER</constant>. 88 </para> 89 <para> 90 Client APIs may not be able to respect the requested 91 rendering buffer. To determine the actual buffer 92 being rendered to by a context, call 93 <citerefentry><refentrytitle>eglQueryContext</refentrytitle></citerefentry>. 94 </para> 95 </listitem> 96 </varlistentry> 97 <varlistentry> 98 <term><constant>EGL_VG_ALPHA_FORMAT</constant></term> 99 <listitem> 100 <para> 101 Specifies how alpha values are interpreted by OpenVG 102 when rendering to the surface. If its value is 103 <constant>EGL_VG_ALPHA_FORMAT_NONPRE</constant>, 104 then alpha values are not premultipled. If its value 105 is <constant>EGL_VG_ALPHA_FORMAT_PRE</constant>, 106 then alpha values are premultiplied. The default 107 value of <constant>EGL_VG_ALPHA_FORMAT</constant> is 108 <constant>EGL_VG_ALPHA_FORMAT_NONPRE</constant>. 109 </para> 110 </listitem> 111 </varlistentry> 112 <varlistentry> 113 <term><constant>EGL_VG_COLORSPACE</constant></term> 114 <listitem> 115 <para> 116 Specifies the color space used by OpenVG when 117 rendering to the surface. If its value is 118 <constant>EGL_VG_COLORSPACE_sRGB</constant>, then a 119 non-linear, perceptually uniform color space is 120 assumed, with a corresponding 121 <type>VGImageFormat</type> of form 122 <constant>VG_s*</constant>. If its value is 123 <constant>EGL_VG_COLORSPACE_LINEAR</constant>, then 124 a linear color space is assumed, with a 125 corresponding <type>VGImageFormat</type> of form 126 <constant>VG_l*</constant>. The default value of 127 <constant>EGL_VG_COLORSPACE</constant> is 128 <constant>EGL_VG_COLORSPACE_sRGB</constant>. 129 </para> 130 </listitem> 131 </varlistentry> 132 </variablelist> 133 <para> 134 Any EGL rendering context that was created with respect to 135 <parameter>config</parameter> can be used to render into the 136 surface. Use 137 <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry> 138 to attach an EGL rendering context to the surface. 139 </para> 140 <para> 141 Use 142 <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry> 143 to retrieve the ID of <parameter>config</parameter>. 144 </para> 145 <para> 146 Use 147 <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry> 148 to destroy the surface. 149 </para> 150 </refsect1> 151 <refsect1 id="notes"><title>Notes</title> 152 <para> 153 Attributes <constant>EGL_RENDER_BUFFER</constant>, 154 <constant>EGL_VG_ALPHA_FORMAT</constant>, and 155 <constant>EGL_VG_COLORSPACE</constant>, and the 156 corresponding attribute values, are supported only if the 157 EGL version is 1.2 or greater. 158 </para> 159 <!-- Might want to mention aliasing of EGL_VG_* -> EGL_* that occurred in EGL 1.3 --> 160 <para> 161 The <constant>EGL_VG_ALPHA_FORMAT</constant> and 162 <constant>EGL_VG_COLORSPACE</constant> attributes are used 163 only by OpenVG. EGL itself, and other client APIs such as 164 OpenGL and OpenGL ES , do not distinguish multiple 165 colorspace models. Refer to section 11.2 of the OpenVG 1.0 166 specification for more information. The native window 167 system's use and interpretation of alpha values is outside 168 the scope of EGL, although the preferred behavior is for the 169 window system to ignore the value of 170 <constant>EGL_VG_ALPHA_FORMAT</constant> when compositing 171 window surfaces. 172 </para> 173 </refsect1> 174 <refsect1 id="errors"><title>Errors</title> 175 <para> 176 <constant>EGL_NO_SURFACE</constant> is returned if creation of 177 the context fails. 178 </para> 179 <para> 180 <constant>EGL_BAD_DISPLAY</constant> is generated if 181 <parameter>display</parameter> is not an EGL display connection. 182 </para> 183 <para> 184 <constant>EGL_NOT_INITIALIZED</constant> is generated if 185 <parameter>display</parameter> has not been initialized. 186 </para> 187 <para> 188 <constant>EGL_BAD_CONFIG</constant> is generated if 189 <parameter>config</parameter> is not an EGL frame buffer configuration. 190 </para> 191 <para> 192 <constant>EGL_BAD_NATIVE_WINDOW</constant> may be generated if 193 <parameter>native_window</parameter> is not a valid native window. 194 </para> 195 <para> 196 <constant>EGL_BAD_ATTRIBUTE</constant> is generated if 197 <parameter>attrib_list</parameter> contains an invalid window attribute 198 or if an attribute value is not recognized or is out of range. 199 </para> 200 <para> 201 <constant>EGL_BAD_ALLOC</constant> is generated if there are not 202 enough resources to allocate the new surface. 203 </para> 204 <para> 205 <constant>EGL_BAD_MATCH</constant> is generated if the attributes of 206 <parameter>native_window</parameter> do not correspond to 207 <parameter>config</parameter> or if 208 <parameter>config</parameter> does not support rendering to windows 209 (the <constant>EGL_SURFACE_TYPE</constant> attribute does not contain 210 <constant>EGL_WINDOW_BIT</constant>). 211 </para> 212 <para> 213 <constant>EGL_BAD_MATCH</constant> is generated if 214 <parameter>config</parameter> does not support the specified 215 OpenVG alpha format attribute (the value of 216 <constant>EGL_VG_ALPHA_FORMAT</constant> is 217 <constant>EGL_VG_ALPHA_FORMAT_PRE</constant> and the 218 <constant>EGL_VG_ALPHA_FORMAT_PRE_BIT</constant> is not set 219 in the <constant>EGL_SURFACE_TYPE</constant> attribute of 220 <parameter>config</parameter>) or colorspace attribute (the 221 value of <constant>EGL_VG_COLORSPACE</constant> is 222 <constant>EGL_VG_COLORSPACE_LINEAR</constant> and the 223 <constant>EGL_VG_COLORSPACE_LINEAR_IT</constant> is not set 224 in the <constant>EGL_SURFACE_TYPE</constant> attribute of 225 <parameter>config</parameter>). 226 </para> 227 </refsect1> 228 <refsect1 id="seealso"><title>See Also</title> 229 <para> 230 <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry>, 231 <citerefentry><refentrytitle>eglChooseConfig</refentrytitle></citerefentry>, 232 <citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry>, 233 <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry>, 234 <citerefentry><refentrytitle>eglQuerySurface</refentrytitle></citerefentry> 235 </para> 236 </refsect1> 237 <refsect3 id="Copyright"><title></title> 238 <!-- Content included from copyright.inc.xsl --> 239 <imageobject> 240 <imagedata fileref="KhronosLogo.jpg" format="jpg" /> 241 </imageobject> 242 <para /> 243 </refsect3> 244</refentry> 245
