EGL 1.5 Specification
Total Page:16
File Type:pdf, Size:1020Kb
Khronos Native Platform Graphics Interface (EGL Version 1.5 - August 27, 2014) Editor: Jon Leech 2 Copyright (c) 2002-2014 The Khronos Group Inc. All Rights Reserved. This specification is protected by copyright laws and contains material proprietary to the Khronos Group, Inc. It or any components may not be reproduced, repub- lished, distributed, transmitted, displayed, broadcast or otherwise exploited in any manner without the express prior written permission of Khronos Group. You may use this specification for implementing the functionality therein, without altering or removing any trademark, copyright or other notice from the specification, but the receipt or possession of this specification does not convey any rights to reproduce, disclose, or distribute its contents, or to manufacture, use, or sell anything that it may describe, in whole or in part. Khronos Group grants express permission to any current Promoter, Contributor or Adopter member of Khronos to copy and redistribute UNMODIFIED versions of this specification in any fashion, provided that NO CHARGE is made for the specification and the latest available update of the specification for any version of the API is used whenever possible. Such distributed specification may be re- formatted AS LONG AS the contents of the specification are not changed in any way. The specification may be incorporated into a product that is sold as long as such product includes significant independent work developed by the seller. A link to the current version of this specification on the Khronos Group web-site should be included whenever possible with specification distributions. Khronos Group makes no, and expressly disclaims any, representations or war- ranties, express or implied, regarding this specification, including, without limita- tion, any implied warranties of merchantability or fitness for a particular purpose or non-infringement of any intellectual property. Khronos Group makes no, and expressly disclaims any, warranties, express or implied, regarding the correctness, accuracy, completeness, timeliness, and reliability of the specification. Under no circumstances will the Khronos Group, or any of its Promoters, Contributors or Members or their respective partners, officers, directors, employees, agents or rep- resentatives be liable for any damages, whether direct, indirect, special or conse- quential damages for lost revenues, lost profits, or otherwise, arising from or in connection with these materials. This document is a derivative work of ”OpenGL R Graphics with the X Window System (Version 1.4)”. Silicon Graphics, Inc. owns, and reserves all rights in, the latter document. Khronos is a trademark of The Khronos Group Inc. OpenGL is a registered trade- mark, and OpenGL ES is a trademark, of Silicon Graphics, Inc. EGL 1.5 - August 27, 2014 Contents 1 Overview1 2 EGL Operation2 2.1 Native Platforms and Rendering APIs . .2 2.1.1 EGL Types . .2 2.1.2 Displays . .3 2.2 Rendering Contexts and Drawing Surfaces . .4 2.2.1 Using Rendering Contexts . .5 2.2.2 Rendering Models . .5 2.2.3 Interaction With Native Rendering . .7 2.3 Direct Rendering and Address Spaces . .7 2.4 Shared State . .8 2.4.1 OpenGL and OpenGL ES Texture Objects . .8 2.4.2 OpenGL and OpenGL ES Buffer Objects . .8 2.5 EGLImages . .9 2.6 Multiple Threads . .9 2.7 Power Management . 10 2.8 Extensions . 10 3 EGL Functions and Errors 12 3.1 Errors . 12 3.1.1 Generic Errors Are Not Described Repeatedly . 14 3.1.2 Parameter Validation . 14 3.2 Initialization . 15 3.3 EGL Queries . 18 3.4 Configuration Management . 19 3.4.1 Querying Configurations . 26 3.4.2 Lifetime of Configurations . 31 3.4.3 Querying Configuration Attributes . 31 i CONTENTS ii 3.5 Rendering Surfaces . 31 3.5.1 Creating On-Screen Rendering Surfaces . 31 3.5.2 Creating Off-Screen Rendering Surfaces . 35 3.5.3 Binding Off-Screen Rendering Surfaces To Client Buffers 37 3.5.4 Creating Native Pixmap Rendering Surfaces . 40 3.5.5 Destroying Rendering Surfaces . 41 3.5.6 Surface Attributes . 42 3.6 Rendering to Textures . 46 3.6.1 Binding a Surface to a OpenGL ES Texture . 46 3.6.2 Releasing a Surface from an OpenGL ES Texture . 48 3.6.3 Implementation Caveats . 49 3.7 Rendering Contexts . 49 3.7.1 Creating Rendering Contexts . 51 3.7.2 Destroying Rendering Contexts . 57 3.7.3 Binding Contexts and Drawables . 58 3.7.4 Context Queries . 61 3.8 Synchronization Primitives . 64 3.8.1 Sync Objects . 65 3.9 EGLImage Specification and Management . 72 3.9.1 Lifetime and Usage of EGLImages . 77 3.10 Posting the Color Buffer . 79 3.10.1 Posting to a Window . 79 3.10.2 Copying to a Native Pixmap . 80 3.10.3 Posting Semantics . 80 3.10.4 Posting Errors . 81 3.11 Obtaining Function Pointers . 82 3.12 Releasing Thread State . 83 4 Extending EGL 85 5 EGL Versions, Header Files, and Enumerants 86 5.1 Header Files . 86 5.2 Compile-Time Version Detection . 87 5.3 Enumerant Values and Header Portability . 87 6 Glossary 89 A Version 1.0 92 A.1 Acknowledgements . 92 EGL 1.5 - August 27, 2014 CONTENTS iii B Version 1.1 93 B.1 Revision 1.1.2 . 93 B.2 Acknowledgements . 93 C Version 1.2 95 C.1 Acknowledgements . 95 D Version 1.3 96 D.1 Acknowledgements . 96 E Version 1.4 98 E.1 Updates to EGL 1.4 . 99 E.2 Acknowledgements . 102 F Version 1.5 104 F.1 Change Log for Released Specifications . 105 F.2 Acknowledgements . 107 EGL 1.5 - August 27, 2014 List of Tables 3.1 EGLConfig attributes. 20 3.2 Types of surfaces supported by an EGLConfig .......... 23 3.3 Types of client APIs supported by an EGLConfig ........ 24 3.4 Default values and match criteria for EGLConfig attributes. 29 3.5 Queryable surface attributes and types. 44 3.6 Size of texture components . 47 3.7 Fence sync attributes and initial values. 67 3.8 OpenCL event sync attributes and initial values. 68 3.9 Attributes accepted by eglGetSyncAttrib.............. 71 3.10 Legal values for eglCreateImage target parameter. 74 3.11 Legal attributes for eglCreateImage attrib list parameter. 75 D.1 Renamed tokens . 97 iv Chapter 1 Overview This document describes EGL, an interface between rendering APIs such as OpenCL, OpenGL, OpenGL ES or OpenVG (referred to collectively as client APIs) and one or more underlying platforms (typically window systems such as X11). It refers to concepts discussed in the specifications for these client APIs, and should be read together with those specifications. EGL uses OpenGL ES conventions for naming entry points and macros. EGL provides mechanisms for creating rendering surfaces onto which client APIs can draw, creating graphics contexts for client APIs, and synchronizing draw- ing by client APIs as well as platform rendering APIs. EGL does not explicitly support remote or indirect rendering, unlike the similar GLX API. 1 Chapter 2 EGL Operation 2.1 Native Platforms and Rendering APIs EGL is intended to be implementable on multiple operating systems (such as An- droid, Unix, and Windows) and platforms1 (including window systems such as X11 and Microsoft Windows, and platforms supporting rendering without a dis- play, such as GBM). Implementations may also choose to allow rendering into specific types of EGL surfaces via native rendering APIs specific to a platform, such as Xlib or GDI. Native rendering is described in more detail in section 2.2.3. To the extent possible, EGL itself is independent of definitions and concepts specific to any platform or rendering API. However, there are a few places where native concepts must be mapped into EGL-specific concepts, including the def- inition of the display on which graphics are drawn, and the definition of native windows and pixmaps which can also support client API rendering. This specification does not define the set of platforms that may be supported by the EGL implementation, nor does it specify behavior specific to any platform. The set of supported platforms and their behavior is defined by extensions. To detect if a particular platform is supported, clients should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY using eglQueryString (see section 3.3). 2.1.1 EGL Types EGLBoolean is an integral type representing a boolean value, and should only take on the values EGL_TRUE (1) and EGL_FALSE (0). If boolean parameters 1 Platforms were previously referred to as “native window systems”, but EGL 1.5 now supports both rendering without a display, and multiple runtime platforms. 2 2.1. NATIVE PLATFORMS AND RENDERING APIS 3 passed to EGL take on other values, behavior is undefined, although typically any non-zero value will be interpreted as EGL_TRUE. EGLint is an integral type, normally the same size as a native platform int. Legal attribute values whose type is boolean, bitmask, enumerant, or integer can be passed in EGLint attribute lists, but handle and pointer values may not be representable in such attribute lists2. EGLAttrib is an integral type defined to be equivalent to the ISO C intptr_t type. It is used in the commands eglCreateImage, eglCre- ateSync, eglCreatePlatformWindowSurface, eglCreatePlatformPixmapSur- face, eglGetPlatformDisplay, and eglGetSyncAttrib, and will be used for all similar commands in the future which take attribute lists or return attribute values, since such commands might at some point need to represent handle and pointer values in attribute lists as well as other integral types3. EGLContext is an opaque type representing a client API context. The defi- nition of contexts depends on the client API, but usually represents the state vector of an abstract machine describing the client API and allows executing client API commmands with respect to that state vector.