1<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:base="" xml:id="eglIntro"> 2 <info> 3 <copyright> 4 <year>2003-2018</year> 5 <holder>The Khronos Group Inc.</holder> 6 </copyright> 7 </info> 8 <refmeta> 9 <refentrytitle>eglIntro</refentrytitle> 10 <manvolnum>3G</manvolnum> 11 </refmeta> 12 <refnamediv> 13 <refname>eglIntro</refname> 14 <refpurpose> 15 introduction to managing client API rendering through the 16 <acronym>EGL</acronym> API. 17 </refpurpose> 18 </refnamediv> 19 <refsect1 xml:id="overview"><title>Overview</title> 20 <para> 21 The <firstterm>Khronos Native Platform Graphics 22 Interface</firstterm> (EGL) provides a means for rendering 23 using a <firstterm>client API</firstterm> such as OpenGL ES 24 (a 3D renderer for embedded systems), OpenGL (a functional 25 superset of OpenGL ES for desktop systems), and OpenVG (a 2D 26 vector graphics renderer) together with a 27 <firstterm>platform</firstterm>, such as Microsoft Windows or 28 the X Window System. 29 </para> 30 <para> 31 Depending on its implementation EGL might be more or less 32 tightly integrated into the platform. Most EGL 33 functions require an EGL display connection, which can be 34 obtained by calling 35 <citerefentry><refentrytitle>eglGetPlatformDisplay</refentrytitle></citerefentry> 36 or 37 <citerefentry><refentrytitle>eglGetDisplay</refentrytitle></citerefentry>. 38 To initialize and 39 query what EGL version is supported on the display 40 connection, call 41 <citerefentry><refentrytitle>eglInitialize</refentrytitle></citerefentry>. 42 </para> 43 <para> 44 The EGL specification does not define the set of platforms that 45 may be supported by an EGL implementation, nor does it specify 46 behavior specific to any platform. The set of supported 47 platforms and their behavior is defined by platform-specific 48 extensions. To detect if a particular platform is supported, 49 clients should query the <constant>EGL_EXTENSIONS</constant> 50 string of <constant>EGL_NO_DISPLAY</constant> using 51 <citerefentry><refentrytitle>eglQueryString</refentrytitle></citerefentry>. 52 </para> 53 <para> 54 Platforms supporting EGL make a subset of their 55 visuals (which may also referred to as pixel formats, frame 56 buffer configurations, or other similar terms) available for 57 client API rendering. Windows and pixmaps created with these 58 visuals may also be rendered into using the platform APIs. 59 </para> 60 <para> 61 An EGL <firstterm>surface</firstterm> extends a native 62 window or pixmap with additional <firstterm>auxillary 63 buffers</firstterm>. These buffers include a color buffer, a 64 depth buffer, a stencil buffer, and an alpha mask buffer. 65 Some or all of the buffers listed are included in each EGL 66 frame buffer configuration. 67 </para> 68 <para> 69 EGL supports rendering into three types of surfaces: 70 windows, pixmaps and pixel buffers (pbuffers). EGL window 71 and pixmap surfaces are associated with corresponding 72 resources of the platform. EGL pixel buffers are 73 EGL-only resources, and do not accept rendering through the 74 platform APIs. 75 </para> 76 <para> 77 To render using a client API into an EGL surface, you must 78 determine the appropriate EGL frame buffer configuration, 79 which supports the rendering features the application 80 requires. 81 <citerefentry><refentrytitle>eglChooseConfig</refentrytitle></citerefentry> 82 returns an <type>EGLConfig</type> matching the required 83 attributes, if any. A complete list of EGL frame buffer 84 configurations can be obtained by calling 85 <citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry>. 86 Attributes of a particular EGL frame buffer configuration 87 can be queried by calling 88 <citerefentry><refentrytitle>eglGetConfigAttrib</refentrytitle></citerefentry>. 89 </para> 90 <para> 91 For EGL window and pixmap surfaces, a suitable native window 92 or pixmap with a matching native visual must be created 93 first. For a given EGL frame buffer configuration, the 94 native visual type and ID can be retrieved with a call to 95 <citerefentry><refentrytitle>eglGetConfigAttrib</refentrytitle></citerefentry>. 96 For pixel buffers, no underlying native resource is 97 required. 98 </para> 99 <para> 100 To create an EGL window surface from a native window, call 101 <citerefentry><refentrytitle>eglCreateWindowSurface</refentrytitle></citerefentry>. 102 To create an EGL pixmap surface from a native pixmap, call 103 <citerefentry><refentrytitle>eglCreatePixmapSurface</refentrytitle></citerefentry>. 104 To create a pixel buffer (pbuffer) surface (which has no 105 associated native buffer), call 106 <citerefentry><refentrytitle>eglCreatePbufferSurface</refentrytitle></citerefentry> 107 To create a pixel buffer (pbuffer) surface whose color 108 buffer is provided by an OpenVG <type>VGImage</type>, call 109 <citerefentry><refentrytitle>eglCreatePbufferFromClientBuffer</refentrytitle></citerefentry>. 110 Use 111 <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry> 112 to release previously allocated resources. 113 </para> 114 <para> 115 An EGL rendering context is required to bind client API 116 rendering to an EGL surface. An EGL surface and an EGL 117 rendering context must have compatible EGL frame buffer 118 configurations. To create an EGL rendering context, call 119 <citerefentry><refentrytitle>eglCreateContext</refentrytitle></citerefentry>. 120 The type of client API context created (OpenGL ES, OpenVG, 121 etc.) can be changed by first calling 122 <citerefentry><refentrytitle>eglBindAPI</refentrytitle></citerefentry>. 123 </para> 124 <para> 125 An EGL rendering context may be bound to one or two EGL 126 surfaces by calling 127 <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry>. 128 This context/surface(s) association specifies the 129 <firstterm>current context</firstterm> and 130 <firstterm>current surface</firstterm>, and is used by all 131 client API rendering commands for the bound context until 132 <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry> 133 is called with different arguments. 134 </para> 135 <para> 136 Both platform and client API commands may be used to operate 137 on certain surfaces. However, the two command streams are 138 not synchronized. Synchronization can be explicitly 139 specified using by calling 140 <citerefentry><refentrytitle>eglWaitClient</refentrytitle></citerefentry>, 141 <citerefentry><refentrytitle>eglWaitNative</refentrytitle></citerefentry>, 142 and possibly by calling other platform APIs. 143 </para> 144 </refsect1> 145 <refsect1 xml:id="examples"><title>Examples</title> 146 <para> 147 Below is a minimal example of creating an RGBA-format window that 148 allows rendering with OpenGL ES. 149 The window is cleared to yellow when the program runs. For simplicity, 150 the program does not check for any errors. 151 </para> 152<programlisting> 153#include <stdlib.h> 154#include <unistd.h> 155#include <EGL/egl.h> 156#include <GLES/gl.h> 157typedef ... NativeWindowType; 158extern NativeWindowType createNativeWindow(void); 159static EGLint const attribute_list[] = { 160 EGL_RED_SIZE, 1, 161 EGL_GREEN_SIZE, 1, 162 EGL_BLUE_SIZE, 1, 163 EGL_NONE 164}; 165int main(int argc, char ** argv) 166{ 167 EGLDisplay display; 168 EGLConfig config; 169 EGLContext context; 170 EGLSurface surface; 171 NativeWindowType native_window; 172 EGLint num_config; 173 174 /* get an EGL display connection */ 175 display = eglGetDisplay(EGL_DEFAULT_DISPLAY); 176 177 /* initialize the EGL display connection */ 178 eglInitialize(display, NULL, NULL); 179 180 /* get an appropriate EGL frame buffer configuration */ 181 eglChooseConfig(display, attribute_list, &config, 1, &num_config); 182 183 /* create an EGL rendering context */ 184 context = eglCreateContext(display, config, EGL_NO_CONTEXT, NULL); 185 186 /* create a native window */ 187 native_window = createNativeWindow(); 188 189 /* create an EGL window surface */ 190 surface = eglCreateWindowSurface(display, config, native_window, NULL); 191 192 /* connect the context to the surface */ 193 eglMakeCurrent(display, surface, surface, context); 194 195 /* clear the color buffer */ 196 glClearColor(1.0, 1.0, 0.0, 1.0); 197 glClear(GL_COLOR_BUFFER_BIT); 198 glFlush(); 199 200 eglSwapBuffers(display, surface); 201 202 sleep(10); 203 return EXIT_SUCCESS; 204} 205</programlisting> 206 </refsect1> 207 <refsect1 xml:id="notes"><title>Notes</title> 208 <para> 209 Prior to EGL 1.5, platforms were referred to as the 210 <firstterm>native window system</firstterm>, and 211 platform-specific queries and APIs were not available. Only a 212 single native window system was supported. 213 </para> 214 </refsect1> 215 <refsect1 xml:id="usingeglextensions"><title>Using EGL Extensions</title> 216 <para> 217 All supported EGL extensions will have a corresponding definition in 218 <filename>egl.h</filename> and a token in the extension strings returned 219 by 220 <citerefentry><refentrytitle>eglQueryString</refentrytitle></citerefentry>. 221 </para> 222 </refsect1> 223 <refsect1 xml:id="futureeglversions"><title>Future EGL Versions</title> 224 <para> 225 <citerefentry><refentrytitle>eglInitialize</refentrytitle></citerefentry> 226 and 227 <citerefentry><refentrytitle>eglQueryString</refentrytitle></citerefentry> 228 can be used to determine at run-time what version of EGL is available. 229 To check the EGL version at compile-time, test whether 230 <constant>EGL_VERSION_<replaceable>x</replaceable>_<replaceable>y</replaceable></constant> 231 is defined, where <replaceable>x</replaceable> and 232 <replaceable>y</replaceable> are the major and minor version 233 numbers. 234 </para> 235 </refsect1> 236 <refsect1 xml:id="files"><title>Files</title> 237 <variablelist> 238 <varlistentry> 239 <term><filename>GLES/egl.h</filename></term> 240 <listitem><para> 241 EGL header file 242 </para></listitem> 243 </varlistentry> 244 </variablelist> 245 </refsect1> 246 <refsect1 xml:id="seealso"><title>See Also</title> 247 <para> 248<!-- 249 <citerefentry><refentrytitle>glIntro</refentrytitle></citerefentry>, 250 <citerefentry><refentrytitle>glFinish</refentrytitle></citerefentry>, 251 <citerefentry><refentrytitle>glFlush</refentrytitle></citerefentry>, 252--> 253 <citerefentry><refentrytitle>eglBindAPI</refentrytitle></citerefentry>, 254 <citerefentry><refentrytitle>eglChooseConfig</refentrytitle></citerefentry>, 255 <citerefentry><refentrytitle>eglCreateContext</refentrytitle></citerefentry>, 256 <citerefentry><refentrytitle>eglCreatePbufferFromClientBuffer</refentrytitle></citerefentry>, 257 <citerefentry><refentrytitle>eglCreatePbufferSurface</refentrytitle></citerefentry>, 258 <citerefentry><refentrytitle>eglCreatePixmapSurface</refentrytitle></citerefentry>, 259 <citerefentry><refentrytitle>eglCreateWindowSurface</refentrytitle></citerefentry>, 260 <citerefentry><refentrytitle>eglDestroyContext</refentrytitle></citerefentry>, 261 <citerefentry><refentrytitle>eglDestroySurface</refentrytitle></citerefentry>, 262 <citerefentry><refentrytitle>eglGetConfigs</refentrytitle></citerefentry>, 263 <citerefentry><refentrytitle>eglGetDisplay</refentrytitle></citerefentry>, 264 <citerefentry><refentrytitle>eglGetPlatformDisplay</refentrytitle></citerefentry>, 265 <citerefentry><refentrytitle>eglInitialize</refentrytitle></citerefentry>, 266 <citerefentry><refentrytitle>eglMakeCurrent</refentrytitle></citerefentry>, 267 <citerefentry><refentrytitle>eglQueryString</refentrytitle></citerefentry>, 268 <citerefentry><refentrytitle>eglSwapBuffers</refentrytitle></citerefentry>, 269 <citerefentry><refentrytitle>eglTerminate</refentrytitle></citerefentry>, 270 <citerefentry><refentrytitle>eglWaitGL</refentrytitle></citerefentry>, 271 <citerefentry><refentrytitle>eglWaitNative</refentrytitle></citerefentry> 272 </para> 273 </refsect1> 274 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="copyright.xml"/> 275</refentry> 276