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