openharmony/third_party_egl
1
0
Fork 0
mirror of https://github.com/openharmony/third_party_egl.git synced 2026-07-01 05:39:22 -04:00
Code Issues Packages Projects Releases Wiki Activity

init from fork

Browse Source 
Signed-off-by: lizheng <lizheng2@huawei.com>
This commit is contained in:
lizheng
2021-11-23 21:47:15 +08:00
parent 5e11dcd58e
commit 880c4dea9d
385 changed files with 92572 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.htaccess
+12
View File
@@ -0,0 +1,12 @@
RewriteEngine on
# Avoid redirect loops
RewriteCond %{ENV:REDIRECT_STATUS} 200
RewriteRule ^ - [L]
# Old versioned-by-date EGL specs redirected to the single per-version copy
RewriteRule ^specs/eglspec.1.1.02.pdf https://www.khronos.org/registry/EGL/specs/eglspec.1.1.pdf [L,R=301]
RewriteRule ^specs/eglspec.1.4.([0-9]+).pdf https://www.khronos.org/registry/EGL/specs/eglspec.1.4.pdf [L,R=301]
RewriteRule ^specs/eglspec.1.4.withchanges.([0-9]+).pdf https://www.khronos.org/registry/EGL/specs/eglspec.1.4.withchanges.pdf [L,R=301]
# RewriteRule ^xhtml/(.*)\.xml https://www.khronos.org/opengles/sdk/docs/man3/html/$1.xhtml [L,R=301]
BUILD.gn
+24
View File
@@ -0,0 +1,24 @@
# Copyright (c) 2021 Huawei Device Co., Ltd.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
config("libEGL_public_config") {
include_dirs = [ "api" ]
defines = [
"ENABLE_EGL",
"EGL_NO_X11",
]
}
group("libEGL") {
public_configs = [ ":libEGL_public_config" ]
}
CODE_OF_CONDUCT.md
+1
View File
@@ -0,0 +1 @@
A reminder that this issue tracker is managed by the Khronos Group. Interactions here should follow the Khronos Code of Conduct (https://www.khronos.org/developers/code-of-conduct), which prohibits aggressive or derogatory language. Please keep the discussion friendly and civil.
README.OpenSource
+11
View File
@@ -0,0 +1,11 @@
[
{
"Name": "EGL",
"License": "MIT License",
"License File": "LICENSE",
"Version Number": "1.5",
"Owner": "lizheng2@huawei.com",
"Upstream URL": "https://github.com/KhronosGroup/EGL-Registry.git",
"Description": "EGL is an interface between Khronos rendering APIs such as OpenGL ES or OpenVG and the underlying native platform window system."
}
]
README.md
+88 -27
View File
@@ -1,39 +1,100 @@
# third_party_EGL
# EGL-Registry
#### 介绍
{**以下是 Gitee 平台说明，您可以替换此简介**
Gitee 是 OSCHINA 推出的基于 Git 的代码托管平台（同时支持 SVN）。专为开发者提供稳定、高效、安全的云端软件开发协作平台
无论是个人、团队、或是企业，都能够用 Gitee 实现代码托管、项目管理、协作开发。企业项目请看 [https://gitee.com/enterprises](https://gitee.com/enterprises)}
The EGL-Registry repository contains the EGL API and Extension Registry,
including specifications, reference pages and reference cards, and the
enumerant registry. It is also used as a backing store for the web view of
the registry at https://www.khronos.org/registry/egl/ ; commits to the
master branch of this repository will be reflected there.
#### 软件架构
软件架构说明
In the past, the EGL registry was maintained in a public Subversion
repository. The history in that repository has not been imported to github,
but it is still available at
https://cvs.khronos.org/svn/repos/registry/trunk/public/egl/ .
Interesting files in this repository include:
* index.php - toplevel index page for the web view. This relies on PHP
include files found elsewhere on www.khronos.org and so is not very useful
in isolation.
* registry.tcl - extension number registry. Documents the names and index
numbers assigned to EGL extension specifications.
* api/egl.xml - extension enumerant and API registry. Defines the EGL API,
including extensions, and is used to generate headers. Documents the EGL
enumerant ranges assigned to different vendors.
* api/EGL/ and api/KHR/ - header files used by an EGL implementation.
EGL/eglext.h and EGL/egl.h are generated from egl.xml. The other headers
are handcoded and express OS and window system (platform) dependencies.
* extensions/ - EGL extension specifications, grouped into vendor-specific
subdirectories.
* sdk/ - EGL reference pages and reference cards. There are separate sets
for each API version.
* specs/ - EGL specification documents.
## Reserving EGL Enumerant Ranges
EGL enumerants are documented in api/egl.xml . New ranges can be allocated
by proposing a pull request to master modifying this file, following the
existing examples. Allocate ranges starting at the lowest free values
available (search for "Reservable for future use"). Ranges are not
officially allocated until your pull request is *accepted* into master. At
that point you can use values from your assigned range for API extensions.
#### 安装教程
## Adding Extension Specifications
1. xxxx
2. xxxx
3. xxxx
Extension specification documents can be added by proposing a pull request
to master, adding the specification .txt file and related changes under
extensions/\<vendor\>/filename.txt. Your pull request must also:
#### 使用说明
* Allocate an extension number in registry.tcl (follow the existing
```<extension>``` examples, search for "Next free extension number", and use
the lowest available extension number).
* Include that extension number in the extension specification document.
* Define the interfaces introduced by this extension in api/egl.xml,
following the examples of existing extensions. If you have difficulty
doing this, consult the registry schema documentation in the GL registry
at www.khronos.org/registry/gl/; you may also create Issues in the
EGL-Registry repository to request help.
* Verify that the EGL headers regenerate properly after applying your XML
changes. In the api/ directory, you must be able to do the following without
errors:
```
# Validate XML changes
make validate
# Verify headers build and are legal C
make clobber
make
make tests
```
* Finally, add a link from the extensions section of index.php to the
extension document, using the specified extension number, so it shows up
in the web view (this could in principle be generated automatically from
registry.tcl / egl.xml, but isn't at present).
1. xxxx
2. xxxx
3. xxxx
Sometimes extension text files contain inappropriate UTF-8 characters. They
should be restricted to the ASCII subset of UTF-8 at present. They can be
removed using the iconv Linux command-line tool via
#### 参与贡献
iconv -c -f utf-8 -t ascii filename.txt
1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request
(see internal Bugzilla issue 16141 for more).
We may transition to an asciidoc-based extension specification format at
some point.
#### 特技
## Build Tools
This section is not complete (see https://github.com/KhronosGroup/EGL-Registry/issues/92).
To validate the XML and build the headers you will need at least GNU make,
'jing' for the 'make validate' step (https://relaxng.org/jclark/jing.html),
and Python 3.5 and the lxml.etree Python library
(https://pypi.org/project/lxml/) for the 'make' step. The 'make tests' step
requires whatever the C and C++ compilers configured for GNU make are,
usually gcc and g++.
All of these components are available prepackaged for major Linux
distributions and for the Windows 10 Debian WSL.
1. 使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
2. Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
3. 你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
4. [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
5. Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
6. Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)
api/1.0/EGL/egl.h
+286
View File
@@ -0,0 +1,286 @@
/* Copyright 2006-2020 The Khronos Group Inc.
* SPDX-License-Identifier: Apache-2.0
*/
/* Sketchy version of egl.h (really only for reserving
* enumerant values to EGL tokens and sanity checking
* prototypes).
*
* Last modified 2006/08/13
*/
#ifndef __egl_h_
#define __egl_h_
/* Windows calling convention boilerplate */
#if defined(_WIN32) && !defined(APIENTRY) && !defined(__CYGWIN__) && !defined(__SCITECH_SNAP__)
#define WIN32_LEAN_AND_MEAN 1
#include <windows.h>
#endif
#ifndef APIENTRY
#define APIENTRY
#endif
#ifndef EGLAPI
#define EGLAPI extern
#endif
/* EGL Types */
#include <sys/types.h>
typedef int32_t EGLint;
typedef unsigned int EGLBoolean;
typedef unsigned int EGLenum;
typedef void *EGLConfig;
typedef void *EGLContext;
typedef void *EGLDisplay;
typedef void *EGLSurface;
typedef void *EGLClientBuffer;
/* NativeDisplayType, NativeWindowType, NativePixmapType TBD */
/* EGL Versioning */
#define EGL_VERSION_1_0 1
#define EGL_VERSION_1_1 1
#define EGL_VERSION_1_2 1
#define EGL_VERSION_1_3 1
/* EGL Enumerants. Exceptional cases aside, most
* enums are assigned unique values starting at 0x3000.
*/
/* EGL aliases */
#define EGL_FALSE 0
#define EGL_TRUE 1
/* Out-of-band handle values */
/* These values may vary depending on semantics of native concepts */
#define EGL_DEFAULT_DISPLAY ((void *)0)
#define EGL_NO_CONTEXT ((EGLContext)0)
#define EGL_NO_DISPLAY ((EGLDisplay)0)
#define EGL_NO_SURFACE ((EGLSurface)0)
/* Out-of-band attribute value */
#define EGL_DONT_CARE ((EGLint)-1)
/* Errors / GetError return values */
#define EGL_SUCCESS 0x3000
#define EGL_NOT_INITIALIZED 0x3001
#define EGL_BAD_ACCESS 0x3002
#define EGL_BAD_ALLOC 0x3003
#define EGL_BAD_ATTRIBUTE 0x3004
#define EGL_BAD_CONFIG 0x3005
#define EGL_BAD_CONTEXT 0x3006
#define EGL_BAD_CURRENT_SURFACE 0x3007
#define EGL_BAD_DISPLAY 0x3008
#define EGL_BAD_MATCH 0x3009
#define EGL_BAD_NATIVE_PIXMAP 0x300A
#define EGL_BAD_NATIVE_WINDOW 0x300B
#define EGL_BAD_PARAMETER 0x300C
#define EGL_BAD_SURFACE 0x300D
#define EGL_CONTEXT_LOST 0x300E /* EGL 1.1 - IMG_power_management */
/* Reserved 0x300F-0x301F for additional errors */
/* Config attributes */
#define EGL_BUFFER_SIZE 0x3020
#define EGL_ALPHA_SIZE 0x3021
#define EGL_BLUE_SIZE 0x3022
#define EGL_GREEN_SIZE 0x3023
#define EGL_RED_SIZE 0x3024
#define EGL_DEPTH_SIZE 0x3025
#define EGL_STENCIL_SIZE 0x3026
#define EGL_CONFIG_CAVEAT 0x3027
#define EGL_CONFIG_ID 0x3028
#define EGL_LEVEL 0x3029
#define EGL_MAX_PBUFFER_HEIGHT 0x302A
#define EGL_MAX_PBUFFER_PIXELS 0x302B
#define EGL_MAX_PBUFFER_WIDTH 0x302C
#define EGL_NATIVE_RENDERABLE 0x302D
#define EGL_NATIVE_VISUAL_ID 0x302E
#define EGL_NATIVE_VISUAL_TYPE 0x302F
#define EGL_PRESERVED_RESOURCES 0x3030
#define EGL_SAMPLES 0x3031
#define EGL_SAMPLE_BUFFERS 0x3032
#define EGL_SURFACE_TYPE 0x3033
#define EGL_TRANSPARENT_TYPE 0x3034
#define EGL_TRANSPARENT_BLUE_VALUE 0x3035
#define EGL_TRANSPARENT_GREEN_VALUE 0x3036
#define EGL_TRANSPARENT_RED_VALUE 0x3037
#define EGL_NONE 0x3038 /* Attrib list terminator */
#define EGL_BIND_TO_TEXTURE_RGB 0x3039
#define EGL_BIND_TO_TEXTURE_RGBA 0x303A
#define EGL_MIN_SWAP_INTERVAL 0x303B
#define EGL_MAX_SWAP_INTERVAL 0x303C
#define EGL_LUMINANCE_SIZE 0x303D
#define EGL_ALPHA_MASK_SIZE 0x303E
#define EGL_COLOR_BUFFER_TYPE 0x303F
#define EGL_RENDERABLE_TYPE 0x3040
#define EGL_MATCH_NATIVE_PIXMAP 0x3041 /* Pseudo-attribute (not queryable) */
/* Reserved 0x3041-0x304F for additional config attributes */
/* Config attribute values */
#define EGL_SLOW_CONFIG 0x3050 /* EGL_CONFIG_CAVEAT value */
#define EGL_NON_CONFORMANT_CONFIG 0x3051 /* EGL_CONFIG_CAVEAT value */
#define EGL_TRANSPARENT_RGB 0x3052 /* EGL_TRANSPARENT_TYPE value */
#define EGL_RGB_BUFFER 0x308E /* EGL_COLOR_BUFFER_TYPE value */
#define EGL_LUMINANCE_BUFFER 0x308F /* EGL_COLOR_BUFFER_TYPE value */
/* More config attribute values, for EGL_TEXTURE_FORMAT */
#define EGL_NO_TEXTURE 0x305C
#define EGL_TEXTURE_RGB 0x305D
#define EGL_TEXTURE_RGBA 0x305E
#define EGL_TEXTURE_2D 0x305F
/* Config attribute mask bits */
#define EGL_PBUFFER_BIT 0x01 /* EGL_SURFACE_TYPE mask bits */
#define EGL_PIXMAP_BIT 0x02 /* EGL_SURFACE_TYPE mask bits */
#define EGL_WINDOW_BIT 0x04 /* EGL_SURFACE_TYPE mask bits */
#define EGL_OPENGL_ES_BIT 0x01 /* EGL_RENDERABLE_TYPE mask bits */
#define EGL_OPENVG_BIT 0x02 /* EGL_RENDERABLE_TYPE mask bits */
#define EGL_OPENGL_ES2_BIT 0x04 /* EGL_RENDERABLE_TYPE mask bits */
/* QueryString targets */
#define EGL_VENDOR 0x3053
#define EGL_VERSION 0x3054
#define EGL_EXTENSIONS 0x3055
#define EGL_CLIENT_APIS 0x308D
/* QuerySurface / CreatePbufferSurface targets */
#define EGL_HEIGHT 0x3056
#define EGL_WIDTH 0x3057
#define EGL_LARGEST_PBUFFER 0x3058
#define EGL_TEXTURE_FORMAT 0x3080
#define EGL_TEXTURE_TARGET 0x3081
#define EGL_MIPMAP_TEXTURE 0x3082
#define EGL_MIPMAP_LEVEL 0x3083
#define EGL_RENDER_BUFFER 0x3086
#define EGL_COLORSPACE 0x3087
#define EGL_ALPHA_FORMAT 0x3088
#define EGL_HORIZONTAL_RESOLUTION 0x3090
#define EGL_VERTICAL_RESOLUTION 0x3091
#define EGL_PIXEL_ASPECT_RATIO 0x3092
#define EGL_SWAP_BEHAVIOR 0x3093
/* EGL_RENDER_BUFFER values / BindTexImage / ReleaseTexImage buffer targets */
#define EGL_BACK_BUFFER 0x3084
#define EGL_SINGLE_BUFFER 0x3085
/* OpenVG color spaces */
#define EGL_COLORSPACE_sRGB 0x3089 /* EGL_COLORSPACE value */
#define EGL_COLORSPACE_LINEAR 0x308A /* EGL_COLORSPACE value */
/* OpenVG alpha formats */
#define EGL_ALPHA_FORMAT_NONPRE 0x308B /* EGL_ALPHA_FORMAT value */
#define EGL_ALPHA_FORMAT_PRE 0x308C /* EGL_ALPHA_FORMAT value */
/* Constant scale factor by which fractional display resolutions &
* aspect ratio are scaled when queried as integer values.
*/
#define EGL_DISPLAY_SCALING 10000
/* Unknown display resolution/aspect ratio */
#define EGL_UNKNOWN ((EGLint)-1)
/* Back buffer swap behaviors */
#define EGL_BUFFER_PRESERVED 0x3094 /* EGL_SWAP_BEHAVIOR value */
#define EGL_BUFFER_DESTROYED 0x3095 /* EGL_SWAP_BEHAVIOR value */
/* CreatePbufferFromClientBuffer buffer types */
#define EGL_OPENVG_IMAGE 0x3096
/* QueryContext targets */
#define EGL_CONTEXT_CLIENT_TYPE 0x3097
/* CreateContext attributes */
#define EGL_CONTEXT_CLIENT_VERSION 0x3098
/* BindAPI/QueryAPI targets */
#define EGL_OPENGL_ES_API 0x30A0
#define EGL_OPENVG_API 0x30A1
/* GetCurrentSurface targets */
#define EGL_DRAW 0x3059
#define EGL_READ 0x305A
/* WaitNative engines */
#define EGL_CORE_NATIVE_ENGINE 0x305B
/* EGL extensions must request enum blocks from the OpenGL ARB
* Secretary, who maintains the EGL enumerant registry.
*/
/* EGL Functions */
EGLAPI EGLint APIENTRY eglGetError();
EGLAPI EGLDisplay APIENTRY eglGetDisplay(const char *display_id);
EGLAPI EGLBoolean APIENTRY eglInitialize(EGLDisplay dpy, EGLint *major, EGLint *minor);
EGLAPI EGLBoolean APIENTRY eglTerminate(EGLDisplay dpy);
EGLAPI const char * APIENTRY eglQueryString(EGLDisplay dpy, EGLint name);
EGLAPI EGLBoolean APIENTRY eglGetConfigs(EGLDisplay dpy, EGLConfig *configs,
EGLint config_size, EGLint *num_config);
EGLAPI EGLBoolean APIENTRY eglChooseConfig(EGLDisplay dpy, const EGLint *attrib_list,
EGLConfig *configs, EGLint config_size,
EGLint *num_config);
EGLAPI EGLBoolean APIENTRY eglGetConfigAttrib(EGLDisplay dpy, EGLConfig config,
EGLint attribute, EGLint *value);
EGLAPI EGLSurface APIENTRY eglCreateWindowSurface(EGLDisplay dpy, EGLConfig config,
NativeWindowType win,
const EGLint *attrib_list);
EGLAPI EGLSurface APIENTRY eglCreatePbufferSurface(EGLDisplay dpy, EGLConfig config,
const EGLint *attrib_list);
EGLAPI EGLSurface APIENTRY eglCreatePixmapSurface(EGLDisplay dpy, EGLConfig config,
NativePixmapType pixmap,
const EGLint *attrib_list);
EGLAPI EGLBoolean APIENTRY eglDestroySurface(EGLDisplay dpy, EGLSurface surface);
EGLAPI EGLBoolean APIENTRY eglQuerySurface(EGLDisplay dpy, EGLSurface surface,
EGLint attribute, EGLint *value);
EGLAPI EGLBoolean APIENTRY eglBindAPI(EGLenum api);
EGLAPI EGLenum APIENTRY eglQueryAPI(void);
EGLAPI EGLBoolean APIENTRY eglWaitClient(void);
EGLAPI EGLBoolean APIENTRY eglReleaseThread(void);
EGLAPI EGLSurface APIENTRY eglCreatePbufferFromClientBuffer(
EGLDisplay dpy, EGLenum buftype, EGLClientBuffer buffer,
EGLConfig config, const EGLint *attrib_list);
EGLAPI EGLBoolean APIENTRY eglSurfaceAttrib(EGLDisplay dpy, EGLSurface surface,
EGLint attribute, EGLint value);
EGLAPI EGLBoolean APIENTRY eglBindTexImage(EGLDisplay dpy, EGLSurface surface, EGLint buffer);
EGLAPI EGLBoolean APIENTRY eglReleaseTexImage(EGLDisplay dpy, EGLSurface surface, EGLint buffer);
EGLAPI EGLBoolean APIENTRY eglSwapInterval(EGLDisplay dpy, EGLint interval);
EGLAPI EGLContext APIENTRY eglCreateContext(EGLDisplay dpy, EGLConfig config,
EGLContext share_context,
const EGLint *attrib_list);
EGLAPI EGLBoolean APIENTRY eglDestroyContext(EGLDisplay dpy, EGLContext ctx);
EGLAPI EGLBoolean APIENTRY eglMakeCurrent(EGLDisplay dpy, EGLSurface draw,
EGLSurface read, EGLContext ctx);
EGLAPI EGLContext APIENTRY eglGetCurrentContext(void);
EGLAPI EGLSurface APIENTRY eglGetCurrentSurface(EGLint readdraw);
EGLAPI EGLDisplay APIENTRY eglGetCurrentDisplay(void);
EGLAPI EGLBoolean APIENTRY eglQueryContext(EGLDisplay dpy, EGLContext ctx,
EGLint attribute, EGLint *value);
EGLAPI EGLBoolean APIENTRY eglWaitGL(void);
EGLAPI EGLBoolean APIENTRY eglWaitNative(EGLint engine);
EGLAPI EGLBoolean APIENTRY eglSwapBuffers(EGLDisplay dpy, EGLSurface surface);
EGLAPI EGLBoolean APIENTRY eglCopyBuffers(EGLDisplay dpy, EGLSurface surface,
NativePixmapType target);
EGLAPI void (* APIENTRY eglGetProcAddress(const char *procname))();
#endif /* __egl_h_ */
api/1.0/egl.h
+283
View File
@@ -0,0 +1,283 @@
/* Sketchy version of egl.h (really only for reserving
* enumerant values to EGL tokens and sanity checking
* prototypes).
*
* Last modified 2006/08/13
*/
#ifndef __egl_h_
#define __egl_h_
/* Windows calling convention boilerplate */
#if defined(_WIN32) && !defined(APIENTRY) && !defined(__CYGWIN__) && !defined(__SCITECH_SNAP__)
#define WIN32_LEAN_AND_MEAN 1
#include <windows.h>
#endif
#ifndef APIENTRY
#define APIENTRY
#endif
#ifndef EGLAPI
#define EGLAPI extern
#endif
/* EGL Types */
#include <sys/types.h>
typedef int32_t EGLint;
typedef unsigned int EGLBoolean;
typedef unsigned int EGLenum;
typedef void *EGLConfig;
typedef void *EGLContext;
typedef void *EGLDisplay;
typedef void *EGLSurface;
typedef void *EGLClientBuffer;
/* NativeDisplayType, NativeWindowType, NativePixmapType TBD */
/* EGL Versioning */
#define EGL_VERSION_1_0 1
#define EGL_VERSION_1_1 1
#define EGL_VERSION_1_2 1
#define EGL_VERSION_1_3 1
/* EGL Enumerants. Exceptional cases aside, most
* enums are assigned unique values starting at 0x3000.
*/
/* EGL aliases */
#define EGL_FALSE 0
#define EGL_TRUE 1
/* Out-of-band handle values */
/* These values may vary depending on semantics of native concepts */
#define EGL_DEFAULT_DISPLAY ((void *)0)
#define EGL_NO_CONTEXT ((EGLContext)0)
#define EGL_NO_DISPLAY ((EGLDisplay)0)
#define EGL_NO_SURFACE ((EGLSurface)0)
/* Out-of-band attribute value */
#define EGL_DONT_CARE ((EGLint)-1)
/* Errors / GetError return values */
#define EGL_SUCCESS 0x3000
#define EGL_NOT_INITIALIZED 0x3001
#define EGL_BAD_ACCESS 0x3002
#define EGL_BAD_ALLOC 0x3003
#define EGL_BAD_ATTRIBUTE 0x3004
#define EGL_BAD_CONFIG 0x3005
#define EGL_BAD_CONTEXT 0x3006
#define EGL_BAD_CURRENT_SURFACE 0x3007
#define EGL_BAD_DISPLAY 0x3008
#define EGL_BAD_MATCH 0x3009
#define EGL_BAD_NATIVE_PIXMAP 0x300A
#define EGL_BAD_NATIVE_WINDOW 0x300B
#define EGL_BAD_PARAMETER 0x300C
#define EGL_BAD_SURFACE 0x300D
#define EGL_CONTEXT_LOST 0x300E /* EGL 1.1 - IMG_power_management */
/* Reserved 0x300F-0x301F for additional errors */
/* Config attributes */
#define EGL_BUFFER_SIZE 0x3020
#define EGL_ALPHA_SIZE 0x3021
#define EGL_BLUE_SIZE 0x3022
#define EGL_GREEN_SIZE 0x3023
#define EGL_RED_SIZE 0x3024
#define EGL_DEPTH_SIZE 0x3025
#define EGL_STENCIL_SIZE 0x3026
#define EGL_CONFIG_CAVEAT 0x3027
#define EGL_CONFIG_ID 0x3028
#define EGL_LEVEL 0x3029
#define EGL_MAX_PBUFFER_HEIGHT 0x302A
#define EGL_MAX_PBUFFER_PIXELS 0x302B
#define EGL_MAX_PBUFFER_WIDTH 0x302C
#define EGL_NATIVE_RENDERABLE 0x302D
#define EGL_NATIVE_VISUAL_ID 0x302E
#define EGL_NATIVE_VISUAL_TYPE 0x302F
#define EGL_PRESERVED_RESOURCES 0x3030
#define EGL_SAMPLES 0x3031
#define EGL_SAMPLE_BUFFERS 0x3032
#define EGL_SURFACE_TYPE 0x3033
#define EGL_TRANSPARENT_TYPE 0x3034
#define EGL_TRANSPARENT_BLUE_VALUE 0x3035
#define EGL_TRANSPARENT_GREEN_VALUE 0x3036
#define EGL_TRANSPARENT_RED_VALUE 0x3037
#define EGL_NONE 0x3038 /* Attrib list terminator */
#define EGL_BIND_TO_TEXTURE_RGB 0x3039
#define EGL_BIND_TO_TEXTURE_RGBA 0x303A
#define EGL_MIN_SWAP_INTERVAL 0x303B
#define EGL_MAX_SWAP_INTERVAL 0x303C
#define EGL_LUMINANCE_SIZE 0x303D
#define EGL_ALPHA_MASK_SIZE 0x303E
#define EGL_COLOR_BUFFER_TYPE 0x303F
#define EGL_RENDERABLE_TYPE 0x3040
#define EGL_MATCH_NATIVE_PIXMAP 0x3041 /* Pseudo-attribute (not queryable) */
/* Reserved 0x3041-0x304F for additional config attributes */
/* Config attribute values */
#define EGL_SLOW_CONFIG 0x3050 /* EGL_CONFIG_CAVEAT value */
#define EGL_NON_CONFORMANT_CONFIG 0x3051 /* EGL_CONFIG_CAVEAT value */
#define EGL_TRANSPARENT_RGB 0x3052 /* EGL_TRANSPARENT_TYPE value */
#define EGL_RGB_BUFFER 0x308E /* EGL_COLOR_BUFFER_TYPE value */
#define EGL_LUMINANCE_BUFFER 0x308F /* EGL_COLOR_BUFFER_TYPE value */
/* More config attribute values, for EGL_TEXTURE_FORMAT */
#define EGL_NO_TEXTURE 0x305C
#define EGL_TEXTURE_RGB 0x305D
#define EGL_TEXTURE_RGBA 0x305E
#define EGL_TEXTURE_2D 0x305F
/* Config attribute mask bits */
#define EGL_PBUFFER_BIT 0x01 /* EGL_SURFACE_TYPE mask bits */
#define EGL_PIXMAP_BIT 0x02 /* EGL_SURFACE_TYPE mask bits */
#define EGL_WINDOW_BIT 0x04 /* EGL_SURFACE_TYPE mask bits */
#define EGL_OPENGL_ES_BIT 0x01 /* EGL_RENDERABLE_TYPE mask bits */
#define EGL_OPENVG_BIT 0x02 /* EGL_RENDERABLE_TYPE mask bits */
#define EGL_OPENGL_ES2_BIT 0x04 /* EGL_RENDERABLE_TYPE mask bits */
/* QueryString targets */
#define EGL_VENDOR 0x3053
#define EGL_VERSION 0x3054
#define EGL_EXTENSIONS 0x3055
#define EGL_CLIENT_APIS 0x308D
/* QuerySurface / CreatePbufferSurface targets */
#define EGL_HEIGHT 0x3056
#define EGL_WIDTH 0x3057
#define EGL_LARGEST_PBUFFER 0x3058
#define EGL_TEXTURE_FORMAT 0x3080
#define EGL_TEXTURE_TARGET 0x3081
#define EGL_MIPMAP_TEXTURE 0x3082
#define EGL_MIPMAP_LEVEL 0x3083
#define EGL_RENDER_BUFFER 0x3086
#define EGL_COLORSPACE 0x3087
#define EGL_ALPHA_FORMAT 0x3088
#define EGL_HORIZONTAL_RESOLUTION 0x3090
#define EGL_VERTICAL_RESOLUTION 0x3091
#define EGL_PIXEL_ASPECT_RATIO 0x3092
#define EGL_SWAP_BEHAVIOR 0x3093
/* EGL_RENDER_BUFFER values / BindTexImage / ReleaseTexImage buffer targets */
#define EGL_BACK_BUFFER 0x3084
#define EGL_SINGLE_BUFFER 0x3085
/* OpenVG color spaces */
#define EGL_COLORSPACE_sRGB 0x3089 /* EGL_COLORSPACE value */
#define EGL_COLORSPACE_LINEAR 0x308A /* EGL_COLORSPACE value */
/* OpenVG alpha formats */
#define EGL_ALPHA_FORMAT_NONPRE 0x308B /* EGL_ALPHA_FORMAT value */
#define EGL_ALPHA_FORMAT_PRE 0x308C /* EGL_ALPHA_FORMAT value */
/* Constant scale factor by which fractional display resolutions &
* aspect ratio are scaled when queried as integer values.
*/
#define EGL_DISPLAY_SCALING 10000
/* Unknown display resolution/aspect ratio */
#define EGL_UNKNOWN ((EGLint)-1)
/* Back buffer swap behaviors */
#define EGL_BUFFER_PRESERVED 0x3094 /* EGL_SWAP_BEHAVIOR value */
#define EGL_BUFFER_DESTROYED 0x3095 /* EGL_SWAP_BEHAVIOR value */
/* CreatePbufferFromClientBuffer buffer types */
#define EGL_OPENVG_IMAGE 0x3096
/* QueryContext targets */
#define EGL_CONTEXT_CLIENT_TYPE 0x3097
/* CreateContext attributes */
#define EGL_CONTEXT_CLIENT_VERSION 0x3098
/* BindAPI/QueryAPI targets */
#define EGL_OPENGL_ES_API 0x30A0
#define EGL_OPENVG_API 0x30A1
/* GetCurrentSurface targets */
#define EGL_DRAW 0x3059
#define EGL_READ 0x305A
/* WaitNative engines */
#define EGL_CORE_NATIVE_ENGINE 0x305B
/* EGL extensions must request enum blocks from the OpenGL ARB
* Secretary, who maintains the EGL enumerant registry.
*/
/* EGL Functions */
EGLAPI EGLint APIENTRY eglGetError();
EGLAPI EGLDisplay APIENTRY eglGetDisplay(const char *display_id);
EGLAPI EGLBoolean APIENTRY eglInitialize(EGLDisplay dpy, EGLint *major, EGLint *minor);
EGLAPI EGLBoolean APIENTRY eglTerminate(EGLDisplay dpy);
EGLAPI const char * APIENTRY eglQueryString(EGLDisplay dpy, EGLint name);
EGLAPI EGLBoolean APIENTRY eglGetConfigs(EGLDisplay dpy, EGLConfig *configs,
EGLint config_size, EGLint *num_config);
EGLAPI EGLBoolean APIENTRY eglChooseConfig(EGLDisplay dpy, const EGLint *attrib_list,
EGLConfig *configs, EGLint config_size,
EGLint *num_config);
EGLAPI EGLBoolean APIENTRY eglGetConfigAttrib(EGLDisplay dpy, EGLConfig config,
EGLint attribute, EGLint *value);
EGLAPI EGLSurface APIENTRY eglCreateWindowSurface(EGLDisplay dpy, EGLConfig config,
NativeWindowType win,
const EGLint *attrib_list);
EGLAPI EGLSurface APIENTRY eglCreatePbufferSurface(EGLDisplay dpy, EGLConfig config,
const EGLint *attrib_list);
EGLAPI EGLSurface APIENTRY eglCreatePixmapSurface(EGLDisplay dpy, EGLConfig config,
NativePixmapType pixmap,
const EGLint *attrib_list);
EGLAPI EGLBoolean APIENTRY eglDestroySurface(EGLDisplay dpy, EGLSurface surface);
EGLAPI EGLBoolean APIENTRY eglQuerySurface(EGLDisplay dpy, EGLSurface surface,
EGLint attribute, EGLint *value);
EGLAPI EGLBoolean APIENTRY eglBindAPI(EGLenum api);
EGLAPI EGLenum APIENTRY eglQueryAPI(void);
EGLAPI EGLBoolean APIENTRY eglWaitClient(void);
EGLAPI EGLBoolean APIENTRY eglReleaseThread(void);
EGLAPI EGLSurface APIENTRY eglCreatePbufferFromClientBuffer(
EGLDisplay dpy, EGLenum buftype, EGLClientBuffer buffer,
EGLConfig config, const EGLint *attrib_list);
EGLAPI EGLBoolean APIENTRY eglSurfaceAttrib(EGLDisplay dpy, EGLSurface surface,
EGLint attribute, EGLint value);
EGLAPI EGLBoolean APIENTRY eglBindTexImage(EGLDisplay dpy, EGLSurface surface, EGLint buffer);
EGLAPI EGLBoolean APIENTRY eglReleaseTexImage(EGLDisplay dpy, EGLSurface surface, EGLint buffer);
EGLAPI EGLBoolean APIENTRY eglSwapInterval(EGLDisplay dpy, EGLint interval);
EGLAPI EGLContext APIENTRY eglCreateContext(EGLDisplay dpy, EGLConfig config,
EGLContext share_context,
const EGLint *attrib_list);
EGLAPI EGLBoolean APIENTRY eglDestroyContext(EGLDisplay dpy, EGLContext ctx);
EGLAPI EGLBoolean APIENTRY eglMakeCurrent(EGLDisplay dpy, EGLSurface draw,
EGLSurface read, EGLContext ctx);
EGLAPI EGLContext APIENTRY eglGetCurrentContext(void);
EGLAPI EGLSurface APIENTRY eglGetCurrentSurface(EGLint readdraw);
EGLAPI EGLDisplay APIENTRY eglGetCurrentDisplay(void);
EGLAPI EGLBoolean APIENTRY eglQueryContext(EGLDisplay dpy, EGLContext ctx,
EGLint attribute, EGLint *value);
EGLAPI EGLBoolean APIENTRY eglWaitGL(void);
EGLAPI EGLBoolean APIENTRY eglWaitNative(EGLint engine);
EGLAPI EGLBoolean APIENTRY eglSwapBuffers(EGLDisplay dpy, EGLSurface surface);
EGLAPI EGLBoolean APIENTRY eglCopyBuffers(EGLDisplay dpy, EGLSurface surface,
NativePixmapType target);
EGLAPI void (* APIENTRY eglGetProcAddress(const char *procname))();
#endif /* __egl_h_ */
api/1.1/EGL/egl.h
+226
View File
@@ -0,0 +1,226 @@
/* Copyright 2006-2020 The Khronos Group Inc.
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef __egl_h_
#define __egl_h_
#include <GLES/gl.h>
#include <GLES/egltypes.h>
/*
** egltypes.h is platform dependent. It defines:
**
** - EGL types and resources
** - Native types
** - EGL and native handle values
**
** EGL types and resources are to be typedef'ed with appropriate platform
** dependent resource handle types. EGLint must be an integer of at least
** 32-bit.
**
** NativeDisplayType, NativeWindowType and NativePixmapType are to be
** replaced with corresponding types of the native window system in egl.h.
**
** EGL and native handle values must match their types.
**
** Example egltypes.h:
*/
#if 0
#include <sys/types.h>
#include <native_window_system.h>
/*
** Types and resources
*/
typedef int EGLBoolean;
typedef int32_t EGLint;
typedef void *EGLDisplay;
typedef void *EGLConfig;
typedef void *EGLSurface;
typedef void *EGLContext;
/*
** EGL and native handle values
*/
#define EGL_DEFAULT_DISPLAY ((NativeDisplayType)0)
#define EGL_NO_CONTEXT ((EGLContext)0)
#define EGL_NO_DISPLAY ((EGLDisplay)0)
#define EGL_NO_SURFACE ((EGLSurface)0)
#endif
/*
** Versioning and extensions
*/
#define EGL_VERSION_1_0 1
#define EGL_VERSION_1_1 1
/*
** Boolean
*/
#define EGL_FALSE 0
#define EGL_TRUE 1
/*
** Errors
*/
#define EGL_SUCCESS 0x3000
#define EGL_NOT_INITIALIZED 0x3001
#define EGL_BAD_ACCESS 0x3002
#define EGL_BAD_ALLOC 0x3003
#define EGL_BAD_ATTRIBUTE 0x3004
#define EGL_BAD_CONFIG 0x3005
#define EGL_BAD_CONTEXT 0x3006
#define EGL_BAD_CURRENT_SURFACE 0x3007
#define EGL_BAD_DISPLAY 0x3008
#define EGL_BAD_MATCH 0x3009
#define EGL_BAD_NATIVE_PIXMAP 0x300A
#define EGL_BAD_NATIVE_WINDOW 0x300B
#define EGL_BAD_PARAMETER 0x300C
#define EGL_BAD_SURFACE 0x300D
#define EGL_CONTEXT_LOST 0x300E
/* 0x300F - 0x301F reserved for additional errors. */
/*
** Config attributes
*/
#define EGL_BUFFER_SIZE 0x3020
#define EGL_ALPHA_SIZE 0x3021
#define EGL_BLUE_SIZE 0x3022
#define EGL_GREEN_SIZE 0x3023
#define EGL_RED_SIZE 0x3024
#define EGL_DEPTH_SIZE 0x3025
#define EGL_STENCIL_SIZE 0x3026
#define EGL_CONFIG_CAVEAT 0x3027
#define EGL_CONFIG_ID 0x3028
#define EGL_LEVEL 0x3029
#define EGL_MAX_PBUFFER_HEIGHT 0x302A
#define EGL_MAX_PBUFFER_PIXELS 0x302B
#define EGL_MAX_PBUFFER_WIDTH 0x302C
#define EGL_NATIVE_RENDERABLE 0x302D
#define EGL_NATIVE_VISUAL_ID 0x302E
#define EGL_NATIVE_VISUAL_TYPE 0x302F
/*#define EGL_PRESERVED_RESOURCES 0x3030*/
#define EGL_SAMPLES 0x3031
#define EGL_SAMPLE_BUFFERS 0x3032
#define EGL_SURFACE_TYPE 0x3033
#define EGL_TRANSPARENT_TYPE 0x3034
#define EGL_TRANSPARENT_BLUE_VALUE 0x3035
#define EGL_TRANSPARENT_GREEN_VALUE 0x3036
#define EGL_TRANSPARENT_RED_VALUE 0x3037
#define EGL_NONE 0x3038 /* Also a config value */
#define EGL_BIND_TO_TEXTURE_RGB 0x3039
#define EGL_BIND_TO_TEXTURE_RGBA 0x303A
#define EGL_MIN_SWAP_INTERVAL 0x303B
#define EGL_MAX_SWAP_INTERVAL 0x303C
/*
** Config values
*/
#define EGL_DONT_CARE ((EGLint) -1)
#define EGL_SLOW_CONFIG 0x3050 /* EGL_CONFIG_CAVEAT value */
#define EGL_NON_CONFORMANT_CONFIG 0x3051 /* " */
#define EGL_TRANSPARENT_RGB 0x3052 /* EGL_TRANSPARENT_TYPE value */
#define EGL_NO_TEXTURE 0x305C /* EGL_TEXTURE_FORMAT/TARGET value */
#define EGL_TEXTURE_RGB 0x305D /* EGL_TEXTURE_FORMAT value */
#define EGL_TEXTURE_RGBA 0x305E /* " */
#define EGL_TEXTURE_2D 0x305F /* EGL_TEXTURE_TARGET value */
/*
** Config attribute mask bits
*/
#define EGL_PBUFFER_BIT 0x01 /* EGL_SURFACE_TYPE mask bit */
#define EGL_PIXMAP_BIT 0x02 /* " */
#define EGL_WINDOW_BIT 0x04 /* " */
/*
** String names
*/
#define EGL_VENDOR 0x3053 /* eglQueryString target */
#define EGL_VERSION 0x3054 /* " */
#define EGL_EXTENSIONS 0x3055 /* " */
/*
** Surface attributes
*/
#define EGL_HEIGHT 0x3056
#define EGL_WIDTH 0x3057
#define EGL_LARGEST_PBUFFER 0x3058
#define EGL_TEXTURE_FORMAT 0x3080 /* For pbuffers bound as textures */
#define EGL_TEXTURE_TARGET 0x3081 /* " */
#define EGL_MIPMAP_TEXTURE 0x3082 /* " */
#define EGL_MIPMAP_LEVEL 0x3083 /* " */
/*
** BindTexImage / ReleaseTexImage buffer target
*/
#define EGL_BACK_BUFFER 0x3084
/*
** Current surfaces
*/
#define EGL_DRAW 0x3059
#define EGL_READ 0x305A
/*
** Engines
*/
#define EGL_CORE_NATIVE_ENGINE 0x305B
/* 0x305C-0x3FFFF reserved for future use */
/*
** Functions
*/
#ifdef __cplusplus
extern "C" {
#endif
GLAPI EGLint APIENTRY eglGetError (void);
GLAPI EGLDisplay APIENTRY eglGetDisplay (NativeDisplayType display);
GLAPI EGLBoolean APIENTRY eglInitialize (EGLDisplay dpy, EGLint *major, EGLint *minor);
GLAPI EGLBoolean APIENTRY eglTerminate (EGLDisplay dpy);
GLAPI const char * APIENTRY eglQueryString (EGLDisplay dpy, EGLint name);
GLAPI void (* APIENTRY eglGetProcAddress (const char *procname))();
GLAPI EGLBoolean APIENTRY eglGetConfigs (EGLDisplay dpy, EGLConfig *configs, EGLint config_size, EGLint *num_config);
GLAPI EGLBoolean APIENTRY eglChooseConfig (EGLDisplay dpy, const EGLint *attrib_list, EGLConfig *configs, EGLint config_size, EGLint *num_config);
GLAPI EGLBoolean APIENTRY eglGetConfigAttrib (EGLDisplay dpy, EGLConfig config, EGLint attribute, EGLint *value);
GLAPI EGLSurface APIENTRY eglCreateWindowSurface (EGLDisplay dpy, EGLConfig config, NativeWindowType window, const EGLint *attrib_list);
GLAPI EGLSurface APIENTRY eglCreatePixmapSurface (EGLDisplay dpy, EGLConfig config, NativePixmapType pixmap, const EGLint *attrib_list);
GLAPI EGLSurface APIENTRY eglCreatePbufferSurface (EGLDisplay dpy, EGLConfig config, const EGLint *attrib_list);
GLAPI EGLBoolean APIENTRY eglDestroySurface (EGLDisplay dpy, EGLSurface surface);
GLAPI EGLBoolean APIENTRY eglQuerySurface (EGLDisplay dpy, EGLSurface surface, EGLint attribute, EGLint *value);
/* EGL 1.1 render-to-texture APIs */
GLAPI EGLBoolean APIENTRY eglSurfaceAttrib (EGLDisplay dpy, EGLSurface surface, EGLint attribute, EGLint value);
GLAPI EGLBoolean APIENTRY eglBindTexImage(EGLDisplay dpy, EGLSurface surface, EGLint buffer);
GLAPI EGLBoolean APIENTRY eglReleaseTexImage(EGLDisplay dpy, EGLSurface surface, EGLint buffer);
/* EGL 1.1 swap control API */
GLAPI EGLBoolean APIENTRY eglSwapInterval(EGLDisplay dpy, EGLint interval);
GLAPI EGLContext APIENTRY eglCreateContext (EGLDisplay dpy, EGLConfig config, EGLContext share_list, const EGLint *attrib_list);
GLAPI EGLBoolean APIENTRY eglDestroyContext (EGLDisplay dpy, EGLContext ctx);
GLAPI EGLBoolean APIENTRY eglMakeCurrent (EGLDisplay dpy, EGLSurface draw, EGLSurface read, EGLContext ctx);
GLAPI EGLContext APIENTRY eglGetCurrentContext (void);
GLAPI EGLSurface APIENTRY eglGetCurrentSurface (EGLint readdraw);
GLAPI EGLDisplay APIENTRY eglGetCurrentDisplay (void);
GLAPI EGLBoolean APIENTRY eglQueryContext (EGLDisplay dpy, EGLContext ctx, EGLint attribute, EGLint *value);
GLAPI EGLBoolean APIENTRY eglWaitGL (void);
GLAPI EGLBoolean APIENTRY eglWaitNative (EGLint engine);
GLAPI EGLBoolean APIENTRY eglSwapBuffers (EGLDisplay dpy, EGLSurface draw);
GLAPI EGLBoolean APIENTRY eglCopyBuffers (EGLDisplay dpy, EGLSurface surface, NativePixmapType target);
#ifdef __cplusplus
}
#endif
#endif /* ___egl_h_ */
api/1.2/EGL/egl.h
+264
View File
@@ -0,0 +1,264 @@
/* Copyright 2006-2020 The Khronos Group Inc.
* SPDX-License-Identifier: Apache-2.0
*/
/* Reference egl.h for EGL 1.2
* Last modified 2006/10/24
*/
#ifndef __egl_h_
#define __egl_h_
/* EGL Types */
#include <sys/types.h>
typedef int32_t EGLint;
typedef unsigned int EGLBoolean;
typedef void *EGLConfig;
typedef void *EGLContext;
typedef void *EGLDisplay;
typedef void *EGLSurface;
/* Define NativeDisplayType, NativeWindowType, NativePixmapType in egltypes.h */
#include <EGL/egltypes.h>
/* EGL Versioning */
#define EGL_VERSION_1_0 1
#define EGL_VERSION_1_1 1
#define EGL_VERSION_1_2 1
/* EGL Enumerants. Exceptional cases aside, most
* enums are assigned unique values starting at 0x3000.
*/
/* EGL aliases */
#define EGL_FALSE 0
#define EGL_TRUE 1
/* Out-of-band handle values */
/* These values may vary depending on semantics of native concepts */
#define EGL_DEFAULT_DISPLAY ((void *)0)
#define EGL_NO_CONTEXT ((EGLContext)0)
#define EGL_NO_DISPLAY ((EGLDisplay)0)
#define EGL_NO_SURFACE ((EGLSurface)0)
/* Out-of-band attribute value */
#define EGL_DONT_CARE ((EGLint)-1)
/* Errors / GetError return values */
#define EGL_SUCCESS 0x3000
#define EGL_NOT_INITIALIZED 0x3001
#define EGL_BAD_ACCESS 0x3002
#define EGL_BAD_ALLOC 0x3003
#define EGL_BAD_ATTRIBUTE 0x3004
#define EGL_BAD_CONFIG 0x3005
#define EGL_BAD_CONTEXT 0x3006
#define EGL_BAD_CURRENT_SURFACE 0x3007
#define EGL_BAD_DISPLAY 0x3008
#define EGL_BAD_MATCH 0x3009
#define EGL_BAD_NATIVE_PIXMAP 0x300A
#define EGL_BAD_NATIVE_WINDOW 0x300B
#define EGL_BAD_PARAMETER 0x300C
#define EGL_BAD_SURFACE 0x300D
#define EGL_CONTEXT_LOST 0x300E /* EGL 1.1 - IMG_power_management */
/* Reserved 0x300F-0x301F for additional errors */
/* Config attributes */
#define EGL_BUFFER_SIZE 0x3020
#define EGL_ALPHA_SIZE 0x3021
#define EGL_BLUE_SIZE 0x3022
#define EGL_GREEN_SIZE 0x3023
#define EGL_RED_SIZE 0x3024
#define EGL_DEPTH_SIZE 0x3025
#define EGL_STENCIL_SIZE 0x3026
#define EGL_CONFIG_CAVEAT 0x3027
#define EGL_CONFIG_ID 0x3028
#define EGL_LEVEL 0x3029
#define EGL_MAX_PBUFFER_HEIGHT 0x302A
#define EGL_MAX_PBUFFER_PIXELS 0x302B
#define EGL_MAX_PBUFFER_WIDTH 0x302C
#define EGL_NATIVE_RENDERABLE 0x302D
#define EGL_NATIVE_VISUAL_ID 0x302E
#define EGL_NATIVE_VISUAL_TYPE 0x302F
#define EGL_PRESERVED_RESOURCES 0x3030
#define EGL_SAMPLES 0x3031
#define EGL_SAMPLE_BUFFERS 0x3032
#define EGL_SURFACE_TYPE 0x3033
#define EGL_TRANSPARENT_TYPE 0x3034
#define EGL_TRANSPARENT_BLUE_VALUE 0x3035
#define EGL_TRANSPARENT_GREEN_VALUE 0x3036
#define EGL_TRANSPARENT_RED_VALUE 0x3037
#define EGL_NONE 0x3038 /* Attrib list terminator */
#define EGL_BIND_TO_TEXTURE_RGB 0x3039
#define EGL_BIND_TO_TEXTURE_RGBA 0x303A
#define EGL_MIN_SWAP_INTERVAL 0x303B
#define EGL_MAX_SWAP_INTERVAL 0x303C
#define EGL_LUMINANCE_SIZE 0x303D
#define EGL_ALPHA_MASK_SIZE 0x303E
#define EGL_COLOR_BUFFER_TYPE 0x303F
#define EGL_RENDERABLE_TYPE 0x3040
/* Reserved 0x3041-0x304F for additional config attributes */
/* Config attribute values */
#define EGL_SLOW_CONFIG 0x3050 /* EGL_CONFIG_CAVEAT value */
#define EGL_NON_CONFORMANT_CONFIG 0x3051 /* EGL_CONFIG_CAVEAT value */
#define EGL_TRANSPARENT_RGB 0x3052 /* EGL_TRANSPARENT_TYPE value */
#define EGL_RGB_BUFFER 0x308E /* EGL_COLOR_BUFFER_TYPE value */
#define EGL_LUMINANCE_BUFFER 0x308F /* EGL_COLOR_BUFFER_TYPE value */
/* More config attribute values, for EGL_TEXTURE_FORMAT */
#define EGL_NO_TEXTURE 0x305C
#define EGL_TEXTURE_RGB 0x305D
#define EGL_TEXTURE_RGBA 0x305E
#define EGL_TEXTURE_2D 0x305F
/* Config attribute mask bits */
#define EGL_PBUFFER_BIT 0x01 /* EGL_SURFACE_TYPE mask bits */
#define EGL_PIXMAP_BIT 0x02 /* EGL_SURFACE_TYPE mask bits */
#define EGL_WINDOW_BIT 0x04 /* EGL_SURFACE_TYPE mask bits */
#define EGL_OPENGL_ES_BIT 0x01 /* EGL_RENDERABLE_TYPE mask bits */
#define EGL_OPENVG_BIT 0x02 /* EGL_RENDERABLE_TYPE mask bits */
/* QueryString targets */
#define EGL_VENDOR 0x3053
#define EGL_VERSION 0x3054
#define EGL_EXTENSIONS 0x3055
#define EGL_CLIENT_APIS 0x308D
/* QuerySurface / CreatePbufferSurface targets */
#define EGL_HEIGHT 0x3056
#define EGL_WIDTH 0x3057
#define EGL_LARGEST_PBUFFER 0x3058
#define EGL_TEXTURE_FORMAT 0x3080
#define EGL_TEXTURE_TARGET 0x3081
#define EGL_MIPMAP_TEXTURE 0x3082
#define EGL_MIPMAP_LEVEL 0x3083
#define EGL_RENDER_BUFFER 0x3086
#define EGL_COLORSPACE 0x3087
#define EGL_ALPHA_FORMAT 0x3088
#define EGL_HORIZONTAL_RESOLUTION 0x3090
#define EGL_VERTICAL_RESOLUTION 0x3091
#define EGL_PIXEL_ASPECT_RATIO 0x3092
#define EGL_SWAP_BEHAVIOR 0x3093
/* EGL_RENDER_BUFFER values / BindTexImage / ReleaseTexImage buffer targets */
#define EGL_BACK_BUFFER 0x3084
#define EGL_SINGLE_BUFFER 0x3085
/* OpenVG color spaces */
#define EGL_COLORSPACE_sRGB 0x3089 /* EGL_COLORSPACE value */
#define EGL_COLORSPACE_LINEAR 0x308A /* EGL_COLORSPACE value */
/* OpenVG alpha formats */
#define EGL_ALPHA_FORMAT_NONPRE 0x308B /* EGL_ALPHA_FORMAT value */
#define EGL_ALPHA_FORMAT_PRE 0x308C /* EGL_ALPHA_FORMAT value */
/* Constant scale factor by which fractional display resolutions &
* aspect ratio are scaled when queried as integer values.
*/
#define EGL_DISPLAY_SCALING 10000
/* Unknown display resolution/aspect ratio */
#define EGL_UNKNOWN ((EGLint)-1)
/* Back buffer swap behaviors */
#define EGL_BUFFER_PRESERVED 0x3094 /* EGL_SWAP_BEHAVIOR value */
#define EGL_BUFFER_DESTROYED 0x3095 /* EGL_SWAP_BEHAVIOR value */
/* CreatePbufferFromClientBuffer buffer types */
#define EGL_OPENVG_IMAGE 0x3096
/* QueryContext targets */
#define EGL_CONTEXT_CLIENT_TYPE 0x3097
/* BindAPI/QueryAPI targets */
#define EGL_OPENGL_ES_API 0x30A0
#define EGL_OPENVG_API 0x30A1
/* GetCurrentSurface targets */
#define EGL_DRAW 0x3059
#define EGL_READ 0x305A
/* WaitNative engines */
#define EGL_CORE_NATIVE_ENGINE 0x305B
/* EGL extensions must request enum blocks from the OpenGL ARB
* Secretary, who maintains the EGL enumerant registry.
*/
/* EGL Functions */
EGLint eglGetError();
EGLDisplay eglGetDisplay(NativeDisplayType display_id);
EGLBoolean eglInitialize(EGLDisplay dpy, EGLint *major, EGLint *minor);
EGLBoolean eglTerminate(EGLDisplay dpy);
const char *eglQueryString(EGLDisplay dpy, EGLint name);
EGLBoolean eglGetConfigs(EGLDisplay dpy, EGLConfig *configs,
EGLint config_size, EGLint *num_config);
EGLBoolean eglChooseConfig(EGLDisplay dpy, const EGLint *attrib_list,
EGLConfig *configs, EGLint config_size,
EGLint *num_config);
EGLBoolean eglGetConfigAttrib(EGLDisplay dpy, EGLConfig config,
EGLint attribute, EGLint *value);
EGLSurface eglCreateWindowSurface(EGLDisplay dpy, EGLConfig config,
NativeWindowType win,
const EGLint *attrib_list);
EGLSurface eglCreatePbufferSurface(EGLDisplay dpy, EGLConfig config,
const EGLint *attrib_list);
EGLSurface eglCreatePixmapSurface(EGLDisplay dpy, EGLConfig config,
NativePixmapType pixmap,
const EGLint *attrib_list);
EGLBoolean eglDestroySurface(EGLDisplay dpy, EGLSurface surface);
EGLBoolean eglQuerySurface(EGLDisplay dpy, EGLSurface surface,
EGLint attribute, EGLint *value);
EGLBoolean eglBindAPI(EGLenum api);
EGLenum eglQueryAPI(void);
EGLBoolean eglWaitClient(void);
EGLBoolean eglReleaseThread(void);
EGLSurface eglCreatePbufferFromClientBuffer(
EGLDisplay dpy, EGLenum buftype, EGLClientBuffer buffer,
EGLConfig config, const EGLint *attrib_list);
EGLBoolean eglSurfaceAttrib(EGLDisplay dpy, EGLSurface surface,
EGLint attribute, EGLint value);
EGLBoolean eglBindTexImage(EGLDisplay dpy, EGLSurface surface, EGLint buffer);
EGLBoolean eglReleaseTexImage(EGLDisplay dpy, EGLSurface surface, EGLint buffer);
EGLBoolean eglSwapInterval(EGLDisplay dpy, EGLint interval);
EGLContext eglCreateContext(EGLDisplay dpy, EGLConfig config,
EGLContext share_context,
const EGLint *attrib_list);
EGLBoolean eglDestroyContext(EGLDisplay dpy, EGLContext ctx);
EGLBoolean eglMakeCurrent(EGLDisplay dpy, EGLSurface draw,
EGLSurface read, EGLContext ctx);
EGLContext eglGetCurrentContext(void);
EGLSurface eglGetCurrentSurface(EGLint readdraw);
EGLDisplay eglGetCurrentDisplay(void);
EGLBoolean eglQueryContext(EGLDisplay dpy, EGLContext ctx,
EGLint attribute, EGLint *value);
EGLBoolean eglWaitGL(void);
EGLBoolean eglWaitNative(EGLint engine);
EGLBoolean eglSwapBuffers(EGLDisplay dpy, EGLSurface surface);
EGLBoolean eglCopyBuffers(EGLDisplay dpy, EGLSurface surface,
NativePixmapType target);
void (*eglGetProcAddress(const char *procname))();
#endif /* __egl_h_ */
api/1.2/egl.h
+260
View File
@@ -0,0 +1,260 @@
/* Reference egl.h for EGL 1.2
* Last modified 2006/10/24
*/
#ifndef __egl_h_
#define __egl_h_
/* EGL Types */
#include <sys/types.h>
typedef int32_t EGLint;
typedef unsigned int EGLBoolean;
typedef void *EGLConfig;
typedef void *EGLContext;
typedef void *EGLDisplay;
typedef void *EGLSurface;
/* Define NativeDisplayType, NativeWindowType, NativePixmapType in egltypes.h */
#include <EGL/egltypes.h>
/* EGL Versioning */
#define EGL_VERSION_1_0 1
#define EGL_VERSION_1_1 1
#define EGL_VERSION_1_2 1
/* EGL Enumerants. Exceptional cases aside, most
* enums are assigned unique values starting at 0x3000.
*/
/* EGL aliases */
#define EGL_FALSE 0
#define EGL_TRUE 1
/* Out-of-band handle values */
/* These values may vary depending on semantics of native concepts */
#define EGL_DEFAULT_DISPLAY ((void *)0)
#define EGL_NO_CONTEXT ((EGLContext)0)
#define EGL_NO_DISPLAY ((EGLDisplay)0)
#define EGL_NO_SURFACE ((EGLSurface)0)
/* Out-of-band attribute value */
#define EGL_DONT_CARE ((EGLint)-1)
/* Errors / GetError return values */
#define EGL_SUCCESS 0x3000
#define EGL_NOT_INITIALIZED 0x3001
#define EGL_BAD_ACCESS 0x3002
#define EGL_BAD_ALLOC 0x3003
#define EGL_BAD_ATTRIBUTE 0x3004
#define EGL_BAD_CONFIG 0x3005
#define EGL_BAD_CONTEXT 0x3006
#define EGL_BAD_CURRENT_SURFACE 0x3007
#define EGL_BAD_DISPLAY 0x3008
#define EGL_BAD_MATCH 0x3009
#define EGL_BAD_NATIVE_PIXMAP 0x300A
#define EGL_BAD_NATIVE_WINDOW 0x300B
#define EGL_BAD_PARAMETER 0x300C
#define EGL_BAD_SURFACE 0x300D
#define EGL_CONTEXT_LOST 0x300E /* EGL 1.1 - IMG_power_management */
/* Reserved 0x300F-0x301F for additional errors */
/* Config attributes */
#define EGL_BUFFER_SIZE 0x3020
#define EGL_ALPHA_SIZE 0x3021
#define EGL_BLUE_SIZE 0x3022
#define EGL_GREEN_SIZE 0x3023
#define EGL_RED_SIZE 0x3024
#define EGL_DEPTH_SIZE 0x3025
#define EGL_STENCIL_SIZE 0x3026
#define EGL_CONFIG_CAVEAT 0x3027
#define EGL_CONFIG_ID 0x3028
#define EGL_LEVEL 0x3029
#define EGL_MAX_PBUFFER_HEIGHT 0x302A
#define EGL_MAX_PBUFFER_PIXELS 0x302B
#define EGL_MAX_PBUFFER_WIDTH 0x302C
#define EGL_NATIVE_RENDERABLE 0x302D
#define EGL_NATIVE_VISUAL_ID 0x302E
#define EGL_NATIVE_VISUAL_TYPE 0x302F
#define EGL_PRESERVED_RESOURCES 0x3030
#define EGL_SAMPLES 0x3031
#define EGL_SAMPLE_BUFFERS 0x3032
#define EGL_SURFACE_TYPE 0x3033
#define EGL_TRANSPARENT_TYPE 0x3034
#define EGL_TRANSPARENT_BLUE_VALUE 0x3035
#define EGL_TRANSPARENT_GREEN_VALUE 0x3036
#define EGL_TRANSPARENT_RED_VALUE 0x3037
#define EGL_NONE 0x3038 /* Attrib list terminator */
#define EGL_BIND_TO_TEXTURE_RGB 0x3039
#define EGL_BIND_TO_TEXTURE_RGBA 0x303A
#define EGL_MIN_SWAP_INTERVAL 0x303B
#define EGL_MAX_SWAP_INTERVAL 0x303C
#define EGL_LUMINANCE_SIZE 0x303D
#define EGL_ALPHA_MASK_SIZE 0x303E
#define EGL_COLOR_BUFFER_TYPE 0x303F
#define EGL_RENDERABLE_TYPE 0x3040
/* Reserved 0x3041-0x304F for additional config attributes */
/* Config attribute values */
#define EGL_SLOW_CONFIG 0x3050 /* EGL_CONFIG_CAVEAT value */
#define EGL_NON_CONFORMANT_CONFIG 0x3051 /* EGL_CONFIG_CAVEAT value */
#define EGL_TRANSPARENT_RGB 0x3052 /* EGL_TRANSPARENT_TYPE value */
#define EGL_RGB_BUFFER 0x308E /* EGL_COLOR_BUFFER_TYPE value */
#define EGL_LUMINANCE_BUFFER 0x308F /* EGL_COLOR_BUFFER_TYPE value */
/* More config attribute values, for EGL_TEXTURE_FORMAT */
#define EGL_NO_TEXTURE 0x305C
#define EGL_TEXTURE_RGB 0x305D
#define EGL_TEXTURE_RGBA 0x305E
#define EGL_TEXTURE_2D 0x305F
/* Config attribute mask bits */
#define EGL_PBUFFER_BIT 0x01 /* EGL_SURFACE_TYPE mask bits */
#define EGL_PIXMAP_BIT 0x02 /* EGL_SURFACE_TYPE mask bits */
#define EGL_WINDOW_BIT 0x04 /* EGL_SURFACE_TYPE mask bits */
#define EGL_OPENGL_ES_BIT 0x01 /* EGL_RENDERABLE_TYPE mask bits */
#define EGL_OPENVG_BIT 0x02 /* EGL_RENDERABLE_TYPE mask bits */
/* QueryString targets */
#define EGL_VENDOR 0x3053
#define EGL_VERSION 0x3054
#define EGL_EXTENSIONS 0x3055
#define EGL_CLIENT_APIS 0x308D
/* QuerySurface / CreatePbufferSurface targets */
#define EGL_HEIGHT 0x3056
#define EGL_WIDTH 0x3057
#define EGL_LARGEST_PBUFFER 0x3058
#define EGL_TEXTURE_FORMAT 0x3080
#define EGL_TEXTURE_TARGET 0x3081
#define EGL_MIPMAP_TEXTURE 0x3082
#define EGL_MIPMAP_LEVEL 0x3083
#define EGL_RENDER_BUFFER 0x3086
#define EGL_COLORSPACE 0x3087
#define EGL_ALPHA_FORMAT 0x3088
#define EGL_HORIZONTAL_RESOLUTION 0x3090
#define EGL_VERTICAL_RESOLUTION 0x3091
#define EGL_PIXEL_ASPECT_RATIO 0x3092
#define EGL_SWAP_BEHAVIOR 0x3093
/* EGL_RENDER_BUFFER values / BindTexImage / ReleaseTexImage buffer targets */
#define EGL_BACK_BUFFER 0x3084
#define EGL_SINGLE_BUFFER 0x3085
/* OpenVG color spaces */
#define EGL_COLORSPACE_sRGB 0x3089 /* EGL_COLORSPACE value */
#define EGL_COLORSPACE_LINEAR 0x308A /* EGL_COLORSPACE value */
/* OpenVG alpha formats */
#define EGL_ALPHA_FORMAT_NONPRE 0x308B /* EGL_ALPHA_FORMAT value */
#define EGL_ALPHA_FORMAT_PRE 0x308C /* EGL_ALPHA_FORMAT value */
/* Constant scale factor by which fractional display resolutions &
* aspect ratio are scaled when queried as integer values.
*/
#define EGL_DISPLAY_SCALING 10000
/* Unknown display resolution/aspect ratio */
#define EGL_UNKNOWN ((EGLint)-1)
/* Back buffer swap behaviors */
#define EGL_BUFFER_PRESERVED 0x3094 /* EGL_SWAP_BEHAVIOR value */
#define EGL_BUFFER_DESTROYED 0x3095 /* EGL_SWAP_BEHAVIOR value */
/* CreatePbufferFromClientBuffer buffer types */
#define EGL_OPENVG_IMAGE 0x3096
/* QueryContext targets */
#define EGL_CONTEXT_CLIENT_TYPE 0x3097
/* BindAPI/QueryAPI targets */
#define EGL_OPENGL_ES_API 0x30A0
#define EGL_OPENVG_API 0x30A1
/* GetCurrentSurface targets */
#define EGL_DRAW 0x3059
#define EGL_READ 0x305A
/* WaitNative engines */
#define EGL_CORE_NATIVE_ENGINE 0x305B
/* EGL extensions must request enum blocks from the OpenGL ARB
* Secretary, who maintains the EGL enumerant registry.
*/
/* EGL Functions */
EGLint eglGetError();
EGLDisplay eglGetDisplay(NativeDisplayType display_id);
EGLBoolean eglInitialize(EGLDisplay dpy, EGLint *major, EGLint *minor);
EGLBoolean eglTerminate(EGLDisplay dpy);
const char *eglQueryString(EGLDisplay dpy, EGLint name);
EGLBoolean eglGetConfigs(EGLDisplay dpy, EGLConfig *configs,
EGLint config_size, EGLint *num_config);
EGLBoolean eglChooseConfig(EGLDisplay dpy, const EGLint *attrib_list,
EGLConfig *configs, EGLint config_size,
EGLint *num_config);
EGLBoolean eglGetConfigAttrib(EGLDisplay dpy, EGLConfig config,
EGLint attribute, EGLint *value);
EGLSurface eglCreateWindowSurface(EGLDisplay dpy, EGLConfig config,
NativeWindowType win,
const EGLint *attrib_list);
EGLSurface eglCreatePbufferSurface(EGLDisplay dpy, EGLConfig config,
const EGLint *attrib_list);
EGLSurface eglCreatePixmapSurface(EGLDisplay dpy, EGLConfig config,
NativePixmapType pixmap,
const EGLint *attrib_list);
EGLBoolean eglDestroySurface(EGLDisplay dpy, EGLSurface surface);
EGLBoolean eglQuerySurface(EGLDisplay dpy, EGLSurface surface,
EGLint attribute, EGLint *value);
EGLBoolean eglBindAPI(EGLenum api);
EGLenum eglQueryAPI(void);
EGLBoolean eglWaitClient(void);
EGLBoolean eglReleaseThread(void);
EGLSurface eglCreatePbufferFromClientBuffer(
EGLDisplay dpy, EGLenum buftype, EGLClientBuffer buffer,
EGLConfig config, const EGLint *attrib_list);
EGLBoolean eglSurfaceAttrib(EGLDisplay dpy, EGLSurface surface,
EGLint attribute, EGLint value);
EGLBoolean eglBindTexImage(EGLDisplay dpy, EGLSurface surface, EGLint buffer);
EGLBoolean eglReleaseTexImage(EGLDisplay dpy, EGLSurface surface, EGLint buffer);
EGLBoolean eglSwapInterval(EGLDisplay dpy, EGLint interval);
EGLContext eglCreateContext(EGLDisplay dpy, EGLConfig config,
EGLContext share_context,
const EGLint *attrib_list);
EGLBoolean eglDestroyContext(EGLDisplay dpy, EGLContext ctx);
EGLBoolean eglMakeCurrent(EGLDisplay dpy, EGLSurface draw,
EGLSurface read, EGLContext ctx);
EGLContext eglGetCurrentContext(void);
EGLSurface eglGetCurrentSurface(EGLint readdraw);
EGLDisplay eglGetCurrentDisplay(void);
EGLBoolean eglQueryContext(EGLDisplay dpy, EGLContext ctx,
EGLint attribute, EGLint *value);
EGLBoolean eglWaitGL(void);
EGLBoolean eglWaitNative(EGLint engine);
EGLBoolean eglSwapBuffers(EGLDisplay dpy, EGLSurface surface);
EGLBoolean eglCopyBuffers(EGLDisplay dpy, EGLSurface surface,
NativePixmapType target);
void (*eglGetProcAddress(const char *procname))();
#endif /* __egl_h_ */
api/EGL/egl.h
+342
View File
@@ -0,0 +1,342 @@
#ifndef __egl_h_
#define __egl_h_ 1
#ifdef __cplusplus
extern "C" {
#endif
/*
** Copyright 2013-2020 The Khronos Group Inc.
** SPDX-License-Identifier: Apache-2.0
**
** This header is generated from the Khronos EGL XML API Registry.
** The current version of the Registry, generator scripts
** used to make the header, and the header can be found at
** http://www.khronos.org/registry/egl
**
** Khronos $Git commit SHA1: b35e89ca9a $ on $Git commit date: 2021-09-01 09:34:00 +0530 $
*/
#include <EGL/eglplatform.h>
#ifndef EGL_EGL_PROTOTYPES
#define EGL_EGL_PROTOTYPES 1
#endif
/* Generated on date 20210901 */
/* Generated C header for:
* API: egl
* Versions considered: .*
* Versions emitted: .*
* Default extensions included: None
* Additional extensions included: _nomatch_^
* Extensions removed: _nomatch_^
*/
#ifndef EGL_VERSION_1_0
#define EGL_VERSION_1_0 1
typedef unsigned int EGLBoolean;
typedef void *EGLDisplay;
#include <KHR/khrplatform.h>
#include <EGL/eglplatform.h>
typedef void *EGLConfig;
typedef void *EGLSurface;
typedef void *EGLContext;
typedef void (*__eglMustCastToProperFunctionPointerType)(void);
#define EGL_ALPHA_SIZE 0x3021
#define EGL_BAD_ACCESS 0x3002
#define EGL_BAD_ALLOC 0x3003
#define EGL_BAD_ATTRIBUTE 0x3004
#define EGL_BAD_CONFIG 0x3005
#define EGL_BAD_CONTEXT 0x3006
#define EGL_BAD_CURRENT_SURFACE 0x3007
#define EGL_BAD_DISPLAY 0x3008
#define EGL_BAD_MATCH 0x3009
#define EGL_BAD_NATIVE_PIXMAP 0x300A
#define EGL_BAD_NATIVE_WINDOW 0x300B
#define EGL_BAD_PARAMETER 0x300C
#define EGL_BAD_SURFACE 0x300D
#define EGL_BLUE_SIZE 0x3022
#define EGL_BUFFER_SIZE 0x3020
#define EGL_CONFIG_CAVEAT 0x3027
#define EGL_CONFIG_ID 0x3028
#define EGL_CORE_NATIVE_ENGINE 0x305B
#define EGL_DEPTH_SIZE 0x3025
#define EGL_DONT_CARE EGL_CAST(EGLint,-1)
#define EGL_DRAW 0x3059
#define EGL_EXTENSIONS 0x3055
#define EGL_FALSE 0
#define EGL_GREEN_SIZE 0x3023
#define EGL_HEIGHT 0x3056
#define EGL_LARGEST_PBUFFER 0x3058
#define EGL_LEVEL 0x3029
#define EGL_MAX_PBUFFER_HEIGHT 0x302A
#define EGL_MAX_PBUFFER_PIXELS 0x302B
#define EGL_MAX_PBUFFER_WIDTH 0x302C
#define EGL_NATIVE_RENDERABLE 0x302D
#define EGL_NATIVE_VISUAL_ID 0x302E
#define EGL_NATIVE_VISUAL_TYPE 0x302F
#define EGL_NONE 0x3038
#define EGL_NON_CONFORMANT_CONFIG 0x3051
#define EGL_NOT_INITIALIZED 0x3001
#define EGL_NO_CONTEXT EGL_CAST(EGLContext,0)
#define EGL_NO_DISPLAY EGL_CAST(EGLDisplay,0)
#define EGL_NO_SURFACE EGL_CAST(EGLSurface,0)
#define EGL_PBUFFER_BIT 0x0001
#define EGL_PIXMAP_BIT 0x0002
#define EGL_READ 0x305A
#define EGL_RED_SIZE 0x3024
#define EGL_SAMPLES 0x3031
#define EGL_SAMPLE_BUFFERS 0x3032
#define EGL_SLOW_CONFIG 0x3050
#define EGL_STENCIL_SIZE 0x3026
#define EGL_SUCCESS 0x3000
#define EGL_SURFACE_TYPE 0x3033
#define EGL_TRANSPARENT_BLUE_VALUE 0x3035
#define EGL_TRANSPARENT_GREEN_VALUE 0x3036
#define EGL_TRANSPARENT_RED_VALUE 0x3037
#define EGL_TRANSPARENT_RGB 0x3052
#define EGL_TRANSPARENT_TYPE 0x3034
#define EGL_TRUE 1
#define EGL_VENDOR 0x3053
#define EGL_VERSION 0x3054
#define EGL_WIDTH 0x3057
#define EGL_WINDOW_BIT 0x0004
typedef EGLBoolean (EGLAPIENTRYP PFNEGLCHOOSECONFIGPROC) (EGLDisplay dpy, const EGLint *attrib_list, EGLConfig *configs, EGLint config_size, EGLint *num_config);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLCOPYBUFFERSPROC) (EGLDisplay dpy, EGLSurface surface, EGLNativePixmapType target);
typedef EGLContext (EGLAPIENTRYP PFNEGLCREATECONTEXTPROC) (EGLDisplay dpy, EGLConfig config, EGLContext share_context, const EGLint *attrib_list);
typedef EGLSurface (EGLAPIENTRYP PFNEGLCREATEPBUFFERSURFACEPROC) (EGLDisplay dpy, EGLConfig config, const EGLint *attrib_list);
typedef EGLSurface (EGLAPIENTRYP PFNEGLCREATEPIXMAPSURFACEPROC) (EGLDisplay dpy, EGLConfig config, EGLNativePixmapType pixmap, const EGLint *attrib_list);
typedef EGLSurface (EGLAPIENTRYP PFNEGLCREATEWINDOWSURFACEPROC) (EGLDisplay dpy, EGLConfig config, EGLNativeWindowType win, const EGLint *attrib_list);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLDESTROYCONTEXTPROC) (EGLDisplay dpy, EGLContext ctx);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLDESTROYSURFACEPROC) (EGLDisplay dpy, EGLSurface surface);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLGETCONFIGATTRIBPROC) (EGLDisplay dpy, EGLConfig config, EGLint attribute, EGLint *value);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLGETCONFIGSPROC) (EGLDisplay dpy, EGLConfig *configs, EGLint config_size, EGLint *num_config);
typedef EGLDisplay (EGLAPIENTRYP PFNEGLGETCURRENTDISPLAYPROC) (void);
typedef EGLSurface (EGLAPIENTRYP PFNEGLGETCURRENTSURFACEPROC) (EGLint readdraw);
typedef EGLDisplay (EGLAPIENTRYP PFNEGLGETDISPLAYPROC) (EGLNativeDisplayType display_id);
typedef EGLint (EGLAPIENTRYP PFNEGLGETERRORPROC) (void);
typedef __eglMustCastToProperFunctionPointerType (EGLAPIENTRYP PFNEGLGETPROCADDRESSPROC) (const char *procname);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLINITIALIZEPROC) (EGLDisplay dpy, EGLint *major, EGLint *minor);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLMAKECURRENTPROC) (EGLDisplay dpy, EGLSurface draw, EGLSurface read, EGLContext ctx);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLQUERYCONTEXTPROC) (EGLDisplay dpy, EGLContext ctx, EGLint attribute, EGLint *value);
typedef const char *(EGLAPIENTRYP PFNEGLQUERYSTRINGPROC) (EGLDisplay dpy, EGLint name);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLQUERYSURFACEPROC) (EGLDisplay dpy, EGLSurface surface, EGLint attribute, EGLint *value);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLSWAPBUFFERSPROC) (EGLDisplay dpy, EGLSurface surface);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLTERMINATEPROC) (EGLDisplay dpy);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLWAITGLPROC) (void);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLWAITNATIVEPROC) (EGLint engine);
#if EGL_EGL_PROTOTYPES
EGLAPI EGLBoolean EGLAPIENTRY eglChooseConfig (EGLDisplay dpy, const EGLint *attrib_list, EGLConfig *configs, EGLint config_size, EGLint *num_config);
EGLAPI EGLBoolean EGLAPIENTRY eglCopyBuffers (EGLDisplay dpy, EGLSurface surface, EGLNativePixmapType target);
EGLAPI EGLContext EGLAPIENTRY eglCreateContext (EGLDisplay dpy, EGLConfig config, EGLContext share_context, const EGLint *attrib_list);
EGLAPI EGLSurface EGLAPIENTRY eglCreatePbufferSurface (EGLDisplay dpy, EGLConfig config, const EGLint *attrib_list);
EGLAPI EGLSurface EGLAPIENTRY eglCreatePixmapSurface (EGLDisplay dpy, EGLConfig config, EGLNativePixmapType pixmap, const EGLint *attrib_list);
EGLAPI EGLSurface EGLAPIENTRY eglCreateWindowSurface (EGLDisplay dpy, EGLConfig config, EGLNativeWindowType win, const EGLint *attrib_list);
EGLAPI EGLBoolean EGLAPIENTRY eglDestroyContext (EGLDisplay dpy, EGLContext ctx);
EGLAPI EGLBoolean EGLAPIENTRY eglDestroySurface (EGLDisplay dpy, EGLSurface surface);
EGLAPI EGLBoolean EGLAPIENTRY eglGetConfigAttrib (EGLDisplay dpy, EGLConfig config, EGLint attribute, EGLint *value);
EGLAPI EGLBoolean EGLAPIENTRY eglGetConfigs (EGLDisplay dpy, EGLConfig *configs, EGLint config_size, EGLint *num_config);
EGLAPI EGLDisplay EGLAPIENTRY eglGetCurrentDisplay (void);
EGLAPI EGLSurface EGLAPIENTRY eglGetCurrentSurface (EGLint readdraw);
EGLAPI EGLDisplay EGLAPIENTRY eglGetDisplay (EGLNativeDisplayType display_id);
EGLAPI EGLint EGLAPIENTRY eglGetError (void);
EGLAPI __eglMustCastToProperFunctionPointerType EGLAPIENTRY eglGetProcAddress (const char *procname);
EGLAPI EGLBoolean EGLAPIENTRY eglInitialize (EGLDisplay dpy, EGLint *major, EGLint *minor);
EGLAPI EGLBoolean EGLAPIENTRY eglMakeCurrent (EGLDisplay dpy, EGLSurface draw, EGLSurface read, EGLContext ctx);
EGLAPI EGLBoolean EGLAPIENTRY eglQueryContext (EGLDisplay dpy, EGLContext ctx, EGLint attribute, EGLint *value);
EGLAPI const char *EGLAPIENTRY eglQueryString (EGLDisplay dpy, EGLint name);
EGLAPI EGLBoolean EGLAPIENTRY eglQuerySurface (EGLDisplay dpy, EGLSurface surface, EGLint attribute, EGLint *value);
EGLAPI EGLBoolean EGLAPIENTRY eglSwapBuffers (EGLDisplay dpy, EGLSurface surface);
EGLAPI EGLBoolean EGLAPIENTRY eglTerminate (EGLDisplay dpy);
EGLAPI EGLBoolean EGLAPIENTRY eglWaitGL (void);
EGLAPI EGLBoolean EGLAPIENTRY eglWaitNative (EGLint engine);
#endif
#endif /* EGL_VERSION_1_0 */
#ifndef EGL_VERSION_1_1
#define EGL_VERSION_1_1 1
#define EGL_BACK_BUFFER 0x3084
#define EGL_BIND_TO_TEXTURE_RGB 0x3039
#define EGL_BIND_TO_TEXTURE_RGBA 0x303A
#define EGL_CONTEXT_LOST 0x300E
#define EGL_MIN_SWAP_INTERVAL 0x303B
#define EGL_MAX_SWAP_INTERVAL 0x303C
#define EGL_MIPMAP_TEXTURE 0x3082
#define EGL_MIPMAP_LEVEL 0x3083
#define EGL_NO_TEXTURE 0x305C
#define EGL_TEXTURE_2D 0x305F
#define EGL_TEXTURE_FORMAT 0x3080
#define EGL_TEXTURE_RGB 0x305D
#define EGL_TEXTURE_RGBA 0x305E
#define EGL_TEXTURE_TARGET 0x3081
typedef EGLBoolean (EGLAPIENTRYP PFNEGLBINDTEXIMAGEPROC) (EGLDisplay dpy, EGLSurface surface, EGLint buffer);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLRELEASETEXIMAGEPROC) (EGLDisplay dpy, EGLSurface surface, EGLint buffer);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLSURFACEATTRIBPROC) (EGLDisplay dpy, EGLSurface surface, EGLint attribute, EGLint value);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLSWAPINTERVALPROC) (EGLDisplay dpy, EGLint interval);
#if EGL_EGL_PROTOTYPES
EGLAPI EGLBoolean EGLAPIENTRY eglBindTexImage (EGLDisplay dpy, EGLSurface surface, EGLint buffer);
EGLAPI EGLBoolean EGLAPIENTRY eglReleaseTexImage (EGLDisplay dpy, EGLSurface surface, EGLint buffer);
EGLAPI EGLBoolean EGLAPIENTRY eglSurfaceAttrib (EGLDisplay dpy, EGLSurface surface, EGLint attribute, EGLint value);
EGLAPI EGLBoolean EGLAPIENTRY eglSwapInterval (EGLDisplay dpy, EGLint interval);
#endif
#endif /* EGL_VERSION_1_1 */
#ifndef EGL_VERSION_1_2
#define EGL_VERSION_1_2 1
typedef unsigned int EGLenum;
typedef void *EGLClientBuffer;
#define EGL_ALPHA_FORMAT 0x3088
#define EGL_ALPHA_FORMAT_NONPRE 0x308B
#define EGL_ALPHA_FORMAT_PRE 0x308C
#define EGL_ALPHA_MASK_SIZE 0x303E
#define EGL_BUFFER_PRESERVED 0x3094
#define EGL_BUFFER_DESTROYED 0x3095
#define EGL_CLIENT_APIS 0x308D
#define EGL_COLORSPACE 0x3087
#define EGL_COLORSPACE_sRGB 0x3089
#define EGL_COLORSPACE_LINEAR 0x308A
#define EGL_COLOR_BUFFER_TYPE 0x303F
#define EGL_CONTEXT_CLIENT_TYPE 0x3097
#define EGL_DISPLAY_SCALING 10000
#define EGL_HORIZONTAL_RESOLUTION 0x3090
#define EGL_LUMINANCE_BUFFER 0x308F
#define EGL_LUMINANCE_SIZE 0x303D
#define EGL_OPENGL_ES_BIT 0x0001
#define EGL_OPENVG_BIT 0x0002
#define EGL_OPENGL_ES_API 0x30A0
#define EGL_OPENVG_API 0x30A1
#define EGL_OPENVG_IMAGE 0x3096
#define EGL_PIXEL_ASPECT_RATIO 0x3092
#define EGL_RENDERABLE_TYPE 0x3040
#define EGL_RENDER_BUFFER 0x3086
#define EGL_RGB_BUFFER 0x308E
#define EGL_SINGLE_BUFFER 0x3085
#define EGL_SWAP_BEHAVIOR 0x3093
#define EGL_UNKNOWN EGL_CAST(EGLint,-1)
#define EGL_VERTICAL_RESOLUTION 0x3091
typedef EGLBoolean (EGLAPIENTRYP PFNEGLBINDAPIPROC) (EGLenum api);
typedef EGLenum (EGLAPIENTRYP PFNEGLQUERYAPIPROC) (void);
typedef EGLSurface (EGLAPIENTRYP PFNEGLCREATEPBUFFERFROMCLIENTBUFFERPROC) (EGLDisplay dpy, EGLenum buftype, EGLClientBuffer buffer, EGLConfig config, const EGLint *attrib_list);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLRELEASETHREADPROC) (void);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLWAITCLIENTPROC) (void);
#if EGL_EGL_PROTOTYPES
EGLAPI EGLBoolean EGLAPIENTRY eglBindAPI (EGLenum api);
EGLAPI EGLenum EGLAPIENTRY eglQueryAPI (void);
EGLAPI EGLSurface EGLAPIENTRY eglCreatePbufferFromClientBuffer (EGLDisplay dpy, EGLenum buftype, EGLClientBuffer buffer, EGLConfig config, const EGLint *attrib_list);
EGLAPI EGLBoolean EGLAPIENTRY eglReleaseThread (void);
EGLAPI EGLBoolean EGLAPIENTRY eglWaitClient (void);
#endif
#endif /* EGL_VERSION_1_2 */
#ifndef EGL_VERSION_1_3
#define EGL_VERSION_1_3 1
#define EGL_CONFORMANT 0x3042
#define EGL_CONTEXT_CLIENT_VERSION 0x3098
#define EGL_MATCH_NATIVE_PIXMAP 0x3041
#define EGL_OPENGL_ES2_BIT 0x0004
#define EGL_VG_ALPHA_FORMAT 0x3088
#define EGL_VG_ALPHA_FORMAT_NONPRE 0x308B
#define EGL_VG_ALPHA_FORMAT_PRE 0x308C
#define EGL_VG_ALPHA_FORMAT_PRE_BIT 0x0040
#define EGL_VG_COLORSPACE 0x3087
#define EGL_VG_COLORSPACE_sRGB 0x3089
#define EGL_VG_COLORSPACE_LINEAR 0x308A
#define EGL_VG_COLORSPACE_LINEAR_BIT 0x0020
#endif /* EGL_VERSION_1_3 */
#ifndef EGL_VERSION_1_4
#define EGL_VERSION_1_4 1
#define EGL_DEFAULT_DISPLAY EGL_CAST(EGLNativeDisplayType,0)
#define EGL_MULTISAMPLE_RESOLVE_BOX_BIT 0x0200
#define EGL_MULTISAMPLE_RESOLVE 0x3099
#define EGL_MULTISAMPLE_RESOLVE_DEFAULT 0x309A
#define EGL_MULTISAMPLE_RESOLVE_BOX 0x309B
#define EGL_OPENGL_API 0x30A2
#define EGL_OPENGL_BIT 0x0008
#define EGL_SWAP_BEHAVIOR_PRESERVED_BIT 0x0400
typedef EGLContext (EGLAPIENTRYP PFNEGLGETCURRENTCONTEXTPROC) (void);
#if EGL_EGL_PROTOTYPES
EGLAPI EGLContext EGLAPIENTRY eglGetCurrentContext (void);
#endif
#endif /* EGL_VERSION_1_4 */
#ifndef EGL_VERSION_1_5
#define EGL_VERSION_1_5 1
typedef void *EGLSync;
typedef intptr_t EGLAttrib;
typedef khronos_utime_nanoseconds_t EGLTime;
typedef void *EGLImage;
#define EGL_CONTEXT_MAJOR_VERSION 0x3098
#define EGL_CONTEXT_MINOR_VERSION 0x30FB
#define EGL_CONTEXT_OPENGL_PROFILE_MASK 0x30FD
#define EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY 0x31BD
#define EGL_NO_RESET_NOTIFICATION 0x31BE
#define EGL_LOSE_CONTEXT_ON_RESET 0x31BF
#define EGL_CONTEXT_OPENGL_CORE_PROFILE_BIT 0x00000001
#define EGL_CONTEXT_OPENGL_COMPATIBILITY_PROFILE_BIT 0x00000002
#define EGL_CONTEXT_OPENGL_DEBUG 0x31B0
#define EGL_CONTEXT_OPENGL_FORWARD_COMPATIBLE 0x31B1
#define EGL_CONTEXT_OPENGL_ROBUST_ACCESS 0x31B2
#define EGL_OPENGL_ES3_BIT 0x00000040
#define EGL_CL_EVENT_HANDLE 0x309C
#define EGL_SYNC_CL_EVENT 0x30FE
#define EGL_SYNC_CL_EVENT_COMPLETE 0x30FF
#define EGL_SYNC_PRIOR_COMMANDS_COMPLETE 0x30F0
#define EGL_SYNC_TYPE 0x30F7
#define EGL_SYNC_STATUS 0x30F1
#define EGL_SYNC_CONDITION 0x30F8
#define EGL_SIGNALED 0x30F2
#define EGL_UNSIGNALED 0x30F3
#define EGL_SYNC_FLUSH_COMMANDS_BIT 0x0001
#define EGL_FOREVER 0xFFFFFFFFFFFFFFFFull
#define EGL_TIMEOUT_EXPIRED 0x30F5
#define EGL_CONDITION_SATISFIED 0x30F6
#define EGL_NO_SYNC EGL_CAST(EGLSync,0)
#define EGL_SYNC_FENCE 0x30F9
#define EGL_GL_COLORSPACE 0x309D
#define EGL_GL_COLORSPACE_SRGB 0x3089
#define EGL_GL_COLORSPACE_LINEAR 0x308A
#define EGL_GL_RENDERBUFFER 0x30B9
#define EGL_GL_TEXTURE_2D 0x30B1
#define EGL_GL_TEXTURE_LEVEL 0x30BC
#define EGL_GL_TEXTURE_3D 0x30B2
#define EGL_GL_TEXTURE_ZOFFSET 0x30BD
#define EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X 0x30B3
#define EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X 0x30B4
#define EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y 0x30B5
#define EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y 0x30B6
#define EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z 0x30B7
#define EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z 0x30B8
#define EGL_IMAGE_PRESERVED 0x30D2
#define EGL_NO_IMAGE EGL_CAST(EGLImage,0)
typedef EGLSync (EGLAPIENTRYP PFNEGLCREATESYNCPROC) (EGLDisplay dpy, EGLenum type, const EGLAttrib *attrib_list);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLDESTROYSYNCPROC) (EGLDisplay dpy, EGLSync sync);
typedef EGLint (EGLAPIENTRYP PFNEGLCLIENTWAITSYNCPROC) (EGLDisplay dpy, EGLSync sync, EGLint flags, EGLTime timeout);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLGETSYNCATTRIBPROC) (EGLDisplay dpy, EGLSync sync, EGLint attribute, EGLAttrib *value);
typedef EGLImage (EGLAPIENTRYP PFNEGLCREATEIMAGEPROC) (EGLDisplay dpy, EGLContext ctx, EGLenum target, EGLClientBuffer buffer, const EGLAttrib *attrib_list);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLDESTROYIMAGEPROC) (EGLDisplay dpy, EGLImage image);
typedef EGLDisplay (EGLAPIENTRYP PFNEGLGETPLATFORMDISPLAYPROC) (EGLenum platform, void *native_display, const EGLAttrib *attrib_list);
typedef EGLSurface (EGLAPIENTRYP PFNEGLCREATEPLATFORMWINDOWSURFACEPROC) (EGLDisplay dpy, EGLConfig config, void *native_window, const EGLAttrib *attrib_list);
typedef EGLSurface (EGLAPIENTRYP PFNEGLCREATEPLATFORMPIXMAPSURFACEPROC) (EGLDisplay dpy, EGLConfig config, void *native_pixmap, const EGLAttrib *attrib_list);
typedef EGLBoolean (EGLAPIENTRYP PFNEGLWAITSYNCPROC) (EGLDisplay dpy, EGLSync sync, EGLint flags);
#if EGL_EGL_PROTOTYPES
EGLAPI EGLSync EGLAPIENTRY eglCreateSync (EGLDisplay dpy, EGLenum type, const EGLAttrib *attrib_list);
EGLAPI EGLBoolean EGLAPIENTRY eglDestroySync (EGLDisplay dpy, EGLSync sync);
EGLAPI EGLint EGLAPIENTRY eglClientWaitSync (EGLDisplay dpy, EGLSync sync, EGLint flags, EGLTime timeout);
EGLAPI EGLBoolean EGLAPIENTRY eglGetSyncAttrib (EGLDisplay dpy, EGLSync sync, EGLint attribute, EGLAttrib *value);
EGLAPI EGLImage EGLAPIENTRY eglCreateImage (EGLDisplay dpy, EGLContext ctx, EGLenum target, EGLClientBuffer buffer, const EGLAttrib *attrib_list);
EGLAPI EGLBoolean EGLAPIENTRY eglDestroyImage (EGLDisplay dpy, EGLImage image);
EGLAPI EGLDisplay EGLAPIENTRY eglGetPlatformDisplay (EGLenum platform, void *native_display, const EGLAttrib *attrib_list);
EGLAPI EGLSurface EGLAPIENTRY eglCreatePlatformWindowSurface (EGLDisplay dpy, EGLConfig config, void *native_window, const EGLAttrib *attrib_list);
EGLAPI EGLSurface EGLAPIENTRY eglCreatePlatformPixmapSurface (EGLDisplay dpy, EGLConfig config, void *native_pixmap, const EGLAttrib *attrib_list);
EGLAPI EGLBoolean EGLAPIENTRY eglWaitSync (EGLDisplay dpy, EGLSync sync, EGLint flags);
#endif
#endif /* EGL_VERSION_1_5 */
#ifdef __cplusplus
}
#endif
#endif
api/EGL/eglext.h
+1454
View File
File diff suppressed because it is too large Load Diff
api/EGL/eglplatform.h
+169
View File
@@ -0,0 +1,169 @@
#ifndef __eglplatform_h_
#define __eglplatform_h_
/*
** Copyright 2007-2020 The Khronos Group Inc.
** SPDX-License-Identifier: Apache-2.0
*/
/* Platform-specific types and definitions for egl.h
*
* Adopters may modify khrplatform.h and this file to suit their platform.
* You are encouraged to submit all modifications to the Khronos group so that
* they can be included in future versions of this file. Please submit changes
* by filing an issue or pull request on the public Khronos EGL Registry, at
* https://www.github.com/KhronosGroup/EGL-Registry/
*/
#include <KHR/khrplatform.h>
/* Macros used in EGL function prototype declarations.
*
* EGL functions should be prototyped as:
*
* EGLAPI return-type EGLAPIENTRY eglFunction(arguments);
* typedef return-type (EXPAPIENTRYP PFNEGLFUNCTIONPROC) (arguments);
*
* KHRONOS_APICALL and KHRONOS_APIENTRY are defined in KHR/khrplatform.h
*/
#ifndef EGLAPI
#define EGLAPI KHRONOS_APICALL
#endif
#ifndef EGLAPIENTRY
#define EGLAPIENTRY KHRONOS_APIENTRY
#endif
#define EGLAPIENTRYP EGLAPIENTRY*
/* The types NativeDisplayType, NativeWindowType, and NativePixmapType
* are aliases of window-system-dependent types, such as X Display * or
* Windows Device Context. They must be defined in platform-specific
* code below. The EGL-prefixed versions of Native*Type are the same
* types, renamed in EGL 1.3 so all types in the API start with "EGL".
*
* Khronos STRONGLY RECOMMENDS that you use the default definitions
* provided below, since these changes affect both binary and source
* portability of applications using EGL running on different EGL
* implementations.
*/
#if defined(EGL_NO_PLATFORM_SPECIFIC_TYPES)
typedef void *EGLNativeDisplayType;
typedef void *EGLNativePixmapType;
typedef void *EGLNativeWindowType;
#elif defined(_WIN32) || defined(__VC32__) && !defined(__CYGWIN__) && !defined(__SCITECH_SNAP__) /* Win32 and WinCE */
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN 1
#endif
#include <windows.h>
typedef HDC EGLNativeDisplayType;
typedef HBITMAP EGLNativePixmapType;
typedef HWND EGLNativeWindowType;
#elif defined(__EMSCRIPTEN__)
typedef int EGLNativeDisplayType;
typedef int EGLNativePixmapType;
typedef int EGLNativeWindowType;
#elif defined(__WINSCW__) || defined(__SYMBIAN32__) /* Symbian */
typedef int EGLNativeDisplayType;
typedef void *EGLNativePixmapType;
typedef void *EGLNativeWindowType;
#elif defined(WL_EGL_PLATFORM)
typedef struct wl_display *EGLNativeDisplayType;
typedef struct wl_egl_pixmap *EGLNativePixmapType;
typedef struct wl_egl_window *EGLNativeWindowType;
#elif defined(__GBM__)
typedef struct gbm_device *EGLNativeDisplayType;
typedef struct gbm_bo *EGLNativePixmapType;
typedef void *EGLNativeWindowType;
#elif defined(__ANDROID__) || defined(ANDROID)
struct ANativeWindow;
struct egl_native_pixmap_t;
typedef void* EGLNativeDisplayType;
typedef struct egl_native_pixmap_t* EGLNativePixmapType;
typedef struct ANativeWindow* EGLNativeWindowType;
#elif defined(USE_OZONE)
typedef intptr_t EGLNativeDisplayType;
typedef intptr_t EGLNativePixmapType;
typedef intptr_t EGLNativeWindowType;
#elif defined(USE_X11)
/* X11 (tentative) */
#include <X11/Xlib.h>
#include <X11/Xutil.h>
typedef Display *EGLNativeDisplayType;
typedef Pixmap EGLNativePixmapType;
typedef Window EGLNativeWindowType;
#elif defined(__unix__)
typedef void *EGLNativeDisplayType;
typedef khronos_uintptr_t EGLNativePixmapType;
typedef khronos_uintptr_t EGLNativeWindowType;
#elif defined(__APPLE__)
typedef int EGLNativeDisplayType;
typedef void *EGLNativePixmapType;
typedef void *EGLNativeWindowType;
#elif defined(__HAIKU__)
#include <kernel/image.h>
typedef void *EGLNativeDisplayType;
typedef khronos_uintptr_t EGLNativePixmapType;
typedef khronos_uintptr_t EGLNativeWindowType;
#elif defined(__Fuchsia__)
typedef void *EGLNativeDisplayType;
typedef khronos_uintptr_t EGLNativePixmapType;
typedef khronos_uintptr_t EGLNativeWindowType;
#else
#error "Platform not recognized"
#endif
/* EGL 1.2 types, renamed for consistency in EGL 1.3 */
typedef EGLNativeDisplayType NativeDisplayType;
typedef EGLNativePixmapType NativePixmapType;
typedef EGLNativeWindowType NativeWindowType;
/* Define EGLint. This must be a signed integral type large enough to contain
* all legal attribute names and values passed into and out of EGL, whether
* their type is boolean, bitmask, enumerant (symbolic constant), integer,
* handle, or other. While in general a 32-bit integer will suffice, if
* handles are 64 bit types, then EGLint should be defined as a signed 64-bit
* integer type.
*/
typedef khronos_int32_t EGLint;
/* C++ / C typecast macros for special EGL handle values */
#if defined(__cplusplus)
#define EGL_CAST(type, value) (static_cast<type>(value))
#else
#define EGL_CAST(type, value) ((type) (value))
#endif
#endif /* __eglplatform_h */
api/KHR/khrplatform.h
+290
View File
@@ -0,0 +1,290 @@
#ifndef __khrplatform_h_
#define __khrplatform_h_
/*
** Copyright (c) 2008-2018 The Khronos Group Inc.
**
** Permission is hereby granted, free of charge, to any person obtaining a
** copy of this software and/or associated documentation files (the
** "Materials"), to deal in the Materials without restriction, including
** without limitation the rights to use, copy, modify, merge, publish,
** distribute, sublicense, and/or sell copies of the Materials, and to
** permit persons to whom the Materials are furnished to do so, subject to
** the following conditions:
**
** The above copyright notice and this permission notice shall be included
** in all copies or substantial portions of the Materials.
**
** THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
** EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
** MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
** IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
** CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
** TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
** MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
*/
/* Khronos platform-specific types and definitions.
*
* The master copy of khrplatform.h is maintained in the Khronos EGL
* Registry repository at https://github.com/KhronosGroup/EGL-Registry
* The last semantic modification to khrplatform.h was at commit ID:
* 67a3e0864c2d75ea5287b9f3d2eb74a745936692
*
* Adopters may modify this file to suit their platform. Adopters are
* encouraged to submit platform specific modifications to the Khronos
* group so that they can be included in future versions of this file.
* Please submit changes by filing pull requests or issues on
* the EGL Registry repository linked above.
*
*
* See the Implementer's Guidelines for information about where this file
* should be located on your system and for more details of its use:
* http://www.khronos.org/registry/implementers_guide.pdf
*
* This file should be included as
* #include <KHR/khrplatform.h>
* by Khronos client API header files that use its types and defines.
*
* The types in khrplatform.h should only be used to define API-specific types.
*
* Types defined in khrplatform.h:
* khronos_int8_t signed 8 bit
* khronos_uint8_t unsigned 8 bit
* khronos_int16_t signed 16 bit
* khronos_uint16_t unsigned 16 bit
* khronos_int32_t signed 32 bit
* khronos_uint32_t unsigned 32 bit
* khronos_int64_t signed 64 bit
* khronos_uint64_t unsigned 64 bit
* khronos_intptr_t signed same number of bits as a pointer
* khronos_uintptr_t unsigned same number of bits as a pointer
* khronos_ssize_t signed size
* khronos_usize_t unsigned size
* khronos_float_t signed 32 bit floating point
* khronos_time_ns_t unsigned 64 bit time in nanoseconds
* khronos_utime_nanoseconds_t unsigned time interval or absolute time in
* nanoseconds
* khronos_stime_nanoseconds_t signed time interval in nanoseconds
* khronos_boolean_enum_t enumerated boolean type. This should
* only be used as a base type when a client API's boolean type is
* an enum. Client APIs which use an integer or other type for
* booleans cannot use this as the base type for their boolean.
*
* Tokens defined in khrplatform.h:
*
* KHRONOS_FALSE, KHRONOS_TRUE Enumerated boolean false/true values.
*
* KHRONOS_SUPPORT_INT64 is 1 if 64 bit integers are supported; otherwise 0.
* KHRONOS_SUPPORT_FLOAT is 1 if floats are supported; otherwise 0.
*
* Calling convention macros defined in this file:
* KHRONOS_APICALL
* KHRONOS_APIENTRY
* KHRONOS_APIATTRIBUTES
*
* These may be used in function prototypes as:
*
* KHRONOS_APICALL void KHRONOS_APIENTRY funcname(
* int arg1,
* int arg2) KHRONOS_APIATTRIBUTES;
*/
#if defined(__SCITECH_SNAP__) && !defined(KHRONOS_STATIC)
# define KHRONOS_STATIC 1
#endif
/*-------------------------------------------------------------------------
* Definition of KHRONOS_APICALL
*-------------------------------------------------------------------------
* This precedes the return type of the function in the function prototype.
*/
#if defined(KHRONOS_STATIC)
/* If the preprocessor constant KHRONOS_STATIC is defined, make the
* header compatible with static linking. */
# define KHRONOS_APICALL
#elif defined(_WIN32)
# define KHRONOS_APICALL __declspec(dllimport)
#elif defined (__SYMBIAN32__)
# define KHRONOS_APICALL IMPORT_C
#elif defined(__ANDROID__)
# define KHRONOS_APICALL __attribute__((visibility("default")))
#else
# define KHRONOS_APICALL
#endif
/*-------------------------------------------------------------------------
* Definition of KHRONOS_APIENTRY
*-------------------------------------------------------------------------
* This follows the return type of the function and precedes the function
* name in the function prototype.
*/
#if defined(_WIN32) && !defined(_WIN32_WCE) && !defined(__SCITECH_SNAP__)
/* Win32 but not WinCE */
# define KHRONOS_APIENTRY __stdcall
#else
# define KHRONOS_APIENTRY
#endif
/*-------------------------------------------------------------------------
* Definition of KHRONOS_APIATTRIBUTES
*-------------------------------------------------------------------------
* This follows the closing parenthesis of the function prototype arguments.
*/
#if defined (__ARMCC_2__)
#define KHRONOS_APIATTRIBUTES __softfp
#else
#define KHRONOS_APIATTRIBUTES
#endif
/*-------------------------------------------------------------------------
* basic type definitions
*-----------------------------------------------------------------------*/
#if (defined(__STDC_VERSION__) && __STDC_VERSION__ >= 199901L) || defined(__GNUC__) || defined(__SCO__) || defined(__USLC__)
/*
* Using <stdint.h>
*/
#include <stdint.h>
typedef int32_t khronos_int32_t;
typedef uint32_t khronos_uint32_t;
typedef int64_t khronos_int64_t;
typedef uint64_t khronos_uint64_t;
#define KHRONOS_SUPPORT_INT64 1
#define KHRONOS_SUPPORT_FLOAT 1
#elif defined(__VMS ) || defined(__sgi)
/*
* Using <inttypes.h>
*/
#include <inttypes.h>
typedef int32_t khronos_int32_t;
typedef uint32_t khronos_uint32_t;
typedef int64_t khronos_int64_t;
typedef uint64_t khronos_uint64_t;
#define KHRONOS_SUPPORT_INT64 1
#define KHRONOS_SUPPORT_FLOAT 1
#elif defined(_WIN32) && !defined(__SCITECH_SNAP__)
/*
* Win32
*/
typedef __int32 khronos_int32_t;
typedef unsigned __int32 khronos_uint32_t;
typedef __int64 khronos_int64_t;
typedef unsigned __int64 khronos_uint64_t;
#define KHRONOS_SUPPORT_INT64 1
#define KHRONOS_SUPPORT_FLOAT 1
#elif defined(__sun__) || defined(__digital__)
/*
* Sun or Digital
*/
typedef int khronos_int32_t;
typedef unsigned int khronos_uint32_t;
#if defined(__arch64__) || defined(_LP64)
typedef long int khronos_int64_t;
typedef unsigned long int khronos_uint64_t;
#else
typedef long long int khronos_int64_t;
typedef unsigned long long int khronos_uint64_t;
#endif /* __arch64__ */
#define KHRONOS_SUPPORT_INT64 1
#define KHRONOS_SUPPORT_FLOAT 1
#elif 0
/*
* Hypothetical platform with no float or int64 support
*/
typedef int khronos_int32_t;
typedef unsigned int khronos_uint32_t;
#define KHRONOS_SUPPORT_INT64 0
#define KHRONOS_SUPPORT_FLOAT 0
#else
/*
* Generic fallback
*/
#include <stdint.h>
typedef int32_t khronos_int32_t;
typedef uint32_t khronos_uint32_t;
typedef int64_t khronos_int64_t;
typedef uint64_t khronos_uint64_t;
#define KHRONOS_SUPPORT_INT64 1
#define KHRONOS_SUPPORT_FLOAT 1
#endif
/*
* Types that are (so far) the same on all platforms
*/
typedef signed char khronos_int8_t;
typedef unsigned char khronos_uint8_t;
typedef signed short int khronos_int16_t;
typedef unsigned short int khronos_uint16_t;
/*
* Types that differ between LLP64 and LP64 architectures - in LLP64,
* pointers are 64 bits, but 'long' is still 32 bits. Win64 appears
* to be the only LLP64 architecture in current use.
*/
#ifdef _WIN64
typedef signed long long int khronos_intptr_t;
typedef unsigned long long int khronos_uintptr_t;
typedef signed long long int khronos_ssize_t;
typedef unsigned long long int khronos_usize_t;
#else
typedef signed long int khronos_intptr_t;
typedef unsigned long int khronos_uintptr_t;
typedef signed long int khronos_ssize_t;
typedef unsigned long int khronos_usize_t;
#endif
#if KHRONOS_SUPPORT_FLOAT
/*
* Float type
*/
typedef float khronos_float_t;
#endif
#if KHRONOS_SUPPORT_INT64
/* Time types
*
* These types can be used to represent a time interval in nanoseconds or
* an absolute Unadjusted System Time. Unadjusted System Time is the number
* of nanoseconds since some arbitrary system event (e.g. since the last
* time the system booted). The Unadjusted System Time is an unsigned
* 64 bit value that wraps back to 0 every 584 years. Time intervals
* may be either signed or unsigned.
*/
typedef khronos_uint64_t khronos_utime_nanoseconds_t;
typedef khronos_int64_t khronos_stime_nanoseconds_t;
#endif
/*
* Dummy value used to pad enum types to 32 bits.
*/
#ifndef KHRONOS_MAX_ENUM
#define KHRONOS_MAX_ENUM 0x7FFFFFFF
#endif
/*
* Enumerated boolean type
*
* Values other than zero should be considered to be true. Therefore
* comparisons should not be made against KHRONOS_TRUE.
*/
typedef enum {
KHRONOS_FALSE = 0,
KHRONOS_TRUE = 1,
KHRONOS_BOOLEAN_ENUM_FORCE_SIZE = KHRONOS_MAX_ENUM
} khronos_boolean_enum_t;
#endif /* __khrplatform_h_ */
api/Makefile
+43
View File
@@ -0,0 +1,43 @@
# Copyright 2013-2020 The Khronos Group Inc.
# SPDX-License-Identifier: Apache-2.0
# Generated headers
EGLHEADERS = EGL/egl.h EGL/eglext.h
# Generation tools
PYTHON = python3
PYFILES = genheaders.py reg.py
REGISTRY = egl.xml
GENOPTS =
GENHEADERS = $(PYTHON) -B genheaders.py $(GENOPTS) -registry $(REGISTRY)
all: $(EGLHEADERS)
EGL/egl.h: egl.xml $(PYFILES)
$(GENHEADERS) EGL/egl.h
EGL/eglext.h: egl.xml $(PYFILES)
$(GENHEADERS) EGL/eglext.h
# Simple test to make sure generated headers compile
KHR = .
TESTS = Tests
tests: egltest.c $(EGLHEADERS)
$(CC) -c -I$(KHR) egltest.c
$(CXX) -c -I$(KHR) egltest.c
-rm egltest.o
# Verify registries against the schema
validate:
jing -c registry.rnc egl.xml
################################################
# Remove intermediate targets from 'make tests'
clean:
rm -f *.[io] Tests/*.[io] diag.txt dumpReg.txt errwarn.txt
clobber: clean
rm -f $(EGLHEADERS)
api/egl.xml
+3466
View File
File diff suppressed because it is too large Load Diff
api/egltest.c
+8
View File
@@ -0,0 +1,8 @@
/*
* Copyright 2013-2020 The Khronos Group Inc.
* SPDX-License-Identifier: Apache-2.0
*/
/* Simple test that generated EGL headers compile with C and C++ */
#include "EGL/egl.h"
#include "EGL/eglext.h"
api/genheaders.py
Executable
+619
View File
@@ -0,0 +1,619 @@
#!/usr/bin/python -i
#
# Copyright 2013-2020 The Khronos Group Inc.
# SPDX-License-Identifier: Apache-2.0
import sys, time, pdb, string, cProfile
from reg import *
# debug - start header generation in debugger
# dump - dump registry after loading
# profile - enable Python profiling
# protect - whether to use #ifndef protections
# registry <filename> - use specified XML registry instead of gl.xml
# target - string name of target header, or all targets if None
# timeit - time length of registry loading & header generation
# validate - validate return & parameter group tags against <group>
debug = False
dump = False
profile = False
protect = True
target = None
timeit = False
validate= False
# Default input / log files
errFilename = None
diagFilename = 'diag.txt'
regFilename = 'gl.xml'
# Simple timer functions
startTime = None
def startTimer():
global startTime
startTime = time.process_time()
def endTimer(msg):
global startTime
endTime = time.process_time()
if (timeit):
write(msg, endTime - startTime)
startTime = None
# Turn a list of strings into a regexp string matching exactly those strings
def makeREstring(list):
return '^(' + '|'.join(list) + ')$'
# These are "mandatory" OpenGL ES 1 extensions, to
# be included in the core GLES/gl.h header.
es1CoreList = [
'GL_OES_read_format',
'GL_OES_compressed_paletted_texture',
'GL_OES_point_size_array',
'GL_OES_point_sprite'
]
# Descriptive names for various regexp patterns used to select
# versions and extensions
allVersions = allExtensions = '.*'
noVersions = noExtensions = None
gl12andLaterPat = '1\.[2-9]|[234]\.[0-9]'
gles2onlyPat = '2\.[0-9]'
gles2through30Pat = '2\.[0-9]|3\.0'
gles2through31Pat = '2\.[0-9]|3\.[01]'
gles2through32Pat = '2\.[0-9]|3\.[012]'
es1CorePat = makeREstring(es1CoreList)
# Extensions in old glcorearb.h but not yet tagged accordingly in gl.xml
glCoreARBPat = None
glx13andLaterPat = '1\.[3-9]'
# Copyright text prefixing all headers (list of strings).
prefixStrings = [
'/*',
'** Copyright 2013-2020 The Khronos Group Inc.',
'** SPDX-' + 'License-Identifier: Apache-2.0',
'**',
'** This header is generated from the Khronos EGL XML API Registry.',
'** The current version of the Registry, generator scripts',
'** used to make the header, and the header can be found at',
'** http://www.khronos.org/registry/egl',
'**',
'** Khronos $' + 'Revision$ on $' + 'Date$',
'*/',
''
]
# glext.h / glcorearb.h define calling conventions inline (no GL *platform.h)
glExtPlatformStrings = [
'#if defined(_WIN32) && !defined(APIENTRY) && !defined(__CYGWIN__) && !defined(__SCITECH_SNAP__)',
'#ifndef WIN32_LEAN_AND_MEAN',
'#define WIN32_LEAN_AND_MEAN 1',
'#endif',
'#include <windows.h>',
'#endif',
'',
'#ifndef APIENTRY',
'#define APIENTRY',
'#endif',
'#ifndef APIENTRYP',
'#define APIENTRYP APIENTRY *',
'#endif',
'#ifndef GLAPI',
'#define GLAPI extern',
'#endif',
''
]
glCorearbPlatformStrings = glExtPlatformStrings + [
'/* glcorearb.h is for use with OpenGL core profile implementations.',
'** It should should be placed in the same directory as gl.h and',
'** included as <GL/glcorearb.h>.',
'**',
'** glcorearb.h includes only APIs in the latest OpenGL core profile',
'** implementation together with APIs in newer ARB extensions which ',
'** can be supported by the core profile. It does not, and never will',
'** include functionality removed from the core profile, such as',
'** fixed-function vertex and fragment processing.',
'**',
'** Do not #include both <GL/glcorearb.h> and either of <GL/gl.h> or',
'** <GL/glext.h> in the same source file.',
'*/',
''
]
# wglext.h needs Windows include
wglPlatformStrings = [
'#if defined(_WIN32) && !defined(APIENTRY) && !defined(__CYGWIN__) && !defined(__SCITECH_SNAP__)',
'#define WIN32_LEAN_AND_MEAN 1',
'#include <windows.h>',
'#endif',
'',
]
# Different APIs use different *platform.h files to define calling
# conventions
gles1PlatformStrings = [ '#include <GLES/glplatform.h>', '' ]
gles2PlatformStrings = [ '#include <GLES2/gl2platform.h>', '' ]
gles3PlatformStrings = [ '#include <GLES3/gl3platform.h>', '' ]
glsc2PlatformStrings = [ '#include <GLSC2/gl2platform.h>', '' ]
eglPlatformStrings = [ '#include <EGL/eglplatform.h>', '' ]
# GLES headers have a small addition to calling convention headers for function pointer typedefs
apiEntryPrefixStrings = [
'#ifndef GL_APIENTRYP',
'#define GL_APIENTRYP GL_APIENTRY*',
'#endif',
''
]
# GLES 2/3 core API headers use a different protection mechanism for
# prototypes, per bug 14206.
glesProtoPrefixStrings = [
'#ifndef GL_GLES_PROTOTYPES',
'#define GL_GLES_PROTOTYPES 1',
'#endif',
''
]
# EGL headers use a protection mechanism similar to GLES.
eglProtoPrefixStrings = [
'#ifndef EGL_EGL_PROTOTYPES',
'#define EGL_EGL_PROTOTYPES 1',
'#endif',
''
]
# Insert generation date in a comment for headers not having *GLEXT_VERSION macros
genDateCommentString = [
format('/* Generated on date %s */' % time.strftime('%Y%m%d')),
''
]
# GL_GLEXT_VERSION is defined only in glext.h
glextVersionStrings = [
format('#define GL_GLEXT_VERSION %s' % time.strftime('%Y%m%d')),
''
]
# WGL_WGLEXT_VERSION is defined only in wglext.h
wglextVersionStrings = [
format('#define WGL_WGLEXT_VERSION %s' % time.strftime('%Y%m%d')),
''
]
# GLX_GLXEXT_VERSION is defined only in glxext.h
glxextVersionStrings = [
format('#define GLX_GLXEXT_VERSION %s' % time.strftime('%Y%m%d')),
''
]
# EGL_EGLEXT_VERSION is defined only in eglext.h
eglextVersionStrings = [
format('#define EGL_EGLEXT_VERSION %s' % time.strftime('%Y%m%d')),
''
]
# Defaults for generating re-inclusion protection wrappers (or not)
protectFile = protect
protectFeature = protect
protectProto = protect
buildList = [
# GL API 1.2+ + extensions - GL/glext.h
CGeneratorOptions(
filename = 'GL/glext.h',
apiname = 'gl',
profile = 'compatibility',
versions = allVersions,
emitversions = gl12andLaterPat,
defaultExtensions = 'gl', # Default extensions for GL
addExtensions = None,
removeExtensions = None,
prefixText = prefixStrings + glExtPlatformStrings + glextVersionStrings,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = protectProto,
protectProtoStr = 'GL_GLEXT_PROTOTYPES',
apicall = 'GLAPI ',
apientry = 'APIENTRY ',
apientryp = 'APIENTRYP '),
# GL core profile + extensions - GL/glcorearb.h
CGeneratorOptions(
filename = 'GL/glcorearb.h',
apiname = 'gl',
profile = 'core',
versions = allVersions,
emitversions = allVersions,
defaultExtensions = 'glcore', # Default extensions for GL core profile (only)
addExtensions = glCoreARBPat,
removeExtensions = None,
prefixText = prefixStrings + glCorearbPlatformStrings,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = protectProto,
protectProtoStr = 'GL_GLEXT_PROTOTYPES',
apicall = 'GLAPI ',
apientry = 'APIENTRY ',
apientryp = 'APIENTRYP '),
# GLES 1.x API + mandatory extensions - GLES/gl.h (no function pointers)
CGeneratorOptions(
filename = 'GLES/gl.h',
apiname = 'gles1',
profile = 'common',
versions = allVersions,
emitversions = allVersions,
defaultExtensions = None, # No default extensions
addExtensions = es1CorePat, # Add mandatory ES1 extensions in GLES1/gl.h
removeExtensions = None,
prefixText = prefixStrings + gles1PlatformStrings + genDateCommentString,
genFuncPointers = False,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = False, # Core ES API functions are in the static link libraries
protectProtoStr = 'GL_GLEXT_PROTOTYPES',
apicall = 'GL_API ',
apientry = 'GL_APIENTRY ',
apientryp = 'GL_APIENTRYP '),
# GLES 1.x extensions - GLES/glext.h
CGeneratorOptions(
filename = 'GLES/glext.h',
apiname = 'gles1',
profile = 'common',
versions = allVersions,
emitversions = noVersions,
defaultExtensions = 'gles1', # Default extensions for GLES 1
addExtensions = None,
removeExtensions = es1CorePat, # Remove mandatory ES1 extensions in GLES1/glext.h
prefixText = prefixStrings + apiEntryPrefixStrings + genDateCommentString,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = protectProto,
protectProtoStr = 'GL_GLEXT_PROTOTYPES',
apicall = 'GL_API ',
apientry = 'GL_APIENTRY ',
apientryp = 'GL_APIENTRYP '),
# GLES 2.0 API - GLES2/gl2.h (now with function pointers)
CGeneratorOptions(
filename = 'GLES2/gl2.h',
apiname = 'gles2',
profile = 'common',
versions = gles2onlyPat,
emitversions = allVersions,
defaultExtensions = None, # No default extensions
addExtensions = None,
removeExtensions = None,
prefixText = prefixStrings + gles2PlatformStrings + apiEntryPrefixStrings + glesProtoPrefixStrings + genDateCommentString,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = 'nonzero', # Core ES API functions are in the static link libraries
protectProtoStr = 'GL_GLES_PROTOTYPES',
apicall = 'GL_APICALL ',
apientry = 'GL_APIENTRY ',
apientryp = 'GL_APIENTRYP '),
# GLES 3.1 / 3.0 / 2.0 extensions - GLES2/gl2ext.h
CGeneratorOptions(
filename = 'GLES2/gl2ext.h',
apiname = 'gles2',
profile = 'common',
versions = gles2onlyPat,
emitversions = None,
defaultExtensions = 'gles2', # Default extensions for GLES 2
addExtensions = None,
removeExtensions = None,
prefixText = prefixStrings + apiEntryPrefixStrings + genDateCommentString,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = protectProto,
protectProtoStr = 'GL_GLEXT_PROTOTYPES',
apicall = 'GL_APICALL ',
apientry = 'GL_APIENTRY ',
apientryp = 'GL_APIENTRYP '),
# GLES 3.2 API - GLES3/gl32.h (now with function pointers)
CGeneratorOptions(
filename = 'GLES3/gl32.h',
apiname = 'gles2',
profile = 'common',
versions = gles2through32Pat,
emitversions = allVersions,
defaultExtensions = None, # No default extensions
addExtensions = None,
removeExtensions = None,
prefixText = prefixStrings + gles3PlatformStrings + apiEntryPrefixStrings + glesProtoPrefixStrings + genDateCommentString,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = 'nonzero', # Core ES API functions are in the static link libraries
protectProtoStr = 'GL_GLES_PROTOTYPES',
apicall = 'GL_APICALL ',
apientry = 'GL_APIENTRY ',
apientryp = 'GL_APIENTRYP '),
# GLES 3.1 API - GLES3/gl31.h (now with function pointers)
CGeneratorOptions(
filename = 'GLES3/gl31.h',
apiname = 'gles2',
profile = 'common',
versions = gles2through31Pat,
emitversions = allVersions,
defaultExtensions = None, # No default extensions
addExtensions = None,
removeExtensions = None,
prefixText = prefixStrings + gles3PlatformStrings + apiEntryPrefixStrings + glesProtoPrefixStrings + genDateCommentString,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = 'nonzero', # Core ES API functions are in the static link libraries
protectProtoStr = 'GL_GLES_PROTOTYPES',
apicall = 'GL_APICALL ',
apientry = 'GL_APIENTRY ',
apientryp = 'GL_APIENTRYP '),
# GLES 3.0 API - GLES3/gl3.h (now with function pointers)
CGeneratorOptions(
filename = 'GLES3/gl3.h',
apiname = 'gles2',
profile = 'common',
versions = gles2through30Pat,
emitversions = allVersions,
defaultExtensions = None, # No default extensions
addExtensions = None,
removeExtensions = None,
prefixText = prefixStrings + gles3PlatformStrings + apiEntryPrefixStrings + glesProtoPrefixStrings + genDateCommentString,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = 'nonzero', # Core ES API functions are in the static link libraries
protectProtoStr = 'GL_GLES_PROTOTYPES',
apicall = 'GL_APICALL ',
apientry = 'GL_APIENTRY ',
apientryp = 'GL_APIENTRYP '),
# GLSC 2.0 API - GLSC2/glsc2.h
CGeneratorOptions(
filename = 'GLSC2/glsc2.h',
apiname = 'glsc2',
profile = 'common',
versions = gles2onlyPat,
emitversions = allVersions,
defaultExtensions = None, # No default extensions
addExtensions = None,
removeExtensions = None,
prefixText = prefixStrings + glsc2PlatformStrings + apiEntryPrefixStrings + genDateCommentString,
genFuncPointers = False,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = False,
protectProtoStr = 'GL_GLEXT_PROTOTYPES',
apicall = 'GL_APICALL ',
apientry = 'GL_APIENTRY ',
apientryp = 'GL_APIENTRYP '),
# GLSC 2.0 extensions - GLSC2/gl2ext.h
CGeneratorOptions(
filename = 'GLSC2/glsc2ext.h',
apiname = 'glsc2',
profile = 'common',
versions = gles2onlyPat,
emitversions = None,
defaultExtensions = 'glsc2', # Default extensions for GLSC 2
addExtensions = None,
removeExtensions = None,
prefixText = prefixStrings + apiEntryPrefixStrings + genDateCommentString,
genFuncPointers = False,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = False,
protectProtoStr = 'GL_GLEXT_PROTOTYPES',
apicall = 'GL_APICALL ',
apientry = 'GL_APIENTRY ',
apientryp = 'GL_APIENTRYP '),
# EGL API - EGL/egl.h (no function pointers, yet @@@)
CGeneratorOptions(
filename = 'EGL/egl.h',
apiname = 'egl',
profile = None,
versions = allVersions,
emitversions = allVersions,
defaultExtensions = None, # No default extensions
addExtensions = None,
removeExtensions = None,
prefixText = prefixStrings + eglPlatformStrings + eglProtoPrefixStrings + genDateCommentString,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = 'nonzero',
protectProtoStr = 'EGL_EGL_PROTOTYPES',
apicall = 'EGLAPI ',
apientry = 'EGLAPIENTRY ',
apientryp = 'EGLAPIENTRYP '),
# EGL extensions - EGL/eglext.h (no function pointers, yet @@@)
CGeneratorOptions(
filename = 'EGL/eglext.h',
apiname = 'egl',
profile = None,
versions = allVersions,
emitversions = None,
defaultExtensions = 'egl', # Default extensions for EGL
addExtensions = None,
removeExtensions = None,
prefixText = prefixStrings + eglPlatformStrings + eglextVersionStrings,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = protectProto,
protectProtoStr = 'EGL_EGLEXT_PROTOTYPES',
apicall = 'EGLAPI ',
apientry = 'EGLAPIENTRY ',
apientryp = 'EGLAPIENTRYP '),
# GLX 1.* API - GL/glx.h
CGeneratorOptions(
filename = 'GL/glx.h',
apiname = 'glx',
profile = None,
versions = allVersions,
emitversions = allVersions,
defaultExtensions = None, # No default extensions
addExtensions = None,
removeExtensions = None,
# add glXPlatformStrings?
prefixText = prefixStrings + genDateCommentString,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = protectProto,
protectProtoStr = 'GLX_GLXEXT_PROTOTYPES',
apicall = '',
apientry = '',
apientryp = ' *'),
# GLX 1.3+ API + extensions - GL/glxext.h (no function pointers, yet @@@)
CGeneratorOptions(
filename = 'GL/glxext.h',
apiname = 'glx',
profile = None,
versions = allVersions,
emitversions = glx13andLaterPat,
defaultExtensions = 'glx', # Default extensions for GLX
addExtensions = None,
removeExtensions = None,
# add glXPlatformStrings?
prefixText = prefixStrings + glxextVersionStrings,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = protectProto,
protectProtoStr = 'GLX_GLXEXT_PROTOTYPES',
apicall = '',
apientry = '',
apientryp = ' *'),
# WGL API + extensions - GL/wgl.h (no function pointers, yet @@@)
CGeneratorOptions(
filename = 'GL/wgl.h',
apiname = 'wgl',
profile = None,
versions = allVersions,
emitversions = allVersions,
defaultExtensions = 'wgl', # Default extensions for WGL
addExtensions = None,
removeExtensions = None,
prefixText = prefixStrings + wglPlatformStrings + genDateCommentString,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = protectProto,
protectProtoStr = 'WGL_WGLEXT_PROTOTYPES',
apicall = '',
apientry = 'WINAPI ',
apientryp = 'WINAPI * '),
# WGL extensions - GL/wglext.h (no function pointers, yet @@@)
CGeneratorOptions(
filename = 'GL/wglext.h',
apiname = 'wgl',
profile = None,
versions = allVersions,
emitversions = None,
defaultExtensions = 'wgl', # Default extensions for WGL
addExtensions = None,
removeExtensions = None,
prefixText = prefixStrings + wglPlatformStrings + wglextVersionStrings,
genFuncPointers = True,
protectFile = protectFile,
protectFeature = protectFeature,
protectProto = protectProto,
protectProtoStr = 'WGL_WGLEXT_PROTOTYPES',
apicall = '',
apientry = 'WINAPI ',
apientryp = 'WINAPI * '),
# End of list
None
]
def genHeaders():
# Loop over targets, building each
generated = 0
for genOpts in buildList:
if (genOpts == None):
break
if (target and target != genOpts.filename):
# write('*** Skipping', genOpts.filename)
continue
write('*** Building', genOpts.filename)
generated = generated + 1
startTimer()
gen = COutputGenerator(errFile=errWarn,
warnFile=errWarn,
diagFile=diag)
reg.setGenerator(gen)
reg.apiGen(genOpts)
write('** Generated', genOpts.filename)
endTimer('Time to generate ' + genOpts.filename + ' =')
if (target and generated == 0):
write('Failed to generate target:', target)
if __name__ == '__main__':
i = 1
while (i < len(sys.argv)):
arg = sys.argv[i]
i = i + 1
if (arg == '-debug'):
write('Enabling debug (-debug)', file=sys.stderr)
debug = True
elif (arg == '-dump'):
write('Enabling dump (-dump)', file=sys.stderr)
dump = True
elif (arg == '-noprotect'):
write('Disabling inclusion protection in output headers', file=sys.stderr)
protect = False
elif (arg == '-profile'):
write('Enabling profiling (-profile)', file=sys.stderr)
profile = True
elif (arg == '-registry'):
regFilename = sys.argv[i]
i = i+1
write('Using registry ', regFilename, file=sys.stderr)
elif (arg == '-time'):
write('Enabling timing (-time)', file=sys.stderr)
timeit = True
elif (arg == '-validate'):
write('Enabling group validation (-validate)', file=sys.stderr)
validate = True
elif (arg[0:1] == '-'):
write('Unrecognized argument:', arg, file=sys.stderr)
exit(1)
else:
target = arg
write('Using target', target, file=sys.stderr)
# Load & parse registry
reg = Registry()
startTimer()
tree = etree.parse(regFilename)
endTimer('Time to make ElementTree =')
startTimer()
reg.loadElementTree(tree)
endTimer('Time to parse ElementTree =')
if (validate):
reg.validateGroups()
if (dump):
write('***************************************')
write('Performing Registry dump to regdump.txt')
write('***************************************')
reg.dumpReg(filehandle = open('regdump.txt','w'))
# create error/warning & diagnostic files
if (errFilename):
errWarn = open(errFilename,'w')
else:
errWarn = sys.stderr
diag = open(diagFilename, 'w')
if (debug):
pdb.run('genHeaders()')
elif (profile):
import cProfile, pstats
cProfile.run('genHeaders()', 'profile.txt')
p = pstats.Stats('profile.txt')
p.strip_dirs().sort_stats('time').print_stats(50)
else:
genHeaders()
api/reg.py
Executable
+1168
View File
File diff suppressed because it is too large Load Diff
api/registry.rnc
+270
View File
@@ -0,0 +1,270 @@
# Copyright 2013-2020 The Khronos Group Inc.
# SPDX-License-Identifier: Apache-2.0
# Relax NG schema for Khronos Registry XML
# See https://www.github.com/KhronosGroup/EGL-Registry
#
# Last modified 2017/02/03
# This definition is subject to change (mostly in the form of additions)
namespace xsd = "http://www.w3.org/2001/XMLSchema-datatypes"
# Toplevel is a <registry> tag.
# May be led by an optional <comment> tag containing e.g. copyrights.
start = element registry {
(
element comment { text } ? |
Types * |
Groups * |
Enums * |
Commands * |
Feature * |
Extensions *
) *
}
# <types> defines a group of types
Types = element types {
Type *
}
# <type> defines a single type. It is usually a C typedef but
# may contain arbitrary C code.
# name - name of this type, if not present in the <name> tag
# api - matches a <feature> api attribute, if present
# requires - name of another type definition required by this one
# type - "group", if present, indicating a group of values in the
# corresponding <enums> definition.
# comment - unused
# <apientry /> - substitutes for an APIENTRY-style macro on output
# <name> - contains typename
Type = element type {
attribute api { text } ? ,
attribute requires { text } ? ,
attribute name { TypeName } ? ,
attribute type { text } ? ,
Comment ? ,
text ,
element apientry { text } ? ,
text ,
element name { TypeName } ? ,
text
}
# <groups> defines a group of enum groups
Groups = element groups {
Group *
}
# <group> defines a single enum group. Enums may
# be in multiple groups.
# name - group name
# comment - unused
# <enum name=""> - members of the group
Group = element group {
Name ,
Comment ? ,
element enum { Name } *
}
# <enums> defines a group of enumerants
# namespace - identifies a numeric namespace
# group - identifies a functional subset of the namespace - same as <group name="">
# start, end - beginning and end of a numeric range in the namespace
# vendor - owner of the numeric range
# type - "bitmask", if present
# comment - unused
Enums = element enums {
attribute namespace { text } ? ,
attribute group { text } ? ,
attribute type { text } ? ,
attribute start { Integer } ? ,
attribute end { Integer } ? ,
Vendor ? ,
Comment ? ,
(Enum | Unused) *
}
# <enum> defines a single enumerant
# value - integer (including hex) value of the enumerant
# api - matches a <feature> api attribute, if present
# type - "u" (unsigned), "ull" (uint64), or integer if not present
# name - enumerant name
# alias - another enumerant this is semantically identical to
# comment - unused
Enum = element enum {
(
attribute value { Integer } &
attribute api { text } ? &
attribute type { TypeSuffix } ? &
attribute name { text } &
attribute alias { text } ? &
Comment ?
)
}
# <unused> defines a range of enumerants not currently being used
# start, end - beginning and end of an unused numeric range
# vendor - unused
# comment - unused
Unused = element unused {
attribute start { Integer } ,
attribute end { Integer } ? ,
Vendor ? ,
Comment ?
}
# <commands> defines a group of commands
# namespace - identifies a function namespace
Commands = element commands {
attribute namespace { text } ? ,
Command *
}
# <command> defines a single command
# <proto> is the C function prototype, including the return type
# <param> are function parameters, in order
# <ptype> is a <type> name, if present
# <name> is the function / parameter name
# The textual contents of <proto> and <param> should be legal C
# for those parts of a function declaration.
# <alias> - denotes function aliasing
# name - name of aliased function
# <vecequiv> - denotes scalar / vector function equivalence
# name - name of corresponding vector form, e.g. (glColor3f -> glColor3fv)
# <glx> - information about GLX protocol
# type - "render", "single", or "vendor" for GLXRender, GLXSingle, GLXVendorPrivate{WithReply}
# opcode - numeric opcode of specified type for this function
# name - if present, protocol name (defaults to command name)
# comment - unused
Command = element command {
Comment ? ,
element proto {
attribute group { text } ? ,
text ,
element ptype { TypeName } ? ,
text ,
element name { text } ,
text
} ,
element param {
attribute group { text } ? ,
attribute len { text } ? ,
text ,
element ptype { TypeName } ? ,
text ,
element name { text } ,
text
} * ,
(
element alias {
Name
} ? &
element vecequiv {
Name
} ? &
element glx {
attribute type { text } ,
attribute opcode { xsd:integer } ,
Name ? ,
Comment ?
} *
)
}
# Each <feature> defines the interface of an API version (e.g. OpenGL 1.2)
# api - API tag (e.g. 'gl', 'gles2', etc. - used internally, not
# neccessarily an actual API name
# name - version name (C preprocessor name, e.g. GL_VERSION_4_2)
# number - version number, e.g. 4.2
# protect - additional #ifdef symbol to place around the feature
# <require> / <remove> contains features to require or remove in
# this version
# profile - only require/remove when generated profile matches
# comment - unused
Feature = element feature {
attribute api { text } ,
Name ,
attribute number { xsd:float } ,
attribute protect { text } ?,
Comment ? ,
(
element require {
ProfileName ? ,
Comment ? ,
InterfaceElement *
} |
element remove {
ProfileName ? ,
Comment ? ,
InterfaceElement *
}
) *
}
Extensions = element extensions {
Extension *
}
# Defines the interface of an API <extension>. Like a <feature>
# tag, but with a slightly different api attribute.
# api - regexp pattern matching one or more API tags, indicating
# which APIs the extension is known to work with. The only
# syntax supported is <name>{|<name>}* and each name must
# exactly match an API being generated (implicit ^$ surrounding).
# In addition, <require> / <remove> tags also support an
# api attribute:
# api - only require/remove these features for the matching API.
# Not a regular expression.
Extension = element extension {
Name ,
attribute protect { text } ?,
attribute supported { StringGroup } ? ,
Comment ? ,
(
element require {
attribute api { text } ? ,
ProfileName ? ,
Comment ? ,
InterfaceElement *
} |
element remove {
attribute api { text } ? ,
ProfileName ? ,
Comment ? ,
InterfaceElement *
}
) *
}
# Contents of a <require> / <remove> tag, defining a group
# of features to require or remove.
# <type> / <enum> / <command> all have attributes
# name - feature name which must match
InterfaceElement =
element type {
Name ,
Comment ?
} |
element enum {
Name ,
Comment ?
} |
element command {
Name ,
Comment ?
}
# Integers are allowed to be either decimal or C-hex (0x[0-9A-F]+), but
# XML Schema types don't seem to support hex notation, so we use this
# as a placeholder.
Integer = text
# TypeName is an argument/return value C type name
TypeName = text
# TypeSuffix is a C numeric type suffix, e.g. 'u' or 'ull'
TypeSuffix = text
# StringGroup is a regular expression with an implicit
# '^(' and ')$' bracketing it.
StringGroup = text
# Repeatedly used attributes
ProfileName = attribute profile { text }
Vendor = attribute vendor { text }
Comment = attribute comment { text }
Name = attribute name { text }
extensions/ANDROID/EGL_ANDROID_GLES_layers.txt
+64
View File
@@ -0,0 +1,64 @@
Name
ANDROID_GLES_layers
Name Strings
EGL_ANDROID_GLES_layers
Contributors
Cody Northrop
Contact
Cody Northrop, Google LLC (cnorthrop 'at' google.com)
Status
Draft
Version
Version 1, March 3, 2019
Number
EGL Extension #132
Extension Type
EGL client extension
Dependencies
Requires EGL 1.5 or EGL_EXT_client_extensions
Overview
This extension indicates the EGL loader supports GLES layering on Android.
It does not add any requirements to drivers or hardware.
See frameworks/native/opengl/libs/EGL/GLES_layers.md in Android for
more information.
New Types
None
New Procedures and Functions
None
New Tokens
None
Issues
None
Revision History
#1 (Cody Northrop, March 3, 2019)
- Initial draft.
extensions/ANDROID/EGL_ANDROID_blob_cache.txt
+211
View File
@@ -0,0 +1,211 @@
Name
ANDROID_blob_cache
Name Strings
EGL_ANDROID_blob_cache
Contributors
Jamie Gennis
Contact
Jamie Gennis, Google Inc. (jgennis 'at' google.com)
Status
Complete
Version
Version 3, December 13, 2012
Number
EGL Extension #48
Dependencies
Requires EGL 1.0
This extension is written against the wording of the EGL 1.4 Specification
Overview
Shader compilation and optimization has been a troublesome aspect of OpenGL
programming for a long time. It can consume seconds of CPU cycles during
application start-up. Additionally, state-based re-compiles done
internally by the drivers add an unpredictable element to application
performance tuning, often leading to occasional pauses in otherwise smooth
animations.
This extension provides a mechanism through which client API
implementations may cache shader binaries after they are compiled. It may
then retrieve those cached shaders during subsequent executions of the same
program. The management of the cache is handled by the application (or
middleware), allowing it to be tuned to a particular platform or
environment.
While the focus of this extension is on providing a persistent cache for
shader binaries, it may also be useful for caching other data. This is
perfectly acceptable, but the guarantees provided (or lack thereof) were
designed around the shader use case.
Note that although this extension is written as if the application
implements the caching functionality, on the Android OS it is implemented
as part of the Android EGL module. This extension is not exposed to
applications on Android, but will be used automatically in every
application that uses EGL if it is supported by the underlying
device-specific EGL implementation.
New Types
/*
* EGLsizeiANDROID is a signed integer type for representing the size of a
* memory buffer.
*/
#include <khrplatform.h>
typedef khronos_ssize_t EGLsizeiANDROID;
/*
* EGLSetBlobFunc is a pointer to an application-provided function that a
* client API implementation may use to insert a key/value pair into the
* cache.
*/
typedef void (*EGLSetBlobFuncANDROID) (const void* key,
EGLsizeiANDROID keySize, const void* value, EGLsizeiANDROID valueSize)
/*
* EGLGetBlobFunc is a pointer to an application-provided function that a
* client API implementation may use to retrieve a cached value from the
* cache.
*/
typedef EGLsizeiANDROID (*EGLGetBlobFuncANDROID) (const void* key,
EGLsizeiANDROID keySize, void* value, EGLsizeiANDROID valueSize)
New Procedures and Functions
void eglSetBlobCacheFuncsANDROID(EGLDisplay dpy,
EGLSetBlobFuncANDROID set,
EGLGetBlobFuncANDROID get);
New Tokens
None.
Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
Add a new subsection after Section 3.8, page 50
(Synchronization Primitives)
"3.9 Persistent Caching
In order to facilitate persistent caching of internal client API state that
is slow to compute or collect, the application may specify callback
function pointers through which the client APIs can request data be cached
and retrieved. The command
void eglSetBlobCacheFuncsANDROID(EGLDisplay dpy,
EGLSetBlobFuncANDROID set, EGLGetBlobFuncANDROID get);
sets the callback function pointers that client APIs associated with
display <dpy> can use to interact with caching functionality provided by
the application. <set> points to a function that inserts a new value into
the cache and associates it with the given key. <get> points to a function
that retrieves from the cache the value associated with a given key. The
semantics of these callback functions are described in Section 3.9.1 (Cache
Operations).
Cache functions may only be specified once during the lifetime of an
EGLDisplay. The <set> and <get> functions may be called at any time and
from any thread from the time at which eglSetBlobCacheFuncsANDROID is
called until the time that the last resource associated with <dpy> is
deleted and <dpy> itself is terminated. Concurrent calls to these
functions from different threads is also allowed.
If eglSetBlobCacheFuncsANDROID generates an error then all client APIs must
behave as though eglSetBlobCacheFuncsANDROID was not called for the display
<dpy>. If <set> or <get> is NULL then an EGL_BAD_PARAMETER error is
generated. If a successful eglSetBlobCacheFuncsANDROID call was already
made for <dpy> and the display has not since been terminated then an
EGL_BAD_PARAMETER error is generated.
3.9.1 Cache Operations
To insert a new binary value into the cache and associate it with a given
key, a client API implementation can call the application-provided callback
function
void (*set) (const void* key, EGLsizeiANDROID keySize,
const void* value, EGLsizeiANDROID valueSize)
<key> and <value> are pointers to the beginning of the key and value,
respectively, that are to be inserted. <keySize> and <valueSize> specify
the size in bytes of the data pointed to by <key> and <value>,
respectively.
No guarantees are made as to whether a given key/value pair is present in
the cache after the set call. If a different value has been associated
with the given key in the past then it is undefined which value, if any, is
associated with the key after the set call. Note that while there are no
guarantees, the cache implementation should attempt to cache the most
recently set value for a given key.
To retrieve the binary value associated with a given key from the cache, a
client API implementation can call the application-provided callback
function
EGLsizeiANDROID (*get) (const void* key, EGLsizeiANDROID keySize,
void* value, EGLsizeiANDROID valueSize)
<key> is a pointer to the beginning of the key. <keySize> specifies the
size in bytes of the binary key pointed to by <key>. If the cache contains
a value associated with the given key then the size of that binary value in
bytes is returned. Otherwise 0 is returned.
If the cache contains a value for the given key and its size in bytes is
less than or equal to <valueSize> then the value is written to the memory
pointed to by <value>. Otherwise nothing is written to the memory pointed
to by <value>.
Issues
1. How should errors be handled in the callback functions?
RESOLVED: No guarantees are made about the presence of values in the cache,
so there should not be a need to return error information to the client API
implementation. The cache implementation can simply drop a value if it
encounters an error during the 'set' callback. Similarly, it can simply
return 0 if it encouters an error in a 'get' callback.
2. When a client API driver gets updated, that may need to invalidate
previously cached entries. How can the driver handle this situation?
RESPONSE: There are a number of ways the driver can handle this situation.
The recommended way is to include the driver version in all cache keys.
That way each driver version will use a set of cache keys that are unique
to that version, and conflicts should never occur. Updating the driver
could then leave a number of values in the cache that will never be
requested again. If needed, the cache implementation can handle those
values in some way, but the driver does not need to take any special
action.
3. How much data can be stored in the cache?
RESPONSE: This is entirely dependent upon the cache implementation.
Presumably it will be tuned to store enough data to be useful, but not
enough to become problematic. :)
Revision History
#3 (Jon Leech, December 13, 2012)
- Fix typo in New Functions section & assign extension #.
#2 (Jamie Gennis, April 25, 2011)
- Swapped the order of the size and pointer arguments to the get and set
functions.
#1 (Jamie Gennis, April 22, 2011)
- Initial draft.
extensions/ANDROID/EGL_ANDROID_create_native_client_buffer.txt
+197
View File
@@ -0,0 +1,197 @@
Name
ANDROID_create_native_client_buffer
Name Strings
EGL_ANDROID_create_native_client_buffer
Contributors
Craig Donner
Contact
Craig Donner, Google Inc. (cdonner 'at' google.com)
Status
Draft
Version
Version 1, January 19, 2016
Number
EGL Extension #99
Dependencies
Requires EGL 1.2.
EGL_ANDROID_image_native_buffer and EGL_KHR_image_base are required.
This extension is written against the wording of the EGL 1.2
Specification as modified by EGL_KHR_image_base and
EGL_ANDROID_image_native_buffer.
Overview
This extension allows creating an EGLClientBuffer backed by an Android
window buffer (struct ANativeWindowBuffer) which can be later used to
create an EGLImage.
New Types
None.
New Procedures and Functions
EGLClientBuffer eglCreateNativeClientBufferANDROID(
const EGLint *attrib_list)
New Tokens
EGL_NATIVE_BUFFER_USAGE_ANDROID 0x3143
EGL_NATIVE_BUFFER_USAGE_PROTECTED_BIT_ANDROID 0x00000001
EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID 0x00000002
EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID 0x00000004
Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
Add the following to section 2.5.1 "EGLImage Specification" (as modified by
the EGL_KHR_image_base and EGL_ANDROID_image_native_buffer specifications),
below the description of eglCreateImageKHR:
"The command
EGLClientBuffer eglCreateNativeClientBufferANDROID(
const EGLint *attrib_list)
may be used to create an EGLClientBuffer backed by an ANativeWindowBuffer
struct. EGL implementations must guarantee that the lifetime of the
returned EGLClientBuffer is at least as long as the EGLImage(s) it is bound
to, following the lifetime semantics described below in section 2.5.2; the
EGLClientBuffer must be destroyed no earlier than when all of its associated
EGLImages are destroyed by eglDestroyImageKHR. <attrib_list> is a list of
attribute-value pairs which is used to specify the dimensions, format, and
usage of the underlying buffer structure. If <attrib_list> is non-NULL, the
last attribute specified in the list must be EGL_NONE.
Attribute names accepted in <attrib_list> are shown in Table aaa,
together with the <target> for which each attribute name is valid, and
the default value used for each attribute if it is not included in
<attrib_list>.
+---------------------------------+----------------------+---------------+
| Attribute | Description | Default Value |
| | | |
+---------------------------------+----------------------+---------------+
| EGL_NONE | Marks the end of the | N/A |
| | attribute-value list | |
| EGL_WIDTH | The width of the | 0 |
| | buffer data | |
| EGL_HEIGHT | The height of the | 0 |
| | buffer data | |
| EGL_RED_SIZE | The bits of Red in | 0 |
| | the color buffer | |
| EGL_GREEN_SIZE | The bits of Green in | 0 |
| | the color buffer | |
| EGL_BLUE_SIZE | The bits of Blue in | 0 |
| | the color buffer | |
| EGL_ALPHA_SIZE | The bits of Alpha in | 0 |
| | the color buffer | |
| | buffer data | |
| EGL_NATIVE_BUFFER_USAGE_ANDROID | The usage bits of | 0 |
| | the buffer data | |
+---------------------------------+----------------------+---------------+
Table aaa. Legal attributes for eglCreateNativeClientBufferANDROID
<attrib_list> parameter.
The maximum width and height may depend on the amount of available memory,
which may also depend on the format and usage flags. The values of
EGL_RED_SIZE, EGL_GREEN_SIZE, and EGL_BLUE_SIZE must be non-zero and
correspond to a valid pixel format for the implementation. If EGL_ALPHA_SIZE
is non-zero then the combination of all four sizes must correspond to a
valid pixel format for the implementation. The
EGL_NATIVE_BUFFER_USAGE_ANDROID flag may include any of the following bits:
EGL_NATIVE_BUFFER_USAGE_PROTECTED_BIT_ANDROID: Indicates that the
created buffer must have a hardware-protected path to external display
sink. If a hardware-protected path is not available, then either don't
composite only this buffer (preferred) to the external sink, or (less
desirable) do not route the entire composition to the external sink.
EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID: The buffer will be
used to create a renderbuffer. This flag must not be set if
EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID is set.
EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID: The buffer will be used to
create a texture. This flag must not be set if
EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID is set.
Errors
If eglCreateNativeClientBufferANDROID fails, NULL will be returned, no
memory will be allocated, and one of the following errors will be
generated:
* If the value of EGL_WIDTH or EGL_HEIGHT is not positive, the error
EGL_BAD_PARAMETER is generated.
* If the combination of the values of EGL_RED_SIZE, EGL_GREEN_SIZE,
EGL_BLUE_SIZE, and EGL_ALPHA_SIZE is not a valid pixel format for the
EGL implementation, the error EGL_BAD_PARAMETER is generated.
* If the value of EGL_NATIVE_BUFFER_ANDROID is not a valid combination
of gralloc usage flags for the EGL implementation, or is incompatible
with the value of EGL_FORMAT, the error EGL_BAD_PARAMETER is
Generated.
* If both the EGL_NATIVE_BUFFER_USAGE_RENDERBUFFER_BIT_ANDROID and
EGL_NATIVE_BUFFER_USAGE_TEXTURE_BIT_ANDROID are set in the value of
EGL_NATIVE_BUFFER_USAGE_ANDROID, the error EGL_BAD_PARAMETER is
Generated."
Issues
1. Should this extension define what combinations of formats and usage flags
EGL implementations are required to support?
RESOLVED: Partially.
The set of valid color combinations is implementation-specific and may
depend on additional EGL extensions, but generally RGB565 and RGBA888 should
be supported. The particular valid combinations for a given Android version
and implementation should be documented by that version.
2. Should there be an eglDestroyNativeClientBufferANDROID to destroy the
client buffers created by this extension?
RESOLVED: No.
A destroy function would add several complications:
a) ANativeWindowBuffer is a reference counted object, may be used
outside of EGL.
b) The same buffer may back multiple EGLImages, though this usage may
result in undefined behavior.
c) The interactions between the lifetimes of EGLImages and their
EGLClientBuffers would become needlessly complex.
Because ANativeWindowBuffer is a reference counted object, implementations
of this extension should ensure the buffer has a lifetime at least as long
as a generated EGLImage (via EGL_ANDROID_image_native_buffer). The simplest
method is to increment the reference count of the buffer in
eglCreateImagKHR, and then decrement it in eglDestroyImageKHR. This should
ensure proper lifetime semantics.
Revision History
#2 (Craig Donner, April 15, 2016)
- Set color formats and usage bits explicitly using additional attributes,
and add value for new token EGL_NATIVE_BUFFER_USAGE_ANDROID.
#1 (Craig Donner, January 19, 2016)
- Initial draft.
extensions/ANDROID/EGL_ANDROID_framebuffer_target.txt
+102
View File
@@ -0,0 +1,102 @@
Name
ANDROID_framebuffer_target
Name Strings
EGL_ANDROID_framebuffer_target
Contributors
Jamie Gennis
Contact
Jamie Gennis, Google Inc. (jgennis 'at' google.com)
Status
Complete
Version
Version 1, September 20, 2012
Number
EGL Extension #47
Dependencies
Requires EGL 1.0
This extension is written against the wording of the EGL 1.4 Specification
Overview
Android supports a number of different ANativeWindow implementations that
can be used to create an EGLSurface. One implementation, which is used to
send the result of performing window composition to a display, may have
some device-specific restrictions. Because of this, some EGLConfigs may
be incompatible with these ANativeWindows. This extension introduces a
new boolean EGLConfig attribute that indicates whether the EGLConfig
supports rendering to an ANativeWindow for which the buffers are passed to
the HWComposer HAL as a framebuffer target layer.
New Types
None.
New Procedures and Functions
None.
New Tokens
Accepted by the <attribute> parameter of eglGetConfigAttrib and
the <attrib_list> parameter of eglChooseConfig:
EGL_FRAMEBUFFER_TARGET_ANDROID 0x3147
Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
Section 3.4, Configuration Management, add a row to Table 3.1.
Attribute Type Notes
------------------------------ ------- ---------------------------
EGL_FRAMEBUFFER_TARGET_ANDROID boolean whether use as a HWComposer
framebuffer target layer is
supported
Section 3.4, Configuration Management, add a row to Table 3.4.
Attribute Default Selection Sort Sort
Criteria Order Priority
------------------------------ ------------- --------- ----- --------
EGL_FRAMEBUFFER_TARGET_ANDROID EGL_DONT_CARE Exact None
Section 3.4, Configuration Management, add a paragraph at the end of the
subsection titled Other EGLConfig Attribute Descriptions.
EGL_FRAMEBUFFER_TARGET_ANDROID is a boolean indicating whether the
config may be used to create an EGLSurface from an ANativeWindow for
which the buffers are to be passed to HWComposer as a framebuffer
target layer.
Section 3.4.1, Querying Configurations, change the last paragraph as follow
EGLConfigs are not sorted with respect to the parameters
EGL_BIND_TO_TEXTURE_RGB, EGL_BIND_TO_TEXTURE_RGBA, EGL_CONFORMANT,
EGL_LEVEL, EGL_NATIVE_RENDERABLE, EGL_MAX_SWAP_INTERVAL,
EGL_MIN_SWAP_INTERVAL, EGL_RENDERABLE_TYPE, EGL_SURFACE_TYPE,
EGL_TRANSPARENT_TYPE, EGL_TRANSPARENT_RED_VALUE,
EGL_TRANSPARENT_GREEN_VALUE, EGL_TRANSPARENT_BLUE_VALUE, and
EGL_RECORDABLE_ANDROID.
Issues
Revision History
#1 (Jamie Gennis, September 20, 2012)
- Initial draft.
extensions/ANDROID/EGL_ANDROID_front_buffer_auto_refresh.txt
+70
View File
@@ -0,0 +1,70 @@
Name
ANDROID_front_buffer_auto_refresh
Name Strings
EGL_ANDROID_front_buffer_auto_refresh
Contributors
Pablo Ceballos
Contact
Pablo Ceballos, Google Inc. (pceballos 'at' google.com)
Status
Draft
Version
Version 1, February 3, 2016
Number
EGL Extension #XXX
Dependencies
Requires EGL 1.2
This extension is written against the wording of the EGL 1.5 Specification
Overview
This extension is intended for latency-sensitive applications that are doing
front-buffer rendering. It allows them to indicate to the Android compositor
that it should perform composition every time the display refreshes. This
removes the overhead of having to notify the compositor that the window
surface has been updated, but it comes at the cost of doing potentially
unneeded composition work if the window surface has not been updated.
New Types
None
New Procedures and Functions
None
New Tokens
EGL_FRONT_BUFFER_AUTO_REFRESH_ANDROID 0x314C
Add to the list of supported tokens for eglSurfaceAttrib in section 3.5.6
"Surface Attributes", page 43:
If attribute is EGL_ANDROID_front_buffer_auto_refresh, then value specifies
whether to enable or disable auto-refresh in the Android compositor when
doing front-buffer rendering.
Issues
None
Revision History
#1 (Pablo Ceballos, February 3, 2016)
- Initial draft.
extensions/ANDROID/EGL_ANDROID_get_frame_timestamps.txt
+259
View File
@@ -0,0 +1,259 @@
Name
ANDROID_get_frame_timestamps
Name Strings
EGL_ANDROID_get_frame_timestamps
Contributors
Brian Anderson
Dan Stoza
Pablo Ceballos
Jesse Hall
Fabien Sanglard
Contact
Brian Anderson, Google Inc. (brianderson 'at' google.com)
Dan Stoza, Google Inc. (stoza 'at' google.com)
Pablo Ceballos, Google Inc. (pceballos 'at' google.com)
Jesse Hall, Google Inc. (jessehall 'at' google.com)
Fabien Sanglard, Google Inc. (sanglardf 'at' google.com)
Status
Draft
Version
Version 8, April 11, 2017
Number
EGL Extension #122
Dependencies
Requires EGL 1.2
This extension is written against the wording of the EGL 1.5 Specification
Overview
This extension allows querying various timestamps related to the composition
and display of window surfaces.
Some examples of how this might be used:
- The display present time can be used to calculate end-to-end latency
of the entire graphics pipeline.
- The queue time and rendering complete time can be used to determine
how long the application's rendering took to complete. Likewise, the
composition start time and finish time can be used to determine how
long the compositor's rendering work took. In combination these can be
used to help determine if the system is GPU or CPU bound.
New Types
/*
* EGLnsecsANDROID is a signed integer type for representing a time in
* nanoseconds.
*/
#include <khrplatform.h>
typedef khronos_stime_nanoseconds_t EGLnsecsANDROID;
New Procedures and Functions
EGLBoolean eglGetNextFrameIdANDROID(EGLDisplay dpy, EGLSurface surface,
EGLuint64KHR *frameId);
EGLBoolean eglGetCompositorTimingANDROID(EGLDisplay dpy,
EGLSurface surface, EGLint numTimestamps,
const EGLint *names, EGLnsecsANDROID *values);
EGLBoolean eglGetFrameTimestampsANDROID(EGLDisplay dpy, EGLSurface surface,
EGLuint64KHR frameId, EGLint numTimestamps,
const EGLint *timestamps, EGLnsecsANDROID *values);
EGLBoolean eglGetFrameTimestampSupportedANDROID(EGLDisplay dpy,
EGLSurface surface, EGLint timestamp);
New Tokens
EGL_TIMESTAMPS_ANDROID 0x3430
EGL_COMPOSITE_DEADLINE_ANDROID 0x3431
EGL_COMPOSITE_INTERVAL_ANDROID 0x3432
EGL_COMPOSITE_TO_PRESENT_LATENCY_ANDROID 0x3433
EGL_REQUESTED_PRESENT_TIME_ANDROID 0x3434
EGL_RENDERING_COMPLETE_TIME_ANDROID 0x3435
EGL_COMPOSITION_LATCH_TIME_ANDROID 0x3436
EGL_FIRST_COMPOSITION_START_TIME_ANDROID 0x3437
EGL_LAST_COMPOSITION_START_TIME_ANDROID 0x3438
EGL_FIRST_COMPOSITION_GPU_FINISHED_TIME_ANDROID 0x3439
EGL_DISPLAY_PRESENT_TIME_ANDROID 0x343A
EGL_DEQUEUE_READY_TIME_ANDROID 0x343B
EGL_READS_DONE_TIME_ANDROID 0x343C
EGL_TIMESTAMP_PENDING_ANDROID -2
EGL_TIMESTAMP_INVALID_ANDROID -1
Add to the list of supported tokens for eglSurfaceAttrib in section 3.5.6
"Surface Attributes", page 43:
If attribute is EGL_TIMESTAMPS_ANDROID, then values specifies whether to
enable/disable timestamp collection for this surface. A value of EGL_TRUE
enables timestamp collection, while a value of EGL_FALSE disables it. The
initial value is false. If surface is not a window surface this has no
effect.
Changes to Chapter 3 of the EGL 1.5 Specification (EGL Functions and Errors)
Add a new subsection under Section 3,
"3.13 Composition and Display Timestamps
The function
EGLBoolean eglGetNextFrameIdANDROID(EGLDisplay dpy, EGLSurface surface,
EGLuint64KHR *frameId);
Returns an identifier for the next frame to be swapped. The identifier can
be used to correlate a particular eglSwapBuffers with its timestamps in
eglGetFrameTimestampsANDROID. If any error is generated, the function will
return EGL_FALSE.
The function
EGLBoolean eglGetCompositorTimingANDROID(EGLDisplay dpy,
EGLSurface surface, EGLint numTimestamps,
const EGLint *names, EGLnsecsANDROID *values);
allows querying anticipated timestamps and durations related to the
composition and display of a window surface. The values are not associated
with a particular frame and can be retrieved before the first swap.
The eglGetCompositorTimingANDROID function takes an array of names to
query and returns their values in the corresponding indices of the values
array. The possible names that can be queried are:
- EGL_COMPOSITE_DEADLINE_ANDROID - The timestamp of the next time the
compositor will begin composition. This is effectively the deadline
for when the compositor must receive a newly queued frame.
- EGL_COMPOSITE_INTERVAL_ANDROID - The time delta between subsequent
composition events.
- EGL_COMPOSITE_TO_PRESENT_LATENCY_ANDROID - The time delta between
the start of composition and the expected present time of that
composition. This can be used to estimate the latency of the
actual present time.
The function
EGLBoolean eglGetFrameTimestampsANDROID(EGLDisplay dpy,
EGLSurface surface, EGLuint64KHR frameId, EGLint numTimestamps,
const EGLint *timestamps, EGLnsecsANDROID *values);
allows querying various timestamps related to the composition and display
of specific frames of a window surface.
The frameId indicates which frame to query. The implementation maintains a
limited history of timestamp data. If a query is made for a frame whose
timestamp history no longer exists then EGL_BAD_ACCESS is generated. If
timestamp collection has not been enabled for the surface then
EGL_BAD_SURFACE is generated. Timestamps for events that might still occur
will have the value EGL_TIMESTAMP_PENDING_ANDROID. Timestamps for events
that did not occur will have the value EGL_TIMESTAMP_INVALID_ANDROID.
Otherwise, the timestamp will be valid and indicate the event has occured.
Timestamp queries that are not supported will generate an EGL_BAD_PARAMETER
error. If any error is generated the function will return EGL_FALSE.
The application can poll for the timestamp of particular events by calling
eglGetFrameTimestamps over and over without needing to call any other EGL
function between calls. This is true even for the most recently swapped
frame. eglGetFrameTimestamps is thread safe and can be called from a
different thread than the swapping thread.
The eglGetFrameTimestampsANDROID function takes an array of timestamps to
query and returns timestamps in the corresponding indices of the values
array. The possible timestamps that can be queried are:
- EGL_REQUESTED_PRESENT_TIME_ANDROID - The time the application
requested this frame be presented. See EGL_ANDROID_presentation_time.
If the application does not request a presentation time explicitly,
this will correspond to buffer's queue time.
- EGL_RENDERING_COMPLETE_TIME_ANDROID - The time when all of the
application's rendering to the surface was completed.
- EGL_COMPOSITION_LATCH_TIME_ANDROID - The time when the compositor
selected this frame as the one to use for the next composition. The
latch is the earliest indication that the frame was submitted in time
to be composited.
- EGL_FIRST_COMPOSITION_START_TIME_ANDROID - The first time at which
the compositor began preparing composition for this frame.
- EGL_LAST_COMPOSITION_START_TIME_ANDROID - The last time at which the
compositor began preparing composition for this frame. If this frame
is composited only once, it will have the same value as
EGL_FIRST_COMPOSITION_START_TIME_ANDROID. If the value is not equal,
that indicates the subsequent frame was not submitted in time to be
latched by the compositor. Note: The value may not be updated for
every display refresh if the compositor becomes idle.
- EGL_FIRST_COMPOSITION_GPU_FINISHED_TIME_ANDROID - The time at which
the compositor's rendering work for this frame finished. This will be
zero if composition was handled by the display and the compositor
didn't do any rendering.
- EGL_DISPLAY_PRESENT_TIME_ANDROID - The time at which this frame
started to scan out to the physical display.
- EGL_DEQUEUE_READY_TIME_ANDROID - The time when the buffer became
available for reuse as a buffer the client can target without
blocking. This is generally the point when all read commands of the
buffer have been submitted, but not necessarily completed.
- EGL_READS_DONE_TIME_ANDROID - The time at which all reads for the
purpose of display/composition were completed for this frame.
Not all implementations may support all of the above timestamp queries. The
functions
EGLBoolean eglGetCompositorTimingSupportedANDROID(EGLDisplay dpy,
EGLSurface surface, EGLint name);
and
EGLBoolean eglGetFrameTimestampSupportedANDROID(EGLDisplay dpy,
EGLSurface surface, EGLint timestamp);
allows querying which values are supported by the implementations of
eglGetCompositorTimingANDROID and eglGetFrameTimestampSupportedANDROID
respectively."
Issues
None
Revision History
#9 (Chris Forbes, June 11, 2019)
- Fix eglGetFrameTimestampSupportedANDROID function name in extension
spec to match reality
#8 (Brian Anderson, April 11, 2017)
- Use reserved enumerant values.
#7 (Brian Anderson, March 21, 2017)
- Differentiate between pending events and events that did not occur.
#6 (Brian Anderson, March 16, 2017)
- Remove DISPLAY_RETIRE_TIME_ANDROID.
#5 (Brian Anderson, January 13, 2017)
- Add eglGetCompositorTimingANDROID.
#4 (Brian Anderson, January 10, 2017)
- Use an absolute frameId rather than a relative framesAgo.
#3 (Brian Anderson, November 30, 2016)
- Add EGL_COMPOSITION_LATCH_TIME_ANDROID,
EGL_LAST_COMPOSITION_START_TIME_ANDROID, and
EGL_DEQUEUE_READY_TIME_ANDROID.
#2 (Brian Anderson, July 22, 2016)
- Replace EGL_QUEUE_TIME_ANDROID with EGL_REQUESTED_PRESENT_TIME_ANDROID.
- Add DISPLAY_PRESENT_TIME_ANDROID.
#1 (Pablo Ceballos, May 31, 2016)
- Initial draft.
extensions/ANDROID/EGL_ANDROID_get_native_client_buffer.txt
+102
View File
@@ -0,0 +1,102 @@
Name
ANDROID_get_native_client_buffer
Name Strings
EGL_ANDROID_get_native_client_buffer
Contributors
Craig Donner
Contact
Craig Donner, Google Inc. (cdonner 'at' google.com)
Status
Complete
Version
Version 3, October 11, 2017
Number
EGL Extension #123
Dependencies
Requires EGL 1.2.
EGL_ANDROID_image_native_buffer and EGL_KHR_image_base are required.
This extension is written against the wording of the EGL 1.2
Specification as modified by EGL_KHR_image_base and
EGL_ANDROID_image_native_buffer.
Overview
This extension allows creating an EGLClientBuffer from an Android
AHardwareBuffer object which can be later used to create an EGLImage.
New Types
struct AHardwareBuffer
New Procedures and Functions
EGLClientBuffer eglGetNativeClientBufferANDROID(const struct AHardwareBuffer *buffer)
New Tokens
None
Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
Add the following to section 2.5.1 "EGLImage Specification" (as modified by
the EGL_KHR_image_base and EGL_ANDROID_image_native_buffer specifications),
below the description of eglCreateImageKHR:
"The command
EGLClientBuffer eglGetNativeClientBufferANDROID(
const struct AHardwareBuffer *buffer)
may be used to create an EGLClientBuffer from an AHardwareBuffer object.
EGL implementations must guarantee that the lifetime of the returned
EGLClientBuffer is at least as long as the EGLImage(s) it is bound to,
following the lifetime semantics described below in section 2.5.2; the
EGLClientBuffer must be destroyed no earlier than when all of its associated
EGLImages are destroyed by eglDestroyImageKHR.
Errors
If eglGetNativeClientBufferANDROID fails, NULL will be returned, no
memory will be allocated, and the following error will be generated:
* If the value of buffer is NULL, the error EGL_BAD_PARAMETER is
generated.
Issues
1. Should this extension define what particular AHardwareBuffer formats EGL
implementations are required to support?
RESOLVED: No.
The set of valid formats is implementation-specific and may depend on
additional EGL extensions. The particular valid combinations for a given
Android version and implementation should be documented by that version.
Revision History
#3 (Jesse Hall, October 11, 2017)
- Assigned extension number, fixed minor issues for publication
#2 (Craig Donner, February 17, 2017)
- Fix typographical errors.
#1 (Craig Donner, January 27, 2017)
- Initial draft.
extensions/ANDROID/EGL_ANDROID_image_native_buffer.txt
+108
View File
@@ -0,0 +1,108 @@
Name
ANDROID_image_native_buffer
Name Strings
EGL_ANDROID_image_native_buffer
Contributors
Mathias Agopian
Jamie Gennis
Jesse Hall
Contact
Jesse Hall, Google Inc. (jessehall 'at' google.com)
Status
Complete
Version
Version 1, November 28, 2012
Number
EGL Extension #49
Dependencies
EGL 1.2 is required.
EGL_KHR_image_base is required.
This extension is written against the wording of the EGL 1.2
Specification.
Overview
This extension enables using an Android window buffer (struct
ANativeWindowBuffer) as an EGLImage source.
New Types
None.
New Procedures and Functions
None.
New Tokens
Accepted by the <target> parameter of eglCreateImageKHR:
EGL_NATIVE_BUFFER_ANDROID 0x3140
Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
Add to section 2.5.1 "EGLImage Specification" (as defined by the
EGL_KHR_image_base specification), in the description of
eglCreateImageKHR:
"Values accepted for <target> are listed in Table aaa, below.
+----------------------------+-----------------------------------------+
| <target> | Notes |
+----------------------------+-----------------------------------------+
| EGL_NATIVE_BUFFER_ANDROID | Used for ANativeWindowBuffer objects |
+----------------------------+-----------------------------------------+
Table aaa. Legal values for eglCreateImageKHR <target> parameter
...
If <target> is EGL_NATIVE_BUFFER_ANDROID, <dpy> must be a valid display,
<ctx> must be EGL_NO_CONTEXT, <buffer> must be a pointer to a valid
ANativeWindowBuffer object (cast into the type EGLClientBuffer), and
attributes other than EGL_IMAGE_PRESERVED_KHR are ignored."
Add to the list of error conditions for eglCreateImageKHR:
"* If <target> is EGL_NATIVE_BUFFER_ANDROID and <buffer> is not a
pointer to a valid ANativeWindowBuffer, the error EGL_BAD_PARAMETER
is generated.
* If <target> is EGL_NATIVE_BUFFER_ANDROID and <ctx> is not
EGL_NO_CONTEXT, the error EGL_BAD_CONTEXT is generated.
* If <target> is EGL_NATIVE_BUFFER_ANDROID and <buffer> was created
with properties (format, usage, dimensions, etc.) not supported by
the EGL implementation, the error EGL_BAD_PARAMETER is generated."
Issues
1. Should this extension define what combinations of ANativeWindowBuffer
properties implementations are required to support?
RESOLVED: No.
The requirements have evolved over time and will continue to change with
future Android releases. The minimum requirements for a given Android
version should be documented by that version.
Revision History
#1 (Jesse Hall, November 28, 2012)
- Initial draft.
extensions/ANDROID/EGL_ANDROID_native_fence_sync.txt
+281
View File
@@ -0,0 +1,281 @@
Name
ANDROID_native_fence_sync
Name Strings
EGL_ANDROID_native_fence_sync
Contributors
Jamie Gennis
Contact
Jamie Gennis, Google Inc. (jgennis 'at' google.com)
Status
Complete
Version
Version 3, September 4, 2012
Number
EGL Extension #50
Dependencies
Requires EGL 1.1
This extension is written against the wording of the EGL 1.2 Specification
EGL_KHR_fence_sync is required.
Overview
This extension enables the creation of EGL fence sync objects that are
associated with a native synchronization fence object that is referenced
using a file descriptor. These EGL fence sync objects have nearly
identical semantics to those defined by the KHR_fence_sync extension,
except that they have an additional attribute storing the file descriptor
referring to the native fence object.
This extension assumes the existence of a native fence synchronization
object that behaves similarly to an EGL fence sync object. These native
objects must have a signal status like that of an EGLSyncKHR object that
indicates whether the fence has ever been signaled. Once signaled the
native object's signal status may not change again.
New Types
None.
New Procedures and Functions
EGLint eglDupNativeFenceFDANDROID(
EGLDisplay dpy,
EGLSyncKHR);
New Tokens
Accepted by the <type> parameter of eglCreateSyncKHR, and returned
in <value> when eglGetSyncAttribKHR is called with <attribute>
EGL_SYNC_TYPE_KHR:
EGL_SYNC_NATIVE_FENCE_ANDROID 0x3144
Accepted by the <attrib_list> parameter of eglCreateSyncKHR:
EGL_SYNC_NATIVE_FENCE_FD_ANDROID 0x3145
Accepted by the <attrib_list> parameter of eglCreateSyncKHR, and returned
by eglDupNativeFenceFDANDROID in the event of an error:
EGL_NO_NATIVE_FENCE_FD_ANDROID -1
Returned in <value> when eglGetSyncAttribKHR is called with <attribute>
EGL_SYNC_CONDITION_KHR:
EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID 0x3146
Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
Add the following after the sixth paragraph of Section 3.8.1 (Sync
Objects), added by KHR_fence_sync
"If <type> is EGL_SYNC_NATIVE_FENCE_ANDROID, an EGL native fence sync
object is created. In this case the EGL_SYNC_NATIVE_FENCE_FD_ANDROID
attribute may optionally be specified. If this attribute is specified, it
must be set to either a file descriptor that refers to a native fence
object or to the value EGL_NO_NATIVE_FENCE_FD_ANDROID.
The default values for the EGL native fence sync object attributes are as
follows:
Attribute Name Initial Attribute Value(s)
--------------- --------------------------
EGL_SYNC_TYPE_KHR EGL_SYNC_NATIVE_FENCE_ANDROID
EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR
EGL_SYNC_CONDITION_KHR EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR
EGL_SYNC_NATIVE_FENCE_FD_ANDROID EGL_NO_NATIVE_FENCE_FD_ANDROID
If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute is not
EGL_NO_NATIVE_FENCE_FD_ANDROID then the EGL_SYNC_CONDITION_KHR attribute is
set to EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID and the EGL_SYNC_STATUS_KHR
attribute is set to reflect the signal status of the native fence object.
Additionally, the EGL implementation assumes ownership of the file
descriptor, so the caller must not use it after calling eglCreateSyncKHR."
Modify Section 3.8.1 (Sync Objects), added by KHR_fence_sync, starting at
the seventh paragraph
"When a fence sync object is created or when an EGL native fence sync
object is created with the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute set
to EGL_NO_NATIVE_FENCE_FD_ANDROID, eglCreateSyncKHR also inserts a fence
command into the command stream of the bound client API's current context
(i.e., the context returned by eglGetCurrentContext), and associates it
with the newly created sync object.
After associating the fence command with an EGL native fence sync object,
the next Flush() operation performed by the current client API causes a
new native fence object to be created, and the
EGL_SYNC_NATIVE_FENCE_ANDROID attribute of the EGL native fence object is
set to a file descriptor that refers to the new native fence object. This
new native fence object is signaled when the EGL native fence sync object
is signaled.
When the condition of the sync object is satisfied by the fence command,
the sync is signaled by the associated client API context, causing any
eglClientWaitSyncKHR commands (see below) blocking on <sync> to unblock.
If the sync object is an EGL native fence sync object then the native
fence object is also signaled when the condition is satisfied. The
EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR condition is satisfied by completion
of the fence command corresponding to the sync object and all preceding
commands in the associated client API context's command stream. The sync
object will not be signaled until all effects from these commands on the
client API's internal and framebuffer state are fully realized. No other
state is affected by execution of the fence command.
The EGL_SYNC_NATIVE_FENCE_SIGNALED_ANDROID condition is satisfied by the
signaling of the native fence object referred to by the
EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute. When this happens any
eglClientWaitSyncKHR commands blocking on <sync> unblock."
Modify the list of eglCreateSyncKHR errors in Section 3.8.1 (Sync Objects),
added by KHR_fence_sync
"Errors
------
* If <dpy> is not the name of a valid, initialized EGLDisplay,
EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is
generated.
* If <type> is EGL_SYNC_FENCE_KHR and <attrib_list> is neither NULL nor
empty (containing only EGL_NONE), EGL_NO_SYNC_KHR is returned and an
EGL_BAD_ATTRIBUTE error is generated.
* If <type> is EGL_SYNC_NATIVE_FENCE_ANDROID and <attrib_list> contains
an attribute other than EGL_SYNC_NATIVE_FENCE_FD_ANDROID,
EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is
generated.
* If <type> is not a supported type of sync object,
EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is
generated.
* If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and
no context is current for the bound API (i.e., eglGetCurrentContext
returns EGL_NO_CONTEXT), EGL_NO_SYNC_KHR is returned and an
EGL_BAD_MATCH error is generated.
* If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and
<dpy> does not match the EGLDisplay of the currently bound context for
the currently bound client API (the EGLDisplay returned by
eglGetCurrentDisplay()) then EGL_NO_SYNC_KHR is returned and an
EGL_BAD_MATCH error is generated.
* If <type> is EGL_SYNC_FENCE_KHR or EGL_SYNC_NATIVE_FENCE_ANDROID and
the currently bound client API does not support the client API
extension indicating it can place fence commands, then EGL_NO_SYNC_KHR
is returned and an EGL_BAD_MATCH error is generated."
Modify table 3.cc in Section 3.8.1 (Sync Objects), added by KHR_fence_sync
"
Attribute Description Supported Sync Objects
----------------- ----------------------- ----------------------
EGL_SYNC_TYPE_KHR Type of the sync object All
EGL_SYNC_STATUS_KHR Status of the sync object All
EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR and
EGL_SYNC_NATIVE_FENCE_ANDROID only
"
Modify the second paragraph description of eglDestroySyncKHR in Section
3.8.1 (Sync Objects), added by KHR_fence_sync
"If no errors are generated, EGL_TRUE is returned, and <sync> will no
longer be the handle of a valid sync object. Additionally, if <sync> is an
EGL native fence sync object and the EGL_SYNC_NATIVE_FENCE_FD_ANDROID
attribute is not EGL_NO_NATIVE_FENCE_FD_ANDROID then that file descriptor
is closed."
Add the following after the last paragraph of Section 3.8.1 (Sync
Objects), added by KHR_fence_sync
The command
EGLint eglDupNativeFenceFDANDROID(
EGLDisplay dpy,
EGLSyncKHR sync);
duplicates the file descriptor stored in the
EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of an EGL native fence sync
object and returns the new file descriptor.
Errors
------
* If <sync> is not a valid sync object for <dpy>,
EGL_NO_NATIVE_FENCE_FD_ANDROID is returned and an EGL_BAD_PARAMETER
error is generated.
* If the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute of <sync> is
EGL_NO_NATIVE_FENCE_FD_ANDROID, EGL_NO_NATIVE_FENCE_FD_ANDROID is
returned and an EGL_BAD_PARAMETER error is generated.
* If <dpy> does not match the display passed to eglCreateSyncKHR
when <sync> was created, the behaviour is undefined."
Issues
1. Should EGLSyncKHR objects that wrap native fence objects use the
EGL_SYNC_FENCE_KHR type?
RESOLVED: A new sync object type will be added.
We don't want to require all EGL fence sync objects to wrap native fence
objects, so we need some way to tell the EGL implementation at sync object
creation whether the sync object should support querying the native fence
FD attribute. We could do this with either a new sync object type or with a
boolean attribute. It might be nice to pick up future signaling conditions
that might be added for fence sync objects, but there may be things that
get added that don't make sense in the context of native fence objects.
2. Who is responsible for dup'ing the native fence file descriptors?
RESOLVED: Whenever a file descriptor is passed into or returned from an
EGL call in this extension, ownership of that file descriptor is
transfered. The recipient of the file descriptor must close it when it is
no longer needed, and the provider of the file descriptor must dup it
before providing it if they require continued use of the native fence.
3. Can the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute be queried?
RESOLVED: No.
Returning the file descriptor owned by the EGL implementation would
violate the file descriptor ownership rule described in issue #2. Having
eglGetSyncAttribKHR return a different (dup'd) file descriptor each time
it's called seems wrong, so a new function was added to explicitly dup the
file descriptor.
That said, the attribute is useful both as a way to pass an existing file
descriptor to eglCreateSyncKHR and as a way to describe the subsequent
behavior of EGL native fence sync objects, so it is left as an attribute
for which the value cannot be queried.
Revision History
#3 (Jamie Gennis, September 4, 2012)
- Reworded the extension to refer to "native fence" objects rather than
"Android fence" objects.
- Added a paragraph to the overview that describes assumptions about the
native fence sync objects.
#2 (Jamie Gennis, July 23, 2012)
- Changed the file descriptor ownership transferring behavior.
- Added the eglDupAndroidFenceFDANDROID function.
- Removed EGL_SYNC_NATIVE_FENCE_FD_ANDROID from the table of gettable
attributes.
- Added language specifying that a native Android fence is created at the
flush following the creation of an EGL Android fence sync object that is
not passed an existing native fence.
#1 (Jamie Gennis, May 29, 2012)
- Initial draft.
extensions/ANDROID/EGL_ANDROID_presentation_time.txt
+140
View File
@@ -0,0 +1,140 @@
Name
ANDROID_presentation_time
Name Strings
EGL_ANDROID_presentation_time
Contributors
Jamie Gennis
Andy McFadden
Jesse Hall
Contact
Jamie Gennis, Google Inc. (jgennis 'at' google.com)
Status
Draft
Version
Version 4, June 6, 2016
Number
EGL Extension #98
Dependencies
Requires EGL 1.1
This extension is written against the wording of the EGL 1.4 Specification
Overview
Often when rendering a sequence of images, there is some time at which each
image is intended to be presented to the viewer. This extension allows
this desired presentation time to be specified for each frame rendered to
an EGLSurface, allowing the native window system to use it.
New Types
/*
* EGLnsecsANDROID is a signed integer type for representing a time in
* nanoseconds.
*/
#include <khrplatform.h>
typedef khronos_stime_nanoseconds_t EGLnsecsANDROID;
New Procedures and Functions
EGLBoolean eglPresentationTimeANDROID(
EGLDisplay dpy,
EGLSurface surface,
EGLnsecsANDROID time);
New Tokens
None.
Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
Add a new subsection before Section 3.9.4, page 53 (Posting Errors)
"3.9.4 Presentation Time
The function
EGLBoolean eglPresentationTimeANDROID(EGLDisplay dpy, EGLSurface
surface, EGLnsecsANDROID time);
specifies the time at which the current color buffer of <surface> should be
presented to the viewer. The <time> parameter should be a time in
nanoseconds, but the exact meaning of the time depends on the native
window system's use of the presentation time. In situations where
an absolute time is needed such as displaying the color buffer on a
display device, the time should correspond to the system monotonic up-time
clock. For situations in which an absolute time is not needed such as
using the color buffer for video encoding, the presentation time of the
first frame may be arbitrarily chosen and those of subsequent frames
chosen relative to that of the first frame.
The presentation time may be set multiple times, with each call to
eglPresentationTimeANDROID overriding prior calls. Setting the
presentation time alone does not cause the color buffer to be made
visible, but if the color buffer is subsequently posted to a native window
or copied to a native pixmap then the presentation time of the surface at
that time may be passed along for the native window system to use.
If the surface presentation time is successfully set, EGL_TRUE is
returned. Otherwise EGL_FALSE is returned and an appropriate error is
set. If <dpy> is not the name of a valid, initialized EGLDisplay, an
EGL_BAD_DISPLAY error is generated. If <surface> is not a valid EGLSurface
then an EGL_BAD_SURFACE error is generated.
Issues
1. How is the presentation time used?
RESOLVED: The uses of the presentation time are intentionally not specified
in this extension. Some possible uses include Audio/Video synchronization,
video frame timestamps for video encoding, display latency metrics, and
display latency control.
2. How can the current value of the clock that should be used for the
presentation time when an absolute time is needed be queried on Android?
RESOLVED: The current clock value can be queried from the Java
System.nanoTime() method, or from the native clock_gettime function by
passing CLOCK_MONOTONIC as the clock identifier.
3. Should the presentation time be state which is used by eglSwapBuffers,
or should it be a new parameter to an extended variant of eglSwapBuffers?
RESOLVED: The presentation time should be new state which is used by
the existing eglSwapBuffers call. Adding new state composes better with
other (hypothetical) extensions that also modify the behavior of
eglSwapBuffers.
Revision History
#4 (Jon Leech, June 6, 2016)
- Clean up for publication. Make prototype parameter name 'surface'
match the spec body.
#3 (Jesse Hall, June 26, 2013)
- Enumerated errors generated by eglPresentationTimeANDROID.
- Added Issue #3 with resolution.
#2 (Jamie Gennis, April 1, 2013)
- Clarified how uses that either do or do not need an absolute time should
be handled.
- Specified the eglPresentationTimeANDROID return value.
#1 (Jamie Gennis, January 8, 2013)
- Initial draft.
extensions/ANDROID/EGL_ANDROID_recordable.txt
+140
View File
@@ -0,0 +1,140 @@
Name
ANDROID_recordable
Name Strings
EGL_ANDROID_recordable
Contributors
Jamie Gennis
Contact
Jamie Gennis, Google Inc. (jgennis 'at' google.com)
Status
Complete
Version
Version 2, July 15, 2011
Number
EGL Extension #51
Dependencies
Requires EGL 1.0
This extension is written against the wording of the EGL 1.4 Specification
Overview
Android supports a number of different ANativeWindow implementations that
can be used to create an EGLSurface. One implementation, which records the
rendered image as a video each time eglSwapBuffers gets called, may have
some device-specific restrictions. Because of this, some EGLConfigs may be
incompatible with these ANativeWindows. This extension introduces a new
boolean EGLConfig attribute that indicates whether the EGLConfig supports
rendering to an ANativeWindow that records images to a video.
New Types
None.
New Procedures and Functions
None.
New Tokens
Accepted by the <attribute> parameter of eglGetConfigAttrib and
the <attrib_list> parameter of eglChooseConfig:
EGL_RECORDABLE_ANDROID 0x3142
Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
Section 3.4, Configuration Management, add a row to Table 3.1.
Attribute Type Notes
---------------------- ------- --------------------------
EGL_RECORDABLE_ANDROID boolean whether video recording is
supported
Section 3.4, Configuration Management, add a row to Table 3.4.
Attribute Default Selection Sort Sort
Criteria Order Priority
---------------------- ------------- --------- ----- --------
EGL_RECORDABLE_ANDROID EGL_DONT_CARE Exact None
Section 3.4, Configuration Management, add a paragraph at the end of the
subsection titled Other EGLConfig Attribute Descriptions.
EGL_RECORDABLE_ANDROID is a boolean indicating whether the config may
be used to create an EGLSurface from an ANativeWindow that is a video
recorder as indicated by the NATIVE_WINDOW_IS_VIDEO_RECORDER query on
the ANativeWindow.
Section 3.4.1, Querying Configurations, change the last paragraph as follow
EGLConfigs are not sorted with respect to the parameters
EGL_BIND_TO_TEXTURE_RGB, EGL_BIND_TO_TEXTURE_RGBA, EGL_CONFORMANT,
EGL_LEVEL, EGL_NATIVE_RENDERABLE, EGL_MAX_SWAP_INTERVAL,
EGL_MIN_SWAP_INTERVAL, EGL_RENDERABLE_TYPE, EGL_SURFACE_TYPE,
EGL_TRANSPARENT_TYPE, EGL_TRANSPARENT_RED_VALUE,
EGL_TRANSPARENT_GREEN_VALUE, EGL_TRANSPARENT_BLUE_VALUE, and
EGL_RECORDABLE_ANDROID.
Issues
1. Should this functionality be exposed as a new attribute or as a bit in
the EGL_SURFACE_TYPE bitfield?
RESOLVED: It should be a new attribute. It does not make sense to use up a
bit in the limit-size bitfield for a platform-specific extension.
2. How should the new attribute affect the sorting of EGLConfigs?
RESOLVED: It should not affect sorting. Some implementations may not have
any drawback associated with using a recordable EGLConfig. Such
implementations should not have to double-up some of their configs to one
sort earlier than . Implementations that do have drawbacks can use the
existing caveat mechanism to report this drawback to the client.
3. How is this extension expected to be implemented?
RESPONSE: There are two basic approaches to implementing this extension
that were considered during its design. In both cases it is assumed that a
color space conversion must be performed at some point because most video
encoding formats use a YUV color space. The two approaches are
distinguished by the point at which this color space conversion is
performed.
One approach involves performing the color space conversion as part of the
eglSwapBuffers call before queuing the rendered image to the ANativeWindow.
In this case, the VisualID of the EGLConfig would correspond to a YUV
Android HAL pixel format from which the video encoder can read. The
EGLConfig would likely have the EGL_SLOW_CONFIG caveat because using that
config to render normal window contents would result in an RGB -> YUV color
space conversion when rendering the frame as well as a YUV -> RGB
conversion when compositing the window.
The other approach involves performing the color space conversion in the
video encoder. In this case, the VisualID of the EGLConfig would
correspond to an RGB HAL pixel format from which the video encoder can
read. The EGLConfig would likely not need to have any caveat set, as using
this config for normal window rendering would not have any added cost.
Revision History
#2 (Jamie Gennis, July 15, 2011)
- Added issue 3.
#1 (Jamie Gennis, July 8, 2011)
- Initial draft.
extensions/ANGLE/EGL_ANGLE_d3d_share_handle_client_buffer.txt
+98
View File
@@ -0,0 +1,98 @@
Name
ANGLE_d3d_share_handle_client_buffer
Name Strings
EGL_ANGLE_d3d_share_handle_client_buffer
Contributors
John Bauman
Alastair Patrick
Daniel Koch
Contacts
John Bauman, Google Inc. (jbauman 'at' chromium.org)
Status
Complete
Implemented (ANGLE r650)
Version
Version 3, May 12, 2011
Number
EGL Extension #38
Dependencies
Requires the EGL_ANGLE_surface_d3d_texture_2d_share_handle extension.
This extension is written against the wording of the EGL 1.4
Specification.
Overview
This extension allows creating EGL surfaces from handles to textures
shared from the Direct3D API or from
EGL_ANGLE_surface_texture_2d_share_handle.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted in the <buftype> parameter of eglCreatePbufferFromClientBuffer:
EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE 0x3200
Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
Replace the last sentence of paragraph 1 of Section 3.5.3 with the
following text.
"Currently, the only client API resources which may be bound in this
fashion are OpenVG VGImage objects and Direct3D share handles."
Replace the last sentence of paragraph 2 ("To bind a client API...") of
Section 3.5.3 with the following text.
"When <buftype> is EGL_OPENVG_IMAGE, the width and height of the pbuffer
are determined by the width and height of <buffer>. When <buftype> is
EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE, the width and height are specified
using EGL_WIDTH and EGL_HEIGHT, or else they default to zero. The width
and height must match the dimensions of the texture which the share handle
was created from or else an EGL_BAD_ALLOC error is generated."
Replace the third paragraph of Section 3.5.3 with the following text.
"<buftype> specifies the type of buffer to be bound. The only allowed values
of <buftype> are EGL_OPENVG_IMAGE and
EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE".
Append the following text to the fourth paragraph of Section 3.5.3.
"When <buftype> is EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE, <buffer> must be
a valid D3D share handle, cast into the type EGLClientBuffer. The handle
may be obtained from the Direct3D9Ex CreateTexture function, from DXGI's
GetSharedHandle method on an ID3D10Texture2D, or from the
EGL_ANGLE_surface_d3d_texture_2d_share_handle extension."
Issues
Revision History
Version 3, 2011/05/12
- publish
Version 2, 2011/05/03
- specify EGL_D3D_TEXTURE_2D_SHARE_HANDLE
- specify error if dimensions don't match
Version 1, 2011/04/12 - first draft.
extensions/ANGLE/EGL_ANGLE_device_d3d.txt
+93
View File
@@ -0,0 +1,93 @@
Name
ANGLE_device_d3d
Name Strings
EGL_ANGLE_device_d3d
Contributors
Jamie Madill (jmadill 'at' google.com)
Contact
Jamie Madill (jmadill 'at' google.com)
Status
Complete.
Version
Version 1, Mar 25, 2015
Number
EGL Extension #90
Extension Type
EGL device extension
Dependencies
This extension is written against the language of EGL 1.5 as
modified by EGL_EXT_device_query.
EGL_EXT_device_query is required.
Overview
ANGLE has the ability to run GPU commands on a native D3D device.
This extension defines a mapping from an EGL device to a D3D
device, after it's queried from an EGL display.
IP Status
No known claims.
New Types
None.
New Procedures and Functions
None.
New Tokens
Accepted as a queried <attribute> in eglQueryDeviceAttribEXT:
EGL_D3D9_DEVICE_ANGLE 0x33A0
EGL_D3D11_DEVICE_ANGLE 0x33A1
Add a new section 2.1.3 (D3D Devices) after 2.1.2 (Devices)
Somewhat analogous to an EGL device, a D3D device establishes a
namespace for D3D operations. In the D3D APIs, such devices are
represented by pointers. For more details, see the D3D
documentation.
Changes to section 3.2 (Devices)
Replace the paragraph immediately following the prototype for
eglQueryDeviceAttribEXT:
<attribute> may be either EGL_D3D9_DEVICE_ANGLE or EGL_D3D11_DEVICE_ANGLE.
On success, EGL_TRUE is returned, and a valid D3D9 or D3D11 device pointer
corresponding to the EGL device is returned in <value>. This handle
is compatible with D3D API functions. If the EGL device is not currently
associated with a D3D9 device and <attribute> is EGL_D3D9_DEVICE_ANGLE,
or if the EGL device is not currently associated with a D3D11 device and
<attribute> is EGL_D3D11_DEVICE_ANGLE, EGL_BAD_ATTRIBUTE is returned,
and <value> is left unchanged.
Issues
None
Revision History
Version 1, Mar 25, 2015 (Jamie Madill)
- Initial Draft
extensions/ANGLE/EGL_ANGLE_query_surface_pointer.txt
+88
View File
@@ -0,0 +1,88 @@
Name
ANGLE_query_surface_pointer
Name Strings
EGL_ANGLE_query_surface_pointer
Contributors
Vladimir Vukicevic
Daniel Koch
Contacts
Vladimir Vukicevic (vladimir 'at' pobox.com)
Status
Complete
Implemented (ANGLE r558)
Version
Version 3, February 11, 2011
Number
EGL Extension #28
Dependencies
This extension is written against the wording of the EGL 1.4
Specification.
Overview
This extension allows querying pointer-sized surface attributes,
thus avoiding problems with coercing 64-bit pointers into a 32-bit
integer.
New Types
None
New Procedures and Functions
EGLBoolean eglQuerySurfacePointerANGLE(
EGLDisplay dpy,
EGLSurface surface,
EGLint attribute,
void **value);
New Tokens
None
Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
Add to the end of the paragraph starting with "To query an
attribute associated with an EGLSurface" in section 3.5.6,
"Surface Attributes":
"If the attribute type in table 3.5 is 'pointer', then
eglQuerySurface returns EGL_FALSE and an EGL_BAD_PARAMETER error
is generated. To query pointer attributes, call:
EGLBoolean eglQuerySurfacePointerANGLE(
EGLDisplay dpy,
EGLSurface surface,
EGLint attribute,
void **value);
eglQuerySurfacePointerANGLE behaves identically to eglQuerySurface,
except that only attributes of type 'pointer' can be queried.
If an attribute queried via eglQuerySurfacePointerANGLE is not
of type 'pointer', then eglQuerySurfacePointer returns EGL_FALSE
and an EGL_BAD_PARAMETER error is generated."
Issues
Revision History
Version 3, 2011/02/11 - publish
Version 2, 2010/12/21 - fix typos.
Version 1, 2010/12/07 - first draft.
extensions/ANGLE/EGL_ANGLE_surface_d3d_texture_2d_share_handle.txt
+95
View File
@@ -0,0 +1,95 @@
Name
ANGLE_surface_d3d_texture_2d_share_handle
Name Strings
EGL_ANGLE_surface_d3d_texture_2d_share_handle
Contributors
Vladimir Vukicevic
Daniel Koch
Contacts
Vladimir Vukicevic (vladimir 'at' pobox.com)
Status
Complete
Implemented (ANGLE r558)
Version
Version 2, December 21, 2010
Number
EGL Extension #29
Dependencies
Requires the EGL_ANGLE_query_surface_pointer extension.
This extension is written against the wording of the EGL 1.4
Specification.
Overview
Some EGL implementations generate EGLSurface handles that are
backed by Direct3D 2D textures. For such surfaces, a D3D share
handle can be generated, allowing access to the same surface
from the Direct3D API.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted in the <attribute> parameter of eglQuerySurfacePointerANGLE:
EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE 0x3200
Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
Add to table 3.5, "Queryable surface attributes and types":
Attribute Type Description
--------- ---- -----------
EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE pointer Direct3D share handle
Add before the last paragraph in section 3.5, "Surface attributes":
"Querying EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE returns a Direct3D
share handle, or NULL if a share handle for the surface is not
available. The share handle must be queried using
eglQuerySurfaceAttribPointerANGLE. Before using a Direct3D surface
created with this share handle, ensure that all rendering
to the EGLSurface with EGL client APIs has completed.
The Direct3D share handle may be passed as the pSharedHandle
parameter of the Direct3D9Ex CreateTexture function, or via the
Direct3D10 OpenSharedResource function. If used with Direct3D 9,
the level argument to CreateTexture must be 1, and the dimensions
must match the dimensions of the EGL surface. If used with
Direct3D 10, OpenSharedResource should be called with the
ID3D10Texture2D uuid to obtain an ID3D10Texture2D object.
Issues
Revision History
Version 3, 2011/02/11 - publish
Version 2, 2010/12/21
- renamed token to EGL_D3D_TEXTURE_2D_SHARE_HANDLE_ANGLE (adding "2D")
- renamed extension to ANGLE_surface_d3d_texture_2d_share_handle
- added language about supported usage of the shared handle from D3D
Version 1, 2010/12/07 - first draft.
extensions/ANGLE/EGL_ANGLE_sync_control_rate.txt
+99
View File
@@ -0,0 +1,99 @@
Name
ANGLE_sync_control_rate
Name Strings
EGL_ANGLE_sync_control_rate
Contact
Jonah Ryan-Davis, Google (jonahr 'at' google.com)
Status
Draft.
Version
Version 1, 2020-03-24
Based on GLX_OML_sync_control Revision 6.0
Related to EGL_CHROMIUM_sync_control Revision 2.0
Number
142
Dependencies
The extension is written against the EGL 1.2 Specification, although it
should work on other versions of these specifications.
Overview
This extension provides counters which let applications know about the
timing of the last vertical retrace. By looking at the system clock, as
well as the refresh rate of the monitor, this should enable applications
to predict the position of future retraces so as to schedule an optimal
workload.
This extension incorporates the use of a counter that provides the
necessary synchronization. The graphics Media Stream Counter (or
graphics MSC) is a counter that is unique to the graphics subsystem
and increments for each vertical retrace that occurs.
By querying the MSC rate for a given surface, the application can
accurately predict the timing for the next vertical retraces and schedule
rendering accordingly.
Issues
None.
IP Status
No known issues.
New Procedures and Functions
Bool eglGetMscRateANGLE(EGLDisplay* dpy,
EGLSurface surface,
int32_t* numerator,
int32_t* denominator)
New Tokens
None
Additions to the EGL 1.3 Specification
The graphics MSC value is incremented once for each screen refresh.
For a non-interlaced display, this means that the graphics MSC value
is incremented for each frame. For an interlaced display, it means
that it will be incremented for each field. For a multi-monitor
system, the monitor used to determine MSC is the one where the surface
is located. If the surface spans multiple monitors, the monitor used
to determine MSC is the one with the biggest coverage in pixels.
eglGetMscRateANGLE returns the rate at which the MSC will be incremented
for the display associated with <dpy> and <surface>. The rate is expressed
in Hertz as <numerator> / <denominator>. If the MSC rate in Hertz is an
integer, then <denominator> will be 1 and <numerator> will be
the MSC rate.
Errors
The function eglGetMscRateANGLE returns FALSE on failure.
If <dpy> is not a valid EGLDisplay, EGL_BAD_DISPLAY is generated.
If <surface> is not a valid EGLSurface, EGL_BAD_SURFACE is generated.
If there is no current EGLContext, EGL_BAD_CONTEXT is generated.
New Implementation Dependent State
None
Revision History
Version 1, 2020-03-24 (Jonah Ryan-Davis)
- Initial draft, based on GLX_OML_sync_control revision 6.0.
extensions/ANGLE/EGL_ANGLE_window_fixed_size.txt
+136
View File
@@ -0,0 +1,136 @@
Name
ANGLE_window_fixed_size
Name Strings
EGL_ANGLE_window_fixed_size
Contributors
John Bauman
Shannon Woods
Contacts
John Bauman, Google Inc. (jbauman 'at' google.com)
Status
Complete
Version
Version 4, February 24, 2014
Number
EGL Extension #85
Dependencies
This extension is written against the wording of the EGL 1.4
Specification.
Overview
This extension allows creating a window surface with a fixed size that is
specified when it is created.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted by the <attribute> parameter of eglQuerySurface and by the
<attrib_list> parameter of eglCreateWindowSurface:
EGL_FIXED_SIZE_ANGLE 0x3201
Additions to Chapter 3 of the EGL 1.4 Specification:
Modify the third paragraph of Section 3.5.1 (Creating On-Screen Rendering Surfaces)
"<attrib_list> specifies a list of attributes for the window. The list has
the same structure as described for eglChooseConfig. Attributes that can
be specified in <attrib_list> include EGL_RENDER_BUFFER,
EGL_VG_COLORSPACE, EGL_VG_ALPHA_FORMAT, EGL_FIXED_SIZE_ANGLE, EGL_WIDTH,
and EGL_HEIGHT."
Add before the last paragraph of Section 3.5.1
"EGL_FIXED_SIZE_ANGLE specifies whether the surface must be resized by the
implementation when the native window is resized. The default value is
EGL_FALSE. Its value can be EGL_TRUE, in which case the size must be
specified when the window is created, or EGL_FALSE, in which case the size
is taken from the native window. Its default value is EGL_FALSE.
If the value of EGL_FIXED_SIZE_ANGLE is EGL_TRUE, the window surface's
size in pixels is specified by the EGL_WIDTH and EGL_HEIGHT attributes,
and will not change throughout the lifetime of the surface. If its value
is EGL_FALSE, then the values of EGL_WIDTH and EGL_HEIGHT are ignored and
the window surface must be resized by the implementation subsequent to the
native window being resized, and prior to copying its contents to the
native window (e.g. in eglSwapBuffers, as described in section 3.9.1.1).
The default values for EGL_WIDTH and EGL_HEIGHT are zero. If the value
specified for either of EGL_WIDTH or EGL_HEIGHT is less than zero then an
EGL_BAD_PARAMETER error is generated."
Add the following entry to Table 3.5
(Queryable surface attributes and types)
Attribute Type Description
-------------------- ------- ---------------------------------------------
EGL_FIXED_SIZE_ANGLE boolean Surface will not be resized with a native
window
Replace the last paragraph on page 37 in Section 3.5.6 (Surface Attributes)
"Querying EGL_WIDTH and EGL_HEIGHT returns respectively the width and
height, in pixels, of the surface. For a pixmap surface or window surface
with EGL_FIXED_SIZE_ANGLE set to EGL_FALSE, these values are initially
equal to the width and height of the native window or pixmap with respect
to which the surface was created. If the native window is resized and the
corresponding window surface is not fixed size, the corresponding window
surface will eventually be resized by the implementation to match (as
discussed in section 3.9.1). If there is a discrepancy because EGL has not
yet resized the window surface, the size returned by eglQuerySurface will
always be that of the EGL surface, not the corresponding native window."
Add the following paragraph to Section 3.5.6 (Surface Attributes)
"Querying EGL_FIXED_SIZE_ANGLE returns EGL_FALSE if the surface will be
resized to match a native window, and EGL_TRUE if the surface cannot be
resized."
Alter the beginning of the first paragraph of Section 3.9.1.1 (Native
Window Resizing)
"If <surface> does not have EGL_FIXED_SIZE_ANGLE set and the native window
corresponding to <surface> has been resized prior to the swap, <surface>
must be resized to match."
Issues
1. Should there be a way to resize a window surface that had its size
specified initially.
RESOLVED: No. Surfaces that have their sizes specified initially must have
EGL_FIXED_SIZE_ANGLE set and can never be resized.
Revision History
Version 4, 2014/02/24 - formatting changes.
Version 3, 2014/02/12 - ignore EGL_WIDTH and EGL_HEIGHT if
EGL_FIXED_SIZE_ANGLE is EGL_FALSE
Version 2, 2014/02/07 - rename to EGL_ANGLE_window_fixed_size, and add an
EGL_FIXED_SIZE_ANGLE token.
Version 1, 2014/02/05 - first draft.
extensions/ARM/EGL_ARM_image_format.txt
+126
View File
@@ -0,0 +1,126 @@
Name
ARM_image_format
Name Strings
EGL_ARM_image_format
Contributors
Jan-Harald Fredriksen
Contact
Jan-Harald Fredriksen (jan-harald.fredriksen 'at' arm.com)
IP Status
No known IP claims.
Status
Complete
Version
Version 1 - February 18, 2020
Number
138
Dependencies
This extension is written against the wording of the EGL 1.4
specification.
This extension reuses tokens from EGL_EXT_pixel_format_float.
Overview
When an EGLImage is created from an existing image resource the
implementation will deduce the format of the image data from that
resource. In some cases, however, the implementation may not know how to
map the existing image resource to a known format. This extension extends
the list of attributes accepted by eglCreateImageKHR such that applications
can tell the implementation how to interpret the data.
New Procedures and Functions
None.
New Tokens
Accepted as an attribute name in the <attrib_list> argument of
eglCreateImageKHR:
EGL_COLOR_COMPONENT_TYPE_EXT 0x3339
Accepted as attribute values for the EGL_COLOR_COMPONENT_TYPE_EXT attribute
of eglCreateImageKHR:
EGL_COLOR_COMPONENT_TYPE_FIXED_EXT 0x333A
EGL_COLOR_COMPONENT_TYPE_FLOAT_EXT 0x333B
EGL_COLOR_COMPONENT_TYPE_UNSIGNED_INTEGER_ARM 0x3287
EGL_COLOR_COMPONENT_TYPE_INTEGER_ARM 0x3288
EGL_RED_SIZE 0x3024
EGL_GREEN_SIZE 0x3023
EGL_BLUE_SIZE 0x3022
EGL_ALPHA_SIZE 0x3021
Modifications to the EGL 1.4 Specification
Add the following rows to Table 3.xx: Legal attributes for
eglCreateImageKHR <attrib_list> parameter:
+------------------------------+------------------------------+-----------+---------------+
| Attribute | Description | Valid | Default Value |
| | | <target>s | |
+------------------------------+------------------------------+-----------+---------------+
| EGL_COLOR_COMPONENT_TYPE_EXT | Specifies the component | All | NA |
| | type the EGLImage source | | |
| | is interpreted as | | |
| EGL_RED_SIZE | Specifies the red component | All | NA |
| | size the EGLImage source | | |
| | is interpreted as | | |
| EGL_GREEN_SIZE | Specifies the green component| All | NA |
| | size the EGLImage source | | |
| | is interpreted as | | |
| EGL_BLUE_SIZE | Specifies the blue component | All | NA |
| | size the EGLImage source | | |
| | is interpreted as | | |
| EGL_ALPHA_SIZE | Specifies the alpha component| All | NA |
| | size the EGLImage source | | |
| | is interpreted as | | |
+------------------------------+------------------------------+-----------+---------------+
If <attrib_list> specifies values for EGL_COLOR_COMPONENT_TYPE_EXT,
EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE, or EGL_ALPHA_SIZE, the
implementation will treat these as hints for how to interpret the contents
of <buffer>.
EGL_COLOR_COMPONENT_TYPE_EXT indicates the component type of <buffer> and
must be either EGL_COLOR_COMPONENT_TYPE_FIXED_EXT for fixed-point,
EGL_COLOR_COMPONENT_TYPE_FLOAT_EXT for floating-point,
EGL_COLOR_COMPONENT_TYPE_UNSIGNED_INTEGER_ARM for unsigned integer, or
EGL_COLOR_COMPONENT_TYPE_INTEGER_ARM for integer components.
Add to the list of error conditions for eglCreateImageKHR:
* If the implementation is unable to interpret the contents <buffer>
according to the component types and sizes in <attrib_list>, then a
EGL_BAD_MATCH error is generated.
Issues
1. Should there be a way to specify the component order?
Resolved. No, the component order is interpreted to be R, G, B, A,
with R mapping to component 0. If the application needs a different
component order it can use swizzle in the client API side or in the
shader.
Revision History
Version 1, 2020/02/18
- Internal revisions
extensions/ARM/EGL_ARM_implicit_external_sync.txt
+219
View File
@@ -0,0 +1,219 @@
Name
ARM_implicit_external_sync
Name Strings
EGL_ARM_implicit_external_sync
Contributors
David Garbett
Ray Smith
Contacts
David Garbett, ARM Ltd. (david 'dot' garbett 'at' arm 'dot' com)
Status
Draft
Version
Version 1, September 8, 2014
Number
EGL Extension #103
Dependencies
Requires EGL 1.1.
This extension is written against the wording of the EGL 1.2 Specification.
EGL_KHR_fence_sync is required.
Overview
This extension extends the "fence sync objects" defined in
EGL_KHR_fence_sync. It allows the condition that triggers the associated
fence command in the client API command stream to be explicitly specified on
fence object creation. It introduces a new condition that can be used to
ensure ordering between operations on buffers that may be accessed
externally to the client API, when those operations use an implicit
synchronization mechanism. Such a fence object will be signaled when all
prior commands affecting such buffers are guaranteed to be executed before
such external commands.
Applications have limited control over when a native buffer is read or
written by the GPU when imported as an EGLImageKHR or via
eglCreatePixmapSurface, which is controlled by the EGL and client API
implementations. While eglWaitClient or a client call such as glFinish
could be called, this forces all rendering to complete, which can result in
CPU/GPU serialization. Note this isn't an issue for window surfaces, where
eglSwapBuffers ensures the rendering occurs in the correct order for the
platform.
Some platforms have an implicit synchronization mechanism associated with
native resources, such as buffers. This means that accesses to the buffer
have an implicit ordering imposed on them, without involvement from the
application. However, this requires that an application that has imported
an affected buffer into EGL has a mechanism to flush any drawing operations
in flight such that they are waiting on the synchronization mechanism.
Otherwise the application cannot guarantee that subsequent operations (such
as displaying a rendered buffer) will occur after the commands performed by
the client API (such as rendering the buffer).
The mechanism to wait for the synchronization mechanism should not require
the application to wait for all rendering to complete, so that it can
continue preparing further commands asynchronously to the queued commands.
This extension provides this functionality using the new condition type for
fence sync objects, so the application only waits for the external
synchronization.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted as a value of the EGL_SYNC_CONDITION_KHR attribute passed in the
<attrib_list> list to eglCreateSyncKHR when <type> is EGL_FENCE_SYNC_KHR,
and can populate <*value> when eglGetSyncAttribKHR is called with
<attribute> set to EGL_SYNC_CONDITION_KHR:
EGL_SYNC_PRIOR_COMMANDS_IMPLICIT_EXTERNAL_ARM 0x328A
Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
Add the following after the fifth paragraph of Section 3.8.1 (Sync Objects),
added by KHR_fence_sync:
"Typically client APIs are considered to execute commands in a linear queue,
where a prior command is executed and completes before a later command is
started. By default fence sync objects adhere to this model - a fence is
signaled once prior commands have completed. However on some platforms a
command in a client API may transition through multiple states before it
completes, which may impact other components of the system. Therefore the
condition that all prior commands must meet before the fence is triggered is
configurable."
Replace the sixth paragraph of Section 3.8.1 (Sync Objects), added by
KHR_fence_sync:
"If, <type> is EGL_SYNC_FENCE_KHR, a fence sync object is created. In this
case <attrib_list> can be NULL or empty, or can specify the
EGL_SYNC_CONDITION_KHR attribute. Attributes of the fence sync object have
the following default values:"
Replace the eighth paragraph of Section 3.8.1 (Sync Objects), added by
KHR_fence_sync:
"When the condition of the sync object is satisfied by the fence command,
the sync is signaled by the associated client API context, causing any
eglClientWaitSyncKHR commands (see below) blocking on <sync> to unblock. The
condition is specified by the EGL_SYNC_CONDITION_KHR attribute passed to
eglCreateSyncKHR.
If the condition is specified as EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR, the
fence sync object is satisfied by completion of the fence command
corresponding to the sync object, and all preceding commands in the
associated client API context's command stream. The sync object will not be
signaled until all effects from these commands on the client API's internal
and framebuffer state are fully realized. No other state is affected by
execution of the fence command.
If the condition is specified as
EGL_SYNC_PRIOR_COMMANDS_IMPLICIT_EXTERNAL_ARM, the fence sync object is
satisfied by the completion of the fence command corresponding to the sync
object, and the <submission> of all preceding commands in the associated
client API context's command stream. <Submission> defines the point in time
when a command has been queued on any implicit synchronization mechanisms
present on the platform which apply to any of the resources used by the
command. This enforces an ordering, as defined by the synchronization
mechanism, between the command and any other operations that also respect
the synchronization mechanism(s)."
Replace the second entry in the list of eglCreateSyncKHR errors in Section
3.8.1 (Sync Objects), added by KHR_fence_sync:
" * If <type> is EGL_SYNC_FENCE_KHR and <attrib_list> contains an attribute
other than EGL_SYNC_CONDITION_KHR, EGL_NO_SYNC_KHR is returned and an
EGL_BAD_ATTRIBUTE error is generated.
* If <type> is EGL_SYNC_FENCE_KHR and the value specified for
EGL_SYNC_CONDITION_KHR is not EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR or
EGL_SYNC_PRIOR_COMMANDS_SUBMITTED_ARM, EGL_NO_SYNC_KHR is returned and
an EGL_BAD_ATTRIBUTE error is generated."
Issues
1. Could glFlush guarantee commands are submitted, making this extension
unnecessary?
RESOLVED: The Open GL ES 3.1 specification defines glFlush() as causing "all
previously issued GL commands to complete in finite time". There is no
requirement for the execution of commands to reach any specific point before
it returns - a valid implementation of glFlush() could spawn a new thread
that sleeps for a minute before submitting the pending commands. While an
implementation could decide to ensure all commands are submitted within
glFlush(), it could not be assumed to be the case across all
implementations.
In addition, there may be scenarios when submitting commands within
glFlush() is harmful. Waiting for command submission may have a performance
impact on some implementations that perform processing of commands
asynchronously. In addition such a change may restrict what is possible in
the future. For example if user events were introduced into OpenGL ES they
have the potential of introducing deadlocks if submission in glFlush() is
guaranteed.
2. Should a new entry point be defined that flushes commands synchronously,
instead of the new fence type as defined by this extension?
RESOLVED: While a synchronous "flush and submit" entrypoint would meet the
requirements for this extension, there may be a small benefit in enabling
the application to continue processing between flushing and waiting for
submission. In addition, the semantics of the existing EGL_KHR_fence_sync
extension closely match what is required for this extension, so defining
the new functionality in terms of fences may enable simpler implementations.
3. Should OpenGL ES 3 glFenceSync be extended in preference to
eglCreateSyncKHR?
RESOLVED: Some platforms are yet to move to a OpenGL ES 3 implementation, or
may be unwilling to expose OpenGL ES 3 entrypoints to applications. As
EGL_KHR_fence_sync is older than OpenGL ES 3, and is comparatively a small
change, it has a better chance of adoption in a platform.
In addition this extension is based on the idea that there are
platform-specific ways to interact with the client API command stream. As
this is platform-specific, and does not fit with the existing model
typically used by client APIs (such as Open GL ES) it is better placed in
EGL.
Finally extending EGL has the advantage that the extension applies to all
client APIs.
4. Should a new <type> parameter be defined, instead of extending the
EGL_FENCE_SYNC_KHR fence sync objects defined by EGL_KHR_fence_sync?
RESOLVED: Whether the new functionality is defined as an extension to the
existing fence sync objects, or whether they are defined as a new type of
sync object, we must acknowledge that the model of a client API processing
commands serially (with prior commands completing before later commands are
executed) is too simplistic for some platforms.
Extending the existing fence sync objects allows us to use the existing
concept of conditions that trigger the fences. It also allows the maximum
amount of reuse of existing functionality, potentially simplifying the
implementation and the use of the extension by applications.
Revision History
#1 (David Garbett, September 8, 2014)
- Initial draft.
extensions/ARM/EGL_ARM_pixmap_multisample_discard.txt
+185
View File
@@ -0,0 +1,185 @@
Name
ARM_pixmap_multisample_discard
Name Strings
EGL_ARM_pixmap_multisample_discard
Contributors
Arne Bergene Fossaa
Tom Cooksey
Endre Sund
David Garbett
Contacts
Tom Cooksey (tom 'dot' cooksey 'at' arm 'dot' com)
Status
Complete.
Version
Version 1, March 5, 2013
Number
EGL Extension #54
Dependencies
EGL 1.0 is required.
This extension is written against the wording of the EGL 1.4 Specification.
Overview
ARM_pixmap_multisample_discard adds an attribute to eglCreatePixmapSurface
that allows the client API implementation to resolve a multisampled pixmap
surface, therefore allowing the multisample buffer to be discarded.
Some GPU architectures - such as tile-based renderers - are capable of
performing multisampled rendering by storing multisample data in internal
high-speed memory and downsampling the data when writing out to external
memory after rendering has finished. Since per-sample data is never written
out to external memory, this approach saves bandwidth and storage space. In
this case multisample data gets discarded, however this is acceptable in
most cases.
The extension provides the EGL_DISCARD_SAMPLES_ARM attribute that allows
for implicit resolution when rendering to a pixmap surface. This complements
the OpenGL ES EXT_multisampled_render_to_texture extension which provides
similar functionality for rendering to an OpenGL ES texture.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted as an attribute name in the <attrib_list> argument of
eglCreatePixmapSurface and by the <attribute> parameter of eglQuerySurface:
EGL_DISCARD_SAMPLES_ARM 0x3286
Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
Modify the second paragraph under "The Multisample Buffer" of Section 3.4,
page 18 (Configuration Management)
"Operations such as posting a surface with eglSwapBuffers (see section
3.9.1, copying a surface with eglCopyBuffers (see section 3.9.2), reading
from the color buffer using client API commands, binding a client API
context to a surface (see section 3.7.3), and flushing to a pixmap surface
created with the EGL_DISCARD_SAMPLES_ARM attribute enabled (see
section 3.5.4) may cause resolution of the multisample buffer to the color
buffer."
Modify the fifth paragraph under "The Multisample Buffer" of Section 3.4,
page 18 (Configuration Management)
"There are no single-sample depth or stencil buffers for a multisample
EGLConfig, or with a pixmap surface created with the
EGL_DISCARD_SAMPLES_ARM attribute (see section 3.5.4). The only depth and
stencil buffers are those in the multisample buffer. If the color samples
in the multisample buffer store fewer bits than are stored in the color
buffers, this fact will not be reported accurately. Presumably a
compression scheme is being employed, and is expected to maintain an
aggregate resolution equal to that of the color buffers."
Modify the fifth paragraph of Section 3.5.4, page 34 (Creating Native
Pixmap Rendering Surfaces)
"attrib list specifies a list of attributes for the pixmap. The list has the
same structure as described for eglChooseConfig. Attributes that can be
specified in attrib list include EGL_VG_COLORSPACE, EGL_VG_ALPHA_FORMAT and
EGL_DISCARD_SAMPLES_ARM."
Add the following between paragraphs eight and nine of Section 3.5.4,
page 34 (Creating Native Pixmap Rendering Surfaces)
"EGL_DISCARD_SAMPLES_ARM specifies whether the client API implementation is
allowed to implicitly resolve the multisample buffer. On some GPU
architectures - such as tile-based renderers - an implicit resolve can avoid
writing the multisample buffer back to external memory as the multisample
data is stored in internal high-speed memory.
The implicit resolve can occur when the client API uses the pixmap as the
source or destination of any operation, when flushing to the pixmap or when
the client API unbinds (or breaks) the pixmap. When these operations occur
is dependent on the client API implementation. They can occur as an explicit
part of client API functions (such as glFinish, glReadPixels and
glCopyTexImage) or they can occur implicitly.
Further rendering causes the implementation to read the surface buffer and
any ancillary buffers back in as single-sampled data.
Therefore use of this attribute may result in lower quality images.
Valid values are EGL_TRUE, in which case the multisample buffer can be
discarded, or EGL_FALSE, in which case the multisample buffer is preserved.
The default value is EGL_FALSE.
Note that the multisample buffer may be discarded during eglMakeCurrent
regardless of the value of the EGL_DISCARD_SAMPLES_ARM attribute (see
section 3.7.3)."
Modify the ninth paragraph of Section 3.5.4, page 34 (Creating Native
Pixmap Rendering Surfaces)
"On failure eglCreatePixmapSurface returns EGL_NO_SURFACE. If the attributes
of pixmap do not correspond to config, then an EGL_BAD_MATCH error is
generated. If config does not support rendering to pixmaps (the
EGL_SURFACE_TYPE attribute does not contain EGL_PIXMAP_BIT), an
EGL_BAD_MATCH error is generated. If config does not support the colorspace
or alpha format attributes specified in attriblist (as defined for
eglCreateWindowSurface), an EGL_BAD_MATCH error is generated. If config does
not specify non-zero EGL_SAMPLES and EGL_SAMPLE_BUFFERS and the
EGL_DISCARD_SAMPLES_ARM attribute is set to EGL_TRUE, then an EGL_BAD_MATCH
error is generated. If config is not a valid EGLConfig, an EGL_BAD_CONFIG
error is generated. If pixmap is not a valid native pixmap handle, then an
EGL_BAD_NATIVE_PIXMAP error should be generated. If there is already an
EGLSurface associated with pixmap (as a result of a previous
eglCreatePixmapSurface call), then a EGL_BAD_ALLOC error is generated.
Finally, if the implementation cannot allocate resources for the new EGL
pixmap, an EGL_BAD_ALLOC error is generated."
Add the following entry to Table 3.5, page 36
(Queryable surface attributes and types)
Attribute Type Description
------------------------- ------- ---------------------------------------
EGL_DISCARD_SAMPLES_ARM boolean Multisample resolve when flushing to
surface
Add the following paragraph before the last paragraph of Section 3.5.7,
page 38 (Surface Attributes)
"Querying EGL_DISCARD_SAMPLES_ARM returns whether a multisample resolve
is forced on every flush to the surface (see section 3.5.4). This will only
return EGL_TRUE for pixmap surfaces created with the EGL_DISCARD_SAMPLES_ARM
attribute set to EGL_TRUE. EGL_FALSE will be returned for window and
pbuffer surfaces."
Issues
1. Should eglSurfaceAttrib accept EGL_DISCARD_SAMPLES_ARM?
RESOLVED: No. The attribute should be decided at surface creation time.
2. Should eglCreateWindowSurface or eglCreatePbufferSurface accept
EGL_DISCARD_SAMPLES_ARM?
RESOLVED: No. While the attribute could equally apply to window and
pbuffer surfaces, no use case has been identified to justify the
additional maintenance this would require.
Revision History
Version 1, 2013/03/05 - Original release.
extensions/EXT/EGL_EXT_bind_to_front.txt
+108
View File
@@ -0,0 +1,108 @@
Name
EXT_bind_to_front
Name Strings
EGL_EXT_bind_to_front
Contributors
Daniel Herring
Contacts
Daniel Herring, Core Avionics & Industrial Inc., daniel dot herring at ch1group dot com
Status
Complete
Version
Version 1.0, February 21, 2017
Number
EGL Extension #121
Dependencies
Requires EGL 1.2.
Overview
This extension allows for using double buffered Pbuffers for rendering to textures, by
allowing a new enumeration to be used in eglBindTexImage. EGL_FRONT_BUFFER_EXT is used
to denote reading the textures data from the front buffer of a double buffered Pbuffer.
New Types
None
New Procedures and Functions
None
New Tokens
EGL_FRONT_BUFFER_EXT 0x3464
Modify Section 3.6.1 of the EGL 1.2 Specification, paragraph 1
Add EGL_FRONT_BUFFER_EXT to list of acceptable values for buffer attribute.
Modify Section 3.6.2 of the EGL 1.2 Specification, paragraph 5
Add EGL_FRONT_BUFFER_EXT to list of acceptable values for buffer attribute.
Modify Section 3.5.2 of the EGL 1.2 Specification, paragraph 4
Add EGL_RENDER_BUFFER to list of attributes which can be accepted in attrib_list.
Add to Section 3.5.2 of the EGL 1.2 Specification
EGL_RENDER_BUFFER specifies the number of color buffers which should be useable by the
client API rendering to the Pbuffer. If its value is EGL_SINGLE_BUFFER, then there is
one color buffer the client APIs will render to directly. If its value is EGL_BACK_BUFFER,
then there are at least two color buffers the client API can render to. eglSwapBuffers
is used to switch which color buffer is currently being rendered to. By default, all
client APIs should render into the back buffer. The default value of EGL_RENDER_BUFFER
is EGL_SINGLE_BUFFER.
Modify Section 2.2.2 of the EGL 1.2 Specification, paragraph 2
Pbuffer surfaces have a back buffer but no associated window, so the back buffer
need not be copied.
Change to:
Pbuffer surfaces have no associated window, and include a back buffer, used by
default, for rendering to by the client API. Pbuffers may have a front buffer
used during render to texture operations to provide a read only texture which may
be used while the back buffer is being rendered to.
Modify Section 3.5.6
Querying EGL RENDER BUFFER returns the buffer which client API rendering
is requested to use. For a window surface, this is the same attribute value
specified when the surface was created. For a Pbuffer surface, it is always
EGL BACK BUFFER. For a pixmap surface, it is always EGL SINGLE BUFFER. To
determine the actual buffer being rendered to by a context, call eglQueryContext
(see section 3.7.4).
Change to:
Querying EGL RENDER BUFFER returns the buffer which client API rendering
is requested to use. For a window surface or Pbuffer surface, this is the
same attribute value specified when the surface was created. For a pixmap
surface, it is always EGL SINGLE BUFFER. To determine the actual buffer being
rendered to by a context, call eglQueryContext (see section 3.7.4).
Revision History
Version 1.0, 21/02/2017 - Initial Version
Question:
What if the implementation already uses double buffering for single buffered PBuffers?
Such as when an implementation must insert a resolve to a texture instead of being
able to use the same memory.
Answer:
EGL_BACK_BUFFER would still refer to the resolved buffer. But in the case of the a
double buffer EGL_FRONT_BUFFER should be used to reference the resolved buffer instead
of EGL_BACK_BUFFER as in this case the user has specified 2 buffers and knows they want
the resolved buffer.
In the double buffer case where only a back draw and a front resolved buffer is used
the implementation may not support EGL_BACK_BUFFER and should generate an EGL_BAD_
PARAMETER error when not supporting EGL_BACK_BUFFER texture binding.
extensions/EXT/EGL_EXT_buffer_age.txt
+329
View File
@@ -0,0 +1,329 @@
Name
EXT_buffer_age
Name Strings
EGL_EXT_buffer_age
Notice
Copyright 2011,2012 Intel Cooperation
IP Status
No known IP claims.
Contributors
Robert Bragg
Neil Roberts
Tapani Pälli
Kristian Høgsberg
Acorn Pooley
James Jones
Contacts
Robert Bragg, Intel (robert.bragg 'at' intel.com)
Status
Complete.
Version
12 - June 13, 2013
Number
EGL Extension #52
Dependencies
Requires EGL 1.4
This extension is written against the wording of the EGL 1.4
Specification.
Overview
The aim of this extension is to expose enough information to
applications about how the driver manages the set of front and
back buffers associated with a given surface to allow applications
to re-use the contents of old frames and minimize how much must be
redrawn for the next frame.
There are lots of different ways for a driver to manage these
buffers, from double buffering, different styles of triple
buffering and even n-buffering or simply single buffer rendering.
We also need to consider that power management events or memory
pressure events might also result in some of the buffers not
currently in-use being freed.
This extension lets applications query the age of the back buffer
contents for an EGL surface as the number of frames elapsed since
the contents were most recently defined. The back buffer can
either be reported as invalid (has an age of 0) or it may be
reported to contain the contents from n frames prior to the
current frame.
Once the application has queried the buffer age, the age of
contents remains valid until the end of the frame for all pixels
that continue to pass the pixel ownership test.
For many use-cases this extension can provide an efficient
alternative to using the EGL_BUFFER_PRESERVED swap behaviour. The
EGL_BUFFER_PRESERVED swap behaviour adds a direct dependency for
any frame n on frame n - 1 which can affect the pipelining of
multiple frames but also implies a costly copy-back of data to
initialize the back-buffer at the start of each frame.
For example if you consider a double buffered application drawing
a small spinning icon, but everything else in the scene is static.
If we know that 2 buffers are continuously being recycled each
time eglSwapBuffers is called then even though 100s of frames may
need to be drawn to animate the icon it can be seen that the two
buffers are remaining unchanged except within the bounds of the
icon. In this scenario ideally the application would simply
perform an incremental update of the old buffer instead of
redundantly redrawing all the static parts of the scene. The
problem up until now though has been that EGL doesn't report how
buffers may be recycled so it wasn't safe for applications to try
and reuse their contents. Now applications can keep track of all
the regions that have changed over the last n frames and by
knowing the age of the buffer they know how to efficiently repair
buffers that are re-cycled instead of redrawing the entire scene.
New Procedures and Functions
None
New Tokens
EGL_BUFFER_AGE_EXT 0x313D
Additions to Section 2.2 of the EGL 1.4 Specification (Rendering
Contexts and drawing surfaces)
Add the following text to a new subsection titled "Pixel
Ownership Test" after the subsection titled "Interaction With
Native Rendering":
A fragment produced by a client api through rasterization
with windows coordinates (x, y) only modifies the pixel in the
rendering surface at that location if it passes the pixel
ownership test defined by the native window system.
The pixel ownership test determines if the pixel at location
(x, y) in a rendering surface is currently owned by the client
api (more precisely, by this its context). If it is not, the
native window system decides the fate of the incoming
fragment. Possible results are that the fragment is discarded
or that some subset of the subsequent per-fragment operations
are applied to the fragment. This test allows the window
system to control the client api behavior, for instance, when
a window surface is obscured.
The pixel ownership test can only fail for window surfaces,
not for pixmap surfaces or pbuffer surfaces.
Most native window systems will be able to guarantee that no
fragment will ever fail the pixel ownership test, but a
notable exception to this is the X11 window system where,
depending on the driver, the pixel ownership test may fail
when portions of a window are obscured.
Additions to Section 3.5 of the EGL 1.4 Specification (Rendering Surfaces)
Add the following to the table of "Queryable surface attributes
and types":
+----------------------+---------+-----------------------------+
| Attribute | Type | Description |
+----------------------+---------+-----------------------------+
| EGL_BUFFER_AGE_EXT | Integer | Age of back-buffer contents |
+----------------------+---------+-----------------------------+
Table aaa: Queryable surface attributes and types.
Add the following text to the subsection titled "Surface
Attributes" in the description for eglQuerySurface
Querying EGL_BUFFER_AGE_EXT returns the age of the color
contents of the current back-buffer as the number of frames
elapsed since it was most recently defined. Applications can,
under certain conditions described below, use this age to
safely rely on the contents of old back- buffers to
potentially reduce the amount of redrawing they do each frame.
A frame is the period between calls to any of the functions in
table 3.X, hereafter referred to as "frame boundaries."
Function name
--------------------
eglSwapBuffers
Table 3.X, Frame Boundary Functions
Buffers' ages are initialized to 0 at buffer creation time.
When a frame boundary is reached, the following occurs before
any exchanging or copying of color buffers:
* The current back buffer's age is set to 1.
* Any other color buffers' ages are incremented by 1 if
their age was previously greater than 0.
For the purposes of buffer age tracking, a buffer's content
is considered defined when its age is a value greater than 0.
For example, with a double buffered surface and an
implementation that swaps via buffer exchanges, the age would
usually be 2. With a triple buffered surface the age would
usually be 3. An age of 1 means the previous swap was
implemented as a copy. An age of 0 means the buffer has only
just been initialized and the contents are undefined. Single
buffered surfaces have no frame boundaries and therefore
always have an age of 0.
Frame boundaries are the only events that can set a buffer's
age to a positive value. Once EGL_BUFFER_AGE_EXT has been
queried then it can be assumed that the age will remain valid
until the next frame boundary. EGL implementations are
permitted, but not required, to reset the buffer age in
response to pixel ownership test changes for any pixels within
the drawable, or if new pixels are added to or removed from
the drawable, i.e., the drawable is resized. A reset of this
nature does not affect the age of content for pixels that pass
the pixel ownership test before and after the event that
caused the reset. In other words, applications can assume
that no event will invalidate the content of pixels that
continuously pass the pixel ownership test between when the
buffer age was queried and the following frame boundary.
It is up to applications to track pixel ownership using data
collected from relevant window system events, such as
configuration and expose events on X11.
If the EGL implementation decides to free un-used back-buffers
when the system is under memory pressure or in response to
power-management events then EGL will return an age of 0 when
it allocates a new buffer at the start of a new frame.
If the EGL_BUFFER_PRESERVED swap behaviour is in use then
it can be assumed that the age will always be 1. It is
recommended where possible though that the
EGL_BUFFER_PRESERVED swap behaviour not be used since it can
have severe performance consequences. Keeping track of the
buffer age and the regions that have changed over the last 2
or 3 frames instead can often replace the need for using
EGL_BUFFER_PRESERVED.
EGL_BUFFER_AGE_EXT state is a property of the EGL surface that
owns the buffers and lives in the address space of the
application. That is, if an EGL surface has been created from
a native window or pixmap that may be shared between
processes, the buffer age is not guaranteed to be synchronized
across the processes. Binding and unbinding a surface to and
from one or more contexts in the same address space will not
affect the ages of any buffers in that surface.
Add the following text to last paragraph of the subsection titled
"Surface Attributes" in the description for eglQuerySurface
errors.
If querying EGL_BUFFER_AGE_EXT and <surface> is not bound as
the draw surface to the calling threads current context
an EGL_BAD_SURFACE error is generated.
Dependencies on OpenGL ES
None
Dependencies on OpenVG
None
Issues
1) What are the semantics if EGL_BUFFER_PRESERVED is in use
RESOLVED: The age will always be 1 in this case. More
clarification about this was added along with the
recommendation to use the buffer age to reuse buffers instead
of EGL_BUFFER_PRESERVED when possible to avoid the
in-efficiencies of introducing a dependency for each frame on
the previous frame.
2) How can an application know that all pixels of a re-usable
buffer were originally owned by the current context?
RESOLVED: It is up to the application to track pixel ownership
using existing window system specific events, such as X11
expose or configure notify events.
3) What are the semantics if the buffer age attribute is queried for
a surface that isn't bound to the calling thread's context as the
draw surface?
RESOLVED: we report an EGL_BAD_SURFACE error as is similarly
done when calling eglSwapBuffers for such a surface.
4) What is the buffer age of a single buffered surface?
RESOLVED: 0. This falls out implicitly from the buffer age
calculations, which dictate that a buffer's age starts at 0,
and is only incremented by frame boundaries. Since frame
boundary functions do not affect single buffered surfaces,
their age will always be 0.
5) What guarantees are provided after querying the buffer age?
RESOLVED: The buffer age of pixels which continue to pass the
pixel ownership test must remain valid until the next frame
boundary otherwise applications can't be absolutely sure of
the consistency of their rendered content. Implementations
may reset the queryable age of the buffer when pixel ownership
changes occur. This is further clarified in section 3.5
Revision History
Version 1, 25/07/2011
- First draft
Version 2, 03/08/2011
- Clarified semantics for using EGL_BUFFER_PRESERVED
Version 3, 01/09/2011
- Fixed a prototype inconsistency
Version 4, 03/11/2011
- Split out the buffer age parts from EGL_INTEL_start_frame
Version 5, 20/03/2012
- Document that once the age is queried it remains valid until
the end of the frame so we can remove the need for a separate
EGL_EXT_start_frame extension.
Version 6, 20/03/2012
- Clarify that only buffers who's contents were fully owned by
the context are tracked.
Version 7, 20/03/2012
- Document that an error will be generated if querying the age
for a surface not bound to the current context.
Version 8, 25/08/2012
- Update in line with changes made to the GLX_EXT_buffer_age draft spec
including more relaxed pixel ownership requirements and explicit
clarification of the buffer age calculation.
Version 9 20/09/2012
- Update in line with changes made to the EGL_EXT_buffer age
draft space
Version 10 29/11/2012
- Add pixel ownership test section and other minor
clarifications
Version 11 13/12/2012
- Allocated enumerant and marked complete.
Version 12, 13/06/2013, Chad Versace <chad.versace@intel.com>
- Remove the "all rights reserved" clause from the copyright notice. The
removal does not change the copyright notice's semantics, since the
clause is already implied by any unadorned copyright notice. But, the
removal does diminish the likelihood of unwarranted caution in readers
of the spec.
- Add "IP Status" section to explicitly state that this extension has no
knonw IP claims.
Version 13, 14/10/2021, Guanzhong Chen
- Fix an incorrect token name
extensions/EXT/EGL_EXT_client_extensions.txt
+408
View File
@@ -0,0 +1,408 @@
Name
EXT_client_extensions
Name Strings
EGL_EXT_client_extensions
Contributors
Chad Versace <chad.versace@intel.com>
Ian Romanick <ian.d.romanick@intel.com>
Jakob Bornecrantz <jakob@vmware.com>
James Jones <jajones@nvidia.com>
Contacts
Chad Versace <chad.versace@intel.com>
Status
Complete
Version
Version 11, 2013.10.10
Number
EGL Extension #58
Extension Type
EGL client extension
Dependencies
Requires EGL 1.4.
This extension is written against the wording of the EGL 1.4
Specification.
Overview
This extension introduces the concept of *extension type*, requires that
each EGL extension belong to exactly one type, and defines two types:
display and client. It also provides a method to query, without
initializing a display, the set of supported client extensions.
A display extension adds functionality to an individual EGLDisplay. This
type of extension has always existed but, until EGL_EXT_client_extensions,
lacked an identifying name.
A client extension adds functionality that is independent of any display.
In other words, it adds functionality to the EGL client library itself. This
is a new type of extension defined by EGL_EXT_client_extensions.
EGL_EXT_client_extensions is itself a client extension.
We suggest that each future extension clearly state its type by including
the following toplevel section in its extension specification, preceding the
Dependencies section. For client extensions, this suggestion is
a requirement.
Extension Type
<Either "EGL display extension" or "EGL client extension" or
a future extension type.>
By cleanly separating display extensions from client extensions,
EGL_EXT_client_extensions solves a bootstrap problem for future EGL
extensions that will modify display initialization. To query for such
extensions without EGL_EXT_client_extensions, an EGL client would need to
initialize a throw-away EGLDisplay solely to query its extension string.
Initialization of the throw-away display may have undesired side-effects
(discussed in the issues section below) for EGL clients that wish to use the
new methods of display initialization.
New Types
None
New Procedures and Functions
None
New Tokens
None
Additions to the EGL 1.4 Specification:
Add the following section to Chapter 2 "EGL Operation":
"2.n Extensions
EGL implementations may expose additional functionality beyond that
described by this specification. Additional functionality may include new
functions, new enumerant values, and extended behavior for existing
functions. Implementations advertise such extensions to EGL by exposing
*extension strings*, which are queryable with eglQueryString.
Each EGL extension belongs to exactly one of the following types:
Display Extensions
A *display extension* adds functionality to an individual
EGLDisplay. Different instances of EGLDisplay may support different
sets of display extensions.
Client Extensions
A *client extension* adds functionality that is independent of any
display. In other words, it adds functionality to the EGL client
library itself. In a given process, there exists exactly one set,
possibly empty, of supported client extensions. When the client
extension string is first queried, that set becomes immutable."
Replace the paragraph in section 3.3 "EGL Versioning" that begins "The
EGL_EXTENSIONS string" with the following text:
"The EGL_EXTENSIONS string describes which set of EGL extensions are
supported. The string is zero-terminated and contains a space-separated
list of extension names; extension names themselves do not contain spaces.
If there are no extensions to EGL, then the empty string is returned.
If <dpy> is EGL_NO_DISPLAY, then the EGL_EXTENSIONS string describes the set
of supported client extensions. If <dpy> is a valid, initialized display,
then the EGL_EXTENSIONS string describes the set of display extensions
supported by the given display. The set of supported client extensions is
disjoint from the set of extensions supported by any given display [fn].
[fn] This is a consequence of the requirement in Section 2.n Extensions that
each extension belong to exactly one extension type."
Replace the last paragraph of section 3.3 "EGL Versioning" with:
"On failure, NULL is returned. An EGL_BAD_DISPLAY error is generated if
<dpy> is not a valid display, unless <dpy> is EGL_NO_DISPLAY and <name> is
EGL_EXTENSIONS. An EGL_NOT_INITIALIZED error is generated if <dpy> is
a valid but uninitialized display. An EGL_BAD_PARAMETER error is generated
if <name> is not one of the values described above."
Conformance Tests
1. Before any call to eglGetDisplay, call `eglQueryString(EGL_NO_DISPLAY,
EGL_EXTENSIONS)`. Verify that either
a. The call returns NULL and generates EGL_BAD_DISPLAY.
b. The call returns an extension string that contains, at a minimum,
this extension and generates no error.
2. Obtain a display with eglGetDisplay but do not initialize it. Verity
that passing the uninitialized display to `eglQueryString(dpy,
EGL_EXTENSIONS)` returns NULL and generates EGL_NOT_INITIALIZED.
3. Obtain a list of display extensions by calling `eglQueryString(dpy,
EGL_EXTENSIONS)` on an initialized display. Obtain the list of client
extensions by calling `eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)`.
If both calls succeed, verify the two lists are disjoint.
Issues
1. How should clients detect if this extension is supported?
RESOLVED: If an EGL implementation supports this extension, then
`eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)` returns
a well-formed extension string and generates no error. Otherwise, it
returns NULL and generates EGL_BAD_DISPLAY.
2. On EGL platforms that define EGL_NO_DISPLAY as NULL, does not calling
`eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)` risk a null pointer
dereference? Therefore, how is it possible on such platforms for
a client to safely detect if this extension is supported?
RESOLVED: According to the EGL 1.4 specification, calling
`eglQueryString(EGL_NO_DISPLAY, name)` returns NULL and generates
EGL_BAD_DISPLAY. No null pointer dereference occurs even if the
platform defines EGL_NO_DISPLAY as NULL.
3. What existing extensions should returned by
`eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS)`?
RESOLVED: Possibly EGL_NV_system_time.
4. What should be the relationship between the extension string of
EGL_NO_DISPLAY and the extension string of a valid display? That is,
should the former be a subset of the latter? Should the two be
disjoint? Should the relationship remain undefined?
Another phrasing of this issue is: When, if ever, should client
extensions appear in a display's extension string?
RESOLVED: The extension string of EGL_NO_DISPLAY must be disjoint
from the extension string of any valid display. That is, EGL_NO_DISPLAY
must advertise only client extensions, and valid displays must not
advertise client extensions. By defining a clear relationship between
the two types of extension strings, we enforce consistent behavior among
implementations, thus preventing possible confusion from application
developers.
DISCUSSION: This resolution has special implications for systems where
libEGL is a vendor-independent library that loads and then dispatches
to the appropriate vendor-provided EGL library. The resolution requires
that client extensions, as well the construction of extension strings,
be at least partially implemented in the vendor-independent library.
The alternative resolution of mandating the 'superset' relation (that
is, that the extension string of a valid display must be a superset of
that of EGL_NO_DISPLAY) was rejected due to potential confusion on
behalf of the application developer as well as the driver implementer.
What follows is an example of each.
a) Suppose an EGL implementation supported creation of
a software-renderer EGLDisplay through a client extension named
EGL_XYZ_platform_software_renderer. If the 'superset' relation were
mandated, then each display, whether it were hardware-accelerated or
software-only, would advertise the EGL_XYZ_platform_software_renderer
extension string. This would likely confuse application developers.
b) If the 'superset' relation were mandated, then the possibility
exists that a vendor would ship a hybrid extension that is both
a client extension and a display extension. Such a hybrid extension
poses subtle difficulties for systems where libEGL is
a vendor-independent library that dispatches to the appropriate
vendor-provided EGL driver. On such a system, the extension's hybrid
nature may require that each vendor-provided EGL driver support the
extension before the vendor-independent EGL library could safely
expose the extension. By choosing the 'disjoint' relation rather
than 'superset', we prevent this problematic situation from
occuring.
5. Should client extension specifications explicitly state they are
returned in the extension string of EGL_NO_DISPLAY?
RESOLVED: Yes. Enforce this by requiring that client extension
specifications contain the toplevel section "Extension Type".
6. As explained in the overview section, this "extension solves
a bootstrap problem for future EGL extensions that modify display
initialization". What solutions to the bootstrap problem were
considered? Why was EGL_EXT_client_extensions chosen as the best
solution?
DISCUSSION: First let's discuss the exact nature of the bootstrap
problem and of the future EGL extensions that modify display
initialization.
Mesa's EGL implementation supports multiple native platforms (such as
Wayland, GBM, and X11) at runtime, and we expect that more
implementations will do so in the future. The EGL API is deficient for
such implementations because it does not yet provide a way for clients
to query the set of supported native platforms. Also, EGL provides no
way for clients to specify to which platform the native display belongs
during display initialization. (That is, eglGetDisplay has a native
display parameter, but no parameter specifying the native platform).
Future EGL extensions, currently under progress, will solve these
deficiencies in the EGL API by (1) adding a variant of eglGetDisplay
that allows specification of the platform to which the native display
belongs and (2) by advertising the set of native platforms supported by
the implementation.
However, there exists a bootstrap problem here. To query if a given
native platform is supported, the EGL client must initialize an
EGLDisplay to query its extension string. But, not yet knowing which
native platforms the EGL implementation supports, the client cannot
safely pass any native display to eglGetDisplay, and therefore cannot
obtain an extension string.
The following solutions to this bootstrap problem have been considered.
For conciseness, let's refer to the future EGL extensions that modify
display initialization as "client extensions".
1. PROPOSED SOLUTION: To determine if an EGL implementation supports
a given client extension, require that the EGL client call
eglGetProcAddress on some function defined by the extension. If
eglGetProcAddress returns non-null, then the implementation
supports the extension.
ANALYSIS: The EGL 1.4 spec permits eglGetProcAddress to return
non-null for unrecognized function names. Therefore, this
solution's method may produce false positives on some
implementations.
Also, this solution does not permit detection of client extensions
that add no new functions.
2. PROPOSED SOLUTION: To determine if an EGL implementation supports
a given client extension, the EGL client should examine the
extension string of EGL_DEFAULT_DISPLAY. Querying
EGL_DEFAULT_DISPLAY is a failsafe mechanism by which the EGL
client can obtain an extension string, because EGL_DEFAULT_DISPLAY
is a valid input to eglGetDisplay regardless of which platforms
the EGL implementation supports.
ANALYSIS: This solution is awkward. It requires that the client
initialize a throw-away EGLDisplay solely to query its extension
string, even though the desired extension is not a property of any
display but of the EGL library itself.
This solution also has a subtle fatal problem. It is not backwards
compatible with Mesa. As of 2013-06-07, Mesa's EGL implementation
stores at runtime a user-chosen native platform in global
write-once state. Calling eglGetDisplay is one action that
results in writing to that state. Therefore, if a client process
running on such a problematic version of Mesa initialized
EGL_DEFAULT_DISPLAY solely to detect some client extension, then
the client process would be confined for its lifetime to use only
that platform to which EGL_DEFAULT_DISPLAY belongs. This
confinement may be fatal if the process had wanted to use
a different platform.
3. PROPOSED SOLUTION: Abandon the concept of client extensions.
Instead, in implementations that support multiple window systems
at runtime, eglGetDisplay should autodetect the platform to which
the native display belongs. A suitable error should be generated
if an unsupported native display is passed to eglGetDisplay.
ANALYSIS: For some native platforms, the display type is opaque
with no defined ABI. (For example, in libX11 the 'Display' type is
an opaque typedef). There exists no method by which eglGetDisplay
could reliably detect that the given native display belongs to
such a platform.
This solution also has a subtle fatal problem. The client
extensions will likely specify that an EGL client may create EGL
resources from multiple platforms in the same process. But, Mesa's
global write-once state, mentioned above, prevents using multiple
platforms in one process. Therefore, under this proposed solution
and on a system where a problematic version of Mesa is installed,
the client would be unable to detect if EGL supported multiple
platforms per process without committing to the platform to which
the first initialized display belonged.
4. ACCEPTED SOLUTION: Allow the EGL client to query the extension
string of EGL_NO_DISPLAY, which would contain the client
extensions.
ANALYSIS: This solution does not require the initialization of
a throw-away EGLDisplay, nor does it require that native display
types have a fixed ABI.
This is the solution described by this extension specification,
EGL_EXT_client_extensions.
Revision History
Version 11, 2013.10.10 (Chad Versace)
- Fix conformance test #3. It should require that the display extension
list be disjoint to rather than a superset of the client extension
list. (The 'superset' requirement was changed pre-publication to
'disjoint' in version 8).
Version 10, 2013.07.03 (Chad Versace)
- Version 9 and 10 are identical due to a versioning error.
Version 9, 2013.07.03 (Chad Versace)
- Define the concept of *extension type*, require require that each EGL
extension belong to exactly one type, and define two types: display
and client.
- Suggest new section "Extension Type" for future extension
specifications.
- Add new section 2.n Extensions.
- Simplify modifications to section 3.3 by using the new extension type
terminology.
Version 8, 2013.07.01 (Chad Versace)
- Change resolution of Issue 4 from the 'superset' relation to the
'disjoint' relation, according to discussion with Jakob Bornecrantz.
Acked by James Jones.
Version 7, 2013.06.10 (Chad Versace)
- Fix typos.
s/unitialized/uninitialized/
s/EGL_NO_EXTENSIONS/EGL_EXTENSIONS/
Version 6, 2013.06.07 (Chad Versace)
- Remove the Motivation section, merging its content into the Overview
section and Issue 6.
Version 5, 2013.06.07 (Chad Versace)
- Resolve issue 3 regarding classifying currently published extensions
as client extensions.
- Resolve issue 4 regarding the relationship among client and display
extension strings.
- Add and resolve issue 5, requiring client extension specifications
to contain language about the EGL_NO_DISPLAY extension string.
Version 4, 2013.05.14 (Chad Versace)
- Add issue 4.
Version 3, 2013.03.24 (Chad Versace)
- Fix conformance test condition 1.b. The returned extension string
should list, at a minimum, this extension. [Found by Ian Romanick].
- Add section "Movivation". [Requested by Ian Romanick].
Version 2, 2013.03.06 (Chad Versace)
- Remove enum EGL_CLIENT_EXTENSIONS_EXT. Reuse EGL_EXTENSIONS for that
purpose.
- To obtain client extensions, require the eglQueryString be called
with dpy=EGL_NO_DISPLAY rather than dpy=NULL. [Suggested by James
Jones].
- Add descriptions of conformance tests. [Suggested by Ian Romanick].
- Add sections "Overview" and "Issues".
Version 1, 2013.03.06 (Chad Versace)
- First draft
# vim: filetype=text expandtab autoindent shiftwidth=4 textwidth=80:
extensions/EXT/EGL_EXT_client_sync.txt
+146
View File
@@ -0,0 +1,146 @@
Name
EXT_client_sync
Name Strings
EGL_EXT_client_sync
Contributors
Daniel Kartch
Contacts
Daniel Kartch, NVIDIA Corporation (dkartch 'at' nvidia.com)
Status
Complete
Version
Version 2, April 20, 2018
Number
EGL Extension #129
Extension type
EGL display extension
Dependencies
Requires EGL_EXT_sync_reuse
Overview
The EGL_KHR_reusable_sync extension defines an EGL_SYNC_REUSABLE_KHR
EGLSync type which is signaled and unsignaled by client events. The
EGL_EXT_sync_reuse extension allows all EGLSyncs to become reusable.
The signaling behavior associated with EGL_SYNC_REUSABLE_KHR is
still desirable, but the name becomes misleading if all EGLSyncs can
be reused. This extension defines an EGLSync type with equivalent
behavior, separating the signaling mechanism from the reusability.
New Procedures and Functions
EGLBoolean eglClientSignalSyncEXT(
EGLDisplay dpy,
EGLSync sync,
const EGLAttrib *attrib_list);
New Types
None
New Tokens
Accepted by the <type> parameter of eglCreateSync, and returned
in <value> when eglGetSyncAttrib is called with <attribute>
EGL_SYNC_TYPE:
EGL_SYNC_CLIENT_EXT 0x3364
Returned in <value> when eglGetSyncAttrib is called with attribute
EGL_SYNC_CONDITION:
EGL_SYNC_CLIENT_SIGNAL_EXT 0x3365
Add to the list of sync object decriptions in 3.8.1 Sync Objects
A <client sync object> reflects the readiness of some client-side
state. Sync objects of this type are not visible to API contexts and
may not be used with eglWaitSync. They may be waited for with
eglClientWaitSync or polled with eglGetSyncAttrib as other sync
types.
Add to the end of 3.8.1 Sync Objects
The command
EGLBoolean eglClientSignalSyncEXT(EGLDisplay dpy, EGLSync sync,
const EGLAttrib *attrib_list);
may be called to switch sync objects which support it to the
signaled state. Currently only sync objects with type
EGL_SYNC_CLIENT_EXT provide this support. The attribute list may be
used to provide additional information to the signaling operation,
as defined for the sync type.
Errors
eglClientSignalSyncEXT returns EGL_FALSE on failure, and has no
effect on <sync>.
If <dpy> is not the name of a valid, initialized EGLDisplay, an
EGL_BAD_DISPLAY error is generated.
If <sync> is not a valid sync object associated with <dpy>, an
EGL_BAD_PARAMETER error is generated.
If <attrib_list> contains an attribute name not defined for the
type of <sync>, an EGL_BAD_ATTRIBUTE error is generated.
If <sync>'s type does not support this direct signaling, an
EGL_BAD_ACCESS error is generated.
Insert new subsection in 3.8.1 Sync Objects
3.8.1.x Creating and Signaling Client Sync Objects
If type is EGL_SYNC_CLIENT_EXT, a client sync object is created. The
EGL_SYNC_STATUS attribute may be specified as either EGL_UNSIGNALED
or EGL_SIGNALED, and will default to EGL_UNSIGNALED. No other
attributes may be specified for a client sync object. The value of
EGL_SYNC_CONDITION will be set to EGL_SYNC_CLIENT_SIGNAL_EXT.
A client sync object in the unsignaled state will switch to the
signaled state when eglClientSignalSyncEXT is called. No attributes
are supported for signaling a sync object of this type. Signaling a
client sync object which is already in the signaled state will have
no effect.
A client sync object which is in the signaled state may be switched
back to the unsignaled state with eglUnsignalSyncEXT. No attributes
are supported for unsignaling a sync object of this type.
Add to the error list for eglWaitSync in 3.8.1.3 Waiting for Sync
Objects
If <sync> is of type EGL_SYNC_CLIENT_EXT, an EGL_BAD_ACCESS error is
generated.
Issues
None
Revision History
#2 (April 20, 2018) Daniel Kartch
- Renamed to EXT
- Fixed missing attrib_list in New Functions section
- Eliminated condition as an allowed attribute at creation. This
is inconsistent with other sync extensions, and there is no
need to make it configurable at this time. Future extensions
can make the condition configurable if desired.
#1 (Feburary 22, 2018) Daniel Kartch
- Initial draft as XXX
extensions/EXT/EGL_EXT_compositor.txt
+400
View File
@@ -0,0 +1,400 @@
Name
EXT_compositor
Name Strings
EGL_EXT_compositor
Contributors
Marc Moody
Daniel Herring
Contacts
Marc Moody, Boeing Inc., marc dot d dot moody at boeing dot com
Daniel Herring, Core Avionics & Industrial Inc., daniel dot herring at ch1group dot com
Status
Complete
Version
Version 1.0, February 3, 2017
Number
EGL Extension #116
Dependencies
Requires EGL 1.0.
This extension is written against the wording of the EGL 1.4
Specification - April 6, 2011, but may be implemented against earlier
versions.
Overview
This extension allows for the composition of multiple windows within
a multi-partition EGL system. The extension allows a primary EGLContext and
window to be created for each display. All other windows are created using
non-displayable surfaces. A handle to each off-screen window is provided
to the primary EGLContext to allow the composition of all non-displayable windows
on a single display.
For each display, there is one EGLContext which has access to create on screen
windows, this is call the primary context for this display. All other EGLContexts
are referred to as secondary contexts.
This extension requires a multi-partition EGL driver to support asynchronous
rendering of off screen surfaces.
Information assurance is provided by preventing context and surface creation by
unregistered contexts and by preventing the non-primary contexts and surfaces
from rendering to the display.
New Types
None
New Procedures and Functions
EGLBoolean eglCompositorSetContextListEXT (const EGLint *external_ref_ids,
EGLint num_entries);
EGLBoolean eglCompositorSetContextAttributesEXT (EGLint external_ref_id,
const EGLint *context_attributes,
EGLint num_entries);
EGLBoolean eglCompositorSetWindowListEXT (EGLint external_ref_id,
const EGLint *external_win_ids,
EGLint num_entries);
EGLBoolean eglCompositorSetWindowAttributesEXT (EGLint external_win_id,
const EGLint *window_attributes,
EGLint num_entries);
EGLBoolean eglCompositorBindTexWindowEXT (EGLint external_win_id);
EGLBoolean eglCompositorSetSizeEXT (EGLint external_win_id,
EGLint width, EGLint height);
EGLBoolean eglCompositorSwapPolicyEXT (EGLint external_win_id,
EGLint policy);
New Tokens
New attributes accepted by the <attrib_list> argument of
eglCreateContext:
EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT 0x3460
New attributes accepted by the <attrib_list> argument of
eglCreateContext and eglCreateWindowSurface:
EGL_EXTERNAL_REF_ID_EXT 0x3461
New attributes accepted by the <policy> argument of
eglCompositorSwapPolicyHint:
EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT 0x3462
EGL_COMPOSITOR_KEEP_NEWEST_FRAME_EXT 0x3463
Modify Section 3.7.1 of the EGL 1.4 Specification, paragraph 2
(Creating Rendering Contexts) on pg. 43
From:
If eglCreateContext succeeds, it initializes the context to the initial state defined
for the current rendering API, and returns a handle to it. The context can be
used to render to any compatible EGLSurface.
To:
If eglCreateContext succeeds, it initializes the context to the initial state defined
for the current rendering API, and returns a handle to it. The context can be
used to render to any compatible off-screen rendering surface (Sections 3.5.2
and 3.5.4). A secondary context can be used to render to compatible window surfaces
which have been associated with the context using eglCompositorSetWindowListEXT. A
non-secondary context can be used to render to any compatible EGLSurface.
Modify Section 3.7.1 of EGL 1.4 Specification, paragraph 5
(Creating Rendering Contexts) on pg. 43
From:
attrib_list specifies a list of attributes for the context. The list has the same
structure as described for eglChooseConfig. The only attribute that can be specified
in attrib_list is EGL_CONTEXT_CLIENT_VERSION, and this attribute may only
be specified when creating a OpenGL ES context (e.g. when the current rendering
API is EGL_OPENGL_ES_API).
To:
attrib_list specifies a list of attributes for the context. The list has the same
structure as described for eglChooseConfig. The attributes that can be specified
in attrib_list are EGL_CONTEXT_CLIENT_VERSION, EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT,
EGL_EXTERNAL_REF_ID_EXT.
Modify Section 3.7.1 of EGL 1.4 Specification, paragraph 7
(Creating Rendering Contexts) on pg. 43
From:
EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL
ES context to create. An attribute value of 1 specifies creation of an OpenGL ES
1.x context. An attribute value of 2 specifies creation of an OpenGL ES 2.x context.
The default value for EGL_CONTEXT_CLIENT_VERSION is 1.
To:
EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL
ES context to create. An attribute value of 1 specifies creation of an OpenGL ES
1.x context. An attribute value of 2 specifies creation of an OpenGL ES 2.x context.
The default value for EGL_CONTEXT_CLIENT_VERSION is 1. EGL_CONTEXT_CLIENT_VERSION
may only be specified when creating a OpenGL ES context (e.g. when the current
rendering API is EGL_OPENGL_ES_API).
Additions to Section 3.7.1 of the EGL 1.4 Specification (Creating Rendering Contexts).
The first call to eglCreateContext with EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT
set as EGL_TRUE in the <attrib-list> returns an EGLContext handle which will
act as the primary context for the specified EGLDisplay. This shall be the
only context on this EGLDisplay which is able to be bound to an on-screen window
on the EGLDisplay. Subsequent calls to eglCreateContext, for the same display,
in any address space with EGL_PRIMIARY_COMPOSITOR_CONTEXT_EXT set as EGL_TRUE
shall return EGL_NO_CONTEXT.
Subsequent calls, in any address space for the same display, to eglCreateContext
which do not use EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT should use the the attribute
EGL_EXTERNAL_REF_ID_EXT and an external reference identifier to create a valid
EGLContext.
Subsequent calls, in any address space for the same display, to eglCreateContext
which do not use EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT and do not use
EGL_EXTERNAL_REF_ID_EXT shall not create a context and shall return
EGL_NO_CONTEXT and set the error EGL_BAD_ACCESS.
EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT notifies EGL that this context is the only
context allowed to render to a on screen window surface for this display. This
attribute is followed in the attribute list by either EGL_TRUE or EGL_FALSE.
EGL_EXTERNAL_REF_ID_EXT is followed by an external reference identifier which
associates this context with the list of allowed contexts set by
eglCompositorSetContextListEXT. If the reference identifier has already been
used to initiate another call to eglCreateContext in any address space, this
call shall fail and set the error EGL_BAD_ATTRIBUTE. IF the external reference
identifier is not a valid identifier the error EGL_BAD_ATTRIBUTE shall be set
and the call shall fail. If this attribute is set and the primary context has
not yet been created then the error EGL_BAD_MATCH and the call shall fail.
Only when the attributes specified via attrib_list and those specified for this
context using eglCompositorSetContextAttributesEXT are compatible will the
context be successfully created.
Modify the list of parameters supported by eglCreateWindowSurface in section 3.5.1
(Creating On-Screen Rendering Surfaces) on p. 27:
An external window identifier (EGLuint external_win_id) is associated with
each off screen window. EGLNativeWindowType shall be EGLint and the
external window identifier shall be used as the value for the <win> parameter.
EGL_EXTERNAL_REF_ID_EXT with the context external reference id shall be in the
attrib_list. If the external window identifier and the external reference identifier
do not match a pair set using eglCompositorSetWindowListEXT window creation shall
fail.
Add the function:
EGLBoolean eglCompositorSetContextListEXT(const EGLint *external_ref_ids,
EGLint num_entries);
This function is called by the primary context to establish the set of
all allowable secondary contexts by defining the set of external reference
identifiers. Secondary contexts shall identify their external reference
identifier by setting the EGL_EXTERNAL_REF_ID_EXT attribute when calling
eglCreateContext.
Calls to this function when the primary context for the display is not active,
shall return EGL_FALSE and do nothing. When this function is successful it
shall return EGL_TRUE and associate the list of external reference identifiers
with the active display.
This function shall only be called once per primary context. Subsequent calls
shall return EGL_FALSE and do nothing.
external_ref_ids shall be an array of user generated integers greater than 1.
num_entries shall specify the number of external_ref_ids.
Add the function:
EGLBoolean eglCompositorSetContextAttributesEXT (EGLint external_ref_id,
const EGLint *context_attributes,
EGLint num_entries);
This function is called by the primary context to establish a list of compatible
context attributes.
Calls to this function when the primary context for the display is not active
shall return EGL_FALSE and do nothing. When the function is successful it shall
return EGL_TRUE and associate the given attributes to the subsequent
eglCreateContext call using the given external reference id.
The list of acceptable context_attributes is the same as the list for
eglCreateContext. Only when this list of attributes is compatible with those
used during context creation will the secondary context be created.
This function shall only be called once per secondary context, and must be called
before the secondary context is able to be created. Subsequent calls shall
return EGL_FALSE and do nothing.
num_entries shall specify the number of attributes in the list. This number
shall prevent accessing memory outside the attribute list, even if EGL_NONE is
not yet found in the list. If EGL_NONE is found sooner than this number of
attributes list parsing shall stop.
Add the function:
EGLBoolean eglCompositorSetWindowListEXT (EGLint external_ref_id,
const EGLint *external_win_ids,
EGLint num_entries);
This function is called by the primary context to establish the set of
all allowable windows associated with a specific secondary context by defining
the set of external window identifiers. Window surface creation within secondary
contexts use the external window identifier as the native window handle parameter
of eglCreateWindowSurface and supply an external reference id as a window creation
attribute.
Calls to this function when the primary context for the display is not active,
shall return EGL_FALSE and do nothing. When this function is successful it
shall return EGL_TRUE and associate the list of external window identifiers
with the specified secondary context (external_ref_ids).
external_win_ids shall be an array of user generated integers greater than 1.
external window identifiers are unique within the primary EGLContext. Any
external window identifier may be associated with multiple secondary contexts
however only the first context which calls eglCreateWindowSurface shall
successfully create a window surface for the given window.
num_entries shall specify the number of external_ref_ids.
Add the function:
EGLBoolean eglCompositorSetWindowAttributesEXT (EGLint external_win_id,
const EGLint *window_attributes,
EGLint num_entries);
This function is called by the primary context to set window specific attributes
for the specified external window id.
The list of valid attributes are: EGL_WIDTH, EGL_HEIGHT, EGL_VERTICAL_RESOLUTION,
EGL_HORIZONRAL_RESOLUTION, EGL_PIXEL_ASPECT_RATIO.
EGL_WIDTH and EGL_HEIGHT shall set the maximum width and height the secondary
context is able to create a window surface with.
EGL_VERTICAL_RESOLUTION, EGL_HORIZONTAL_RESOLUTION, and EGL_PIXEL_ASPECT_RATIO
shall set the values of these used by the secondary context.
Calls to this function when the primary context for the display is not active,
shall return EGL_FALSE and do nothing. When this function is successful it
shall return EGL_TRUE and associate the list of attributes with the off screen
window ID (external_win_id).
This function shall only be called once per window, and must be called before
the secondary context is able to create the window surface. Subsequent calls
shall return EGL_FALSE and do nothing.
num_entries shall specify the number of attributes in the list. This number
shall prevent accessing memory outside the attribute list, even if EGL_NONE is
not yet found in the list. If EGL_NONE is found sooner than this number of
attributes list parsing shall stop.
Add the function:
EGLBoolean eglCompositorBindTexWindowEXT (EGLint external_win_id);
This function is similar to eglBindTexImage in that it binds the windows
color buffers to a texture object which can then be composited on the native
window by the primary context. This function shall only be callable within
the primary context while there is a texture object actively bound by the
native rendering API. The function shall return EGL_TRUE if the window is
successfully bound to the active texture object. The function shall return
EGL_FALSE if binding fails, the context is not the primary context, or the
external_win_id is not a valid external window reference as set using
eglCompositorSetWindowListEXT.
Add the function:
EGLBoolean eglCompositorSetSizeEXT(EGLint external_win_id,
EGLint width, EGLint height);
This function shall be called by the primary context to set the width and
height of the window. This function returns EGL_FALSE when called by a context
other than the primary context. This function will also return EGL_FALSE if
the new width and height are larger than the maximums set by
eglCompositorSetWindowAttributesEXT. Upon successful window resizing the function
shall return EGL_TRUE.
Secondary contexts may use EGL to query the windows width and height at runtime
to detect window resize events. The window buffer resizing shall be applied
to the newly active buffer after the secondary context calls eglSwapBuffers.
This will leave an average of 2 buffers which will have to be scaled by the
native rendering API to the new resolution.
Add the function:
EGLBoolean eglCompositorSwapPolicyEXT(EGLint external_win_id,
EGLint policy);
This function shall be called by the primary context to specify the handling
of buffer swaps of the context specified by external_ref_id.
When the policy is set to EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT, and the
secondary context completes a frame by calling eglSwapbuffers, and the
primary context is actively reading from the front buffer associated with
the external window ID, then the just completed frame is dropped, no buffer
swap occurs, and eglSwapBuffers will return EGL_TRUE.
If EGL_COMPOSITOR_KEEP_NEWEST_FRAME_EXT is specified and the primary context
is actively reading from the front buffer associated with the external window
ID then the secondary context's call to eglSwapBuffers will return EGL_FALSE.
eglSwapBuffers will continue to return EGL_FALSE as long as the primary context
is actively reading from the front buffer. Once the primary context finishes
reading from the front buffer the next call to eglSwapBuffers will
return EGL_TRUE. It is up to the application to decide if it will wait until
eglSwapBuffers returns EGL_TRUE before rendering again. If the secondary
context continues to render after eglSwapBuffers returns EGL_FALSE then it will
be as if the swap policy was EGL_COMPOSITOR_DROP_NEWEST_FRAME_EXT.
Revision History
Version 0.1, 30/08/2014 - first draft.
Version 0.2, 24/09/2014 second draft.
Version 0.3, 21/12/2016
Khronos vendor extension clean-up.
Version 0.4, 05/01/2016
- Change from context and display limitation to context and window limitations
- Added additional functions related to external window ids contexts.
Version 1.0, 03/02/2017
- Fixed misc issues related to parameter names and types.
Question: How are external reference and window IDs assigned and managed? Are they
reserved somehow within a new EGL C header file?
Answer: External IDs are assigned from the software component with the primary
context during an EGL initialization stage using eglCompositorSet*ListEXT.
The secondary contexts are provided the appropriate external reference ID
during end system integration. It is recommended that these values be able
to be set via a configuration parameter to the application, to ease
integration of multiple programs.
Question: What happens when the secondary contexts render faster than the
primary context?
Answer: This is based on the swap policy set by the compositor, and the rate
difference between the render and the compositor. Secondary contexts
will be notified by EGL_FALSE being returned if the windows front buffer
is currently being read by the compositor. However, if the compositor is
not currently reading the front buffer the swap will succeed and the
secondary contexts latest rendered frame will now be in the front buffer
to be composited.
Question: What happens when the primary context renders faster than the
secondary context(s)?
Answer: The contents of the windows front buffer will be repeated.
Question: Does this infer any Z-ordering for the off-screen surfaces?
Answer: No, the Z-order is applied by the compositor when doing the final on
screen rendering of the off-screen surfaces. Or may be set if a Z-ordering
extension is applied to the attribute list of the window using
eglCompositorSetWindowAttributesEXT
Comments:
The driver should also have to have enough protection in it to prevent a random
software component from passing random buffer handles to the driver to prevent
access to other software components.
The driver may force use of double buffering event if the window surface was created
using an EGL_RENDER_BUFFER attribute set to EGL_SINGLE_BUFFER.
If EGL_PRIMARY_COMPOSITOR_CONTEXT_EXT is not used to create a context for a specified
display then EGL will act as though this extension is not enabled.
extensions/EXT/EGL_EXT_config_select_group.txt
+111
View File
@@ -0,0 +1,111 @@
Name
EGL_EXT_config_select_group
Name Strings
EGL_EXT_config_select_group
Contributors
Hal Gentz <zegentzy@protonmail.com>
Adam Jackson <ajax@redhat.com>
Robert Mader <robert.mader@posteo.de>
Contacts
Hal Gentz <zegentzy@protonmail.com>
Status
Draft
Version
Version 4, 2021-06-24
Number
EGL Extension #145
Extension Type
EGL client extension
Dependencies
This extension is written against the wording of the 2014.08.27 revision
of the EGL 1.5 Specification.
Overview
This extension provides a mechanism to lower the config selection priority
of the configs returned by eglChooseConfig. A new config attribute is
introduced, providing a way for the implementation to group configs into
different config selection categories. The config selection priorities of
all the configs in one category may be higher or lower than the ones in
other categories. The config selection priorities in one category follow
the rules of eglChooseConfig. See also GLX_SGIX_visual_select_group.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted as a new EGLConfig attribute:
EGL_CONFIG_SELECT_GROUP_EXT 0x34C0
Additions to the EGL 1.5 Specification
In section 3.4 "Configuration Management", under the "Buffer Descriptions
and Attributes" heading, append to table 3.1 the following:
"EGL_CONFIG_SELECT_GROUP_EXT | integer | the config select group"
In section 3.4 "Configuration Management", under the "Other EGLConfig
Attribute Descriptions" heading, append to the end the following:
"The attribute EGL_CONFIG_SELECT_GROUP_EXT is used to specify the config
selection category of the config. Configs in the i-th category have a higher
config selection priority than those found in the (i+1)-th category.
"The attribute EGL_CONFIG_SELECT_GROUP_EXT is used by the implementation to
override the default sorting rules, by collecting configurations into
groups. It is not accepted by the <attrib_list> parameter of
eglChooseConfig, but it is accepted as the <attribute> in
eglGetConfigAtrrib."
In section 3.4 "Configuration Management", under the "Sorting of EGLConfigs"
heading, append to table 3.4 the following:
"EGL_CONFIG_SELECT_GROUP_EXT | 0 | Ignore | Smaller | 0"
In section 3.4 "Configuration Management", under the "Sorting of EGLConfigs"
heading, append before the list entry which starts with "1. Special: by
EGL_CONFIG_CAVEAT" the following entry:
"0. Smaller EGL_CONFIG_SELECT_GROUP_EXT."
Issues
None
Revision History
Version 4, 2021-06-24 (Robert Mader)
- Moved to EXT, changed enum value to 0x34C0.
Version 3, 2020-04-06 (Robert Mader)
- Changed enum value to 0x31DF, added contributors.
Version 2, 2019-07-11 (Hal Gentz)
- Resolved issues pointed out by Adam Jackson.
Version 1, 2019-06-21 (Hal Gentz)
- Initial draft
extensions/EXT/EGL_EXT_create_context_robustness.txt
+169
View File
@@ -0,0 +1,169 @@
Name
EXT_create_context_robustness
Name Strings
EGL_EXT_create_context_robustness
Contributors
Daniel Koch, TransGaming
Contributors to EGL_KHR_create_context
Contact
Greg Roth (groth 'at' nvidia.com)
Status
Complete.
Version
Version 3, 2011/10/31
Number
EGL Extension #37
Dependencies
Requires EGL 1.4
Written against the EGL 1.4 specification.
An OpenGL implementation supporting GL_ARB_robustness, an OpenGL ES
implementation supporting GL_EXT_robustness, or an implementation
supporting equivalent functionality is required.
Overview
This extension allows creating an OpenGL or OpenGL ES context
supporting robust buffer access behavior and a specified graphics
reset notification behavior.
New Procedures and Functions
None
New Tokens
Accepted as an attribute name in the <*attrib_list> argument to
eglCreateContext:
EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT 0x30BF
EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_EXT 0x3138
Accepted as an attribute value for EGL_CONTEXT_RESET_NOTIFICATION_-
STRATEGY_EXT in the <*attrib_list> argument to eglCreateContext:
EGL_NO_RESET_NOTIFICATION_EXT 0x31BE
EGL_LOSE_CONTEXT_ON_RESET_EXT 0x31BF
Additions to the EGL 1.4 Specification
Replace section 3.7.1 "Creating Rendering Contexts" from the
fifth paragraph through the seventh paragraph:
<attrib_list> specifies a list of attributes for the context. The
list has the same structure as described for eglChooseConfig. If an
attribute is not specified in <attrib_list>, then the default value
specified below is used instead. <attrib_list> may be NULL or empty
(first attribute is EGL_NONE), in which case attributes assume their
default values as described below. Most attributes are only meaningful
for specific client APIs, and will generate an EGL_BAD_ATTRIBUTE
error when specified to create for another client API context.
Context Versions
----------------
EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL ES
context to create. This attribute may only be specified when creating
an OpenGL ES context (e.g. when the current rendering API is
EGL_OPENGL_ES_API). An attribute value of 1 specifies creation of an
OpenGL ES 1.x context. An attribute value of 2 specifies creation of an
Open GL ES 2.x context. The default value for EGL_CONTEXT_CLIENT_VERSION
is 1.
Context Robust Access
-------------
EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT indicates whether <robust buffer
access> should be enabled for the OpenGL ES context. Robust buffer
access is defined in the GL_EXT_robustness extension specification,
and the resulting context must support GL_EXT_robustness and robust
buffer access as described therein. The default value of
EGL_CONTEXT_OPENGL_ROBUST_ACCESS_EXT is EGL_FALSE.
Context Reset Notification
--------------------------
The attribute name EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_-
EXT specifies the <reset notification behavior> of the rendering
context. This attribute is only meaningful for OpenGL ES contexts,
and specifying it for other types of contexts will generate an
EGL_BAD_ATTRIBUTE error.
Reset notification behavior is defined in the GL_EXT_robustness
extension for OpenGL ES, and the resulting context must support
GL_EXT_robustness and the specified reset strategy. The attribute
value may be either EGL_NO_RESET_NOTIFICATION_EXT or EGL_LOSE_-
CONTEXT_ON_RESET_EXT, which respectively result in disabling
delivery of reset notifications or the loss of all context state
upon reset notification as described by the GL_EXT_robustness. The
default value for EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_EXT
is EGL_NO_RESET_NOTIFICATION_EXT.
Add to the eglCreateContext context creation errors:
* If <config> does not support a client API context compatible
with the requested context flags and context reset notification
behavior (for client API types where these attributes are
supported), then an EGL_BAD_CONFIG error is generated.
* If the reset notification behavior of <share_context> and the
newly created context are different then an EGL_BAD_MATCH error is
generated.
Errors
EGL_BAD_CONFIG is generated if EGL_CONTEXT_OPENGL_ROBUST_ACCESS_-
EXT is set to EGL_TRUE and no GL context supporting the GL_EXT_-
robustness extension and robust access as described therein can be
created.
EGL_BAD_CONFIG is generated if no GL context supporting the
GL_EXT_robustness extension and the specified reset notification
behavior (the value of attribute EGL_CONTEXT_RESET_NOTIFICATION_-
STRATEGY_EXT) can be created.
BAD_MATCH is generated if the reset notification behavior of
<share_context> does not match the reset notification behavior of
the context being created.
New State
None
Conformance Tests
TBD
Sample Code
TBD
Issues
None
Revision History
Rev. Date Author Changes
---- ------------ --------- ----------------------------------------
3 31 Oct 2011 groth Reverted to attribute for robust access. Now it's a
companion to rather than subset of KHR_create_context
2 11 Oct 2011 groth Merged ANGLE and NV extensions.
1 15 July 2011 groth Initial version
extensions/EXT/EGL_EXT_device_base.txt
+243
View File
@@ -0,0 +1,243 @@
Name
EXT_device_base
Name Strings
EGL_EXT_device_base
Contributors
James Jones
Daniel Kartch
Jamie Madill
Contacts
James Jones, NVIDIA (jajones 'at' nvidia.com)
Status
Complete
Rewritten in terms of split functionality in EXT_dispay_device and
EXT_device_enumeration.
Version
Version 9 - March 24th, 2015
Number
EGL Extension #72
Extension Type
EGL client extension
Dependencies
Written against the wording of EGL 1.5.
The specifications of EGL_EXT_device_query and
EGL_EXT_device_enumeration are required to determine the
specification of this extension, although those extensions may not
be supported.
Overview
Increasingly, EGL and its client APIs are being used in place of
"native" rendering APIs to implement the basic graphics
functionality of native windowing systems. This creates demand
for a method to initialize EGL displays and surfaces directly on
top of native GPU or device objects rather than native window
system objects. The mechanics of enumerating the underlying
native devices and constructing EGL displays and surfaces from
them have been solved in various platform and implementation-
specific ways. The EGL device family of extensions offers a
standardized framework for bootstrapping EGL without the use of
any underlying "native" APIs or functionality.
This extension defines the first step of this bootstrapping
process: Device enumeration.
New Types
As defined by EGL_EXT_device_query.
New Functions
As defined by EGL_EXT_device_query and EGL_EXT_device_enumeration.
New Tokens
As defined by EGL_EXT_device_query.
Add to section "3.2 Devices"
"EGL_EXT_device_base is equivalent to the combination of the
functionality defined by EGL_EXT_device_query and
EGL_EXT_device_enumeration."
Issues
1. Should there be a mechanism (such as an attribute list) to
filter devices in eglQueryDevicesEXT()?
RESOLVED: No. This could develop too much complexity, like
the EGLConfig mechanism. Instead, force applications to query
all devices and implement any desired filtering themselves.
2. Should there be an eglSetDeviceAttribEXT()?
RESOLVED: No. Device properties are immutable.
3. Should a device file descriptor attribute be included in the
base specification?
RESOLVED: No. It seems like an arbitrary attribute to include
in the base extension. Other extensions can easily be added
if this or other device attributes are needed.
4. Should EGLDeviceEXT handles be opaque pointers or 32-bit
values?
RESOLVED: Opaque pointers. The trend seems to be to use
opaque pointers for object handles, and opaque pointers allow
more implementation flexibility than 32-bit values.
Additionally, the introduction of the EGLAttrib type allows
inclusion of pointer-sized types in attribute lists, which was
the only major advantage of 32-bit types.
5. Should eglQueryDisplayAttribEXT be defined as part of this
extension?
RESOLVED: Yes. There are no other known uses for this
function, so it should be defined here. If other uses are
found, future extension specifications can reference this
extension or retroactively move it to a separate extension.
6. How should bonded GPU configurations, such as SLI or Crossfire
be enumerated? What about other hybrid rendering solutions?
RESOLVED: Bonded GPUs should appear as one device in this API,
since the client APIs generally treat them as one device.
Further queries can be added to distinguish the lower-level
hardware within these bonded devices.
Hybrid GPUs, which behave independently but are switched
between in a manner transparent to the user, should be
enumerated separately. This extension is intended to be used
at a level of the software stack below this type of automatic
switching or output sharing.
7. Should this extension require all displays to have an
associated, queryable device handle?
RESOLVED: Yes. This allows creating new namespace containers
that all displays can be grouped in to and allows existing
applications with display-based initialization code to easily
add device-level functionality. Future extensions are
expected to expose methods to correlate EGL devices and native
devices, and to use devices as namespaces for future objects
and operations, such as cross-display EGL streams.
8. Are device handles returned by EGL valid in other processes?
RESOLVED: No. Another level of indirection is required to
correlate two EGL devices in separate processes.
9. Is a general display pointer query mechanism needed, or should
an eglGetDevice call be added to query a display's associated
device?
RESOLVED: A general mechanism is better. It may have other
uses in the future.
10. Should a new type of extension be introduced to query device-
specific extensions?
RESOLVED: Yes. Without this mechanism, it is likely that most
device extensions would require a separate mechanism to
determine which devices actually support them. Further,
requiring all device-level extensions to be listed as client
extensions forces them to be implemented in the EGL client
library, or "ICD". This is unfortunate since vendors will
likely wish to expose vendor-specific device extensions.
These advantages were weighed against the one known
disadvantage of a separate extension type: Increasing the
complexity of this extension and the EGL extension mechanism
in general.
11. Is eglQueryDeviceStringEXT necessary, or should the device
extension string be queried using eglQueryDeviceAttribEXT?
RESOLVED: Using a separate query seems more consistent with
how the current extension strings are queried.
12. Should this extension contain both device enumeration and
the ability to query the device backing an EGLDisplay?
RESOLVED: This extension initially included both of these
abilities. To allow simpler implementations to add only the
ability to query the device of an existing EGLDisplay, this
extension was split into two separate extensions:
EGL_EXT_device_query
EGL_EXT_device_enumeration
The presence of this extension now only indicates support
for both of the above extensions.
Revision History:
#9 (March 24th, 2015) James Jones
- Split the extension into two child extensions:
EGL_EXT_device_query
EGL_EXT_device_enumeration
#8 (May 16th, 2014) James Jones
- Marked the extension complete.
- Marked all issues resolved.
#7 (April 8th, 2014) James Jones
- Renamed eglGetDisplayAttribEXT back to
eglQueryDisplayAttribEXT.
- Update wording based on the EGL 1.5 specification.
- Use EGLAttrib instead of EGLAttribEXT.
- Assigned values to tokens.
#6 (November 6th, 2013) James Jones
- Added EGL_BAD_DEVICE_EXT error code.
- Renamed some functions for consistency with the core spec
#5 (November 6th, 2013) James Jones
- Specified this is a client extension
- Renamed eglQueryDisplayPointerEXT eglGetDisplayAttribEXT
and modified it to use the new EGLAttribEXT type rather than
a void pointer
- Introduced the "device" extension type.
- Added eglQueryDeviceStringEXT to query device extension
strings
- Removed issues 5, 10, and 12 as they are no longer relevant
- Added issues 10 and 11.
#4 (May 14th, 2013) James Jones
- Merged in EGL_EXT_display_attributes
- Changed eglGetDisplayPointerEXT to eglQueryDisplayPointerEXT
- Remove eglGetDisplayAttribEXT since it has no known use case
#3 (April 23rd, 2013) James Jones
- Include EGL_NO_DEVICE_EXT
- Added issues 8 and 9
#2 (April 18th, 2013) James Jones
- Reworded issue 3 and flipped the resolution
- Added issues 5, 6, and 7
- Filled in the actual spec language modifications
- Renamed from EGL_EXT_device to EGL_EXT_device_base
- Fixed some typos
#1 (April 16th, 2013) James Jones
- Initial Draft
extensions/EXT/EGL_EXT_device_drm.txt
+223
View File
@@ -0,0 +1,223 @@
Name
EXT_device_drm
EXT_output_drm
Name Strings
EGL_EXT_device_drm
EGL_EXT_output_drm
Contributors
Daniel Kartch
James Jones
Christopher James Halse Rogers
Contacts
Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com)
Status
Complete
Version
Version 5 - December 28th, 2015
Number
EGL Extension #79
Extension Type
EGL device extension for EGL_EXT_device_drm
EGL display extension for EGL_EXT_output_drm
Dependencies
EGL_EXT_device_drm requires EGL_EXT_device_base.
EGL_EXT_device_drm interacts with EGL_EXT_platform_device
EGL_EXT_device_drm requires a DRM driver.
EGL_EXT_output_drm requires EGL_EXT_output_base.
EGL_EXT_output_drm requires a DRM driver which supports KMS.
An EGLDisplay supporting EGL_EXT_output_drm must be associated
with an EGLDevice supporting EGL_EXT_device_drm.
Overview
Increasingly, EGL and its client APIs are being used in place of
"native" rendering APIs to implement the basic graphics
functionality of native windowing systems. This creates demand
for a method to initialize EGL displays and surfaces directly on
top of native GPU or device objects rather than native window
system objects. The mechanics of enumerating the underlying
native devices and constructing EGL displays and surfaces from
them have been solved in various platform and implementation-
specific ways. The EGL device family of extensions offers a
standardized framework for bootstrapping EGL without the use of
any underlying "native" APIs or functionality.
These extensions define how to map device and output handles between
EGL and DRM/KMS. An EGL implementation which provides these
extensions must have access to sufficient knowledge of the DRM
implementation to be able to perform these mappings. No requirements
are imposed on how this information is obtained, nor does this
support have any implications for how EGL devices and outputs are
implemented. Among the possibilities, support may be implemented in
a generic fashion by layering on top of DRM, or EGL and DRM backends
may be provided by the same vendor and share privileged lower level
resources. An implementation which supports these extensions may
support other low level device interfaces, such as OpenWF Display,
as well.
New Types
None
New Procedures and Functions
None
New Tokens
Added by EXT_device_drm:
Accepted as the <name> parameter of eglQueryDeviceStringEXT
EGL_DRM_DEVICE_FILE_EXT 0x3233
If EGL_EXT_platform_device is present, the following is accepted
in the <attrib_list> of eglGetPlatformDisplayEXT().
EGL_DRM_MASTER_FD_EXT 0x333C
Added by EXT_output_drm:
Accepted in the <attrib_list> of eglGetOutputLayersEXT and as
the <attribute> parameter of eglQueryOutputLayerAttribEXT
EGL_DRM_CRTC_EXT 0x3234
EGL_DRM_PLANE_EXT 0x3235
Accepted in the <attrib_list> of eglGetOutputPortsEXT and as
the <attribute> parameter of eglQueryOutputPortAttribEXT
EGL_DRM_CONNECTOR_EXT 0x3236
New Behavior for EXT_device_drm
EGLDeviceEXTs may be mapped to DRM device files.
To obtain a DRM device file for an EGLDeviceEXT, call
eglQueryDeviceStringEXT with <name> set to EGL_DRM_DEVICE_FILE_EXT.
The function will return a pointer to a string containing the name
of the device file (e.g. "/dev/dri/cardN").
If EGL_EXT_platform_device is present, replace the last sentence of the
third paragraph in section 3.2 "Initialization" with the following:
When <platform> is EGL_PLATFORM_DEVICE_EXT, the only valid attribute
name is EGL_DRM_MASTER_FD_EXT. If specified, the value must be a file
descriptor with DRM master permissions on the DRM device associated
with the specified EGLDevice, as determined by EGL_DRM_DEVICE_FILE_EXT.
If the file descriptor does not refer to the correct DRM device or
does not have master permissions, the behavior is undefined. Calls to
eglGetPlatformDeviceEXT() with the same values for <platform> and
<native_display> but distinct EGL_DRM_MASTER_FD_EXT values will return
separate EGLDisplays.
If EGL requires the use of the DRM file descriptor beyond the duration
of the call to eglGetPlatformDispay(), it will duplicate it. If no
file descriptor is specified and EGL requires one, it will attempt to
open the device itself. Applications should only need to specify a
file descriptor in situations where EGL may fail to open a file
descriptor itself, generally due to lack of permissions, or when EGL
will fail to acquire DRM master permissions due to conflicts with an
existing DRM client. DRM master permissions are only required when EGL
must modify output attributes. This extension does not define any
situations in which output attributes will be modified.
New Behavior for EXT_output_drm
KMS CRTC, plane, and connector IDs may be used to restrict EGL
output handle searches and may be queried from EGL output handles.
Add to Table 3.10.3.1 in EGL_EXT_output_base:
Attribute Type Access
--------------------- ------- ------
EGL_DRM_CRTC_EXT integer S|R
EGL_DRM_PLANE_EXT integer S|R
Add to Table 3.10.3.2 in EGL_EXT_output_base:
Attribute Type Access
--------------------- ------- ------
EGL_DRM_CONNECTOR_EXT integer S|R
Add to description of eglOutputLayerAttribEXT:
If <layer> corresponds to a KMS CRTC and <attribute> is
EGL_DRM_PLANE_EXT, or if <layer> corresponds to a KMS plane and
<attribute> is EGL_DRM_CRTC_EXT, an EGL_BAD_MATCH error is
generated.
Issues
1) Should different values of EGL_DRM_MASTER_FD_EXT result in separate
EGLDisplays?
RESOLVED: Yes. Consider an application made up of two independent
modules running in two independently scheduled threads. Each
module calls eglGetPlatformDisplayEXT():
int fd = open("/dev/dri/card0", O_RDWR);
int attr1[] = { EGL_DRM_MASTER_FD_EXT, fd };
dpy1 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT,
eglDev,
attr1);
...
dpy2 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT,
eglDev,
NULL);
Presumably, if dpy1 == dpy2, they would both be using the same DRM
fd for output operations internally. That would mean display
attribute updates would likely fail if dpy2 happened to be created
before dpy1. This would be painful to debug. If dpy2 != dpy1,
failure for dpy2 would be consistent and obvious. The application
author would be required to work out a scheme to share the master
FD between modules before creating EGL displays.
Revision History:
#5 (December 28th, 2015) James Jones
- Added EGL_DRM_MASTER_FD_EXT and associated
language.
- Added issue 1.
#4 (August 22nd, 2014) James Jones
- Marked complete.
- Listed Daniel as the contact.
#3 (June 5th, 2014) Daniel Kartch
- Assigned enumerated values for constants.
#2 (May 28th, 2014) Daniel Kartch
- Simplified description of new behavior based on refinements
to EGL_EXT_output_base.
#1 (January 31st, 2014) Daniel Kartch
- Initial draft, representing a signficant reworking of
functionality previously proposed in
EGL_EXT_native_device_drm.
extensions/EXT/EGL_EXT_device_drm_render_node.txt
+106
View File
@@ -0,0 +1,106 @@
Name
EXT_device_drm_render_node
Name Strings
EXT_device_drm_render_node
Contributors
James Jones
Simon Ser
Daniel Stone
Contacts
James Jones, NVIDIA (jajones 'at' nvidia.com)
Status
Draft
Version
Version 1 - June 4th, 2021
Number
EGL Extension #144
Extension Type
EGL device extension
Dependencies
Written based on the wording of the EGL 1.5 specification.
EGL_EXT_device_query is required.
EGL_EXT_device_drm interacts with this extension.
Overview
The EGL_EXT_device_drm extension provided a method for applications
to query the DRM device node file associated with a given
EGLDeviceEXT object. However, it was not clear whether it referred to
the primary or render device node. This extension adds an enum to
refer explicitly to the render device node and defines the existing
EGL_DRM_DEVICE_FILE_EXT as explicitly refering to the primary device
node.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted as the <name> parameter of eglQueryDeviceStringEXT
EGL_DRM_RENDER_NODE_FILE_EXT 0x3377
Changes to section 3.2 (Devices)
Add the following paragraph to the description of
eglQueryDeviceStringEXT:
"To obtain a DRM device file for the render node associated with an
EGLDeviceEXT, call eglQueryDeviceStringEXT with <name> set to
EGL_DRM_RENDER_NODE_FILE_EXT. The function will return a pointer to
a string containing the name of the device file (e.g.
"/dev/dri/renderDN"), or NULL if the device has no associated DRM
render node."
If EGL_EXT_device_drm is present, append the following to the
paragraph in the same section describing EGL_DRM_DEVICE_FILE_EXT:
"If the EGL_EXT_device_drm_render_node extension is supported, the
value returned will refer to a primary device node, and will be NULL
if the device has no associated DRM primary node. If
EGL_EXT_device_drm_render_node is not supported, the value returned
will refer to a primary device node if there exists one associated
with the device. Otherwise, it will refer to a render device node if
there exists one associated with the device. If neither exists, NULL
is returned."
Issues
1) Should this extension clarify that EGL_DRM_DEVICE_FILE_EXT refers
only to primary device nodes?
RESOLVED: Yes, but only when this extension is supported. Existing
implementations return render node paths for that string when no
suitable primary node is available.
Revision History:
#2 (June 8th, 2021) James Jones
- Added issue #1 and related spec changes.
#1 (June 4th, 2021) James Jones
- Initial draft.
extensions/EXT/EGL_EXT_device_enumeration.txt
+111
View File
@@ -0,0 +1,111 @@
Name
EXT_device_enumeration
Name Strings
EGL_EXT_device_enumeration
Contributors
James Jones
Jamie Madill
Contacts
James Jones, NVIDIA (jajones 'at' nvidia.com)
Status
Complete.
Version
Version 1 - March 24th, 2015
Number
EGL Extension #88
Extension Type
EGL client extension
Dependencies
Written against the wording of EGL 1.5.
Requires EGL 1.5 or an earlier verison of EGL with the
EGL_EXT_client_extensions extension.
Requires the EGL_EXT_device_query extension.
Overview
Increasingly, EGL and its client APIs are being used in place of
"native" rendering APIs to implement the basic graphics
functionality of native windowing systems. This creates demand
for a method to initialize EGL displays and surfaces directly on
top of native GPU or device objects rather than native window
system objects. The mechanics of enumerating the underlying
native devices and constructing EGL displays and surfaces from
them have been solved in various platform and implementation-
specific ways. The EGL device family of extensions offers a
standardized framework for bootstrapping EGL without the use of
any underlying "native" APIs or functionality.
The original EGL_EXT_device_base extension combined the conceptually
separate operations of querying the underlying device used by a
given EGLDisplay and enumerating devices from scratch. It was later
identified that the former is useful even in EGL implementations
that have no need or ability to allow enumerating all the devices
available on a system. To accommodate this, the extension was
split in two.
New Types
None
New Functions
EGLBoolean eglQueryDevicesEXT(EGLint max_devices,
EGLDeviceEXT *devices,
EGLint *num_devices);
Add the following at the beginning of section "3.2 Devices"
"EGL devices can be enumerated before EGL is initialized. Use:
EGLBoolean eglQueryDevicesEXT(EGLint max_devices,
EGLDeviceEXT *devices,
EGLint *num_devices);
"to obtain a list of all supported devices in the system. On
success, EGL_TRUE is returned, and <num_devices> devices are
stored in the array pointed to by <devices>. <num_devices> will
be less than or equal to <max_devices>. If <devices> is NULL,
then <max_devices> will be ignored, no devices will be returned in
<devices>, and <num_devices> will be set to the number of
supported devices in the system. All implementations must support
at least one device.
"On failure, EGL_FALSE is returned. An EGL_BAD_PARAMETER error is
generated if <max_devices> is less than or equal to zero unless
<devices> is NULL, or if <num_devices> is NULL."
Remove the following paragraph from section "3.4 Display Attributes"
"Because the EGLDeviceEXT is a property of <dpy>, any use of an
associated EGLDeviceEXT after <dpy> has been terminated gives
undefined results. Querying an EGL_DEVICE_EXT from <dpy> after a
call to eglTerminate() (and subsequent re-initialization) may
return a different value."
Issues
None
Revision History:
#1 (March 24th, 2015) James Jones
- Initial branch from EGL_EXT_device_base version #8
extensions/EXT/EGL_EXT_device_openwf.txt
+230
View File
@@ -0,0 +1,230 @@
Name
EXT_device_openwf
EXT_output_openwf
Name Strings
EGL_EXT_device_openwf
EGL_EXT_output_openwf
Contributors
Daniel Kartch
James Jones
Christopher James Halse Rogers
Contacts
Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com)
Status
Complete
Version
Version 5 - January 21, 2016
Number
EGL Extension #80
Extension Type
EGL device extension for EGL_EXT_device_openwf
EGL display extension for EGL_EXT_output_openwf
Dependencies
EGL_EXT_device_openwf requires EGL_EXT_device_base.
EGL_EXT_output_openwf requires EGL_EXT_output_base.
Both require OpenWF Display
EGL_EXT_device_openwf interacts with EGL_EXT_platform_device
An EGLDisplay supporting EGL_EXT_output_openwf must be associated
with an EGLDevice supporting EGL_EXT_device_openwf.
Overview
Increasingly, EGL and its client APIs are being used in place of
"native" rendering APIs to implement the basic graphics
functionality of native windowing systems. This creates demand
for a method to initialize EGL displays and surfaces directly on
top of native GPU or device objects rather than native window
system objects. The mechanics of enumerating the underlying
native devices and constructing EGL displays and surfaces from
them have been solved in various platform and implementation-
specific ways. The EGL device family of extensions offers a
standardized framework for bootstrapping EGL without the use of
any underlying "native" APIs or functionality.
These extensions define how to map device and output handles between
EGL and OpenWF Display. An EGL implementation which provides these
extensions must have access to sufficient knowledge of the OpenWF
implementation to be able to perform these mappings. No requirements
are imposed on how this information is obtained, nor does this
support have any implications for how EGL devices and outputs are
implemented. An implementation which supports these extensions may
support other low level device interfaces, such as DRM/KMS, as well.
New Types
None
New Procedures and Functions
None
New Tokens
Added by EXT_device_openwf:
Accepted as the <attribute> parameter of eglQueryDeviceAttribEXT
EGL_OPENWF_DEVICE_ID_EXT 0x3237
If EGL_EXT_platform_device is present, the following is accepted
in the <attrib_list> of eglGetPlatformDisplayEXT().
EGL_OPENWF_DEVICE_EXT 0x333D
Added by EXT_output_openwf:
Accepted in the <attrib_list> of eglGetOutputLayersEXT and as
the <attribute> parameter of eglQueryOutputLayerAttribEXT
EGL_OPENWF_PIPELINE_ID_EXT 0x3238
Accepted in the <attrib_list> of eglGetOutputPortsEXT and as
the <attribute> parameter of eglQueryOutputPortAttribEXT
EGL_OPENWF_PORT_ID_EXT 0x3239
New Behavior for EXT_device_openwf
EGLDeviceEXTs may be mapped to OpenWF Display devices.
To obtain a WFD_DEVICE_ID for an EGLDeviceEXT, call
eglQueryDeviceAtribEXT with <attribute> set to
EGL_OPENWF_DEVICE_ID_EXT.
If EGL_EXT_platform_device is present, replace the last sentence of the
third paragraph in section 3.2 "Initialization" with the following:
When <platform> is EGL_PLATFORM_DEVICE_EXT, the only valid attribute
name is EGL_OPENWF_DEVICE_EXT. If specified, the value must be a
WFDDevice created with the device ID returned by querying
EGL_OPENWF_DEVICE_ID_EXT from the specified EGLDevice. If the device
handle does not refer to the correct OpenWF device the behavior is
undefined. Calls to eglGetPlatformDeviceEXT() with the same values
for <platform> and <native_display> but distinct EGL_OPENWF_DEVICE_EXT
values will return separate EGLDisplays.
EGL may require the use of the OpenWF device beyond the duration of
the call to eglGetPlatformDisplayEXT(). The application must ensure
the device handle remains valid for the lifetime of the display
returned. If no OpenWF device handle is specified and EGL requires
one, it will attempt to create the device itself. Applications
should only need to specify an OpenWF device in situations where EGL
may fail to create one itself due to an existing instance of the same
underlying device in the process.
New Behavior for EXT_output_openwf
OpenWF pipeline and port IDs may be used to restrict EGL output
handle searches and may be queried from EGL output handles.
Add to Table 3.10.3.1 in EGL_EXT_output_base:
Attribute Type Access
-------------------------- ------- ------
EGL_OPENWF_PIPELINE_ID_EXT integer S|R
Add to Table 3.10.3.2 in EGL_EXT_output_base:
Attribute Type Access
-------------------------- ------- ------
EGL_OPENWF_PORT_ID_EXT integer S|R
Issues
1. Although the overview says that we do not impose any
restrictions on how the features are implemented, restrictions
in the OpenWF specification combined with the chosen interface
here do implicitly impose limitations. Specifically, the
wfdCreate* functions can only be called once to obtain OpenWF
handles. This means that an EGLDevice/Output implementation
cannot be layered on top of OpenWF without preventing the
application from calling these functions. So we must assume that
the implementation instead has some backdoor into OpenWF to
obtain the object IDs. Possible resolutions include:
a) Keep the access model as is. This assumption is a reasonable
one.
b) Flip the requirement. The EGL device/output implementation
should always create the OpenWF handles itself. We can add
queries so that the application can get these handles from
EGL.
c) Generalize this extension to support both models. The
application would have to first query EGL to determine
whether or not it owns the handles, and then be prepared to
either query them from EGL or create them itself.
d) Require the application to provide its OpenWF device handle
if it has one.
RESOLVED: (d), though implementations are free to use (a) when
possible.
2. Should different values of EGL_OPENWF_DEVICE_EXT result in separate
EGLDisplays?
RESOLVED: Yes. Consider an application made up of two independent
modules running in two independently scheduled threads. Each
module calls eglGetPlatformDisplayEXT():
WFDDevice wfdDev = wfdCreateDevice(WFD_DEFAULT_DEVICE_ID, NULL);
int attr1[] = { EGL_OPENWF_DEVICE_EXT, wfdDev };
dpy1 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT,
eglDev,
attr1);
...
dpy2 = eglGetPlatformDisplayEXT(EGL_PLATFORM_DEVICE_EXT,
eglDev,
NULL);
Presumably, if dpy1 == dpy2, they would both be using the same
WFDDevice for output operations internally. That would mean
output operations would likely fail if dpy2 happened to be created
before dpy1. This would be painful to debug. If dpy2 != dpy1,
failure for dpy2 would be consistent and obvious. The application
author would be required to work out a scheme to share the WFDDevice
between modules before creating EGL displays.
Revision History:
#5 (January 21st, 2016) James Jones
- Add EGL_OPENWF_DEVICE_EXT to resolve issue 1.
- Added possible solution (d) to issue 1, and resolve to use it.
- Added issue 2.
#4 (August 22nd, 2014) James Jones
- Marked complete.
- Listed Daniel as the contact.
#3 (June 5th, 2014) Daniel Kartch
- Assign enumerated values for constants.
#2 (May 28th, 2014) Daniel Kartch
- Simplified description of new behavior based on refinements
to EGL_EXT_output_base.
#1 (January 31st, 2014) Daniel Kartch
- Initial draft, representing a signficant reworking of
functionality previously proposed in
EGL_EXT_native_device_openwf.
extensions/EXT/EGL_EXT_device_persistent_id.txt
+202
View File
@@ -0,0 +1,202 @@
Name
EXT_device_persistent_id
Name Strings
EGL_EXT_device_persistent_id
Contributors
Kyle Brenneman, NVIDIA (kbrenneman 'at' nvidia.com)
Contact
Kyle Brenneman, NVIDIA (kbrenneman 'at' nvidia.com)
Version
Version 1 - April 19, 2021
Number
EGL Extension #142
Extension Type
EGL device extension
Dependencies
Written based on the wording of the EGL 1.5 specification.
EGL_EXT_device_query is required.
Overview
Applications can query a list of EGLDeviceEXT handles, but those
handles are only valid within the process that queried them. An
application has no way, for example, to record its selection and
select the same device when run again later.
This extension provides a vendor name and a set of UUID's, which
provide a unique, persistent identifier for EGLDeviceEXT handles.
This allows applications to find the EGLDeviceEXT for the same
device across multiple processes, and across multiple APIs.
New Procedures and Functions
EGLBoolean eglQueryDeviceBinaryEXT(EGLDeviceEXT device,
EGLint name,
EGLint max_size,
void *value,
EGLint *size);
New Tokens
Accepted by the <name> parameter of eglQueryDeviceStringEXT:
EGL_DRIVER_NAME_EXT 0x335E
Accepted by the <name> parameter of eglQueryDeviceBinaryEXT:
EGL_DEVICE_UUID_EXT 0x335C
EGL_DRIVER_UUID_EXT 0x335D
Changes to section 3.2 (Devices)
Add the following paragraph to the description of
eglQueryDeviceStringEXT:
EGL_DRIVER_NAME_EXT returns a string which identifies the driver
that controls the device. This string remains persistent across
multiple versions of a driver, and an application can use strcmp(3)
to compare the strings for equality. Otherwise, the contents are
implementation-defined.
Add to the end of section 3.2:
To query a binary attribute for a device, use:
EGLBoolean eglQueryDeviceBinaryEXT(EGLDeviceEXT device,
EGLint name,
EGLint max_size,
void *value,
EGLint *size);
On success, EGL_TRUE is returned. If <value> is NULL, then
<max_size> is ignored, and the size of the attribute in bytes is
returned in <size>.
On failure, EGL_FALSE is returned. An EGL_BAD_ATTRIBUTE error is
generated if <name> is not a valid attribute. An EGL_BAD_DEVICE_EXT
error is generated if <device> is not a valid EGLDeviceEXT.
If <value> is not NULL, then the attribute value is returned in
<value>. At most <max_size> bytes are written. <size> returns the
number of bytes that were actually written.
Note that the EGL_DEVICE_UUID_EXT and EGL_DRIVER_UUID_EXT attributes
are always 16-byte values, and so the application can simply use a
16-byte buffer without needing to query the size beforehand. Future
extensions may add variable-length attributes.
EGL_DEVICE_UUID_EXT is a UUID that identifies a physical device,
returned as a 16-byte binary value. The device UUID uniquely
identifies a physical device, and is persistent across reboots,
processes, APIs, and (to the extent possible) driver versions.
EGL_DEVICE_UUID_EXT may or may not be persistent across changes in
hardware configuration. Similarly, it is not guaranteed to be unique
or persistent across different (physical or virtual) computers.
Note that EGL_DEVICE_UUID_EXT alone is not guaranteed to be unique
across all EGLDeviceEXT handles. If an EGL implementation supports
multiple drivers, and two drivers can use the same physical device,
then there will be a separate EGLDeviceEXT handle from each driver.
Both EGLDeviceEXT handles may use the same device UUID.
In that case, an application must use EGL_DRIVER_NAME_EXT or
EGL_DRIVER_UUID_EXT to distinguish between the two EGLDeviceEXT
handles.
EGL_DRIVER_UUID_EXT is a UUID that identifies a driver build
in use for a device. The driver UUID is persistent across reboots,
processes, and APIs, but is not persistent across driver versions.
Issues
1. Should we use UUID's or strings to identify devices?
RESOLVED: Use UUID's for devices, plus a vendor name string to
disambiguate devices that are supported by multiple drivers.
A device UUID and driver UUID allow an application to correlate
an EGLDeviceEXT with the same device in other APIs, such as a
VkPhysicalDevice in Vulkan.
A UUID does not impose any additional requirements on an EGL
implementation compared to a string: If an EGL implementation
could generate a string identifier, then the implementation can
simply hash that string to generate a UUID value.
2. Can two EGLDeviceEXT handles have the same EGL_DEVICE_UUID_EXT?
RESOLVED: Yes, if they correspond to the same physical device.
The semantics of the device and driver UUID's are inherited from
Vulkan, which only requires that a device UUID be unique to a
physical device, not unique across VkPhysicalDevice handles.
3. Do we need the EGL_DRIVER_NAME_EXT string?
RESOLVED: Yes, because the EGL_DEVICE_UUID_EXT alone is not
unique, and EGL_DRIVER_UUID_EXT is not persistent.
A (EGL_DRIVER_NAME_EXT, EGL_DEVICE_UUID_EXT) pair provides a
unique, persistent identifier.
In addition, on systems that use libglvnd, applications could
use EGL_DRIVER_NAME_EXT to match the vendor names from
GLX_EXT_libglvnd.
4. What happens if an application stores a device UUID, and the
hardware configuration or driver version changes?
RESOLVED: The device UUID may become invalid, and the
application should select a new device.
If a device is removed from a system, then there will be no
EGLDeviceEXT handle for it, and thus no device UUID for it.
Similarly, if a device is moved within a system (e.g., plugged
into a different PCI slot), then a driver may not be able to
identify it as the same device, and so the device might get a
different UUID.
While not a requirement, drivers should still try to keep device
UUID's persistent whenever possible, to avoid invalidating
config files. Similarly, if a device is removed or replaced,
then a driver should try to ensure that the same device UUID
does not refer to a different device.
As an example, a driver could derive a UUID based on a PCI
vendor and device number, plus the PCI domain, bus, slot, and
function numbers:
* The PCI device number ensures that replacing a GPU with a
different model in the same PCI slot produces a different
device UUID string.
* Using the PCI bus numbers ensures that two identical
GPU's in the same system have unique UUID's.
* The whole tuple can easily stay persistent across driver
versions.
Revision History
#1 (April 19, 2021) Kyle Brenneman
- Initial draft
extensions/EXT/EGL_EXT_device_query.txt
+188
View File
@@ -0,0 +1,188 @@
Name
EXT_device_query
Name Strings
EGL_EXT_device_query
Contributors
James Jones, NVIDIA (jajones 'at' nvidia.com)
Jamie Madill, Google (jmadill 'at' google.com)
Contacts
Jamie Madill, Google (jmadill 'at' google.com)
Status
Complete.
Version
Version 1 - Mar 25rd, 2015
Number
EGL Extension #89
Extension Type
EGL client extension
Dependencies
Written against the wording of EGL 1.5.
Requires EGL 1.5 or an earlier verison of EGL with the
EGL_EXT_client_extensions extension.
Overview
Increasingly, EGL and its client APIs are being used in place of
"native" rendering APIs to implement the basic graphics
functionality of native windowing systems. This creates demand
for a method to access native GPU or device objects directly
rather than calling EGL or GL entry points.
This extension defines the method for an application to query
native device objects from an EGL Display.
New Types
This is the type of a handle that represents an EGLDeviceEXT
object.
typedef void* EGLDeviceEXT;
If EGL 1.5 is not supported, the following type is added, as
defined in the EGL 1.5 specification:
typedef intptr_t EGLAttrib;
New Functions
EGLBoolean eglQueryDeviceAttribEXT(EGLDeviceEXT device,
EGLint attribute,
EGLAttrib *value);
const char *eglQueryDeviceStringEXT(EGLDeviceEXT device,
EGLint name);
EGLBoolean eglQueryDisplayAttribEXT(EGLDisplay dpy,
EGLint attribute,
EGLAttrib *value);
New Tokens
Functions with a return type of EGLDeviceEXT will return this
value on failure:
EGL_NO_DEVICE_EXT ((EGLDeviceEXT)0)
This error value will be generated by functions that take an
EGLDeviceEXT object as a parameter:
EGL_BAD_DEVICE_EXT 0x322B
Accepted by the <attribute> parameter of
eglQueryDisplayAttribEXT:
EGL_DEVICE_EXT 0x322C
Add a new section "2.1.2 Devices" after "2.1.1 Scalar Types"
All EGL operations occur on an EGLDeviceEXT. However, devices
themselves expose no functionality. They are simple abstract
objects that exist only for the sake of enumeration and
defining a namespace.
Modify the last sentence of section "2.1.3" Displays" to read:
Besides devices, objects are always specified by the combination
of an EGLDisplay parameter with a parameter representing the
handle of the object.
Add a new extension type to the list in section "2.8 Extensions"
Device Extensions
A *device extension* adds functionality to an individual
EGLDeviceEXT. Different instances of EGLDeviceEXT may support
different sets of device extensions
Add a new error to section "3.1 Errors"
EGL_BAD_DEVICE_EXT
An EGLDeviceEXT argument does not refer to a valid
EGLDeviceEXT. Any command taking an EGLDeviceEXT parameter
may generate this error.
Add a section "3.2 Devices" after "3.1 Errors"
To query the properties of a device, use:
EGLBoolean eglQueryDeviceAttribEXT(EGLDeviceEXT device,
EGLint attribute,
EGLAttrib *value);
On success, EGL_TRUE is returned and the requested attribute value
is returned in <value>. Currently there are no valid values of
<attribute> defined.
On failure, EGL_FALSE is returned. An EGL_BAD_ATTRIBUTE error is
generated if <attribute> is not a valid attribute. An
EGL_BAD_DEVICE_EXT error is generated if <device> is not a valid
EGLDeviceEXT.
const char *eglQueryDeviceStringEXT(EGLDeviceEXT device,
EGLint name);
returns a pointer to a static, zero-terminated string describing
some aspect of the specified EGLDeviceEXT. <name> must be
EGL_EXTENSIONS.
The EGL_EXTENSIONS string describes which device extensions are
supported by <device>. The string is of the same format specified
for display and client extension strings in section 3.4. Note that
device extensions are properties of the device, and are distinct
from other extension strings.
On failure, NULL is returned. An EGL_BAD_DEVICE_EXT error is
generated if <device> is not a valid EGLDeviceEXT. An
EGL_BAD_PARAMETER error is generated if <name> is not one of the
values described above.
Add a section "3.4 Display Attributes" after "3.3 EGL Versioning"
To query attributes of an initialized display, use:
EGLBoolean eglQueryDisplayAttribEXT(EGLDisplay dpy,
EGLint name,
EGLAttrib *value);
On success, EGL_TRUE is returned. If <name> is EGL_DEVICE_EXT,
the EGLDeviceEXT associated with <dpy> is returned in <value>.
All displays have an associated EGLDeviceEXT, regardless of how
they were created. A successful query of EGL_DEVICE_EXT will
never return EGL_NO_DEVICE_EXT.
On failure, EGL_FALSE is returned. An EGL_NOT_INITIALIZED error
is generated if EGL is not initialized for <dpy>. An
EGL_BAD_ATTRIBUTE error is generated if <name> is not a valid
value.
Because the EGLDeviceEXT is a property of <dpy>, any use of an
associated EGLDeviceEXT after <dpy> has been terminated gives
undefined results. Querying an EGL_DEVICE_EXT from <dpy> after a
call to eglTerminate() (and subsequent re-initialization) may
return a different value.
Issues
None.
Revision History:
#1 (Mar 25rd, 2015) Jamie Madill
- Initial Draft based on EGL_EXT_device_base
extensions/EXT/EGL_EXT_device_query_name.txt
+104
View File
@@ -0,0 +1,104 @@
Name
EXT_device_query_name
Name Strings
EGL_EXT_device_query_name
Contributors
Kyle Brenneman, NVIDIA (kbrenneman 'at' nvidia.com)
Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com)
Contact
Kyle Brenneman, NVIDIA (kbrenneman 'at' nvidia.com)
Status
Complete
Version
Version 1 - June 12, 2020
Number
EGL Extension #140
Extension Type
EGL device extension
Dependencies
Written based on the wording of the EGL 1.5 specification.
EGL_EXT_device_query is required.
Overview
The EGL_EXT_device_enumeration and EGL_EXT_device_query extensions
provide a list of devices and a list of extensions, but lacks a way
to find a name for a device that an application can present to a
user.
This extension adds two new strings that an application can query to
find human-readable names.
New Types
None
New Functions
None
New Tokens
Accepted by the <name> parameter of eglQueryDeviceStringEXT:
EGL_RENDERER_EXT 0x335F
New Device Queries
eglQueryDeviceStringEXT accepts two new attributes.
EGL_VENDOR and EGL_RENDERER_EXT return a human-readable name for the
vendor and device, respectively.
The format of the EGL_VENDOR and EGL_RENDERER strings is
implementation-dependent.
The EGL_VENDOR string for an EGLDeviceEXT is not required to match
the EGL_VENDOR string for an EGLDisplay or the GL_VENDOR string for
a context. Similarly, the EGL_RENDERER string is not required to
match the GL_RENDERER string for a context.
Issues
1. Do we need a device query, instead of just creating an
EGLDisplay and calling eglQueryString?
RESOLVED: Yes, a device-level query is useful, because some
devices might not be usable with EGL_EXT_platform_device. This
is especially true on systems where different devices are
handled by different drivers.
2. If an application creates an EGLDisplay from an EGLDevice,
are the EGL_VENDOR strings required to match?
RESOLVED: No. Some implementations might not load a driver until
eglInitialize, and so might have a different or more specific
EGL_VENDOR string associated with an EGLDisplay than with an
EGLDeviceEXT. In addition, an implementation might select a
driver to use based on other parameters in
eglGetPlatformDisplay.
Revision History
#1 (June 12, 2020) Kyle Brenneman
- Initial draft
extensions/EXT/EGL_EXT_gl_colorspace_bt2020_linear.txt
+175
View File
@@ -0,0 +1,175 @@
Name
EXT_gl_colorspace_bt2020
Name Strings
EGL_EXT_gl_colorspace_bt2020_linear
EGL_EXT_gl_colorspace_bt2020_pq
Contributors
Tom Cooksey
Andrew Garrard
Jesse Hall
Mathias Heyer
Lauri Hyvarinen
Adam Jackson
James Jones
Daniel Koch
Jeff Leger
Weiwan Liu
Jeff Vigil
Contact
Weiwan Liu (weiwliu 'at' nvidia.com)
IP Status
No known IP claims.
Status
Complete
Version
Version 7 - Nov 22, 2016
Number
EGL Extension #107
Dependencies
These extensions are written against the wording of the EGL 1.5
specification (August 27, 2014).
These extensions require EGL_KHR_gl_colorspace.
Overview
Applications may wish to take advantage of a larger color gamut in the
BT.2020 (ITU-R Recommendation BT.2020) color space. These extensions allow
applications to do so by communicating to the platform the color space the
framebuffer data is in, i.e. BT.2020 color space, as well as the encoding
of the framebuffer data, which can be either linear or PQ (Dolby Perceptual
Quantizer - SMPTE ST 2084) encoding. Applications are expected to prepare
the framebuffer data properly.
New Procedures and Functions
None.
New Tokens
Accepted as attribute values for EGL_GL_COLORSPACE by
eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface:
[[ If EGL_EXT_gl_colorspace_bt2020_linear is supported ]]
EGL_GL_COLORSPACE_BT2020_LINEAR_EXT 0x333F
[[ If EGL_EXT_gl_colorspace_bt2020_pq is supported ]]
EGL_GL_COLORSPACE_BT2020_PQ_EXT 0x3340
Modifications to the EGL 1.5 Specification
Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On-
Screen Rendering Surfaces, before "The default value of EGL_GL_COLORSPACE
is EGL_GL_COLORSPACE_LINEAR.":
[[ If EGL_EXT_gl_colorspace_bt2020_linear is supported ]]
If its value is EGL_GL_COLORSPACE_BT2020_LINEAR_EXT, then a linear BT.2020
color space is assumed, with a corresponding GL_FRAMEBUFFER_ATTACHMENT_-
COLOR_ENCODING value of GL_LINEAR.
[[ If EGL_EXT_gl_colorspace_bt2020_pq is supported ]]
If its value is EGL_GL_COLORSPACE_BT2020_PQ_EXT, then a non-linear, PQ
encoded BT.2020 color space is assumed, with a corresponding GL_FRAMEBUFFER-
_ATTACHMENT_COLOR_ENCODING value of GL_LINEAR, as neither OpenGL nor OpenGL
ES supports PQ framebuffers. Applications utilizing this option need to
ensure that PQ encoding is performed on the application side.
Modify the 4th paragraph on the same page:
Note that the EGL_GL_COLORSPACE_SRGB attribute is used only by OpenGL and
OpenGL ES contexts supporting sRGB framebuffers. EGL itself does not
distinguish multiple colorspace models. Refer to the "sRGB Conversion"
sections of the OpenGL 4.4 and OpenGL ES 3.0 specifications for more
information.
Add a paragraph after the 4th paragraph above:
[[ If EGL_EXT_gl_colorspace_bt2020_linear is supported ]]
When using a floating-point EGL surface with EGL_GL_COLORSPACE_BT2020_-
LINEAR_EXT, the output values in the display-referred range of [0.0, 1.0]
correspond to a luminance range of 0 to 80 nits, which is the same luminance
range for sRGB. To achieve a larger dynamic range of 0 to 10000 nits, which
is the same range for PQ, the display-referred output values can go beyond
1.0 and to a range of [0.0, 125.0], where 0.0 corresponds to 0 nit and 125.0
corresponds to 10000 nits.
[[ If EGL_EXT_gl_colorspace_bt2020_pq is supported ]]
When using a floating-point EGL surface with EGL_GL_COLORSPACE_BT2020_PQ_-
EXT, to achieve the luminance range of 0 to 10000 nits (candela per square
meter) as defined by the SMPTE 2084 standard, applications can output values
in a display-referred range of [0.0, 1.0], where 0.0 corresponds to 0 nit
and 1.0 corresponds to 10000 nits.
Errors
Modify below error in the "Errors" section on page 34:
"If config does not support the OpenVG colorspace or alpha format at-
tributes specified in attrib list (as defined for eglCreatePlatformWindow-
Surface), an EGL_BAD_MATCH error is generated."
To include OpenGL colorspace as well:
"If config does not support the OpenGL colorspace, the OpenVG colorspace or
alpha format attributes specified in attrib list (as defined for eglCreate-
PlatformWindowSurface), an EGL_BAD_MATCH error is generated."
Issues
1. When creating an EGL surface, what happens when the specified colorspace
is not compatible with or supported by the EGLConfig?
RESOLVED: There is currently no way to query the compatibility of a
EGLConfig and colorspace pair. So the only option is to define an error
case similar to that of OpenVG colorspace, i.e. if config does not
support the colorspace specified in attrib list (as defined for egl-
CreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface),
an EGL_BAD_MATCH error is generated.
Revision History
Version 1, 2016/04/27
- Internal revisions
Version 2, 2016/05/20
- Rename to EXT
Version 3, 2016/05/25
- Add issues
Version 4, 2016/06/06
- Split up the extension and put each colorspace option into an individual
extension
Version 5, 2016/06/17
- Correct the meaning of the data from scene-referred to display-referred
Version 6, 2016/10/27
- Mark issue #1 as "RESOLVED" and add an error case
Version 7, 2016/11/22
- Change status to complete
extensions/EXT/EGL_EXT_gl_colorspace_display_p3.txt
+137
View File
@@ -0,0 +1,137 @@
Name
EXT_gl_colorspace_display_p3
Name Strings
EGL_EXT_gl_colorspace_display_p3_linear
EGL_EXT_gl_colorspace_display_p3
Contributors
Courtney Goeltzenleuchter
Jesse Hall
Contact
Courtney Goeltzenleuchter (courtneygo 'at' google.com)
IP Status
No known IP claims.
Status
Draft
Version
Version 2 - Oct 4, 2018
Number
EGL Extension #118
Extension Type
EGL display extension
Dependencies
These extensions are written against the wording of the EGL 1.5
specification (August 27, 2014).
These extensions require EGL_KHR_gl_colorspace.
Overview
Applications that want to use the Display-P3 color space (DCI-P3 primaries
and linear or sRGB-like transfer function) can use this extension to
communicate to the platform that framebuffer contents represent colors in
the Display-P3 color space.
The application is responsible for producing appropriate framebuffer
contents, but will typically use built-in sRGB encoding in OpenGL and OpenGL
ES to accomplish this.
New Procedures and Functions
None.
New Tokens
Accepted as attribute values for EGL_GL_COLORSPACE by
eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface:
[[ If EGL_EXT_gl_colorspace_display_p3_linear is supported ]]
EGL_GL_COLORSPACE_DISPLAY_P3_LINEAR_EXT 0x3362
[[ If EGL_EXT_gl_colorspace_display_p3 is supported ]]
EGL_GL_COLORSPACE_DISPLAY_P3_EXT 0x3363
Modifications to the EGL 1.5 Specification
Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On-
Screen Rendering Surfaces, before "The default value of EGL_GL_COLORSPACE
is EGL_GL_COLORSPACE_LINEAR.":
[[ If EGL_EXT_gl_colorspace_display_p3_linear is supported ]]
If its value is EGL_GL_COLORSPACE_DISPLAY_P3_LINEAR_EXT, then a linear
Display-P3 color space is assumed, with a corresponding
GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of GL_LINEAR.
[[ If EGL_EXT_gl_colorspace_display_p3 is supported ]]
If its value is EGL_GL_COLORSPACE_DISPLAY_P3_EXT, then a non-linear, sRGB
encoded Display-P3 color space is assumed, with a corresponding GL_FRAME-
BUFFER_ATTACHMENT_COLOR_ENCODING value of GL_SRGB.
Only OpenGL and OpenGL ES contexts which support sRGB rendering must
respect requests for EGL_GL_COLORSPACE_SRGB_KHR, and only to sRGB
formats supported by the context (normally just SRGB8).
Modify the 4th paragraph on the same page:
Note that the EGL_GL_COLORSPACE_SRGB attribute is used only by OpenGL and
OpenGL ES contexts supporting sRGB framebuffers. EGL itself does not
distinguish multiple colorspace models. Refer to the "sRGB Conversion"
sections of the OpenGL 4.4 and OpenGL ES 3.0 specifications for more
information.
Errors
Modify below error in the "Errors" section on page 34:
"If config does not support the OpenVG colorspace or alpha format at-
tributes specified in attrib list (as defined for eglCreatePlatformWindow-
Surface), an EGL_BAD_MATCH error is generated."
To include OpenGL colorspace as well:
"If config does not support the OpenGL colorspace, the OpenVG colorspace or
alpha format attributes specified in attrib list (as defined for eglCreate-
PlatformWindowSurface), an EGL_BAD_MATCH error is generated."
Issues
1. Removed section talking about HDR features, e.g. luminance > 80nits.
Do we want to keep that here in anticipation of HDR support in the future?
2. When creating an EGL surface, what happens when the specified colorspace
is not compatible with or supported by the EGLConfig?
RESOLVED: There is currently no way to query the compatibility of a
EGLConfig and colorspace pair. So the only option is to define an error
case similar to that of OpenVG colorspace, i.e. if config does not
support the colorspace specified in attrib list (as defined for egl-
CreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface),
an EGL_BAD_MATCH error is generated.
Revision History
Version 1, 2017/03/22
- Internal revisions
Version 2, 2018/10/04
- Fix typo to correct extension reference
extensions/EXT/EGL_EXT_gl_colorspace_display_p3_passthrough.txt
+139
View File
@@ -0,0 +1,139 @@
Name
EXT_gl_colorspace_display_p3_passthrough
Name Strings
EGL_EXT_gl_colorspace_display_p3_passthrough
Contributors
Chris Forbes
Courtney Goeltzenleuchter
Contact
Courtney Goeltzenleuchter (courtneygo 'at' google.com)
IP Status
No known IP claims.
Status
Draft
Version
Version 1 - Dec 4, 2018
Number
EGL Extension #130
Extension Type
EGL display extension
Dependencies
This extension is written against the wording of the EGL 1.5
specification (August 27, 2014).
This extension requires EGL_KHR_gl_colorspace.
Overview
Applications that want to use the Display-P3 color space (DCI-P3 primaries
with sRGB-like transfer function) can use this extension to
communicate to the platform that framebuffer contents represent colors in
the non-linear Display-P3 color space.
The application is responsible for producing appropriate framebuffer
contents. An application would want to use this extension rather than
EGL_EXT_gl_colorspace_display_p3 if they apply the sRGB transfer function
themselves and do not need the HW to do it.
New Procedures and Functions
None.
New Tokens
Accepted as attribute values for EGL_GL_COLORSPACE by
eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface:
[[ If EGL_EXT_gl_colorspace_display_p3_linear is supported ]]
EGL_GL_COLORSPACE_DISPLAY_P3_PASSTHROUGH_EXT 0x3490
Modifications to the EGL 1.5 Specification
Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On-
Screen Rendering Surfaces, before "The default value of EGL_GL_COLORSPACE
is EGL_GL_COLORSPACE_LINEAR.":
[[ If EGL_EXT_gl_colorspace_display_p3_passthrough is supported ]]
If its value is EGL_GL_COLORSPACE_DISPLAY_P3_PASSTHROUGH_EXT, then a
non-linear, sRGB encoded Display-P3 color space is assumed, with a
corresponding GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of GL_LINEAR.
The application is responsible for applying the appropriate transfer
function when writing and reading pixels.
Insert below text after the 4th paragraph on the same page:
Note that the EGL_GL_COLORSPACE_DISPLAY_P3_PASSTHROUGH_EXT attribute
indicates that a colorspace of Display P3 will be communicated to the
Window system. While EGL itself is color space agnostic, the surface
will eventually be presented to a display device with specific color
reproduction characteristics. If any color space transformations are
necessary before an image can be displayed, the color space of the
presented image must be known to the window system.
Errors
Modify below error in the "Errors" section on page 34:
"If config does not support the OpenVG colorspace or alpha format at-
tributes specified in attrib list (as defined for eglCreatePlatformWindow-
Surface), an EGL_BAD_MATCH error is generated."
To include OpenGL colorspace as well:
"If config does not support the OpenGL colorspace, the OpenVG colorspace or
alpha format attributes specified in attrib list (as defined for eglCreate-
PlatformWindowSurface), an EGL_BAD_MATCH error is generated."
Issues
1. When creating an EGL surface, what happens when the specified colorspace
is not compatible with or supported by the EGLConfig?
RESOLVED: There is currently no way to query the compatibility of a
EGLConfig and colorspace pair. So the only option is to define an error
case similar to that of OpenVG colorspace, i.e. if config does not
support the colorspace specified in attrib list (as defined for egl-
CreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface),
an EGL_BAD_MATCH error is generated.
2. Why the new enum instead of DISPLAY_P3_EXT + EXT_srgb_write_control?
RESOLVED:
We want to rely on "surface state" rather than a "context state", e.g.
EXT_srgb_write_control is global where we only want behavior to apply to
specific surface.
3. Should sRGB framebuffer support affect the pixel path?
RESOLVED: No.
sRGB rendering is defined by GL/GLES. Specifically, glReadPixels and
other pixel paths operations are not affected by sRGB rendering. But
glBlitFramebuffer is. Though, of course, if this extension were to
apply it would be a no-op.
Revision History
Version 1, 2018/12/04
- Internal revisions
extensions/EXT/EGL_EXT_gl_colorspace_scrgb.txt
+130
View File
@@ -0,0 +1,130 @@
Name
EXT_gl_colorspace_scrgb
Name Strings
EGL_EXT_gl_colorspace_scrgb
Contributors
Courtney Goeltzenleuchter
Lauri Hyvarinen
Weiwan Liu
Arun Swain
Contact
Courtney Goeltzenleuchter (courtneygo 'at' google.com)
IP Status
No known IP claims.
Status
Draft
Version
Version 2 - August 25, 2017
Number
EGL Extension #119
Dependencies
This extension is written against the wording of the EGL 1.5 specification
(August 27, 2014).
This extension requires EGL_KHR_gl_colorspace and EGL_EXT_pixel_format_-
float, and interacts with EGL_EXT_surface_SMPTE2086_metadata. This extension
is closely related to EGL_EXT_gl_colorspace_scrgb_linear.
Overview
This extension provides an extended sRGB (also called scRGB) color
space option for applications to choose from when creating an EGLSurface.
This extension defines the non-linear display referred scRGB color space.
It has the same white point and color primaries as sRGB, and thus is
backward-compatible with sRGB. Refer to the IEC 61966-2-2:2003 standard
for details on scRGB color space.
This extension chooses to use floating-point formats for scRGB color space.
For each color channel, the floating-point values of 0.0 and 1.0 still
correspond to sRGB chromaticities and luminance levels. However, scRGB
space allows for color values beyond the range of [0.0, 1.0], and can thus
achieve a larger color volume than that of sRGB. As it is display referred,
scRGB space makes assumptions of how the floating-point color values should
map to luminance levels by the underlying display pipeline. The expected
mapping is such that a color value of (1.0, 1.0, 1.0) corresponds to a
luminance level of 80 nits on a standardized studio monitor. As the color
value per channel goes beyond 1.0 and up to ~7.83, the corresponding
luminance levels also increase to a maximum of 10000 nits.
The application is responsible for applying the extended sRGB transfer
function to color values written to or read from a surface with a
colorspace of EGL_EXT_gl_colorspace_scrgb.
New Procedures and Functions
None.
New Tokens
Accepted as attribute values for EGL_GL_COLORSPACE by
eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface:
EGL_GL_COLORSPACE_SCRGB_EXT 0x3351
Modifications to the EGL 1.5 Specification
Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On-
Screen Rendering Surfaces", before "The default value of EGL_GL_COLORSPACE
is EGL_GL_COLORSPACE_LINEAR.":
[[ If EGL_EXT_gl_colorspace_scrgb is supported ]]
If its value is EGL_GL_COLORSPACE_SCRGB_EXT, then a non-linear scRGB
color space is assumed. with a corresponding GL_FRAMEBUFFER_ATTACHMENT_-
COLOR_ENCODING value of GL_LINEAR as neither OpenGL nor OpenGL ES
supports framebuffers using an scRGB transfer function.
The application is responsible for applying the appropriate extended
sRGB transfer function when reading or writing to this buffer.
scRGB is defined to use the same primaries and white-point as sRGB.
See IEC 61966-2-2:2003 for details.
Add two paragraphs after the 4th paragraph above:
When using a floating-point EGL surface with EGL_GL_COLORSPACE_SCRGB_EXT,
the display-referred values in the range of (0.0, 0.0, 0.0) to
(1.0, 1.0, 1.0) correspond to a luminance range of 0 to 80 nits, which is
the same luminance range for sRGB. To achieve a larger dynamic range of up
to 10000 nits, the output values can go beyond 1.0 and to a range of
[0.0, ~7.83] for each channel.
The effective color gamut and luminance range of the content that extend
beyond those of sRGB may be described via EGL_EXT_surface_SMPTE2086_metadata.
It is highly recommended to supply such metadata, so the display pipeline
may use this information to transform the the colors in a manner that
attempts to preserve the creative intent of the color data.
In the "Errors" section on page 34 in 3.5.1 "Creating On Screen Rendering
Surfaces", change the 3rd error definition to:
* If config does not support the OpenGL colorspace, the OpenVG colorspace or
alpha format attributes specified in attrib list (as defined for
eglCreatePlatformWindowSurface), an EGL_BAD_MATCH error is generated.
Issues
* Clarifications on the scRGB colorspace extensions
Revision History
Version 1, 2017/06/21
- Initial draft
Version 2, 2017/08/25
- Clarify definition of color space
extensions/EXT/EGL_EXT_gl_colorspace_scrgb_linear.txt
+127
View File
@@ -0,0 +1,127 @@
Name
EXT_gl_colorspace_scrgb_linear
Name Strings
EGL_EXT_gl_colorspace_scrgb_linear
Contributors
Courtney Goeltzenleuchter
Lauri Hyvarinen
Weiwan Liu
Arun Swain
Contact
Weiwan Liu (weiwliu 'at' nvidia.com)
IP Status
No known IP claims.
Status
Complete
Version
Version 4 - August 25, 2017
Number
EGL Extension #108
Dependencies
This extension is written against the wording of the EGL 1.5 specification
(August 27, 2014).
This extension requires EGL_KHR_gl_colorspace and EGL_EXT_pixel_format_-
float, and interacts with EGL_EXT_surface_SMPTE2086_metadata. This extension
is closely related to the EGL_EXT_gl_colorspace_scrgb.
Overview
This extension provides an extended sRGB (also called scRGB) color
space option for applications to choose from when creating an EGLSurface.
This extension defines the linear display referred scRGB color space.
It has the same white point and color primaries as sRGB, and thus is
backward-compatible with sRGB. Refer to the IEC 61966-2-2:2003 standard
for details on scRGB color space.
This extension chooses to use floating-point formats for scRGB color space.
For each color channel, the floating-point values of 0.0 and 1.0 still
correspond to sRGB chromaticities and luminance levels. However, scRGB
space allows for color values beyond the range of [0.0, 1.0], and can thus
achieve a larger color volume than that of sRGB. As it is display referred,
scRGB space makes assumptions of how the floating-point color values should
map to luminance levels by the underlying display pipeline. The expected
mapping is such that a color value of (1.0, 1.0, 1.0) corresponds to a
luminance level of 80 nits on a standardized studio monitor. As the color
value per channel goes beyond 1.0 and up to 125.0, the corresponding
luminance levels also increase linearly to a maximum of 10000 nits.
New Procedures and Functions
None.
New Tokens
Accepted as attribute values for EGL_GL_COLORSPACE by
eglCreateWindowSurface, eglCreatePbufferSurface and eglCreatePixmapSurface:
EGL_GL_COLORSPACE_SCRGB_LINEAR_EXT 0x3350
Modifications to the EGL 1.5 Specification
Insert below text in the 3rd paragraph on page 33 in 3.5.1 "Creating On-
Screen Rendering Surfaces", before "The default value of EGL_GL_COLORSPACE
is EGL_GL_COLORSPACE_LINEAR.":
If its value is EGL_GL_COLORSPACE_SCRGB_LINEAR_EXT, then a linear scRGB
color space is assumed, with a corresponding GL_FRAMEBUFFER_ATTACHMENT_-
COLOR_ENCODING value of GL_LINEAR. scRGB is defined to use the same
primaries and white-point as sRGB. See IEC 61966-2-2:2003 for details.
Add two paragraphs after the 4th paragraph above:
When using a floating-point EGL surface with EGL_GL_COLORSPACE_SCRGB_-
LINEAR_EXT, the display-referred values in the range of (0.0, 0.0, 0.0) to
(1.0, 1.0, 1.0) correspond to a luminance range of 0 to 80 nits, which is
the same luminance range for sRGB. To achieve a larger dynamic range of up
to 10000 nits, the output values can go beyond 1.0 and to a range of
[0.0, 125.0] for each channel.
The effective color gamut and luminance range of the content that extend
beyond those of sRGB may be described via EGL_EXT_surface_SMPTE2086_metadata.
It is highly recommended to supply such metadata, so the display pipeline
may use this information to transform the colors in a manner that
attempts to preserve the creative intent of the color data.
In the "Errors" section on page 34 in 3.5.1 "Creating On Screen Rendering
Surfaces", change the 3rd error definition to:
* If config does not support the OpenGL colorspace, the OpenVG colorspace or
alpha format attributes specified in attrib list (as defined for
eglCreatePlatformWindowSurface), an EGL_BAD_MATCH error is generated.
Issues
* Clarifications on the scRGB colorspace extensions
Revision History
Version 1, 2016/10/21
- Initial draft
Version 2, 2016/11/18
- Add reference to IEC 61966-2-2:2003 standard and minor wording changes
Version 3, 2016/11/22
- Change status to complete
Version 4, 2017/08/25
- Clarifications on the definition of scRGB colorspace
extensions/EXT/EGL_EXT_image_dma_buf_import.txt
+428
View File
@@ -0,0 +1,428 @@
Name
EXT_image_dma_buf_import
Name Strings
EGL_EXT_image_dma_buf_import
Contributors
Jesse Barker
Rob Clark
Tom Cooksey
Contacts
Jesse Barker (jesse 'dot' barker 'at' linaro 'dot' org)
Tom Cooksey (tom 'dot' cooksey 'at' arm 'dot' com)
Status
Complete.
Version
Version 7, December 13, 2013
Number
EGL Extension #53
Dependencies
EGL 1.2 is required.
EGL_KHR_image_base is required.
The EGL implementation must be running on a Linux kernel supporting the
dma_buf buffer sharing mechanism.
This extension is written against the wording of the EGL 1.2 Specification.
Overview
This extension allows creating an EGLImage from a Linux dma_buf file
descriptor or multiple file descriptors in the case of multi-plane YUV
images.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted by the <target> parameter of eglCreateImageKHR:
EGL_LINUX_DMA_BUF_EXT 0x3270
Accepted as an attribute in the <attrib_list> parameter of
eglCreateImageKHR:
EGL_LINUX_DRM_FOURCC_EXT 0x3271
EGL_DMA_BUF_PLANE0_FD_EXT 0x3272
EGL_DMA_BUF_PLANE0_OFFSET_EXT 0x3273
EGL_DMA_BUF_PLANE0_PITCH_EXT 0x3274
EGL_DMA_BUF_PLANE1_FD_EXT 0x3275
EGL_DMA_BUF_PLANE1_OFFSET_EXT 0x3276
EGL_DMA_BUF_PLANE1_PITCH_EXT 0x3277
EGL_DMA_BUF_PLANE2_FD_EXT 0x3278
EGL_DMA_BUF_PLANE2_OFFSET_EXT 0x3279
EGL_DMA_BUF_PLANE2_PITCH_EXT 0x327A
EGL_YUV_COLOR_SPACE_HINT_EXT 0x327B
EGL_SAMPLE_RANGE_HINT_EXT 0x327C
EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT 0x327D
EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT 0x327E
Accepted as the value for the EGL_YUV_COLOR_SPACE_HINT_EXT attribute:
EGL_ITU_REC601_EXT 0x327F
EGL_ITU_REC709_EXT 0x3280
EGL_ITU_REC2020_EXT 0x3281
Accepted as the value for the EGL_SAMPLE_RANGE_HINT_EXT attribute:
EGL_YUV_FULL_RANGE_EXT 0x3282
EGL_YUV_NARROW_RANGE_EXT 0x3283
Accepted as the value for the EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT &
EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT attributes:
EGL_YUV_CHROMA_SITING_0_EXT 0x3284
EGL_YUV_CHROMA_SITING_0_5_EXT 0x3285
Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation)
Add to section 2.5.1 "EGLImage Specification" (as defined by the
EGL_KHR_image_base specification), in the description of
eglCreateImageKHR:
"Values accepted for <target> are listed in Table aaa, below.
+-------------------------+--------------------------------------------+
| <target> | Notes |
+-------------------------+--------------------------------------------+
| EGL_LINUX_DMA_BUF_EXT | Used for EGLImages imported from Linux |
| | dma_buf file descriptors |
+-------------------------+--------------------------------------------+
Table aaa. Legal values for eglCreateImageKHR <target> parameter
...
If <target> is EGL_LINUX_DMA_BUF_EXT, <dpy> must be a valid display, <ctx>
must be EGL_NO_CONTEXT, and <buffer> must be NULL, cast into the type
EGLClientBuffer. The details of the image is specified by the attributes
passed into eglCreateImageKHR. Required attributes and their values are as
follows:
* EGL_WIDTH & EGL_HEIGHT: The logical dimensions of the buffer in pixels
* EGL_LINUX_DRM_FOURCC_EXT: The pixel format of the buffer, as specified
by drm_fourcc.h and used as the pixel_format parameter of the
drm_mode_fb_cmd2 ioctl.
* EGL_DMA_BUF_PLANE0_FD_EXT: The dma_buf file descriptor of plane 0 of
the image.
* EGL_DMA_BUF_PLANE0_OFFSET_EXT: The offset from the start of the
dma_buf of the first sample in plane 0, in bytes.
* EGL_DMA_BUF_PLANE0_PITCH_EXT: The number of bytes between the start of
subsequent rows of samples in plane 0. May have special meaning for
non-linear formats.
For images in an RGB color-space or those using a single-plane YUV format,
only the first plane's file descriptor, offset & pitch should be specified.
For semi-planar YUV formats, that first plane (plane 0) holds only the luma
samples and chroma samples are stored interleaved in a second plane (plane
1). For fully planar YUV formats, the first plane (plane 0) continues to
hold the luma samples however the chroma samples are stored seperately in
two additional planes (plane 1 & plane 2). If present, planes 1 & 2 are
specified by the following attributes, which have the same meanings as
defined above for plane 0:
* EGL_DMA_BUF_PLANE1_FD_EXT
* EGL_DMA_BUF_PLANE1_OFFSET_EXT
* EGL_DMA_BUF_PLANE1_PITCH_EXT
* EGL_DMA_BUF_PLANE2_FD_EXT
* EGL_DMA_BUF_PLANE2_OFFSET_EXT
* EGL_DMA_BUF_PLANE2_PITCH_EXT
The ordering of samples within a plane is taken from the drm_fourcc
pixel_format specified for EGL_LINUX_DRM_FOURCC_EXT. For example, if
EGL_LINUX_DRM_FOURCC_EXT is set to DRM_FORMAT_NV12, the chroma plane
specified by EGL_DMA_BUF_PLANE1* contains samples in the order V, U,
whereas if EGL_LINUX_DRM_FOURCC_EXT is DRM_FORMAT_NV21, the order is U,
V. Similarly, the ordering of planes for fully-planar formats is also taken
from the pixel_format specified as EGL_LINUX_DRM_FOURCC_EXT. For example,
if EGL_LINUX_DRM_FOURCC_EXT is set to DRM_FORMAT_YUV410, the luma plane is
specified by EGL_DMA_BUF_PLANE0*, the plane containing U-samples is
specified by EGL_DMA_BUF_PLANE1* and the plane containing the V-samples is
specified by EGL_DMA_BUF_PLANE2*, whereas if EGL_LINUX_DRM_FOURCC_EXT is
set to DRM_FORMAT_YVU410, plane 1 contains the V-samples and plane 2
contains the U-samples.
In addition to the above required attributes, the application may also
provide hints as to how the data should be interpreted by the GL. If any of
these hints are not specified, the GL will guess based on the pixel format
passed as the EGL_LINUX_DRM_FOURCC_EXT attribute or may fall-back to some
default value. Not all GLs will be able to support all combinations of
these hints and are free to use whatever settings they choose to achieve
the closest possible match.
* EGL_YUV_COLOR_SPACE_HINT_EXT: The color-space the data is in. Only
relevant for images in a YUV format, ignored when specified for an
image in an RGB format. Accepted values are:
EGL_ITU_REC601_EXT, EGL_ITU_REC709_EXT & EGL_ITU_REC2020_EXT.
* EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT &
EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT: Where chroma samples are
sited relative to luma samples when the image is in a sub-sampled
format. When the image is not using chroma sub-sampling, the luma and
chroma samples are assumed to be co-sited. Siting is split into the
vertical and horizontal and is in a fixed range. A siting of zero
means the first luma sample is taken from the same position in that
dimension as the chroma sample. This is best illustrated in the
diagram below:
(0.5, 0.5) (0.0, 0.5) (0.0, 0.0)
+ + + + + + + + * + * +
x x x x
+ + + + + + + + + + + +
+ + + + + + + + * + * +
x x x x
+ + + + + + + + + + + +
Luma samples (+), Chroma samples (x) Chrome & Luma samples (*)
Note this attribute is ignored for RGB images and non sub-sampled
YUV images. Accepted values are: EGL_YUV_CHROMA_SITING_0_EXT (0.0)
& EGL_YUV_CHROMA_SITING_0_5_EXT (0.5)
* EGL_SAMPLE_RANGE_HINT_EXT: The numerical range of samples. Only
relevant for images in a YUV format, ignored when specified for
images in an RGB format. Accepted values are: EGL_YUV_FULL_RANGE_EXT
(0-256) & EGL_YUV_NARROW_RANGE_EXT (16-235).
If eglCreateImageKHR is successful for a EGL_LINUX_DMA_BUF_EXT target, the
EGL will take a reference to the dma_buf(s) which it will release at any
time while the EGLDisplay is initialized. It is the responsibility of the
application to close the dma_buf file descriptors."
Add to the list of error conditions for eglCreateImageKHR:
"* If <target> is EGL_LINUX_DMA_BUF_EXT and <buffer> is not NULL, the
error EGL_BAD_PARAMETER is generated.
* If <target> is EGL_LINUX_DMA_BUF_EXT, and the list of attributes is
incomplete, EGL_BAD_PARAMETER is generated.
* If <target> is EGL_LINUX_DMA_BUF_EXT, and the EGL_LINUX_DRM_FOURCC_EXT
attribute is set to a format not supported by the EGL, EGL_BAD_MATCH
is generated.
* If <target> is EGL_LINUX_DMA_BUF_EXT, and the EGL_LINUX_DRM_FOURCC_EXT
attribute indicates a single-plane format, EGL_BAD_ATTRIBUTE is
generated if any of the EGL_DMA_BUF_PLANE1_* or EGL_DMA_BUF_PLANE2_*
attributes are specified.
* If <target> is EGL_LINUX_DMA_BUF_EXT and the value specified for
EGL_YUV_COLOR_SPACE_HINT_EXT is not EGL_ITU_REC601_EXT,
EGL_ITU_REC709_EXT or EGL_ITU_REC2020_EXT, EGL_BAD_ATTRIBUTE is
generated.
* If <target> is EGL_LINUX_DMA_BUF_EXT and the value specified for
EGL_SAMPLE_RANGE_HINT_EXT is not EGL_YUV_FULL_RANGE_EXT or
EGL_YUV_NARROW_RANGE_EXT, EGL_BAD_ATTRIBUTE is generated.
* If <target> is EGL_LINUX_DMA_BUF_EXT and the value specified for
EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT or
EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT is not
EGL_YUV_CHROMA_SITING_0_EXT or EGL_YUV_CHROMA_SITING_0_5_EXT,
EGL_BAD_ATTRIBUTE is generated.
* If <target> is EGL_LINUX_DMA_BUF_EXT and one or more of the values
specified for a plane's pitch or offset isn't supported by EGL,
EGL_BAD_ACCESS is generated.
Issues
1. Should this be a KHR or EXT extension?
ANSWER: EXT. Khronos EGL working group not keen on this extension as it is
seen as contradicting the EGLStream direction the specification is going in.
The working group recommends creating additional specs to allow an EGLStream
producer/consumer connected to v4l2/DRM or any other Linux interface.
2. Should this be a generic any platform extension, or a Linux-only
extension which explicitly states the handles are dma_buf fds?
ANSWER: There's currently no intention to port this extension to any OS not
based on the Linux kernel. Consequently, this spec can be explicitly written
against Linux and the dma_buf API.
3. Does ownership of the file descriptor pass to the EGL library?
ANSWER: No, EGL does not take ownership of the file descriptors. It is the
responsibility of the application to close the file descriptors on success
and failure.
4. How are the different YUV color spaces handled (BT.709/BT.601)?
ANSWER: The pixel formats defined in drm_fourcc.h only specify how the data
is laid out in memory. It does not define how that data should be
interpreted. Added a new EGL_YUV_COLOR_SPACE_HINT_EXT attribute to allow the
application to specify which color space the data is in to allow the GL to
choose an appropriate set of co-efficients if it needs to convert that data
to RGB for example.
5. What chroma-siting is used for sub-sampled YUV formats?
ANSWER: The chroma siting is not specified by either the v4l2 or DRM APIs.
This is similar to the color-space issue (4) in that the chroma siting
doesn't affect how the data is stored in memory. However, the GL will need
to know the siting in order to filter the image correctly. While the visual
impact of getting the siting wrong is minor, provision should be made to
allow an application to specify the siting if desired. Added additional
EGL_YUV_CHROMA_HORIZONTAL_SITING_HINT_EXT &
EGL_YUV_CHROMA_VERTICAL_SITING_HINT_EXT attributes to allow the siting to
be specified using a set of pre-defined values (0 or 0.5).
6. How can an application query which formats the EGL implementation
supports?
PROPOSAL: Don't provide a query mechanism but instead add an error condition
that EGL_BAD_MATCH is raised if the EGL implementation doesn't support that
particular format.
7. Which image formats should be supported and how is format specified?
Seem to be two options 1) specify a new enum in this specification and
enumerate all possible formats. 2) Use an existing enum already in Linux,
either v4l2_mbus_pixelcode and/or those formats listed in drm_fourcc.h?
ANSWER: Go for option 2) and just use values defined in drm_fourcc.h.
8. How can AYUV images be handled?
ANSWER: At least on fourcc.org and in drm_fourcc.h, there only seems to be
a single AYUV format and that is a packed format, so everything, including
the alpha component would be in the first plane.
9. How can you import interlaced images?
ANSWER: Interlaced frames are usually stored with the top & bottom fields
interleaved in a single buffer. As the fields would need to be displayed as
at different times, the application would create two EGLImages from the same
buffer, one for the top field and another for the bottom. Both EGLImages
would set the pitch to 2x the buffer width and the second EGLImage would use
a suitable offset to indicate it started on the second line of the buffer.
This should work regardless of whether the data is packed in a single plane,
semi-planar or multi-planar.
If each interlaced field is stored in a separate buffer then it should be
trivial to create two EGLImages, one for each field's buffer.
10. How are semi-planar/planar formats handled that have a different
width/height for Y' and CbCr such as YUV420?
ANSWER: The spec says EGL_WIDTH & EGL_HEIGHT specify the *logical* width and
height of the buffer in pixels. For pixel formats with sub-sampled Chroma
values, it should be trivial for the EGL implementation to calculate the
width/height of the Chroma sample buffers using the logical width & height
and by inspecting the pixel format passed as the EGL_LINUX_DRM_FOURCC_EXT
attribute. I.e. If the pixel format says it's YUV420, the Chroma buffer's
width = EGL_WIDTH/2 & height =EGL_HEIGHT/2.
11. How are Bayer formats handled?
ANSWER: As of Linux 2.6.34, drm_fourcc.h does not include any Bayer formats.
However, future kernel versions may add such formats in which case they
would be handled in the same way as any other format.
12. Should the spec support buffers which have samples in a "narrow range"?
Content sampled from older analogue sources typically don't use the full
(0-256) range of the data type storing the sample and instead use a narrow
(16-235) range to allow some headroom & toeroom in the signals to avoid
clipping signals which overshoot slightly during processing. This is
sometimes known as signals using "studio swing".
ANSWER: Add a new attribute to define if the samples use a narrow 16-235
range or the full 0-256 range.
13. Specifying the color space and range seems cumbersome, why not just
allow the application to specify the full YUV->RGB color conversion matrix?
ANSWER: Some hardware may not be able to use an arbitrary conversion matrix
and needs to select an appropriate pre-defined matrix based on the color
space and the sample range.
14. How do you handle EGL implementations which have restrictions on pitch
and/or offset?
ANSWER: Buffers being imported using dma_buf pretty much have to be
allocated by a kernel-space driver. As such, it is expected that a system
integrator would make sure all devices which allocate buffers suitable for
exporting make sure they use a pitch supported by all possible importers.
However, it is still possible eglCreateImageKHR can fail due to an
unsupported pitch. Added a new error to the list indicating this.
15. Should this specification also describe how to export an existing
EGLImage as a dma_buf file descriptor?
ANSWER: No. Importing and exporting buffers are two separate operations and
importing an existing dma_buf fd into an EGLImage is useful functionality in
itself. Agree that exporting an EGLImage as a dma_buf fd is useful, E.g. it
could be used by an OpenMAX IL implementation's OMX_UseEGLImage function to
give access to the buffer backing an EGLImage to video hardware. However,
exporting can be split into a separate extension specification.
Revision History
#7 (Kristian H. Kristensen, December 13, 2017)
- Clarify plane ordering to match Linux FOURCC conventions (Bug 16017).
#6 (David Garbett, December 05, 2013)
- Application now retains ownership of dma_buf file descriptors.
#5 (Tom Cooksey, February 19, 2013)
- Assigned enum values
- Moved out of drafts
#4 (Tom Cooksey, October 04, 2012)
- Fixed issue numbering!
- Added issues 8 - 15.
- Promoted proposal for Issue 3 to be the answer.
- Added an additional attribute to allow an application to specify the color
space as a hint which should address issue 4.
- Added an additional attribute to allow an application to specify the chroma
siting as a hint which should address issue 5.
- Added an additional attribute to allow an application to specify the sample
range as a hint which should address the new issue 12.
- Added language to end of error section clarifying who owns the fd passed
to eglCreateImageKHR if an error is generated.
#3 (Tom Cooksey, August 16, 2012)
- Changed name from EGL_EXT_image_external and re-written language to
explicitly state this for use with Linux & dma_buf.
- Added a list of issues, including some still open ones.
#2 (Jesse Barker, May 30, 2012)
- Revision to split eglCreateImageKHR functionality from export
Functionality.
- Update definition of EGLNativeBufferType to be a struct containing a list
of handles to support multi-buffer/multi-planar formats.
#1 (Jesse Barker, March 20, 2012)
- Initial draft.
extensions/EXT/EGL_EXT_image_dma_buf_import_modifiers.txt
+244
View File
@@ -0,0 +1,244 @@
Name
EXT_image_dma_buf_import_modifiers
Name Strings
EGL_EXT_image_dma_buf_import_modifiers
Contributors
Pekka Paalanen, Collabora Ltd.
Louis-Francis Ratté-Boulianne
Daniel Stone, Collabora Ltd.
Kristian Høgsberg
Contacts
Pekka Paalanen (pq 'at' collabora 'dot' com)
Daniel Stone (daniels 'at' collabora 'dot' com)
Status
Complete
Version
Version 5, March 12, 2019
Number
EGL Extension #105
Dependencies
EGL 1.2 is required.
EGL_KHR_image_base is required.
EGL_EXT_image_dma_buf_import is required.
The EGL implementation must be running on a Linux kernel supporting the
dma_buf buffer sharing mechanism.
This extension is written against the wording of the EGL 1.2 Specification.
In order to support imports for the GL_TEXTURE_EXTERNAL_OES target, a
compatible OpenGL ES implementation supporting GL_OES_EGL_image_external
must be present.
Overview
This extension builds on EGL_EXT_image_dma_buf_import, in order to support
format modifiers used for tiling, compression, and additional non-linear
modes. It also adds support for a fourth auxiliary plane, and queries for
the implementation-supported types.
New Types
None
New Procedures and Functions
EGLBoolean eglQueryDmaBufFormatsEXT(
EGLDisplay dpy,
EGLint max_formats,
EGLint *formats,
EGLint *num_formats)
EGLBoolean eglQueryDmaBufModifiersEXT(
EGLDisplay dpy,
EGLint format,
EGLint max_modifiers,
EGLuint64KHR *modifiers,
EGLBoolean *external_only,
EGLint *num_modifiers)
New Tokens
Accepted as an attribute in the <attrib_list> parameter of
eglCreateImageKHR:
EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT 0x3443
EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT 0x3444
EGL_DMA_BUF_PLANE1_MODIFIER_LO_EXT 0x3445
EGL_DMA_BUF_PLANE1_MODIFIER_HI_EXT 0x3446
EGL_DMA_BUF_PLANE2_MODIFIER_LO_EXT 0x3447
EGL_DMA_BUF_PLANE2_MODIFIER_HI_EXT 0x3448
EGL_DMA_BUF_PLANE3_FD_EXT 0x3440
EGL_DMA_BUF_PLANE3_OFFSET_EXT 0x3441
EGL_DMA_BUF_PLANE3_PITCH_EXT 0x3442
EGL_DMA_BUF_PLANE3_MODIFIER_LO_EXT 0x3449
EGL_DMA_BUF_PLANE3_MODIFIER_HI_EXT 0x344A
New Types
This extension uses the 64-bit unsigned integer type EGLuint64KHR
first introduced by the EGL_KHR_stream extension, but does not
depend on that extension. The typedef may be reproduced separately
for this extension, if not already present in eglext.h.
typedef khronos_uint64_t EGLuint64KHR;
Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation)
Add to section 2.5.1 "EGLImage Specification" (as defined by the
EGL_KHR_image_base specification), in the description of
eglCreateImageKHR:
If <target> is EGL_LINUX_DMA_BUF_EXT, both or neither of the following
attribute values may be given. These attribute values together form an
unsigned 64-bit value called a format modifier. Format modifiers are
specified by drm_fourcc.h and used as the modifier parameter of the
drm_mode_fb_cmd2 ioctl. If neither of the two attributes are given, or
if the modifier is explicitly declared to be DRM_FORMAT_MOD_INVALID, the
effective format modifier is implementation-defined. The two attributes
are:
* EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT: The lowest 32 bits of the
64-bit format modifier.
* EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT: The highest 32 bits of the
64-bit format modifier.
For semi-planar and planar YUV formats, or other formats which require
multiple memory planes, planes 1, 2 and 3 are specified by the following
attributes, which have the same meanings as defined above for plane 0:
* EGL_DMA_BUF_PLANE1_MODIFIER_LO_EXT
* EGL_DMA_BUF_PLANE1_MODIFIER_HI_EXT
* EGL_DMA_BUF_PLANE2_MODIFIER_LO_EXT
* EGL_DMA_BUF_PLANE2_MODIFIER_HI_EXT
* EGL_DMA_BUF_PLANE3_FD_EXT
* EGL_DMA_BUF_PLANE3_OFFSET_EXT
* EGL_DMA_BUF_PLANE3_PITCH_EXT
* EGL_DMA_BUF_PLANE3_MODIFIER_LO_EXT
* EGL_DMA_BUF_PLANE3_MODIFIER_HI_EXT
Modifiers may modify any attribute of a buffer import, including but not
limited to adding extra planes to a format which otherwise does not have
those planes. As an example, a modifier may add a plane for an external
compression buffer to a single-plane format. The exact meaning and effect
of any modifier is canonically defined by drm_fourcc.h, not as part of this
extension.
Implementations are required to validate the full combination of base
format and per-plane modifiers, and reject any combination which is not
explicitly supported.
Add to the list of error conditions for eglCreateImageKHR:
* If <target> is EGL_LINUX_DMA_BUF_EXT, and the list of attributes
contains EGL_DMA_BUF_PLANE0_MODIFIER_LO_EXT but not
EGL_DMA_BUF_PLANE0_MODIFIER_HI_EXT or vice versa, EGL_BAD_PARAMETER
is generated. This applies similarly for planes 1, 2, and 3 also.
Add section 2.5.3 "EGLImage dma_buf formats and modifiers"
The command
EGLBoolean eglQueryDmaBufFormatsEXT(
EGLDisplay dpy,
EGLint max_formats,
EGLint *formats,
EGLint *num_formats)
is used to query the dma_buf formats supported by <dpy>. Each format is
returned using its FourCC format as defined in the drm_fourcc.h header file.
EGL_TRUE is returned if QueryDmaBufFormatsEXT succeeds, EGL_FALSE indicates
failure to query.
* If <dpy> is not the handle of a valid EGLDisplay object, the error
EGL_BAD_DISPLAY is generated.
* If <max_formats> is 0, no formats are returned, but the total number
of formats is returned in <num_formats>, and no error is generated.
* If <max_formats> has a negative value, the error EGL_BAD_PARAMETER
is generated.
* If <max_formats> is a positive integer but <formats> is NULL, the error
EGL_BAD_PARAMETER is generated.
The command
EGLBoolean eglQueryDmaBufModifiersEXT(
EGLDisplay dpy,
EGLint format,
EGLint max_modifiers,
EGLuint64KHR *modifiers,
EGLBoolean *external_only,
EGLint *num_modifiers)
is used to query the dma_buf format modifiers supported by <dpy> for the
given format. The format must be one of those returned by the
eglQueryDmaBufFormatsEXT command. The returned modifiers should be
defined in the canonical drm_fourcc.h header file. If the user also
passes an array for <external_only>, this will be populated with whether
the requested format and modifier combination is only supported for use
with the GL_TEXTURE_EXTERNAL_OES texture target. If <dpy> cannot support
any context with GL_OES_EGL_image_external, the array will be populated with
EGL_FALSE. EGL_TRUE is returned if QueryDmaBufModifiersEXT succeeds,
EGL_FALSE indicates failure.
* If <dpy> is not the handle of a valid EGLDisplay object, the error
EGL_BAD_DISPLAY is generated.
* If <max_modifiers> is 0, no modifiers are returned, but the total
number of modifiers is returned in <num_modifiers>, and no error is
generated.
* If <max_modifiers> has a negative value, the error EGL_BAD_PARAMETER
is generated.
* If <max_modifiers> is a positive integer but <modifiers> is NULL, the
error EGL_BAD_PARAMETER is generated.
* If <format> is not one of the formats advertised by
QueryDmaBufFormatsEXT for the same <dpy>, the error EGL_BAD_PARAMETER
is generated.
Revision History
#5 (Daniel Stone, March 12, 2019)
- Correct description of behaviour when a modifier is not explicitly given;
zero is not correct as it is an explicit modifier itself (linear).
#4 (Daniel Stone, October 20, 2016)
- Switch to EGLuint64KHR for modifier types.
#3 (Daniel Stone, October 20, 2016)
- Clarify that the effect that modifiers can have.
- Disambiguate references to displays.
- Explicitly refer to max_formats/max_modifiers behaviour when zero.
#2 (Daniel Stone, September 29, 2016)
- Add missing tokens for plane 3 FD/offset/pitch.
- Fix description.
- Allow max_formats/max_modifiers to be zero, to get the counter.
- Add external_only to modifiers query.
#1 (Pekka Paalanen, October 14, 2015)
- Initial draft.
extensions/EXT/EGL_EXT_image_gl_colorspace.txt
+136
View File
@@ -0,0 +1,136 @@
Name
EXT_image_gl_colorspace
Name Strings
EGL_EXT_image_gl_colorspace
Contributors
Jesse Hall, Google
Philip Rideout, Google
Mohan Maiya, Qualcomm
Jan-Harald Fredriksen, ARM
Contact
Krzysztof Kosiński, Google (krzysio 'at' google.com)
Status
Complete
Version
Version 9, February 26, 2018
Number
EGL Extension #125
Dependencies
Written against the EGL 1.5 specification.
Can be supported on EGL 1.4 provided that EGL_KHR_gl_colorspace is
implemented, as well as either EGL_KHR_image or EGL_KHR_image_base.
Interacts with the GL_OES_EGL_image_external specification.
Overview
This extension relaxes the restriction that only the eglCreate*Surface
functions can accept the EGL_GL_COLORSPACE attribute. With this change,
eglCreateImage can also accept this attribute.
New Tokens
EGL_GL_COLORSPACE_DEFAULT_EXT 0x314D
New Procedures and Functions
None.
Additions to the EGL 1.5 Specification
Add to table 3.11 on page 75:
"Attribute Type Description
-------------------- ---- -----------
EGL_GL_COLORSPACE enum Color space for OpenGL and OpenGL ES"
Add the following paragraph to the end of section 3.9, "EGLImage
Specification and Management" on page 77:
"EGL_GL_COLORSPACE specifies the color space used by OpenGL and OpenGL
ES when rendering to the image, or sampling from the image. It has the
same meaning as when used with eglCreatePlatformWindowSurface, with the
exception that its default value is EGL_GL_COLORSPACE_DEFAULT_EXT. This
means that the color space should not be overriden. For example, if an
image is created from an existing OpenGL texture, then
GL_COLORSPACE_DEFAULT_EXT means that the original color space should be
preserved."
Add the following paragraphs to the "Errors" subsection in section 3.9
on page 76:
"If EGL_GL_COLORSPACE is not one of the legal values, the error
EGL_BAD_PARAMETER is generated."
"If ctx specifies a GL context that does not support creating an EGLImage
with the given value for EGL_GL_COLORSPACE, EGL_BAD_MATCH error is
generated."
Interaction with OES_EGL_image_external:
The first sentence in the second to last paragraph in section 3.7.14
should be changed from:
"Sampling an external texture will return an RGBA vector in the same
colorspace as the source image."
to:
"Sampling an external texture will return an RGBA vector in the same color
space as the source image, unless the image's EGL_GL_COLORSPACE attribute
results in sRGB encoding as described in EGL_EXT_image_gl_colorspace."
The three parenthetical sentences in this same paragraph should be
simplified since they partially conflict with existing language in the
ES30 specification. Change them from:
"(But these RGB values will be in the same colorspace as the
original image. Colorspace here includes the linear or non-linear
encoding of the samples. For example, if the original image is in the
sRGB color space then the RGB value returned by the sampler will also
be sRGB, and if the original image is stored in ITU-R Rec. 601 YV12
then the RGB value returned by the sampler will be an RGB value in the
ITU-R Rec. 601 colorspace.)"
to:
"(For example, if the original image is stored in ITU-R Rec. 601 YV12
then the RGB value returned by the sampler will be an RGB value in the
ITU-R Rec. 601 colorspace.)"
Issues
Revision History
Rev. Date Author Changes
---- -------- -------- -----------------------------------------
1 11/22/17 philip Initial draft
2 12/8/17 philip Add note about OES_EGL_image_external
3 12/11/17 philip Changed from KHR to EXT.
4 12/15/17 philip Add diffs against the EGL 1.5 specification.
5 12/20/17 philip Add EGL_GL_COLORSPACE_DEFAULT_EXT.
6 1/2/18 philip Updated changes to OES_EGL_image_external.
7 1/2/18 philip Tweaked the changes to OES_EGL_image_external.
8 2/2/18 philip Add value for EGL_GL_COLORSPACE_DEFAULT_EXT.
9 2/26/18 krzysio Update contact information, finalize.
9 4/20/18 krzysio Fix stray reference to KHR.
extensions/EXT/EGL_EXT_image_implicit_sync_control.txt
+131
View File
@@ -0,0 +1,131 @@
Name
EXT_image_implicit_sync_control
Name Strings
EGL_EXT_image_implicit_sync_control
Contributors
Daniel Stone, Collabora Ltd.
Contacts
Daniel Stone (daniels 'at' collabora 'dot' com)
Status
Complete
Version
Version 2, March 16, 2020
Number
EGL Extension #120
Dependencies
EGL 1.2 is required.
EGL_KHR_image_base and EGL_EXT_image_dma_buf_import are required.
The EGL implementation must be running on a Linux kernel supporting implicit
synchronization, as the usage is defined in the
EGL_ARM_implicit_external_sync extension, but does not require that extension.
This extension is written against the wording of the EGL 1.2 Specification.
Overview
This extension allows a client to selectively use implicit or explicit
synchronization mechanisms when addressing externally-imported EGLImages.
A new token is added to EGLImage creation which allows the client to select
whether a platform's implicit synchronization will be in use for a buffer
imported into EGLImage.
Heterogeneous systems (supporting multiple APIs, mixed legacy/updated
clients, etc) already supporting implicit synchronization, may not be able
to change to explict synchronization in a single switch. This extension
allows synchronization to be controlled on a per-buffer basis, so explicit
synchronization can be enabled for a complete pipeline which supports it,
or implicit synchronization used otherwise.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted as an attribute in the <attrib_list> parameter of
eglCreateImageKHR:
EGL_IMPORT_SYNC_TYPE_EXT 0x3470
Accepted as the value for the EGL_IMPORT_SYNC_TYPE_EXT attribute:
EGL_IMPORT_IMPLICIT_SYNC_EXT 0x3471
EGL_IMPORT_EXPLICIT_SYNC_EXT 0x3472
New Types
None.
Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation)
Add to section 2.5.1 "EGLImage Specification" (as defined by the
EGL_KHR_image_base specification), in the description of
eglCreateImageKHR:
Add the following to Table bbb (Legal attributes for eglCreateImageKHR
<attr_list> parameter), Section 2.5.1 (EGLImage Specification)
+-----------------------------+-------------------------+---------------------------+---------------+
| Attribute | Description | Valid <target>s | Default Value |
+-----------------------------+-------------------------+---------------------------+---------------+
| EGL_IMPORT_SYNC_TYPE_EXT | The type of | EGL_LINUX_DMA_BUF_EXT | EGL_IMPORT_ |
| | synchronization to | | IMPLICT_SYNC_ |
| | apply to previously | | EXT |
| | submitted rendering on | | |
| | the platform buffer | | |
+-----------------------------+-------------------------+---------------------------+---------------+
Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> parameter
...
Add to section 2.5.1 "EGLImage Specification" (as defined by the
EGL_KHR_image_base specification), in the description of
eglCreateImageKHR:
The behaviour of the imported buffer with regard to commands previously
submitted (including via other APIs and from other clients) is controlled
by the EGL_IMPORT_SYNC_TYPE_EXT attribute. If the default value of
implicit synchronization is used, the platform may synchronize any access
to the imported buffer, against accesses previously made (including by
other clients or APIs) to that same buffer. If explicit synchronization
is specified, the platform will not synchronize access to that buffer
against other accesses; the client must use another synchronization
mechanism if it wishes to order its accesses with respect to others.
Add to the list of error conditions for eglCreateImageKHR:
* If <attrib_list> contains the EGL_IMPORT_SYNC_TYPE_EXT name, but the
value is not one of EGL_IMPORT_IMPLICIT_SYNC_EXT or
EGL_IMPORT_EXPLICIT_SYNC_EXT, EGL_BAD_ATTRIBUTE is generated.
Revision History
#1 (Daniel Stone, May 15, 2017)
- Initial revision.
#2 (Eric Engestrom, March 16, 2020)
- Change "bad attribute value" error from EGL_BAD_PARAMETER to
EGL_BAD_ATTRIBUTE to follow the EGL convention.
extensions/EXT/EGL_EXT_multiview_window.txt
+126
View File
@@ -0,0 +1,126 @@
Name
EXT_multiview_window
Name Strings
EGL_EXT_multiview_window
Contributors
Acorn Pooley
Greg Roth
Contacts
Greg Roth (groth 'at' nvidia.com)
Status
Complete
Version
Version 3, Sept 03, 2011
Number
EGL Extension #42
Dependencies
Requires EGL 1.4
Written against the EGL 1.4 specification.
Overview
Adds support for creating an onscreen EGLSurface containing
multiple color buffers.
EXT_multi_draw_buffers can be used with this extension to
render and display multiple color buffers to a supported
device.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted as an attribute in the <attrib_list> parameter of
CreateWindowSurface:
EGL_MULTIVIEW_VIEW_COUNT_EXT 0x3134
Additions to Chapter 3 of the EGL 1.2 Specification:
Additions to section 3.5.1 (Creating On-Screen Rendering Surfaces)
Alter the end of the second paragraph:
Attributes that can be specified in <attrib_list> include
EGL_RENDER_BUFFER, EGL_VG_COLORSPACE, EGL_VG_ALPHA_FORMAT, and
EGL_MULTIVIEW_VIEW_COUNT_EXT.
Add before the last paragraph of section 3.5.1:
EGL_MULTIVIEW_VIEW_COUNT_EXT specifies how many multiview color
buffers should be created for the surface. Each color buffer has
the same properties as the primary color buffer as specified by
window and surface attributes. The default value of
EGL_MULTIVIEW_VIEW_COUNT_EXT is one.
EGL may not be able to create as many multiview color buffers as
EGL_MULTIVIEW_VIEW_COUNT_EXT specifies. To determine the number
of multiview color buffers created by a context, call
eglQueryContext (see section 3.7.4).
Add to the last paragraph of section 3.5.1:
If the value specified for EGL_MULTIVIEW_VIEW_COUNT_EXT is less
than one, an EGL_BAD_PARAMETER error is generated. If the value
specified for EGL_MULTIVIEW_VIEW_COUNT_EXT is greater than one
and the <config> does not support multiple multiview color
buffers, an EGL_BAD_MATCH error is generated.
Additions to section 3.5.6 (Surface Attributes)
Add to table 3.5, "Queryable surface attributes and types"
Attribute Type Description
--------- ---- -----------
EGL_MULTIVIEW_VIEW_COUNT_EXT integer Requested multiview
color buffers
Add before the last paragraph describing eglQuerySurface:
Querying EGL_MULTIVIEW_VIEW_COUNT_EXT for a window surface
returns the number of multiview color buffers requested. For a
pbuffer or pixmap surface, the contents of <value> are not
modified. To determine the actual number of multiview color
buffers created by a context, call eglQueryContext (see
section 3.7.4).
Additions to section 3.7.4 (Context Queries)
Add before the last paragraph describing eglQueryContext:
Querying EGL_MULTIVIEW_VIEW_COUNT_EXT returns the number of
multiview color buffers created. The value returned depends on
properties of both the context, and the surface to which the
context is bound.
Issues
None
Revision History
Version 3, 03 Sept 2011 EXTify add support for multiple or single depth buffer.
Version 2, 02 Aug 2011 Responses to feedback.
Version 1, 14 April 2011 First draft.
extensions/EXT/EGL_EXT_output_base.txt
+564
View File
@@ -0,0 +1,564 @@
Name
EXT_output_base
Name Strings
EGL_EXT_output_base
Contributors
Daniel Kartch
James Jones
Christopher James Halse Rogers
Contacts
Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com)
Status
Complete
Version
Version 9 - August 22, 2014
Number
EGL Extension #78
Extension Type
EGL display extension
Dependencies
Written against the wording of EGL 1.5, plus the EGL_EXT_device_base
specification.
Requires EGL_EXT_device_base
Overview
Increasingly, EGL and its client APIs are being used in place of
"native" rendering APIs to implement the basic graphics
functionality of native windowing systems. This creates demand
for a method to initialize EGL displays and surfaces directly on
top of native GPU or device objects rather than native window
system objects. The mechanics of enumerating the underlying
native devices and constructing EGL displays and surfaces from
them have been solved in various platform and implementation-
specific ways. The EGL device family of extensions offers a
standardized framework for bootstrapping EGL without the use of
any underlying "native" APIs or functionality.
This extension defines new EGL resource types for referencing
display control hardware associated with an EGL device. Its purpose
is to allow rendering to be directed to a screen in the absence of
(or bypassing) a window system. Because the use models for these
resources are potentially diverse, only the objects themselves and
basic functions to acquire and query them are defined here. More
detailed functions and enumerants required to operate on outputs
are provided by separate extensions.
New Types
A handle representing a portion of display control hardware which
accepts a single image as input and processes it for output on a
display device:
typedef void* EGLOutputLayerEXT;
A handle representing a portion of display control hardware which
transmits a signal to a display device:
typedef void* EGLOutputPortEXT;
New Functions
EGLBoolean eglGetOutputLayersEXT(
EGLDisplay dpy,
const EGLAttrib *attrib_list,
EGLOutputLayerEXT *layers,
EGLint max_layers,
EGLint *num_layers);
EGLBoolean eglGetOutputPortsEXT(
EGLDisplay dpy,
const EGLAttrib *attrib_list,
EGLOutputPortEXT *ports,
EGLint max_ports,
EGLint *num_ports);
EGLBoolean eglOutputLayerAttribEXT(
EGLDisplay dpy,
EGLOutputLayerEXT layer,
EGLint attribute,
EGLAttrib value);
EGLBoolean eglQueryOutputLayerAttribEXT(
EGLDisplay dpy,
EGLOutputLayerEXT layer,
EGLint attribute,
EGLAttrib *value);
const char* eglQueryOutputLayerStringEXT(
EGLDisplay dpy,
EGLOutputLayerEXT layer,
EGLint name);
EGLBoolean eglOutputPortAttribEXT(
EGLDisplay dpy,
EGLOutputPortEXT port,
EGLint attribute,
EGLAttrib value);
EGLBoolean eglQueryOutputPortAttribEXT(
EGLDisplay dpy,
EGLOutputPortEXT port,
EGLint attribute,
EGLAttrib *value);
const char* eglQueryOutputPortStringEXT(
EGLDisplay dpy,
EGLOutputPortEXT port,
EGLint name);
New Tokens
Functions with a return type of EGLOutputLayerEXT will return this
value on failure:
EGL_NO_OUTPUT_LAYER_EXT ((EGLOutputLayerEXT)0)
Functions with a return type of EGLOutputPortEXT will return this
value on failure:
EGL_NO_OUTPUT_PORT_EXT ((EGLOutputPortEXT)0)
Functions which fail due to a bad EGLOutputLayerEXT handle will set
this error code:
EGL_BAD_OUTPUT_LAYER_EXT 0x322D
Functions which fail due to a bad EGLOutputPortEXT handle will set
this error code:
EGL_BAD_OUTPUT_PORT_EXT 0x322E
Functions which set or query the swap interval use this attribute
name:
EGL_SWAP_INTERVAL_EXT 0x322F
Add a new section "2.1.4 Outputs" after "2.1.3 Displays":
An EGLDisplay may have zero or more associated EGLOutputLayerEXT
and EGLOutputPortEXT objects. These represent, respectively, the
inputs and outputs of display control hardware.
An EGLOutputLayerEXT is an abstract handle representing an element
of display control hardware which receives image data and processes
it for display. This processing is hardware-dependent, and may
include, but is not limited to, color space transformation, scaling
and rotation, and composition/blending with images from other
EGLOutputLayerEXTs.
An EGLOutputPortEXT is an abstract handle representing an element of
display control hardware which sends a signal to drive a display
screen. In general, this signal is the result of the processing of
one or more EGLOutputLayerEXTs.
Add new entries to section "3.1 Errors":
EGL_BAD_OUTPUT_LAYER_EXT
An EGLOutputLayerEXT argument does not name a valid
EGLOutputLayerEXT. Any command taking an EGLOutputLayerEXT
parameter may generate this error.
EGL_BAD_OUTPUT_PORT_EXT
An EGLOutputPortEXT argument does not name a valid
EGLOutputPortEXT. Any command taking an EGLOutputPortEXT
parameter may generate this error.
Add a new section "3.10 Device Outputs" after "3.9 Posting the Color Buffer":
3.10 Device Outputs
A simple platform running a custom software suite may not require a
formal window system. Instead, individual applications or a
compositor may send rendering results directly to display control
hardware, represented by EGLOutputLayerEXT and EGLOutputPortEXT
handles.
As with other EGL resources, EGLOutputLayerEXT and EGLOutputPortEXT
handles are owned by an EGLDisplay, but not all EGLDisplays are
required to support these objects. In general, they will only be
available for EGLDisplays obtained from platforms which allow direct
manipulation of display devices.
3.10.1 Acquiring Outputs
To obtain EGLOutputLayerEXT handles associated with a display which
match a list of attributes, use
EGLBoolean eglGetOutputLayersEXT(
EGLDisplay dpy,
const EGLAttrib *attrib_list,
EGLOutputLayerEXT *layers,
EGLint max_layers,
EGLint *num_layers)
On success, EGL_TRUE is returned. If <layers> is NULL, <max_layers>
is ignored and the number of output layers which match <attrib_list>
is returned in <num_layers>. Otherwise, up to <max_layers> matching
layers will be returned in <layers> and <num_layers> will be set to
the number of layer handles returned. The states of the output
layers are not altered by this query, and output layer handles can
be retrieved by multiple calls to this function.
<attrib_list> may be NULL or a list of name/value pairs terminated
by EGL_NONE. If no attributes are provided, all output layers
associated with <dpy> will match. Otherwise, only those layers
matching all attributes provided in the list will be returned,
unless the value specified is EGL_DONT_CARE. If there are no
matching layers but all parameters are otherwise valid, success is
returned but num_layers is set to 0.
On failure, EGL_FALSE will be returned and the memory referenced by
<layers> and <num_layers> will be unaffected. If <dpy> is not a
valid, initialized EGLDisplay, an EGL_BAD_DISPLAY error is
generated. If any name in <attrib_list> is not a valid layer
attribute name defined in Table 3.10.3.1, an EGL_BAD_ATTRIBUTE error
is generated. If any name in <attrib_list> does not allow search
access, an EGL_BAD_ACCESS error is generated.
To obtain EGLOutputPortEXT handles associated with a display which
match a list of attributes, use
EGLBoolean eglGetOutputPortsEXT(
EGLDisplay dpy,
const EGLAttrib *attrib_list,
EGLOutputPortEXT *ports,
EGLint max_ports,
EGLint *num_ports)
On success, EGL_TRUE is returned. If <ports> is NULL, <max_ports> is
ignored and the number of output ports which match <attrib_list> is
returned in <num_ports>. Otherwise, up to <max_ports> matching
layers will be returned in <ports> and <num_ports> will be set to
the number of port handles returned. The states of the output ports
are not altered by this query, and output port handles can be
retrieved by multiple calls to this function.
<attrib_list> may be NULL or a list of name/value pairs terminated
by EGL_NONE. If no attributes are provided, all output ports
associated with <dpy> will match. Otherwise, only those ports
matching all attributes provided in the list will be returned,
unless the value specified is EGL_DONT_CARE. If there are no
matching ports but all parameters are otherwise valid, success is
returned but num_ports is set to 0.
On failure, EGL_FALSE will be returned and the memory referenced by
<ports> and <num_ports> will be unaffected. If <dpy> is not a valid,
initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If
any name in <attrib_list> is not a valid port attribute name defined
in Table 3.10.3.2, an EGL_BAD_ATTRIBUTE error is generated. If any
name in <attrib_list> does not allow search access, an
EGL_BAD_ACCESS error is generated.
3.10.2 Lifetime of Output Handles
An initialized EGLDisplay has a fixed set of output layer and port
resources available. Implementations may defer creation of handles
and allocation of data structions for these objects until they are
first requested. However, once acquired, they remain valid as long
as the EGLDisplay is not terminated.
3.10.3 Output Attributes
Valid attributes associated with output layers and ports are listed
in Tables 3.10.3.1 and 3.10.3.2, respectively. Additional attributes
may be defined by other extensions. The Access columns contain one
or more of the letters "S", "R", and W". A value of "S" indicates
the attribute may be used to restrict the search when obtaining a
list of output handles. A value of "R" indicates the value may be
queried from an output handle. A value of "W" indicates the value
may be modified using an output handle.
Attribute Type Access
--------------------- ------- ------
EGL_SWAP_INTERVAL_EXT integer R|W
EGL_MIN_SWAP_INTERVAL integer R
EGL_MAX_SWAP_INTERVAL integer R
Table 3.10.3.1 Output layer attributes
Attribute Type Access
--------------------- ------- ------
[no attributes supported]
Table 3.10.3.2 Output port attributes
3.10.3.1 Querying Output Attributes
To query attributes of an EGLOutputLayerEXT, use
EGLBoolean eglQueryOutputLayerAttribEXT(
EGLDisplay dpy,
EGLOutputLayerEXT layer,
EGLint attribute,
EGLAttrib *value)
On success, this function returns EGL_TRUE and stores the value of
<attribute> in <value>.
On failure, EGL_FALSE is returned. If <dpy> is not a valid,
initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If
<layer> is not a valid EGLOutputLayerEXT associated with <dpy>, an
EGL_BAD_OUTPUT_LAYER_EXT error is generated. If <attribute> is not a
valid layer attribute name defined in Table 3.10.3.1, an
EGL_BAD_ATTRIBUTE error is generated. If <attribute> has string
type or does not allow read access, an EGL_BAD_ACCESS error is
generated.
To query string properties of an EGLOutputLayerEXT, use
const char* eglQueryOutputLayerStringEXT(
EGLDisplay dpy,
EGLOutputLayerEXT layer,
EGLint attribute)
On success, this function returns a zero-terminated string
containing the value associated with <name>.
On failure, NULL is returned. If <dpy> is not a valid, initialized
EGLDisplay, an EGL_BAD_DISPLAY error is generated. If <layer> is not
a valid EGLOutputLayerEXT associated with <dpy>, an
EGL_BAD_OUTPUT_LAYER_EXT error is generated. If <name> is not a
valid layer attribute name defined in Table 3.10.3.1, an
EGL_BAD_ATTRIBUTE error is generated. If <attribute> has non-string
type or does not allow read access, an EGL_BAD_ACCESS error is
generated.
To query attributes of an EGLOutputPortEXT, use
EGLBoolean eglQueryOutputPortAttribEXT(
EGLDisplay dpy,
EGLOutputPortEXT port,
EGLint attribute,
EGLAttrib *value)
On success, this function returns EGL_TRUE and stores the value of
<attribute> in <value>.
On failure, EGL_FALSE is returned. If <dpy> is not a valid,
initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If
<port> is not a valid EGLOutputPortEXT associated with <dpy>, an
EGL_BAD_OUTPUT_PORT_EXT error is generated. If <attribute> is not a
valid port attribute name defined in Table 3.10.3.2, an
EGL_BAD_ATTRIBUTE error is generated. If <attribute> has string
type or does not allow read access, an EGL_BAD_ACCESS error is
generated.
To query string properties of an EGLOutputPortEXT, use
const char* eglQueryOutputPortStringEXT(
EGLDisplay dpy,
EGLOutputPortEXT port,
EGLint attribute)
On success, this function returns a zero-terminated string
containing the value associated with <name>.
On failure, NULL is returned. If <dpy> is not a valid, initialized
EGLDisplay, an EGL_BAD_DISPLAY error is generated. If <port> is not
a valid EGLOutputPortEXT associated with <dpy>, an
EGL_BAD_OUTPUT_PORT_EXT error is generated. If <name> is not a
valid port attribute name defined in Table 3.10.3.2, an
EGL_BAD_ATTRIBUTE error is generated. If <attribute> has non-string
type or does not allow read access, an EGL_BAD_ACCESS error is
generated.
3.10.3.2 Setting Output Attributes
To set attributes of an EGLOutputLayerEXT, use
EGLBoolean eglOutputLayerAttribEXT(
EGLDisplay dpy,
EGLOutputLayerEXT layer,
EGLint attribute,
EGLAttrib value)
On success, this function returns EGL_TRUE and sets the value of
<attribute> to <value>.
If <attribute> is EGL_SWAP_INTERVAL_EXT, the value provided will be
silently clamped to the range specified by the layer's
EGL_MIN_SWAP_INTERVAL and EGL_MAX_SWAP_INTERVAL values.
On failure, EGL_FALSE is returned. If <dpy> is not a valid,
initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If
<layer> is not a valid EGLOutputLayerEXT associated with <dpy>, an
EGL_BAD_OUTPUT_LAYER_EXT error is generated. If <attribute> is not a
valid layer attribute name defined in Table 3.10.3.1, an
EGL_BAD_ATTRIBUTE error is generated. If <attribute> does not
allow write access, an EGL_BAD_ACCESS error is generated.
To set attributes of an EGLOutputPortEXT, use
EGLBoolean eglOutputPortAttribEXT(
EGLDisplay dpy,
EGLOutputPortEXT port,
EGLint attribute,
EGLAttrib value)
On success, this function returns EGL_TRUE and sets the value of
<attribute> to <value>.
On failure, EGL_FALSE is returned. If <dpy> is not a valid,
initialized EGLDisplay, an EGL_BAD_DISPLAY error is generated. If
<port> is not a valid EGLOutputPortEXT associated with <dpy>, an
EGL_BAD_OUTPUT_PORT_EXT error is generated. If <attribute> is not a
valid port attribute name defined in Table 3.10.3.2, an
EGL_BAD_ATTRIBUTE error is generated. If <attribute> does not
allow write access, an EGL_BAD_ACCESS error is generated.
3.10.4 Setting Output Modes
EGL does not currently define any mechanims to adjust display
modes through EGLOutputPortEXTs. These may be added via additional
extensions.
3.10.5 Posting to Outputs
EGL does not currently define any mechanisms to post rendering
results to EGLOutputsLayerEXTs. These may be added via additional
extensions. However, unless otherwise specified, such mechanims
will respect the layer's EGL_SWAP_INTERVAL_EXT value, which
specifies the minimum number of video frame periods for which the
frames should be displayed, in a manner analogous to using
eglSwapInterval for the current draw surface. The default value of
EGL_SWAP_INTERVAL_EXT is 1, clamped to the layer's
EGL_MIN_SWAP_INTERVAL and EGL_MAX_SWAP_INTERVAL values.
(Example: See extension specification
EGL_EXT_stream_consumer_egloutput)
Issues
1. Should this extension provide a mechanism to enumerate outputs
associated with an EGLDevice and set their modes?
RESOLVED: No. On many operating systems there already exist
standardized and/or widely accepted low level mechanisms for
performing these tasks. Duplicating this support in EGL would
impose an undesirable implementation burden where output handles
are only required as a means to direct rendering to a display
screen. Functions for enumerating screens or obtaining them from
platform-dependent representations will be provided by other
extensions.
2. Should output layer and port handles be associated with an
EGLDisplay, or vice versa?
RESOLVED: Yes. Furthermore, it may only be possible to obtain
output handles from some EGLDisplays. The primary intended use
case is the EGLDisplay associated with an EGLDevice, through the
platform defined by EGL_EXT_platform_device. This represents raw
device access available in the absence of a window system.
EGLDisplays associated with other platforms typically represent
handles provided by window systems, which may not allow direct
access to the display control hardware.
3. Can the EGLDeviceEXT handle be returned by a query function
which returns integer attributes?
RESOLVED: Yes. Function definition has been updated to use
EGLAttribEXT, which is compatible with EGL handles.
4. What display mode properties should be queriable by the base
extension? Does the application require width/height/refresh or
should those be left to other mechanisms or additional
extensions? If hardware supports selecting a portion of the
image for display, or restricting an image to a portion of the
screen, or scaling an image to a different resolution for
display, should all these settings be queriable?
RESOLVED: The base extension will not define any display
properties. These will be left to future extensions if required.
5. How should stereo/multiview displays be handled? Should all
views share a single output or does each one have its own?
UNRESOLVED. Left for a future extension to define.
6. This extension is currently focused on individual display layers
for the purpose of directing rendering output. An API covering
all hardware would associate one or more of those layers with a
display port. Do we need to abstract both?
RESOLVED: Yes. Extension has been modified to abstract both
inputs (layers) and outputs (ports) of display control hardware.
An implementation is not required to return any ports in the
query function if it provides no means to operate on them.
Revision History:
#9 (August 22nd, 2014) James Jones
- Marked complete.
- Added minor coments to issue 5.
- Listed Daniel as the contact.
#8 (June 10th, 2014) Daniel Kartch
- Fixed prototypes for layer/port attribute setting functions.
#7 (June 5th, 2014) Daniel Kartch
- Assigned enumerated values for constants.
- Indicated default swap interval value.
#6 (May 28th, 2014) Daniel Kartch
- Updated wording based on EGL 1.5 specification, using
EGLAttrib instead of EGLAttribEXT.
- Added functions to set layer and port attributes.
- Added table of valid attributes, with min/max/current swap
interval values, and adjusted function descriptions
accordingly.
- Refined description for output enumeration functions to better
indicate the effect of attribute list.
- Added effect of swap interval in posting section.
#5 (January 31st, 2014) Daniel Kartch
- Added eglGetOutput* functions, folding in and generalizing
functionality previously provided by EXT_native_output
extension.
- Separated descriptions for layer and port query functions for
clarity.
#4 (January 22nd, 2014) Daniel Kartch
- Added section clarifying that this extension provides no means
to use output ports to set display modes, but future
extensions may.
#3 (January 17th, 2014) Daniel Kartch
- Updated names of example extension for obtaining and using
output handles.
- Fixed typos.
#2 (November 12th, 2013) Daniel Kartch
- Replaced EGLOutput with EGLOutputLayer and added
EGLOutputPort (and modified/added corresponding functions), to
allow both inputs and outputs of display control hardware to
be abstracted.
- Modified attribute query functions to use EGLAttribEXT and
added string query functions.
- Removed display mode attributes. These can be defined by a
separate extension if desired.
- Removed destructor function for outputs and added section on
lifetime, as well as language describing their relationship to
EGLDisplays.
#1 (October 25nd, 2013) Daniel Kartch
- Initial draft
extensions/EXT/EGL_EXT_pixel_format_float.txt
+136
View File
@@ -0,0 +1,136 @@
Name
EXT_pixel_format_float
Name Strings
EGL_EXT_pixel_format_float
Contributors
Tom Cooksey
Jesse Hall
Mathias Heyer
Adam Jackson
James Jones
Daniel Koch
Jeff Leger
Weiwan Liu
Jeff Vigil
Contact
Weiwan Liu, NVIDIA (weiwliu 'at' nvidia.com)
Status
Complete
Version
Version 4 - Nov 22, 2016
Number
EGL Extension #106
Dependencies
This extension is written against the wording of the EGL 1.5 specification
(August 27, 2014).
Overview
This extensions aims to provide similar functionality as GL_ARB_color_-
buffer_float, WGL_ARB_pixel_format_float and GLX_ARB_fbconfig_float. This
extension allows exposing new EGLConfigs that support formats with
floating-point RGBA components. This is done by introducing a new EGLConfig
attribute that represents the component type, i.e. fixed-point or
floating-point. Such new EGLConfigs can be used to create floating-point
rendering surfaces and contexts.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted as an attribute name in the <attrib_list> argument of
eglChooseConfig, and the <attribute> argument of eglGetConfigAttrib:
EGL_COLOR_COMPONENT_TYPE_EXT 0x3339
Accepted as attribute values for the EGL_COLOR_COMPONENT_TYPE_EXT attribute
of eglChooseConfig:
EGL_COLOR_COMPONENT_TYPE_FIXED_EXT 0x333A
EGL_COLOR_COMPONENT_TYPE_FLOAT_EXT 0x333B
Additions to table 3.1, "EGLConfig attributes" in Section 3.4 "Configuration
Management":
Attribute Type Notes
--------- ---- ---------
EGL_COLOR_COMPONENT_TYPE_EXT enum color component type
Append one paragraph at the end of "The Color Buffer" section on page 21:
EGL_COLOR_COMPONENT_TYPE_EXT indicates the color buffer component type,
and must be either EGL_COLOR_COMPONENT_TYPE_FIXED_EXT for fixed-point
color buffers, or EGL_COLOR_COMPONENT_TYPE_FLOAT_EXT for floating-point
color buffers.
Add one entry to Table 3.4 and increment "Sort Priority" between "2" and
"11" by one for existing entries:
Attribute Default
----------- ------------
EGL_COLOR_COMPONENT_TYPE_EXT EGL_COLOR_COMPONENT_TYPE_FIXED_EXT
Selection Criteria Sort Order Priority
------------------ ---------- --------
Exact Special 2
Insert before the entry for EGL_COLOR_BUFFER_TYPE, and increment its
numbering and subsequent numbering by one:
2. Special: by EGL_COLOR_COMPONENT_TYPE_EXT where the precedence is
EGL_COLOR_COMPONENT_TYPE_FIXED_EXT, EGL_COLOR_COMPONENT_TYPE_FLOAT_EXT
Change footnote 8 on page 30 to:
Within the same EGL_COLOR_COMPONENT_TYPE_EXT, this rule places configs
with deeper color buffers first in the list returned by
eglChooseConfig...
Issues
1. When reading from or rendering to a floating-point EGL surface, is there
any clamping performed on the values?
RESOLVED: It depends on the behavior of the client API. For example, in
OpenGL and ES, by default no clamping will be done on the floating-point
values, unless the clamping behavior is changed via the client API.
2. When rendering to a floating-point EGL surface, since values may not be
clamped to [0, 1], what is the range of values that applications can use
to get display's "darkest black" and "brightest white"?
RESOLVED: It is not in the scope of this extension to define a range of
values that corresponds to display's capability. Please refer to the EGL
specification for the chosen colorspace (EGL_GL_COLORSPACE), where such a
reference range may be defined.
Revision History
Rev. Date Author Changes
---- -------- --------------- ------------------------------------------
1 12/11/15 Weiwan Liu Initial version
2 05/18/16 Weiwan Liu Rename to EXT
3 05/31/16 Weiwan Liu Add issues
4 11/22/16 Weiwan Liu Change status to complete
extensions/EXT/EGL_EXT_platform_base.txt
+371
View File
@@ -0,0 +1,371 @@
Name
EXT_platform_base
Name Strings
EGL_EXT_platform_base
Contributors
Chad Versace <chad.versace@intel.com>
James Jones <jajones@nvidia.com>
Contacts
Chad Versace <chad.versace@intel.com>
Status
Complete
Version
Version 9, 2014.01.09
Number
EGL Extension #57
Extension Type
EGL client extension
Dependencies
Requires EGL 1.4.
Requires EGL_EXT_client_extensions to query its existence without
a display.
This extension is written against the wording of the 2013.02.11 revision
of the EGL 1.4 Specification.
Overview
This extension defines functionality and behavior for EGL implementations
that support multiple platforms at runtime. For example, on Linux an EGL
implementation could support X11, Wayland, GBM (Generic Buffer Manager),
Surface Flinger, and perhaps other platforms.
In particular, this extension defines the following:
1. A mechanism by which an EGL client can detect which platforms the
EGL implementation supports.
2. New functions that enable an EGL client to specify to which
platform a native resource belongs when creating an EGL resource
from that native resource. For example, this extension enables an
EGL client to specify, when creating an EGLSurface from a native
window, that the window belongs to X11.
3. That an EGL client is not restricted to interacting with a single
platform per process. A client process can create and manage EGL
resources from multiple platforms.
The generic term 'platform' is used throughout this extension
specification rather than 'window system' because not all EGL platforms
are window systems. In particular, those platforms that allow headless
rendering without a display server, such as GBM, are not window systems.
This extension does not specify behavior specific to any platform, nor
does it specify the set of platforms that an EGL implementation may
support. Platform-specific details lie outside this extension's scope and
are instead described by extensions layered atop this one.
New Types
None
New Procedures and Functions
EGLDisplay eglGetPlatformDisplayEXT(
EGLenum platform,
void *native_display,
const EGLint *attrib_list);
EGLSurface eglCreatePlatformWindowSurfaceEXT(
EGLDisplay dpy,
EGLConfig config,
void *native_window,
const EGLint *attrib_list);
EGLSurface eglCreatePlatformPixmapSurfaceEXT(
EGLDisplay dpy,
EGLConfig config,
void *native_pixmap,
const EGLint *attrib_list);
New Tokens
None
Additions to the EGL 1.4 Specification
Replace each occurence of the term "window system" with "platform". The
rationale behind this change is that not all platforms are window systems,
yet the EGL 1.4 specification uses the two terms interchangeably. In
particular, platforms that allow headless rendering without a display
server, such as GBM, are not window systems.
Append the following paragraph to the initial, unnamed subsection of
section 2.1 "Native Window System and Rendering APIs".
"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.
Replace the text of section 3.2 "Initialization", from the start of the
section and up to and excluding the phrase "EGL may be intialized on
a display", with the following:
"A display can be obtained by calling
EGLDisplay eglGetPlatformDisplayEXT(
EGLenum platform,
void *native_display,
const EGLint *attrib_list);
EGL considers the returned EGLDisplay as belonging to the native platform
specified by <platform>. This specification defines no valid value for
<platform>. Any specification that does define a valid value for
<platform> will also define requirements for the <native_display>
parameter. For example, an extension specification that defines support
for the X11 platform may require that <native_display> be a pointer to an
X11 Display, and an extension specification that defines support for the
Microsoft Windows platform may require that <native_display> be a pointer
to a Windows Device Context.
All attribute names in <attrib_list> are immediately followed by the
corresponding desired value. The list is terminated with EGL_NONE. The
<attrib_list> is considered empty if either <attrib_list> is NULL or if
its first element is EGL_NONE. This specification defines no valid
attribute names for <attrib_list>.
Multiple calls made to eglGetPlatformDisplayEXT with the same <platform>
and <native_display> will return the same EGLDisplay handle.
An EGL_BAD_PARAMETER error is generated if <platform> has an invalid value.
If <platform> is valid but no display matching <native_display> is
available, then EGL_NO_DISPLAY is returned; no error condition is raised
in this case.
A display can also be obtained by calling
EGLDisplay eglGetDisplay(EGLNativeDisplayType display_id);
The behavior of eglGetDisplay is similar to that of
eglGetPlatformDisplayEXT, but is specifided in terms of implementation-
specific behavior rather than platform-specific extensions.
As for eglGetPlatformDisplayEXT, EGL considers the returned EGLDisplay
as belonging to the same platform as <display_id>. However, the set of
platforms to which <display_id> is permitted to belong, as well as the
actual type of <display_id>, are implementation-specific. If <display_id>
is EGL_DEFAULT_DISPLAY, a default display is returned. Multiple calls
made to eglGetDisplay with the same <display_id> will return the same
EGLDisplay handle. If no display matching <display_id> is available,
EGL_NO_DISPLAY is returned; no error condition is raised in this case."
In section 3.5.1 "Creating On-Screen Rendering Surfaces", replace the
second paragraph, which begins with "Using the platform-specific type" and
ends with "render into this surface", with the following:
"Then call
EGLSurface eglCreatePlatformWindowSurfaceEXT(
EGLDisplay dpy,
EGLConfig config,
void *native_window,
const EGLint *attrib_list);
eglCreatePlatformWindowSurfaceEXT creates an onscreen EGLSurface and
returns a handle to it. Any EGL context created with a compatible
EGLConfig can be used to render into this surface.
<native_window> must belong to the same platform as <dpy>, and EGL
considers the returned EGLSurface as belonging to that same platform. The
extension that defines the platform to which <dpy> belongs also defines
the requirements for the <native_window> parameter."
In the remainder of section 3.5.1, replace each occurrence of
'eglCreateWindowSurface' with 'eglCreatePlatformWindowSurfaceEXT'.
Insert the sentence below after the first sentence of the last paragraph
of section 3.5.1:
"If <dpy> and <native_window> do not belong to the same platform, then
undefined behavior occurs. [1]"
Add the following footnote to section 3.5.1:
"[1] See section 3.1.0.2 "Parameter Validation".
Append the following to section 3.5.1:
"An on-screen rendering surface may also be created by calling
EGLSurface eglCreateWindowSurface(
EGLDisplay dpy,
EGLConfig config,
EGLNativeWindowType win,
const EGLint *attrib_list);
The behavior of eglCreateWindowSurface is identical to that of
eglCreatePlatformWindowSurfaceEXT except that the set of platforms to
which <dpy> is permitted to belong, as well as the actual type of <win>,
are implementation specific.
In section 3.5.4 "Creating Native Pixmap Rendering Surfaces", replace the
third paragraph, which begins with "Using the platform-specific type" and
ends with "render into this surface", with the following:
"Then call
EGLSurface eglCreatePlatformPixmapSurfaceEXT(
EGLDisplay dpy,
EGLConfig config,
void *native_pixmap,
const EGLint *attrib_list);
eglCreatePlatformPixmapSurfaceEXT creates an offscreen EGLSurface and
returns a handle to it. Any EGL context created with a compatible
EGLConfig can be used to render into this surface.
<native_pixmap> must belong to the same platform as <dpy>, and EGL
considers the returned EGLSurface as belonging to that same platform. The
extension that defines the platform to which <dpy> belongs also defines
the requirements for the <native_pixmap> parameter."
In the remainder of section 3.5.4, replace each occurrence of
'eglCreatePixmapSurface' with 'eglCreatePlatformPixmapSurfaceEXT' and each
occurence of 'eglCreateWindowSurface' with
'eglCreatePlatformWindowSurfaceEXT'.
Insert the sentence below after the first sentence of the last paragraph
of section 3.5.4:
"If <dpy> and <native_pixmap> do not belong to the same platform, then
undefined behavior occurs. [1]"
Add the following footnote to section 3.5.3:
"[1] See section 3.1.0.2 "Parameter Validation".
Append the following to section 3.5.2:
"An offscreen rendering surface may also be created by calling
EGLSurface eglCreatePixmapSurface(
EGLDisplay dpy,
EGLConfig config,
EGLNativePixmapType pixmap,
const EGLint *attrib_list);
The behavior of eglCreatePixmapSurface is identical to that of
eglCreatePlatformPixmapSurfaceEXT except that the set of platforms to
which <dpy> is permitted to belong, as well as the actual type of
<pixmap>, are implementation specific.
Issues
1. What rules define how EGL resources are shared among displays belonging
to different platforms?
RESOLVED: Neither the EGL 1.4 specification nor any extension allow EGL
resources to be shared among displays. This extension does not remove
that restriction.
2. Rather than define the new function eglGetPlatformDisplayEXT(), should
this extension instead define new thread-local state for the currently
bound platform and an associated binding function, such as
eglBindPlatformEXT()?
RESOLVED: No, for the following reasons.
- A current trend among the Khronos workgroups is to remove use of
global state by introducing bindless objects. Introducing a new
thread-local binding point defies that trend.
- Additional specification language would be required to define
the interactions between the currently bound platform and all
EGL functions that accept an EGLDisplay. (For example, if the
currently bound platform is Wayland, then what is the result of
calling eglCreateWindowSurface() with a display and native
window belonging to X11?) By choosing to not introduce the
notion of a "currently bound platform", we obtain a cleaner
extension specification and eliminate for EGL users a class of
potential bugs.
3. Should this extension define the notion of a default platform?
RESOLVED: No. eglGetDisplay() can be used if a default platform is
needed.
4. Rather than define the new functions
eglCreatePlatform{Window,Pixmap}SurfaceEXT(), should we instead
redefine the EGLNative* types in eglplatform.h as void*?
RESOLVED: No, this introduces problems for X11 applications.
Suppose that a 64-bit X11 application is compiled against an old EGL
library (where EGLNativeWindowType is a typedef for XID, which is in
turn a typedef for a 64-bit unsigned integer on Fedora 18) and then
attempts to run against a new EGL library (where EGLNativeType is
a typedef for void*). To preserve the ABI of eglCreateWindowSurface()
in this situation, the new EGL library must re-interpret the
<native_window> parameter as an integer.
However, this preservation of the ABI breaks source compatibility for
existing X11 applications. To successfully compile, each call to
eglCreateWindowSurface(dpy, window, attribs)
in existing X11 application source code would need to be replaced with
eglCreateWindowSurface(dpy, (void*) window, attribs) .
Requiring such widespread code modifications would be an unnecessary
burden to developers and Linux package maintainers.
Revision History
Version 9, 2014.01.09 (Jon Leech)
- Fix typo eglGetDisplayPlatformEXT -> eglGetPlatformDisplayEXT
Version 8, 2013.07.03 (Chad Versace)
- Add "Extension Type" section, required by EGL_EXT_client_extensions v9.
Version 7, 2013.06.07 (Chad Versace)
- Fix some awkward text (s/the EGL/EGL/).
- Remove text "attribute names are defined by platform-specific
extensions".
Version 6, 2013.06.07 (Chad Versace)
- To "Dependencies" section, expand text that discusses
EGL_EXT_client_extensions.
Version 5, 2013.05.18 (Chad Versace)
- Removed restriction that "attribute names are defined only by
platform-specific extensions".
- Resolve issue 3 as NO.
- Clarified some text and fixed grammatical errors.
Version 4, 2013.05.14 (Chad Versace)
- Add <attrib_list> parameter to eglGetPlatformDisplayEXT, per
feedback at the April Khronos F2F.
Version 3, 2013.04.26 (Chad Versace)
- Add issues 2, 3, 4.
Version 2, 2013.03.24 (Chad Versace)
- Complete draft by adding text for pixmaps.
- The footnotes regarding undefined behavior, simplify them by
simply referring to section 3.1.0.2.
- Add issue 1 from Eric Anholt <eric@anholt.net>.
- Fix spelling and formatting errors.
Version 1, 2013.03.13 (Chad Versace)
- Incomplete draft posted for review
extensions/EXT/EGL_EXT_platform_device.txt
+161
View File
@@ -0,0 +1,161 @@
Name
EXT_platform_device
Name Strings
EGL_EXT_platform_device
Contributors
James Jones
Daniel Kartch
Contacts
James Jones, NVIDIA (jajones 'at' nvidia.com)
Status
Complete
Version
Version 6 - May 16th, 2014
Number
EGL Extension #73
Extension Type
EGL device extension
Dependencies
Requires EGL_EXT_device_base
Requires EGL_EXT_platform_base or EGL 1.5
Written against the wording of EGL 1.5
Overview
Increasingly, EGL and its client APIs are being used in place of
"native" rendering APIs to implement the basic graphics
functionality of native windowing systems. This creates demand
for a method to initialize EGL displays and surfaces directly on
top of native GPU or device objects rather than native window
system objects. The mechanics of enumerating the underlying
native devices and constructing EGL displays and surfaces from
them have been solved in various platform and implementation-
specific ways. The EGL device family of extensions offers a
standardized framework for bootstrapping EGL without the use of
any underlying "native" APIs or functionality.
This extension defines a method to create an EGLDisplay from an
EGLDeviceEXT by treating the EGLDeviceEXT as an EGLNativeDisplay
object.
New Types
None
New Functions
None
New Tokens
Accepted by the <platform> parameter of eglGetPlatformDisplayEXT
and eglGetPlatformDisplay:
EGL_PLATFORM_DEVICE_EXT 0x313F
Replace the last paragraph of section 2.1 "Native Window System and
Rendering APIs"
"This specification defines only the EGLDeviceEXT platform, and
behavior specific to it. Implementations may support other
platforms, but their existence and behavior is defined by
extensions. To detect support for other platforms, clients should
query the EGL_EXTENSIONS string of EGL_NO_DISPLAY using
eglQueryString (see section 3.3).
Replace the second sentence of the paragraph following the
eglGetPlatformDisplay prototype
"The only valid value for <platform> is EGL_PLATFORM_DEVICE_EXT.
When <platform> is EGL_PLATFORM_DEVICE_EXT, <native_display> must
be an EGLDeviceEXT object. Platform-specific extensions may
define other valid values for <platform>."
Add the following sentence to the end of the second paragraph after
the eglCreatePlatformWindowSurface prototype.
"There are no valid values of <native_window> when <dpy> belongs
to the EGL_PLATFORM_DEVICE_EXT platform."
Add the following sentence to the end of the second paragraph after
the eglCreatePlatformPixmapSurface prototype.
"There are no valid values of <native_pixmap> when <dpy> belongs
to the EGL_PLATFORM_DEVICE_EXT platform.
Issues
1. Do EGLDevice-backed displays support window or pixmap surfaces?
If so, what native objects are they associated with? If not,
are EGLDevice-backed displays useful in any way?
RESOLVED: This extension defines no method to create window or
pixmap surfaces on the EGLDeviceEXT platform. Other
extensions may define such functionality. Presumably, if
there are no other extensions that expose native window or
pixmap types associated with EGL devices, EGLDeviceEXT-backed
displays could expose EGLConfigs that only support rendering
to EGLStreamKHR or EGLPbuffer surfaces.
2. Should the EGL_PLATFORM_DEVICE_EXT platform be included in the
EGL specification as a special "blessed" platform, or exist
only as an extension like other platforms?
RESOLVED: EGL devices are defined as part of the EGL
specification, so there's no reason to exclude their
associated platform from the core EGL specification. They are
not native objects, therefore they can not be referred to as a
native platform, even though they are used interchangeably
with native objects in this extension.
Revision History:
#6 (May 16th, 2014) James Jones
- Marked the extension complete
- Marked all issues resolved
#5 (April 8th, 2014) James Jones
- Updated wording based on the EGL 1.5 spec
- Assigned values to tokens
#4 (November 6th, 2013) James Jones
- Specified this is a device extension
- Requires, rather than interacts with EGL_EXT_platform_base
- Removed EGL_SUPPORTS_PLATFORM_DEVICE_EXT. There is no need
for a separate query now that the name string is listed in
the per-device extension string
#3 (April 23rd, 2013) James Jones
- Fixed minor typos
#2 (April 18th, 2013) James Jones
- Moved eglGetDisplayPointerEXT to a stand-alone extension
- Renamed from EGL_EXT_device_display to
EGL_EXT_platform_device
- Filled in the actual spec language modifications
- Replaced issue 2, since the original was moved to
EGL_EXT_display_attributes
- Reworded issue 1.
- Fixed some typos
#1 (April 16th, 2013) James Jones
- Initial Draft
extensions/EXT/EGL_EXT_platform_wayland.txt
+135
View File
@@ -0,0 +1,135 @@
Name
EXT_platform_wayland
Name Strings
EGL_EXT_platform_wayland
Contributors
Chad Versace <chad.versace@intel.com>
Contacts
Chad Versace <chad.versace@intel.com>
Status
Complete
Version
Version 4, 2014-03-10
Number
EGL Extension #63
Extension Type
EGL client extension
Dependencies
Requires EGL_EXT_client_extensions to query its existence without
a display.
Requires EGL_EXT_platform_base.
This extension is written against the wording of version 7 of the
EGL_EXT_platform_base specification.
Overview
This extension defines how to create EGL resources from native Wayland
resources using the functions defined by EGL_EXT_platform_base.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted as the <platform> argument of eglGetPlatformDisplayEXT:
EGL_PLATFORM_WAYLAND_EXT 0x31D8
Additions to the EGL Specification
None.
New Behavior
To determine if the EGL implementation supports this extension, clients
should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY.
To obtain an EGLDisplay backed by a Wayland display, call
eglGetPlatformDisplayEXT with <platform> set to EGL_PLATFORM_WAYLAND_EXT. The
<native_display> parameter specifies the Wayland display to use and must
either point to a `struct wl_display` or be EGL_DEFAULT_DISPLAY. If
<native_display> is EGL_DEFAULT_DISPLAY, then EGL will create a new
wl_display structure by connecting to the default Wayland socket. The
manual page wl_display_connect(3) defines the location of the default
Wayland socket.
To obtain an on-screen rendering surface from a Wayland window, call
eglCreatePlatformWindowSurfaceEXT with a <dpy> that belongs to Wayland and
a <native_window> that points to a `struct wl_egl_surface`.
It is not valid to call eglCreatePlatformPixmapSurfaceEXT with a <dpy>
that belongs to Wayland. Any such call fails and generates
EGL_BAD_PARAMETER.
Issues
1. Should this extension permit EGL_DEFAULT_DISPLAY as input to
eglGetPlatformDisplayEXT()?
RESOLUTION: Yes. When given EGL_DEFAULT_DISPLAY, eglGetPlatformDisplayEXT
returns a display backed by the default Wayland display.
2. Should this extension support creation EGLPixmap resources from Wayland
pixmaps?
RESOLVED. No. Wayland has no pixmap type.
3. Should the extension namespace be EXT or MESA?
The only shipping EGL implementation today (2013-04-26) that supports
Wayland is Mesa. However, perhaps the extension should reside in the
EXT namespace in expectation that other vendors will also begin
supporting Wayland.
RESOLVED. Use the EXT namespace because other vendors have expressed
interest in Wayland.
Revision History
Version 4, 2014-03-10(Chad Versace)
- Change resolution of issue #1 from "no" to "yes". Now
eglGetPlatformDisplayEXT accepts EGL_DEFAULT_DISPLAY for Wayland.
- Explain in more detail how EGL connects to the default Wayland
display.
Version 3, 2013-10-16 (Chad Versace)
- Resolve issue #3 to use EXT namespace.
Version 2, 2013-09-12 (Chad Versace)
- Update to wording of version 7 of EGL_EXT_platform_base spec.
- Add section "Extension Type".
- Rephrase the discussion of how to create a Wayland EGLDisplay
to follow the analogous discussion in the published
EGL_EXT_platform_x11 spec.
- Change resolution of issue 1 from yes to no, because of likely type
mismatch between EGL_DEFAULT_DISPLAY_TYPE and void*.
Version 1, 2013-04-26 (Chad Versace)
- Initial draft
# vim:ai:et:sw=4:ts=4:
extensions/EXT/EGL_EXT_platform_x11.txt
+414
View File
@@ -0,0 +1,414 @@
Name
EXT_platform_x11
Name Strings
EGL_EXT_platform_x11
Contributors
Chad Versace <chad.versace@intel.com>
James Jones <jajones@nvidia.com>
Contacts
Chad Versace <chad.versace@intel.com>
Status
Complete
Version
Version 13, 2014-03-10
Number
EGL Extension #59
Extension Type
EGL client extension
Dependencies
Requires EGL_EXT_client_extensions to query its existence without
a display.
Requires EGL_EXT_platform_base.
This extension is written against the wording of version 7 of the
EGL_EXT_platform_base specification.
Overview
This extension defines how to create EGL resources from native X11
resources using the functions defined by EGL_EXT_platform_base.
This extension defines only how to create EGL resources from Xlib
resources. It does not define how to do so from xcb resources. All X11
types discussed here are defined by the header `Xlib.h`.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted as the <platform> argument of eglGetPlatformDisplayEXT:
EGL_PLATFORM_X11_EXT 0x31D5
Accepted as an attribute name in the <attrib_list> argument of
eglGetPlatformDisplayEXT:
EGL_PLATFORM_X11_SCREEN_EXT 0x31D6
Additions to the EGL Specification
None.
New Behavior
To determine if the EGL implementation supports this extension, clients
should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY.
On the X11 platform, an EGLDisplay refers to a specific X11 screen rather
than an X11 display connection. This is the case because separate X11
screens, even when belonging to the same X11 display connection, may
reside on different GPUs and/or be driven by different drivers. Therefore,
different X11 screens may have different EGL capabilities.
To obtain an EGLDisplay backed by an X11 screen, call
eglGetPlatformDisplayEXT with <platform> set to EGL_PLATFORM_X11_EXT. The
<native_display> parameter specifies the X11 display connection to use, and
must point to a valid X11 `Display` or be NULL. If <native_display> is
EGL_DEFAULT_DISPLAY, then EGL will create [1] a connection to the default
X11 display. The environment variable DISPLAY determines the default X11
display as described in the manual page for XOpenDisplay(3). The value of
attribute EGL_PLATFORM_X11_SCREEN_EXT specifies the X11 screen to use. If
the attribute is omitted from <attrib_list>, then the display connection's
default screen is used. Otherwise, the attribute's value must be a valid
screen on the display connection. If the attribute's value is not a valid
screen, then an EGL_BAD_ATTRIBUTE error is generated.
[fn1] The method by which EGL creates a connection to the default X11
display is an internal implementation detail. The implementation may use
XOpenDisplay, xcb_connect, or any other method.
To obtain an on-screen rendering surface from an X11 Window, call
eglCreatePlatformWindowSurfaceEXT with a <dpy> that belongs to X11 and
a <native_window> that points to an X11 Window.
To obtain an offscreen rendering surface from an X11 Pixmap, call
eglCreatePlatformPixmapSurfaceEXT with a <dpy> that belongs to X11 and
a <native_pixmap> that points to an X11 Pixmap.
Issues
1. Should this extension permit EGL_DEFAULT_DISPLAY as input to
eglGetPlatformDisplayEXT()?
RESOLVED. Yes. When given EGL_DEFAULT_DISPLAY, eglGetPlatformDisplayEXT
returns an EGLDisplay backed by the default X11 display.
2. When given EGL_DEFAULT_DISPLAY, does eglGetPlatformDisplayEXT reuse an
existing X11 display connection or create a new one?
RESOLVED. eglGetPlatformDisplayEXT creates a new connection because the
alternative is infeasible. EGL cannot reliably detect if the client
process already has a X11 display connection.
Example Code
// This example program creates two EGL surfaces: one from an X11 Window
// and the other from an X11 Pixmap.
//
// If the macro USE_EGL_EXT_PLATFORM_X11 is defined, then the program
// creates the surfaces using the methods defined in this specification.
// Otherwise, it uses the methods defined by the EGL 1.4 specification.
//
// Compile with `cc -std=c99 example.c -lX11 -lEGL`.
#include <stdlib.h>
#include <string.h>
#include <EGL/egl.h>
#include <X11/Xlib.h>
struct my_display {
Display *x11;
EGLDisplay egl;
};
struct my_config {
struct my_display dpy;
XVisualInfo *x11;
Colormap colormap;
EGLConfig egl;
};
struct my_window {
struct my_config config;
Window x11;
EGLSurface egl;
};
struct my_pixmap {
struct my_config config;
Pixmap x11;
EGLSurface egl;
};
static void
check_extensions(void)
{
#ifdef USE_EGL_EXT_PLATFORM_X11
const char *client_extensions = eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS);
if (!client_extensions) {
// EGL_EXT_client_extensions is unsupported.
abort();
}
if (!strstr(client_extensions, "EGL_EXT_platform_x11")) {
abort();
}
#endif
}
static struct my_display
get_display(void)
{
struct my_display dpy;
dpy.x11 = XOpenDisplay(NULL);
if (!dpy.x11) {
abort();
}
#ifdef USE_EGL_EXT_PLATFORM_X11
dpy.egl = eglGetPlatformDisplayEXT(EGL_PLATFORM_X11_EXT, dpy.x11,
NULL);
#else
dpy.egl = eglGetDisplay(dpy.x11);
#endif
if (dpy.egl == EGL_NO_DISPLAY) {
abort();
}
EGLint major, minor;
if (!eglInitialize(dpy.egl, &major, &minor)) {
abort();
}
return dpy;
}
static struct my_config
get_config(struct my_display dpy)
{
struct my_config config = {
.dpy = dpy,
};
EGLint egl_config_attribs[] = {
EGL_BUFFER_SIZE, 32,
EGL_RED_SIZE, 8,
EGL_GREEN_SIZE, 8,
EGL_BLUE_SIZE, 8,
EGL_ALPHA_SIZE, 8,
EGL_DEPTH_SIZE, EGL_DONT_CARE,
EGL_STENCIL_SIZE, EGL_DONT_CARE,
EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT,
EGL_SURFACE_TYPE, EGL_WINDOW_BIT | EGL_PIXMAP_BIT,
EGL_NONE,
};
EGLint num_configs;
if (!eglChooseConfig(dpy.egl,
egl_config_attribs,
&config.egl, 1,
&num_configs)) {
abort();
}
if (num_configs == 0) {
abort();
}
XVisualInfo x11_visual_info_template;
if (!eglGetConfigAttrib(dpy.egl,
config.egl,
EGL_NATIVE_VISUAL_ID,
(EGLint*) &x11_visual_info_template.visualid)) {
abort();
}
int num_visuals;
config.x11 = XGetVisualInfo(dpy.x11,
VisualIDMask,
&x11_visual_info_template,
&num_visuals);
if (!config.x11) {
abort();
}
config.colormap = XCreateColormap(dpy.x11,
RootWindow(dpy.x11, 0),
config.x11->visual,
AllocNone);
if (config.colormap == None) {
abort();
}
return config;
}
static struct my_window
get_window(struct my_config config)
{
XSetWindowAttributes attr;
unsigned long mask;
struct my_window window = {
.config = config,
};
attr.colormap = config.colormap;
mask = CWColormap;
window.x11 = XCreateWindow(config.dpy.x11,
DefaultRootWindow(config.dpy.x11), // parent
0, 0, // x, y
256, 256, // width, height
0, // border_width
config.x11->depth,
InputOutput, // class
config.x11->visual,
mask, // valuemask
&attr); // attributes
if (!window.x11) {
abort();
}
#ifdef USE_EGL_EXT_PLATFORM_X11
window.egl = eglCreatePlatformWindowSurfaceEXT(config.dpy.egl,
config.egl,
&window.x11,
NULL);
#else
window.egl = eglCreateWindowSurface(config.dpy.egl,
config.egl,
window.x11,
NULL);
#endif
if (window.egl == EGL_NO_SURFACE) {
abort();
}
return window;
}
static struct my_pixmap
get_pixmap(struct my_config config)
{
struct my_pixmap pixmap = {
.config = config,
};
pixmap.x11 = XCreatePixmap(config.dpy.x11,
DefaultRootWindow(config.dpy.x11),
256, 256, // width, height
config.x11->depth);
if (!pixmap.x11) {
abort();
}
#ifdef USE_EGL_EXT_PLATFORM_X11
pixmap.egl = eglCreatePlatformPixmapSurfaceEXT(config.dpy.egl,
config.egl,
&pixmap.x11,
NULL);
#else
pixmap.egl = eglCreatePixmapSurface(config.dpy.egl,
config.egl,
pixmap.x11,
NULL);
#endif
if (pixmap.egl == EGL_NO_SURFACE) {
abort();
}
return pixmap;
}
int
main(void)
{
check_extensions();
struct my_display dpy = get_display();
struct my_config config = get_config(dpy);
struct my_window window = get_window(config);
struct my_pixmap pixmap = get_pixmap(config);
return 0;
}
Revision History
Version 13, 2014-03-10 (Chad Versace)
- Update text to reflect resolution of issue #1. State that
<native_display> may be EGL_DEFAULT_DISPLAY.
- Explain in more detail how EGL connects to the default X11 display.
- Add and resolve issue #2.
Version 12, 2014-02-11 (Chad Versace)
- Fix 2nd argument to XCreatePixmap in example code.
Version 11, 2013-07-10 (Jon Leech)
- Fix enumerant values and assign extension number for publication
(Bug 10240).
Version 10, 2013-07-03 (Chad Versace)
- Add "Extension Type" section, required by EGL_EXT_client_extensions v9.
Version 9, 2013-06-11 (Chad Versace)
- Replace reference to version 5 of EGL_EXT_platform_base to version 7.
- Add James Jones as contributor.
Version 8, 2013-06-07 (Chad Versace)
- Assign enum values to new tokens.
Version 7, 2013-06-07 (Chad Versace)
- Explicitly require EGL_EXT_client_extensions in the Dependencies
section.
Version 6, 2013-06-07 (Chad Versace)
- Add attribute EGL_PLATFORM_X11_SCREEN_EXT.
Version 5, 2013-06-07 (Chad Versace)
- Rephrase against version 7 of EGL_EXT_platform_base.
Version 4, 2013-06-07 (Chad Versace)
- Fix compilation of example code.
Version 3, 2013-04-26 (Chad Versace)
- Add missing EXT suffix to new token.
Version 2, 2013-04-22 (Chad Versace)
- Discuss EGL_DEFAULT_DISPLAY.
- Fix minor typographical and grammatical errors.
Version 1, 2013.03.24 (Chad Versace)
- First draft
extensions/EXT/EGL_EXT_platform_xcb.txt
+382
View File
@@ -0,0 +1,382 @@
Name
EXT_platform_xcb
Name Strings
EGL_EXT_platform_xcb
Contributors
Yuxuan Shui <yshuiv7@gmail.com>
Contacts
Yuxuan Shui <yshuiv7@gmail.com>
Status
Complete
Version
Version 1, 2020-08-28
Number
EGL Extension #141
Extension Type
EGL client extension
Dependencies
Requires EGL_EXT_client_extensions to query its existence without
a display.
Requires EGL_EXT_platform_base.
This extension is written against the wording of version 9 of the
EGL_EXT_platform_base specification.
Overview
This extension defines how to create EGL resources from native X11
resources using the functions defined by EGL_EXT_platform_base.
The native X11 resources required by this extension are xcb resources.
All X11 types discussed here are defined by the header `xcb.h`.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted as the <platform> argument of eglGetPlatformDisplayEXT:
EGL_PLATFORM_XCB_EXT 0x31DC
Accepted as an attribute name in the <attrib_list> argument of
eglGetPlatformDisplayEXT:
EGL_PLATFORM_XCB_SCREEN_EXT 0x31DE
Additions to the EGL Specification
None.
New Behavior
To determine if the EGL implementation supports this extension, clients
should query the EGL_EXTENSIONS string of EGL_NO_DISPLAY.
This extension defines the same set of behaviors as EGL_EXT_platform_x11,
except Xlib types are replaced with xcb types.
To obtain an EGLDisplay backed by an X11 screen, call
eglGetPlatformDisplayEXT with <platform> set to EGL_PLATFORM_XCB_EXT. The
<native_display> parameter specifies the X11 display connection to use, and
must point to a valid xcb `xcb_connection_t` or be EGL_DEFAULT_DISPLAY. If
<native_display> is EGL_DEFAULT_DISPLAY, then EGL will create [1] a
connection to the default X11 display. The environment variable DISPLAY
determines the default X11 display, and, unless overridden by the
EGL_PLATFORM_XCB_SCREEN_EXT attribute, the default X11 screen - as
described in the documentation of `xcb_connect`. If the environment
variable DISPLAY is not present in this case, the result is undefined. The
value of attribute EGL_PLATFORM_XCB_SCREEN_EXT specifies the X11 screen to
use. If the attribute is omitted from <attrib_list>, and <native_display>
is not EGL_DEFAULT_DISPLAY, then screen 0 will be used. Otherwise, the
attribute's value must be a valid screen on the display connection. If the
attribute's value is not a valid screen, then an EGL_BAD_ATTRIBUTE error is
generated.
[fn1] The method by which EGL creates a connection to the default X11
display is an internal implementation detail. The implementation may use
xcb_connect, or any other method.
To obtain an on-screen rendering surface from an X11 Window, call
eglCreatePlatformWindowSurfaceEXT with a <dpy> that belongs to X11 and
a <native_window> that points to an xcb_window_t.
To obtain an offscreen rendering surface from an X11 Pixmap, call
eglCreatePlatformPixmapSurfaceEXT with a <dpy> that belongs to X11 and
a <native_pixmap> that points to an xcb_pixmap_t.
Issues
1. As xcb_connection_t doesn't carry a screen number, how should a screen be
selected in eglGetPlatformDisplayEXT()?
RESOLVED. The screen will be chosen with the following logic:
* If EGL_PLATFORM_XCB_SCREEN_EXT is specified, it will always take
precedence. Whether <native_display> is EGL_DEFAULT_DISPLAY or not.
* Otherwise, if <native_display> is not EGL_DEFAULT_DISPLAY, then
screen 0 will be used.
* Otherwise, which is to say <native_display> is EGL_DEFAULT_DISPLAY.
Then the DISPLAY environment variable will be used to determine the
screen number. If DISPLAY contains a screen number, that will be
used; if not, then 0 will be used.
* If the DISPLAY environment variable is not present when
<native_display> is EGL_DEFAULT_DISPLAY, the result will be undefined.
Example Code
// This example program creates two EGL surfaces: one from an X11 Window
// and the other from an X11 Pixmap.
//
// Compile with `cc example.c -lxcb -lEGL`.
#include <stddef.h>
#include <stdlib.h>
#include <string.h>
#include <EGL/egl.h>
#include <EGL/eglext.h>
#include <xcb/xcb.h>
struct my_display {
xcb_connection_t *x11;
int screen;
int root_of_screen;
EGLDisplay egl;
};
struct my_config {
struct my_display dpy;
xcb_colormap_t colormap;
xcb_visualid_t visualid;
int depth;
EGLConfig egl;
};
struct my_window {
struct my_config config;
xcb_window_t x11;
EGLSurface egl;
};
struct my_pixmap {
struct my_config config;
xcb_pixmap_t x11;
EGLSurface egl;
};
static void check_extensions(void) {
const char *client_extensions =
eglQueryString(EGL_NO_DISPLAY, EGL_EXTENSIONS);
if (!client_extensions) {
// EGL_EXT_client_extensions is unsupported.
abort();
}
if (!strstr(client_extensions, "EGL_EXT_platform_xcb")) {
abort();
}
}
xcb_screen_t *get_screen(xcb_connection_t *c, int screen) {
xcb_screen_iterator_t iter;
iter = xcb_setup_roots_iterator(xcb_get_setup(c));
for (; iter.rem; --screen, xcb_screen_next(&iter))
if (screen == 0)
return iter.data;
return NULL;
}
int get_visual_depth(xcb_connection_t *c, xcb_visualid_t visual) {
const xcb_setup_t *setup = xcb_get_setup(c);
for (xcb_screen_iterator_t i = xcb_setup_roots_iterator(setup); i.rem;
xcb_screen_next(&i)) {
for (xcb_depth_iterator_t j =
xcb_screen_allowed_depths_iterator(i.data);
j.rem; xcb_depth_next(&j)) {
const int len = xcb_depth_visuals_length(j.data);
const xcb_visualtype_t *visuals = xcb_depth_visuals(j.data);
for (int k = 0; k < len; k++) {
if (visual == visuals[k].visual_id) {
return j.data->depth;
}
}
}
}
abort();
}
static struct my_display get_display(void) {
struct my_display dpy;
dpy.x11 = xcb_connect(NULL, &dpy.screen);
if (!dpy.x11) {
abort();
}
dpy.egl = eglGetPlatformDisplayEXT(EGL_PLATFORM_XCB_EXT, dpy.x11,
(const EGLint[]){
EGL_PLATFORM_XCB_SCREEN_EXT,
dpy.screen,
EGL_NONE,
});
if (dpy.egl == EGL_NO_DISPLAY) {
abort();
}
EGLint major, minor;
if (!eglInitialize(dpy.egl, &major, &minor)) {
abort();
}
xcb_screen_t *screen = get_screen(dpy.x11, dpy.screen);
dpy.root_of_screen = screen->root;
return dpy;
}
static struct my_config get_config(struct my_display dpy) {
struct my_config config = {
.dpy = dpy,
};
EGLint egl_config_attribs[] = {
EGL_BUFFER_SIZE,
32,
EGL_RED_SIZE,
8,
EGL_GREEN_SIZE,
8,
EGL_BLUE_SIZE,
8,
EGL_ALPHA_SIZE,
8,
EGL_DEPTH_SIZE,
EGL_DONT_CARE,
EGL_STENCIL_SIZE,
EGL_DONT_CARE,
EGL_RENDERABLE_TYPE,
EGL_OPENGL_ES2_BIT,
EGL_SURFACE_TYPE,
EGL_WINDOW_BIT | EGL_PIXMAP_BIT,
EGL_NONE,
};
EGLint num_configs;
if (!eglChooseConfig(dpy.egl, egl_config_attribs, &config.egl, 1,
&num_configs)) {
abort();
}
if (num_configs == 0) {
abort();
}
if (!eglGetConfigAttrib(dpy.egl, config.egl, EGL_NATIVE_VISUAL_ID,
(EGLint *)&config.visualid)) {
abort();
}
config.colormap = xcb_generate_id(dpy.x11);
if (xcb_request_check(dpy.x11,
xcb_create_colormap_checked(
dpy.x11, XCB_COLORMAP_ALLOC_NONE, config.colormap,
dpy.root_of_screen, config.visualid))) {
abort();
}
config.depth = get_visual_depth(dpy.x11, config.visualid);
return config;
}
static struct my_window get_window(struct my_config config) {
xcb_generic_error_t *e;
struct my_window window = {
.config = config,
};
window.x11 = xcb_generate_id(config.dpy.x11);
e = xcb_request_check(
config.dpy.x11,
xcb_create_window_checked(config.dpy.x11, // connection
XCB_COPY_FROM_PARENT, // depth
window.x11, // window id
config.dpy.root_of_screen, // root
0, 0, // x, y
256, 256, // width, height
0, // border_width
XCB_WINDOW_CLASS_INPUT_OUTPUT, // class
config.visualid, // visual
XCB_CW_COLORMAP, // mask
(const int[]){
config.colormap,
XCB_NONE,
}));
if (e) {
abort();
}
window.egl = eglCreatePlatformWindowSurfaceEXT(config.dpy.egl, config.egl,
&window.x11, NULL);
if (window.egl == EGL_NO_SURFACE) {
abort();
}
return window;
}
static struct my_pixmap get_pixmap(struct my_config config) {
struct my_pixmap pixmap = {
.config = config,
};
pixmap.x11 = xcb_generate_id(config.dpy.x11);
if (xcb_request_check(
config.dpy.x11,
xcb_create_pixmap(config.dpy.x11, config.depth, pixmap.x11,
config.dpy.root_of_screen, 256, 256))) {
abort();
}
pixmap.egl = eglCreatePlatformPixmapSurfaceEXT(config.dpy.egl, config.egl,
&pixmap.x11, NULL);
if (pixmap.egl == EGL_NO_SURFACE) {
abort();
}
return pixmap;
}
int main(void) {
check_extensions();
struct my_display dpy = get_display();
struct my_config config = get_config(dpy);
struct my_window window = get_window(config);
struct my_pixmap pixmap = get_pixmap(config);
return 0;
}
Revision History
Version 2, 2020.10.13 (Yuxuan Shui)
- Some wording changes
- Address the question about screen selection
Version 1, 2020.08.28 (Yuxuan Shui)
- First draft
extensions/EXT/EGL_EXT_present_opaque.txt
+118
View File
@@ -0,0 +1,118 @@
Name
EXT_present_opaque
Name Strings
EGL_EXT_present_opaque
Contributors
Eric Engestrom
Contacts
Eric Engestrom (eric 'at' engestrom.ch)
IP Status
No known IP claims.
Status
Complete
Version
#1, August 8, 2021
Number
EGL Extension #146
Extension Type
EGL display extension
Dependencies
Requires EGL 1.4 and EGL_KHR_image_base extension
This extension is written against the wording of the EGL 1.4
specification, and EGL_KHR_image_base version 6.
Overview
This extension adds a new EGL surface attribute EGL_PRESENT_OPAQUE_EXT
to indicate that the surface should be presented as opaque,
disregarding any alpha channel if present.
If surface attribute EGL_PRESENT_OPAQUE_EXT is EGL_TRUE, then the
surface will be presented as opaque.
New Types
None
New Procedures and Functions
None
New Tokens
New EGLSurface attribute name:
EGL_PRESENT_OPAQUE_EXT 0x31DF
Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Surfaces)
Change the second paragraph in section 3.5 on p. 28 (describing
eglCreateWindowSurface):
"Attributes that can be specified in attrib list include EGL_RENDER_BUFFER,
EGL_PRESENT_OPAQUE_EXT, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_FORMAT."
Add the following paragraph in section 3.5 on p. 28 before
"EGL_VG_COLORSPACE specifies the color space used by OpenVG"
(describing eglCreateWindowSurface attrib_list):
"EGL_PRESENT_OPAQUE_EXT specifies the presentation opacity mode
of the window surface. If its value is EGL_TRUE, then the
surface's alpha channel (if any) will be ignored and considered
fully opaque. If its value is EGL_FALSE, then the compositor
doesn't change its behaviour, and considers the surface's alpha
channel the same way as if the extension wasn't implemented. The
default value of EGL_PRESENT_OPAQUE_EXT is EGL_FALSE."
Add to Table 3.5: Queryable surface attributes and types on p. 37
EGL_PRESENT_OPAQUE_EXT boolean Surface presentation opacity mode
Add following the second paragraph in section 3.6 on p. 39 (describing
eglQuerySurface):
"Querying EGL_PRESENT_OPAQUE_EXT returns the presentation
opacity mode of the surface. The presentation opacity mode of
window surfaces is specified in eglCreateWindowSurface. The
presentation opacity mode of pbuffer and pixmap surfaces is
always EGL_FALSE."
Add following after "which must be a valid native pixmap handle." in section 3.9.2 on
p. 53 (describing eglCopyBuffers):
"If attribute EGL_PRESENT_OPAQUE_EXT of surface has value of EGL_TRUE, then
an EGL_BAD_ACCESS error is returned."
Issues
None
Revision History
Version 2, 2021-08-17 (Eric Engestrom)
- Re-worded the compositor's behaviour for EGL_FALSE.
- Marked extension as Complete.
Version 1, 2021-08-08 (Eric Engestrom)
- Initial draft
extensions/EXT/EGL_EXT_protected_content.txt
+315
View File
@@ -0,0 +1,315 @@
Name
EXT_protected_content
Name Strings
EGL_EXT_protected_content
Contributors
Ramesh Viswanathan
Brian Ellis
Colin Sharp
Rajeev Kulkarni
Mohan Maiya
Maurice Ribble
Craig Donner
Jan-Harald Fredriksen
Daniel Koch
Michael Golds
Ray Smith
Contacts
Maurice Ribble (mribble 'at' qti.qualcomm.com)
IP Status
No known IP claims.
Status
Complete.
Version
Version 12, April 14, 2016
Number
EGL Extension #97
Dependencies
Requires EGL 1.4.
Interactions with EGL_KHR_image_base extension.
This extension is written against the wording of the EGL 1.4.
Specification (12/04/2013)
This extension has interactions with EGL_EXT_protected_surface if that
extension is supported. The interactions are described in the main text.
Overview
This extension introduces the concept of protected contexts and protected
resources, specifically surfaces and EGLImages. Applications can choose at
creation time whether a context, surface or EGLImage is protected or not.
A protected context is required to allow the GPU to operate on protected
resources, including protected surfaces and protected EGLImages.
An explanation of undefined behavior in this extension: Several places
in this extension mention undefined behavior can result, which can
include program termination. The reason for this is because one way
to handle protected content is by using a protected virtual to physical
memory translation layer. With this sort of solution a system may generate
read or write faults when a non-protected source tries to access a protected
buffer. Depending on the system these faults might be ignored or they might
cause process termination. This undefined behavior should not include
actually allowing a transfer of data from a protected surface to a
non-protected surface.
New Types
None
New Procedures and Functions
None
New Tokens
New EGLSurface attribute name:
EGL_PROTECTED_CONTENT_EXT 0x32C0
Add a new section 2.7 entitled "Protected Content" at the end of Chapter 2 (EGL
Operation)
"The attribute EGL_PROTECTED_CONTENT_EXT can be applied to EGL contexts,
EGL surfaces and EGLImages. If the attribute EGL_PROTECTED_CONTENT_EXT
is set to EGL_TRUE by the application, then the newly created EGL object
is said to be protected. A protected context is required to allow the
GPU to operate on protected resources, including protected surfaces and
protected EGLImages.
GPU operations are grouped into pipeline stages. Pipeline stages can be
defined to be protected or not protected. Each stage defines
restrictions on whether it can read or write protected and unprotected
resources, as follows:
When a GPU stage is protected, it:
- Can read from protected resources
- Can read from unprotected resources
- Can write to protected resources
- Can NOT write to unprotected resources
When a GPU stage is not protected, it:
- Can NOT read from protected resources
- Can read from unprotected resources
- Can NOT write to protected resources
- Can write to unprotected resources
Any accesses not following these restrictions will result in undefined
behavior.
This extension does not specify which pipeline stages of a protected
context are protected or not. This is left to a client API extension to
define. All stages in a regular (not protected) context are not
protected. However, if EGL_EXT_protected_surface is also supported, a
regular (not protected) context will execute stages where one or more
protected resources is accessed as if it were a protected context.
Note that the protection state of a stage may be left implementation
defined by a client API extension. This means that no guarantees can be
made about whether the stage will be protected or not protected.
Practically this means that the permitted operations for such a stage
are the intersection of the allowed operations for protected and not
protected stages, i.e it:
- Can NOT read from protected resources
- Can read from unprotected resources
- Can NOT write to protected resources
- Can NOT write to unprotected resources
Since this is not a very useful set of operations refer to the client API
extension to see what operations are actually allowed.
This extension does not guarantee the implementation abides by a
system's digital rights management requirements. It must be verified
beyond the existence of this extension that the implementation of this
extension is trustworthy according to the requirements of a content
protection system."
Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Contexts)
Change the fifth paragraph in section 3.7.1 Creating Rendering Contexts:
"attrib list specifies a list of attributes for the context. The
list has the same structure as described for eglChooseConfig.
Attributes that can be specified in attrib list include
EGL_CONTEXT_CLIENT_VERSION and EGL_PROTECTED_CONTENT_EXT. The
EGL_CONTEXT_CLIENT_VERSION attribute may only be specified when
creating a OpenGL ES context (e.g. when the current rendering API is
EGL_OPENGL_ES_API)."
Add the following paragraph in section 3.7.1 on p. 44 before "attrib list
may be NULL or empty (first attribute is EGL_NONE), in which case
attributes assume their default values as described below."
"EGL_PROTECTED_CONTENT_EXT specifies the protected state of the new
context. If its value is EGL_TRUE, then the context is said to be
protected. If its value is EGL_FALSE, then the context is not
protected. See section 2.7 (Protected Content) for more information
about protected contexts.
The default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE."
Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Surfaces)
Change the second paragraph in section 3.5 on p. 28 (describing
eglCreateWindowSurface):
"Attributes that can be specified in attrib list include
EGL_RENDER_BUFFER, EGL_PROTECTED_CONTENT_EXT, EGL_VG_COLORSPACE, and
EGL_VG_ALPHA_FORMAT."
Add the following paragraph in section 3.5 on p. 28 before
"EGL_VG_COLORSPACE specifies the color space used by OpenVG" (describing
eglCreateWindowSurface(attrib_list):
"EGL_PROTECTED_CONTENT_EXT specifies the protected state of the
window surface. If its value is EGL_TRUE, then the surface content
is said to be protected. If its value is EGL_FALSE, then the surface
content is not protected. See section 2.7 (Protected Content) for
more information about protected and non-protected surfaces.
Client APIs will not allow contents of protected surfaces to be
accessed by non-protected contexts in the system (including
non-secure software running on the CPU). Such operations will result
in undefined behavior.
Calling eglSwapBuffers on such a protected surface will succeed, but
the contents may or may not be posted successfully depending on
whether those parts of the pipeline are capable of handling
protected content. Any disallowed operation will fail and result in
undefined behavior.
The default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE."
Additions to EGL_KHR_image_base extension specification
Add to section 2.5.1 Table bbb:
+-----------------------------+-------------------------+---------------+
| Attribute | Description | Default Value |
+-----------------------------+-------------------------+---------------+
| EGL_NONE | Marks the end of the | N/A |
| | attribute-value list | |
| EGL_IMAGE_PRESERVED_KHR | Whether to preserve | EGL_FALSE |
| | pixel data | |
| EGL_PROTECTED_CONTENT_EXT | Content protection | EGL_FALSE |
| | state | |
+-----------------------------+-------------------------+---------------+
Table bbb. Legal attributes for eglCreateImageKHR <attrib_list>
parameter
Add the following paragraph to section 2.5.1 before "Errors" (describing
eglCreateImageKHR):
"If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_TRUE
and the EGLImage sources can be guaranteed to be protected, then the
EGLImage is said to be protected. See section 2.7 (Protected Content)
for more information about protected resources including EGLImages.
If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_FALSE then:
- If EGLImage sources are not protected, the EGLImage is said to be
not protected. See section 2.7 (Protected Content) for more
information about non-protected resources including EGLImages.
- If EGLImage sources are protected then the EGLImage content will
be inaccessible to any client context irrespective of whether the
context is protected or not. Trying to access such an EGLImage's
content will result in undefined behavior."
Add the following to the Errors list in section 2.5.1
"If the value specified in <attrib_list> for EGL_PROTECTED_CONTENT_EXT
is EGL_TRUE, and EGL and its client is unable to make guarantees
regarding the protected state of the EGLImage source, the error
EGL_BAD_ACCESS is generated."
Issues
1) Can a protected context be shared with a non-protected context?
RESOLVED - Yes. The rule that protected surfaces can only be used by
protected contexts still applies. An example use case is where
someone wants to render to unprotected textures within an unprotected
context and then share it with a protected context to be used as a texture.
2) Should all surfaces within a protected context be protected by default?
RESOLVED - No, several implementations have limited amounts of protected
memory, so the API will require opting into protected memory.
3) Can these protected surfaces be used by stages other than fragment
shader stage?
RESOLVED - Some hardware can't handle this so this behavior is undefined
unless there is explicit working in some new spec saying the behavior is
defined. This is put as an issue because this is an EGL extension and
should not be controlling OpenGL functionality.
4) Why is EGL_PROTECTED_CONTENT_EXT flag needed for EGLImages?
RESOLVED - A few reasons for having an explicit flag instead
of inferring the protected status from EGLImage sources -
1) There are multiple EGL image extensions (EGL QCOM image, EGL
android image and so on) that accept buffers from external modules
instead of client resources or allow internally allocated memory.
For these use cases a protected attribute is useful, so we want to
keep this flag.
2) An implementation might have a few non-standard setup steps that
need to be completed before a protected EGL image can be accessed.
This attribute along with a corresponding protected buffer will act
as a signal for the graphics driver to initiate/complete any such
steps.
3) An application creating an image from an external resource may not
be aware of the fact that the resource is protected or may be unable
to access its content. The successful mapping of and access to a
protected buffer through an EGLImage will be predicated on the
buffer being protected, having a protected context and the intent of
the application to access that buffer by passing in EGL_TRUE for the
attribute EGL_PROTECTED_CONTENT_EXT.
Revision History
Rev. Date Author Changes
---- -------- -------- ----------------------------------------------
1 09/24/14 Ramesh Initial draft.
2 11/20/14 Rajeev Second draft.
3 03/07/16 mribble Make EXT and clean up for release.
4 03/10/16 mribble Cleanup.
5 03/18/16 mribble Fix issues brought up by Khronos group.
6 03/24/16 mribble Resolved some small issues found by Jan-Harald.
7 03/25/16 mribble Fix createContext wording.
8 03/30/16 mribble Added issue 5.
9 04/05/16 mribble Added issue 6 and better defined eglImage case.
10 04/08/16 rsmith - Added general section on protected content.
Protected context, surface and image creation now
refer to the general protected content principles.
- Added explicit definition of which stages are
protected, including allowing for the protected
state of a stage to be undefined.
- Formalised interactions with
EGL_EXT_protected_surface.
- Removed references to the GPU protected mode,
including issue 3.
11 04/10/16 mribble Merge and cleanup.
12 04/14/16 Jon Leech Cleanup formatting, reflow paragraphs and
quote additions consistently. Assign extension
number.
extensions/EXT/EGL_EXT_protected_surface.txt
+230
View File
@@ -0,0 +1,230 @@
Name
EXT_protected_surface
Name Strings
EGL_EXT_protected_surface
Contributors
Frido Garritsen, Vivante
Yanjun Zhang, Vivante
Pontus Lidman, Marvell
Jesse Hall, Google
Contacts
Frido Garritsen (frido 'at' vivantecorp.com)
Yanjun Zhang (yzhang 'at' vivantecorp.com)
Notice
Copyright 2013 Vivante Corporation
IP Status
No known IP claims.
Status
Draft
Version
#7, January 20, 2014
Number
EGL Extension #67
Dependencies
Requires EGL 1.4 and EGL_KHR_image_base extension
This extension is written against the wording of the EGL 1.4
Specification (12/04/2013), and EGL_KHR_image_base spec. version 6.
Overview
This extension adds a new EGL surface attribute EGL_PROTECTED_CONTENT_EXT
to indicate if the content in the surface buffer is protected or not.
If surface attribute EGL_PROTECTED_CONTENT_EXT is EGL_TRUE, then the
surface content is only accessible to secure accesses. Any attempt to access
the buffer content non-securely will fail and result in undefined behavior
up to and including program termination. Also, any copy operations from the
protected surface to any non-protected surface by GPU are considered illegal.
New Types
None
New Procedures and Functions
None
New Tokens
New EGLSurface attribute name:
EGL_PROTECTED_CONTENT_EXT 0x32C0
Additions to Chapter 3 of the EGL 1.4 Specification (Rendering Surfaces)
Change the second paragraph in section 3.5 on p. 28 (describing eglCreateWindowSurface):
"Attributes that can be specified in attrib list include EGL_RENDER_BUFFER,
EGL_PROTECTED_CONTENT_EXT, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_FORMAT."
Add the following paragraph in section 3.5 on p. 28 before "EGL_VG_COLORSPACE
specifies the color space used by OpenVG" (describing eglCreateWindowSurface
attrib_list):
"EGL_PROTECTED_CONTENT_EXT specifies the protection state of the window
surface. If its value is EGL_TRUE, then the surface content resides in a
secure memory region. Secure surfaces may be written to by client APIs
using any combination of protected and non-protected input data. EGL and
client APIs will not allow contents of protected surfaces to be accessed
by non-secure devices in the system (including non-secure software
running on the CPU). They will also not allow the contents to be copied
to non-protected surfaces. Copies within a protected surface, or from one
protected surface to another, are allowed. eglSwapBuffers is allowed for
protected surfaces if and only if the window system is able to maintain
the security of the buffer contents. Any disallowed operation will
fail and result in undefined behavior, up to and including program
termination. If EGL_PROTECTED_CONTENT_EXT is EGL_FALSE, then the surface
content can be accessed by secure or non-secure devices and can be copied
to any other surfaces. The definition of secure and non-secure access is
up to the implementation and is out of scope of this specification. The
default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE."
Change the second paragraph in section 3.5 on p. 30 (describing
eglCreatePbufferSurface):
"Attributes that can be specified in attrib list include EGL_WIDTH,
EGL_HEIGHT, EGL_LARGEST_PBUFFER, EGL_TEXTURE_FORMAT, EGL_TEXTURE_TARGET,
EGL_MIPMAP_TEXTURE, EGL_PROTECTED_CONTENT_EXT, EGL_VG_COLORSPACE, and
EGL_VG_ALPHA_FORMAT."
Add following the second paragraph in section 3.5 on p. 31 (describing
eglCreatePbufferSurface attrib_list):
"EGL_PROTECTED_CONTENT_EXT specifies the protection state of the pbuffer
surface. If its value is EGL_TRUE, then the surface content resides in a
secure memory region. Secure surfaces may be written to by client APIs
using any combination of protected and non-protected input data. EGL and
client APIs will not allow contents of protected surfaces to be accessed
by non-secure devices in the system (including non-secure software
running on the CPU). They will also not allow the contents to be copied
to non-protected surfaces. Copies within a protected surface, or from one
protected surface to another, are allowed. Any disallowed operation will
fail and result in undefined behavior, up to and including program
termination. If EGL_PROTECTED_CONTENT_EXT is EGL_FALSE, then the surface
content can be accessed by secure or non-secure devices and can be copied
to any other surfaces. The definition of secure and non-secure access is
up to the implementation and is out of scope of this specification. The
default value of EGL_PROTECTED_CONTENT_EXT is EGL_FALSE."
Add to Table 3.5: Queryable surface attributes and types on p. 37
EGL_PROTECTED_CONTENT_EXT boolean Content protection state
Add following the second paragraph in section 3.6 on p. 39 (describing
eglQuerySurface):
"Querying EGL_PROTECTED_CONTENT_EXT returns the content protection state of
the surface. The protection state of window and pbuffer surfaces is specified
in eglCreateWindowSurface and eglCreatePbufferSurface. The protection state of
pixmap and client buffer (pbuffer) surfaces is always EGL_FALSE."
Add following after "if either draw or read are bound to contexts in another thread,
an EGL_BAD_ACCESS error is generated." in section 3.7.3 p46 (describing eglMakeCurrent
errors):
"If EGL_PROTECTED_CONTENT_EXT attributes of read is EGL_TRUE and
EGL_PROTECTED_CONTENT_EXT attributes of draw is EGL_FALSE, an
EGL_BAD_ACCESS error is generated."
Add following after "which must be a valid native pixmap handle." in section 3.9.2 on
p. 53 (describing eglCopyBuffers):
"If attribute EGL_PROTECTED_CONTENT_EXT of surface has value of EGL_TRUE, then
an EGL_BAD_ACCESS error is returned."
Additions to EGL_KHR_image_base extension specification
Add to section 2.5.1 Table bbb:
+-----------------------------+-------------------------+---------------+
| Attribute | Description | Default Value |
+-----------------------------+-------------------------+---------------+
| EGL_NONE | Marks the end of the | N/A |
| | attribute-value list | |
| EGL_IMAGE_PRESERVED_KHR | Whether to preserve | EGL_FALSE |
| | pixel data | |
| EGL_PROTECTED_CONTENT_EXT | Content protection | EGL_FALSE |
| | state | |
+-----------------------------+-------------------------+---------------+
Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> parameter
Add the following paragraph to section 2.5.1 before "Errors" (describing
eglCreateImageKHR):
"If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_TRUE, then
image content is only accessible by secure devices in the system. A
complete definition of secure device is implementation-specific, but at
minimum a secure device must not expose the contents of a protected image
to non-secure devices or allow contents to be copied to non-protected
regions of memory. If an EGL client API cannot make such guarantees,
attempts to create an EGLImage sibling within that client API will fail
with an API-specific error.
If the value of attribute EGL_PROTECTED_CONTENT_EXT is EGL_FALSE, then the
surface content can be accessed by secure or non-secure devices and can be
copied to any other surfaces."
Issues
1. Should the spec define the behavior of secure and non-secure access?
PROPOSED: No. Different CPU and GPU architectures have different secure access
implementations. The behavior of secure access violation is also different. Some
architectures will take a CPU exeception. On other architectures, reads will get
zeroes and writes will have no effect. This includes DMA transactions. So it is
better to leave the defination of illegal operation behavior out of this
specification.
2. Should the spec enumerate the legal and illegal operations in client APIs
such as OpenGL ES?
PROPOSED: No. Enumerating these is possible, but is likely to get out of date
as new extensions and client API versions are introduced. Better to state the
principles that determine whether an operation is legal or illegal. If a version
of this extension is promoted to KHR or core status, enumerating the legal
operations because there will be a greater expectation that future extensions
will consider interactions. For OpenGL ES 3.0, a non-normative list of examples
would be:
* glReadPixels is illegal when the READ framebuffer is protected,
* glCopyTexImage2D is illegal when the READ framebuffer is protected,
* glCopyTexSubImage2D is illegal when the READ framebuffer is protected, unless
the target texture is a protected pbuffer,
* glBlitFramebuffer is illegal if the READ framebuffer is protected and the
DRAW framebuffer is not protected.
Revision History
Rev. Date Author Changes
---- -------- -------- -------------------------------------------------
7 01/20/14 Jesse Reword PROTECTED_CONTENT descriptions to be more specific
about legality of client API operations. Add issue #2.
6 01/14/14 Yanjun Change the extension from vendor specific to EXT. Add
EGL_BAD_ACCESS error to eglMakeCurrent, eglCopyBuffers.
5 01/13/14 Jesse Define illegal operation behavior more broadly.
4 01/10/14 Pontus Update description of illegal operation behavior in
terms of secure memory region and secure access.
3 01/03/14 Yanjun Define the GPU and CPU behavior for illegal operations.
2 12/13/13 Yanjun Prohibit GPU illegal copy from the protected surface to
non-protected surface.
1 12/11/13 Yanjun Initial draft.
extensions/EXT/EGL_EXT_stream_consumer_egloutput.txt
+248
View File
@@ -0,0 +1,248 @@
Name
EXT_stream_consumer_egloutput
Name Strings
EGL_EXT_stream_consumer_egloutput
Contributors
Daniel Kartch
James Jones
Christopher James Halse Rogers
Contacts
Daniel Kartch, NVIDIA (dkartch 'at' nvidia.com)
Status
Complete
Version
Version 7 - December 28th, 2015
Number
EGL Extension #81
Extension Type
EGL display extension
Dependencies
Requires EGL_KHR_stream.
Requires EGL_EXT_output_base.
Overview
Increasingly, EGL and its client APIs are being used in place of
"native" rendering APIs to implement the basic graphics
functionality of native windowing systems. This creates demand
for a method to initialize EGL displays and surfaces directly on
top of native GPU or device objects rather than native window
system objects. The mechanics of enumerating the underlying
native devices and constructing EGL displays and surfaces from
them have been solved in various platform and implementation-
specific ways. The EGL device family of extensions offers a
standardized framework for bootstrapping EGL without the use of
any underlying "native" APIs or functionality.
This extension describes how to bind EGLOutputLayerEXTs as stream
consumers to send rendering directly to a display device without an
intervening window system.
New Types
None
New Functions
EGLBoolean eglStreamConsumerOutputEXT(
EGLDisplay dpy,
EGLStreamKHR stream,
EGLOutputLayerEXT layer);
New Tokens
None
Replace section "3.10.2.1 No way to connect consumer to EGLStream" in
the EGL_KHR_stream extension with:
3.10.2.1 EGLOutputLayerEXT consumer
Call
EGLBoolean eglStreamConsumerOutputEXT(
EGLDisplay dpy,
EGLStreamKHR stream,
EGLOutputLayerEXT layer);
to connect <output> as the consumer of <stream>.
On failure EGL_FALSE is returned and an error is generated.
- EGL_BAD_DISPLAY is generated if <dpy> is not a valid,
initialized EGLDisplay.
- EGL_BAD_STREAM_KHR is generated if <stream> is not a valid
EGLStreamKHR created for <dpy>.
- EGL_BAD_STATE_KHR is generated if <stream> is not in state
EGL_STREAM_STATE_CREATED_KHR.
- EGL_BAD_OUTPUT_LAYER_EXT is generated if <layer> is not a
valid EGLOutputLayerEXT created for <dpy>.
On success, <layer> is bound to <stream>, <stream> is placed in the
EGL_STREAM_STATE_CONNECTING_KHR state, and EGL_TRUE is returned.
Initially, no changes occur to the image displayed on <layer>. When
the <stream> enters state EGL_STREAM_STATE_NEW_FRAME_AVAILABLE_KHR,
<layer> will begin displaying frames, without further action
required on the application's part, as they become available, taking
into account any timestamps, swap intervals, or other limitations
imposed by the stream or producer attributes.
Modifying the output layer's display mode is outside the scope of
EGL. If the producer does not automatically adjust it's dimensions
to match the consumer, then the caller is responsible for ensuring
that the producer's frame size and the display mode are compatible
before the first frame is placed in the stream. If these are not
compatible, the behavior is implementation dependent, but may not
hang or terminate. Among other possible behaviors, the
implementation may scale or letterbox the frames, post a blank image
to the display, or discard the frames without posting.
Many display mode setting APIs have a mechanism that restricts
which of their clients can modify output attributes. Since
EGLOutput stream consumers will need to modify output attributes,
they require access to a display mode setting API handle with the
appropriate capabilities. If the application fails to provide
access to such permissions or privileged native objects when creating
the EGLDisplay associated with an output stream consumer and EGL is
not able to acquire them, the behavior of the stream consumer will be
undefined. Similarly, if the application or operating system revokes
the output modification permissions provided to the EGLDisplay, or
revokes permissions from the privileged native objects provided to
the EGLDisplay, future behavior of the stream consumer is undefined.
If <layer> is rebound to a different stream by a subsequent call
to eglStreamConumerOutputEXT, then <stream> will be placed into the
EGL_STREAM_STATE_DISCONNECTED_KHR state.
Issues
1. What happens to the display if the stream is destroyed while
still connected?
RESOLVED: The EGLOutputLayer will maintain a reference to the
last frame consumed from the stream until a new frame is
received (through connection of a new stream or some interface
defined by another extension) or until the EGLOutputLayer is
destroyed. Until one of these occurs, the output will ensure
that memory containing the frame remains valid, but will do no
further reprogramming of the display layer state. In the event
the EGLOutputLayer is destroyed, the reference to the frame is
released, and random/invalid images may subsequently be
displayed if the application does not take separate action to
reprogram or disable the display. This behavior should
probably be defined in the EGL_EXT_output_base extension and
be shared regardless of the means by which the displayed image
was posted.
2. What happens to the stream if the display output is flipped to a
different image by a mechanism outside EGL?
RESOLVED: Using native display APIs to directly change the
visible framebuffer while an EGLStream is bound to an
EGLOutputLayer has undefined results which depend on the
implementation, the display capabilities, and the
compatibility of the competing framebuffer sizes and formats.
A partial list of possible outcomes includes one interface
overriding the other, the visible image alternating between
the two frames, or the visible image becoming corrupted or
displaying random memory.
3. What happens if the display mode settings are not compatible
with the size and/or format of the incoming frames?
RESOLVED: The behavior is implementation and device dependent.
The display may not terminate or hang, but otherwise may modify
or ignore the incoming frames. Additional extensions can be
defined if greater control of this behavior is desired.
4. How can changes to the display mode settings be synchronized
with changes in the size/format of frames generated by the
producer?
RESOLVED: The base specification will assume that the
producer's frame size and the output layer's display mode are
established at initialization time and do not change for the
life of the stream. The ability to modify these states and
synchronize such modifications must be provided by additional
extensions.
5. The EGL_KHR_stream_producer_eglsurface extension, which is
likely to be used as a producer for streams directed to outputs,
explicitly ignores eglSwapInterval. But a swap interval is
desirable when directing output to a display screen. How can
this functionality be provided?
RESOLVED: EGL_SWAP_INTERVAL_EXT added as an attribute to output
layers in the EGL_EXT_output_base specification.
6. How does EGL acquire the necessary capabilities to modify
display attributes from the application?
RESOLVED: The application provides EGL with the necessary
permissions or native object handles when creating its EGLDisplay.
7. What is the behavior of EGLOutput stream consumers when EGL does
not have the necessary permissions to modify output attributes?
RESOLVED: The behavior is undefined. Other options would be to
block consumption of frames indefinitely until permissions are
acquired via unspecified or native mechanisms, or to return
frames to the producer immediately when consumption fails due to
lack of permissions. However, both of these options may rely on
assumptions about the behavior of the underlying mode setting
APIs. Future extensions may refined the behavior of streams in
this case.
Revision History:
#7 (December 28th, 2015) James Jones
- Added issues 6 and 7.
- Added language to document the resolution of issues 6 and 7.
#6 (August 22nd, 2014) James Jones
- Marked complete.
- Marked remaining unresolved issues resolved.
- Added an "Extension Type" section.
- Listed Daniel as the contact.
#5 (June 5th, 2014) Daniel Kartch
- Added resolution for issues 3 and 4 and updated description
accordingly.
#4 (May 28th, 2014) Daniel Kartch
- Added Issue 5 and its resolution.
#3 (January 17th, 2014) Daniel Kartch
- Updated issues section with some proposed solutions and new
issues.
#2 (November 13th, 2013) Daniel Kartch
- Replaced EGLOutputEXT with EGLOutputLayerEXT, as per changes
to EXT_output_base.
- Updated possible error states to reflect requirement that
output handles are now associated with a particular
EGLDisplay.
#1 (October 28th, 2013) Daniel Kartch
- Initial draft
extensions/EXT/EGL_EXT_surface_CTA861_3_metadata.txt
+136
View File
@@ -0,0 +1,136 @@
Name
EXT_surface_CTA861_3_metadata
Name Strings
EGL_EXT_surface_CTA861_3_metadata
Contact
Courtney Goeltzenleuchter (courtneygo 'at' google.com)
Contributors
James Jones
Weiwan Liu
IP Status
No known IP claims.
Status
Complete
Version
Version 5 - Nov 29, 2016
Number
EGL Extension #117
Dependencies
This extension requires EGL 1.5 and EGL_EXT_surface_SMPTE2086_metadata.
This extension is written against the wording of the EGL 1.5 specification
(August 27, 2014).
Overview
This extension adds additional EGL surface attributes for the metadata
defined by the CTA (Consumer Technology Association) 861.3 standard.
This metadata, in addition to the SMPTE 2086 metadata, is used to define the
color volume of the mastering display as well as the content (CTA-861.3),
The mastering display is the display where creative work is done and creative
intent is established. To preserve such creative intent as much as possible
and achieve consistent color reproduction on different viewing displays,
it is useful for the display pipeline to know the color volume of the
original mastering display where content is created or tuned. This avoids
performing unnecessary mapping of colors that are not displayable on the
original mastering display.
This extension adds the ability to pass the CTA-861.3 metadata via EGL,
from which the color volume can be derived. While the general purpose of the
metadata is to assist in the transformation between different color volumes
of different displays and help achieve better color reproduction, it is not
in the scope of this extension to define how exactly the metadata should be
used in such a process. It is up to the implementation to determine how to
make use of the metadata.
New Procedures and Functions
None.
New Tokens
Accepted as attribute by eglSurfaceAttrib and eglQuerySurface:
EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT 0x3360
EGL_CTA861_3_MAX_FRAME_AVERAGE_LEVEL_EXT 0x3361
Additions to Chapter "3.5.6 Surface Attributes" of the EGL 1.5 Specification
Add the following paragraph before the "Errors" section on page 43,
If attribute is EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT or EGL_CTA861_3_-
MAX_FRAME_AVERAGE_LEVEL_EXT, then value indicates the corresponding
maximum content light level and maximum frame average level.
The unit of value is 1 nit (candela per square meter). The
floating-point luminance values should be multiplied by
EGL_METADATA_SCALING, a constant scaling factor of 50000, before being
passed into eglSurfaceAttrib as integers.
Exactly how the color volume information is used to assist the color
reproduction process is implementation dependant.
The initial values of EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT and
EGL_CTA861_3_MAX_FRAME_AVERAGE_LEVEL_EXT are EGL_DONT_CARE, which causes the
hints to be ignored. If value is not in the implementation's supported
range for attribute, a EGL_INVALID_VALUE error is generated, and some or
all of the metadata fields are ignored.
Change the original footnote 12 at the end of section "3.5.6 Surface
Attributes" on page 45 to,
[13] EGL_DISPLAY_SCALING (10000) and EGL_METADATA_SCALING_EXT (50000)
are used where EGL needs to take or return floating-point attribute
values, which would normally be smaller than 1, as integers while still
retaining sufficient precision to be meaningful.
Addition to Table 3.5 "Queryable surface attributes and types",
Attribute Type
------------------------------------------------
EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT integer
EGL_CTA861_3_MAX_FRAME_AVERAGE_LEVEL_EXT integer
Description
--------------------------------------------------------------------------------------
Maximum content light level in nit multiplied by EGL_METADATA_SCALING_EXT
Maximum frame average light level in nit multiplied by EGL_METADATA_SCALING_EXT
Add the following paragraph at the end of section "3.5.6 Surface Attributes"
on page 45,
Querying EGL_CTA861_3_MAX_CONTENT_LIGHT_LEVEL_EXT EGL_CTA861_3_MAX_-
FRAME_AVERAGE_LEVEL_EXT returns respectively the maximum content light level
and maximum frame average level respectively. The values returned are
in units of 1 nit (candela per square meter), multiplied by the constant
value EGL_METADATA_SCALING_EXT (50000). The value of EGL_CTA861_3_MAX_-
CONTENT_LIGHT_LEVEL_EXT and EGL_CTA861_3_MAX_FRAME_AVERAGE_LEVEL_EXT can
be set via eglSurfaceAttrib as described above.
Errors
Described in the body text above.
Issues
Revision History
Version 1, 2017/02/28
- Initial draft
extensions/EXT/EGL_EXT_surface_SMPTE2086_metadata.txt
+247
View File
@@ -0,0 +1,247 @@
Name
EXT_surface_SMPTE2086_metadata
Name Strings
EGL_EXT_surface_SMPTE2086_metadata
Contact
Weiwan Liu (weiwliu 'at' nvidia.com)
Contributors
Tom Cooksey
Courtney Goeltzenleuchter
Mathias Heyer
Lauri Hyvarinen
James Jones
Daniel Koch
Jeff Leger
Sandeep Shinde
IP Status
No known IP claims.
Status
Complete
Version
Version 8 - Oct 16, 2017
Number
EGL Extension #109
Dependencies
This extension requires EGL 1.4.
This extension is written against the wording of the EGL 1.5 specification
(August 27, 2014).
Overview
This extension adds a new set of EGL surface attributes for the metadata
defined by the SMPTE (the Society of Motion Picture and Television
Engineers) ST 2086 standard. The SMPTE 2086 metadata includes the color
primaries, white point and luminance range of the mastering display, which
all together define the color volume that contains all the possible colors
the mastering display can produce. The mastering display is the display
where creative work is done and creative intent is established. To preserve
such creative intent as much as possible and achieve consistent color
reproduction on different viewing displays, it is useful for the display
pipeline to know the color volume of the original mastering display where
content is created or tuned. This avoids performing unnecessary mapping of
colors that are not displayable on the original mastering display.
This extension adds the ability to pass the SMPTE 2086 metadata via EGL,
from which the color volume can be derived. While the general purpose of the
metadata is to assist in the transformation between different color volumes
of different displays and help achieve better color reproduction, it is not
in the scope of this extension to define how exactly the metadata should be
used in such a process. It is up to the implementation to determine how to
make use of the metadata.
New Procedures and Functions
None.
New Tokens
Accepted as attribute by eglSurfaceAttrib and eglQuerySurface:
EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT 0x3341
EGL_SMPTE2086_DISPLAY_PRIMARY_RY_EXT 0x3342
EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT 0x3343
EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT 0x3344
EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT 0x3345
EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT 0x3346
EGL_SMPTE2086_WHITE_POINT_X_EXT 0x3347
EGL_SMPTE2086_WHITE_POINT_Y_EXT 0x3348
EGL_SMPTE2086_MAX_LUMINANCE_EXT 0x3349
EGL_SMPTE2086_MIN_LUMINANCE_EXT 0x334A
Additions to Chapter "3.5.6 Surface Attributes" of the EGL 1.5 Specification
Add the following paragraph before the "Errors" section on page 43,
If attribute is EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_SMPTE2086_-
DISPLAY_PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT, EGL_-
SMPTE2086_DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT
or EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT, then value indicates the
corresponding xy chromaticity coordinate[12] of the mastering display's
red, green or blue color primary, as configured for the mastering
process. The floating-point display primary coordinates should be
multiplied by EGL_METADATA_SCALING_EXT (50000)[13], before being passed
into eglSurfaceAttrib as integers.
If attribute is EGL_SMPTE2086_WHITE_POINT_X_EXT or EGL_SMPTE2086_WHITE_-
POINT_Y_EXT, then value indicates the corresponding xy chromaticity
coordinate[12] of the mastering display's white point, as configured for
the mastering process. The floating-point white point chromaticity
coordinates should be multiplied by EGL_METADATA_SCALING_EXT (50000),
before being passed into eglSurfaceAttrib as integers.
If attribute is EGL_SMPTE2086_MAX_LUMINANCE_EXT or EGL_SMPTE2086_MIN_-
LUMINANCE_EXT, then value indicates the maximum or minimum display
luminance of the mastering display, as configured for the mastering
process. The unit of value is 1 nit (candela per square meter). The
floating-point luminance values should be multiplied by
EGL_METADATA_SCALING_EXT, a constant scaling factor of 50000, before
being passed into eglSurfaceAttrib as integers.
By defining the mastering display's color volume through color
primaries, white point, and luminance range, applications give EGL
and the underlying display pipeline hints as to how to reproduce colors
more closely to the original content when created on the mastering
display. Exactly how the color volume information is used to assist the
color reproduction process is implementation dependant.
The initial values of EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_-
SMPTE2086_DISPLAY_PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT,
EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_-
EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT, EGL_SMPTE2086_WHITE_POINT_X_-
EXT, EGL_SMPTE2086_WHITE_POINT_Y_EXT, EGL_SMPTE2086_MAX_LUMINANCE_EXT
and EGL_SMPTE2086_MIN_LUMINANCE_EXT are EGL_DONT_CARE, which causes the
hints to be ignored. If value is not in the implementation's supported
range for attribute, a EGL_BAD_PARAMETER error is generated, and some or
all of the metadata fields are ignored.
Add the following footnote at the end of page 43, and increment all the
subsequent footnote numbers in Chapter 3,
[12] Chromaticity coordinates x and y are as specified in CIE
15:2004 "Calculation of chromaticity coordinates" (Section 7.3) and are
limited to between 0 and 1 for real colors for the mastering display.
Change the original footnote 12 at the end of section "3.5.6 Surface
Attributes" on page 45 to,
[13] EGL_DISPLAY_SCALING (10000) and EGL_METADATA_SCALING_EXT (50000)
are used where EGL needs to take or return floating-point attribute
values, which would normally be smaller than 1, as integers while still
retaining sufficient precision to be meaningful.
Addition to Table 3.5 "Queryable surface attributes and types",
Attribute Type
------------------------------------------------
EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT integer
EGL_SMPTE2086_DISPLAY_PRIMARY_RY_EXT integer
EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT integer
EGL_SMPTE2086_DISPLAY_PRIMARY_GY_EXT integer
EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT integer
EGL_SMPTE2086_DISPLAY_PRIMARY_BY_EXT integer
EGL_SMPTE2086_WHITE_POINT_X_EXT integer
EGL_SMPTE2086_WHITE_POINT_Y_EXT integer
EGL_SMPTE2086_MAX_LUMINANCE_EXT integer
EGL_SMPTE2086_MIN_LUMINANCE_EXT integer
Description
------------------------------------------------------------------------------------------
x chromaticity coordinate for red display primary multiplied by EGL_METADATA_SCALING_EXT
y chromaticity coordinate for red display primary multiplied by EGL_METADATA_SCALING_EXT
x chromaticity coordinate for green display primary multiplied by EGL_METADATA_SCALING_EXT
y chromaticity coordinate for green display primary multiplied by EGL_METADATA_SCALING_EXT
x chromaticity coordinate for blue display primary multiplied by EGL_METADATA_SCALING_EXT
y chromaticity coordinate for blue display primary multiplied by EGL_METADATA_SCALING_EXT
x chromaticity coordinate for white point multiplied by EGL_METADATA_SCALING_EXT
y chromaticity coordinate for white point multiplied by EGL_METADATA_SCALING_EXT
Maximum luminance in nit multiplied by EGL_METADATA_SCALING_EXT
Minimum luminance in nit multiplied by EGL_METADATA_SCALING_EXT
Add the following paragraph at the end of section "3.5.6 Surface Attributes"
on page 45,
Querying EGL_SMPTE2086_DISPLAY_PRIMARY_RX_EXT, EGL_SMPTE2086_DISPLAY_-
PRIMARY_RY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_GX_EXT, EGL_SMPTE2086_-
DISPLAY_PRIMARY_GY_EXT, EGL_SMPTE2086_DISPLAY_PRIMARY_BX_EXT or EGL_-
SMPTE2086_DISPLAY_PRIMARY_BY_EXT returns respectively the xy
chromaticity coordinate of the mastering display's red, green or blue
color primary, multiplied by the constant value EGL_METADATA_SCALING_EXT
(50000). The display primary coordinates can be set via eglSurfaceAttrib
as described above.
Querying EGL_SMPTE2086_WHITE_POINT_X_EXT, or EGL_SMPTE2086_WHITE_POINT_-
Y_EXT returns respectively the xy chromaticity coordinate of the
mastering display's white point, multiplied by the constant value EGL_-
METADATA_SCALING (50000). The white point coordinates can be set via
eglSurfaceAttrib as described above.
Querying EGL_SMPTE2086_MAX_LUMINANCE_EXT or EGL_SMPTE2086_MIN_-
LUMINANCE_EXT returns respectively the maximum and minimum display
luminance of the mastering display. The values returned are in units of
1 nit (candela per square meter), multiplied by the constant value EGL_-
METADATA_SCALING (50000). The value of EGL_SMPTE2086_MAX_LUMINANCE_EXT
and EGL_SMPTE2086_MIN_LUMINANCE_EXT can be set via eglSurfaceAttrib as
described above.
Errors
Described in the body text above.
Issues
1. Should this extension define a valid data range for each metadata field?
RESOLVED: No. It is not in the scope of this extension to define how the
metadata hints should be used in the display pipeline and, as a result,
what the valid data ranges are for the metadata fields. It is
implementation dependant, but related standards, such as SMPTE ST 2086,
can be used as reference. As described in the body, implemetations may
generate a EGL_BAD_PARAMTER error to notify applications that the input
metadata values are invalid or not supported.
Revision History
Version 1, 2016/04/22
- Initial draft
Version 2, 2016/05/25
- Rename to EXT and introduce a new scaling factor
Version 3, 2016/10/19
- Add an error and revise issue 1
Version 4, 2016/11/22
- Change status to complete
Version 5, 2016/11/29
- Add token assigments
Version 6, 2017/02/28
- Add 'EXT' suffix to 'EGL_METADATA_SCALING'
Version 7, 2017/10/13
- Rename EGL_INVALID_VALUE (which doesn't exist) to EGL_FALSE
Version 8, 2017/10/16
- Fix v7 change to use EGL_BAD_PARAMETER as the error code
generated vs. EGL_FALSE which is the expected return value of
the function.
extensions/EXT/EGL_EXT_swap_buffers_with_damage.txt
+343
View File
@@ -0,0 +1,343 @@
Name
EXT_swap_buffers_with_damage
Name Strings
EGL_EXT_swap_buffers_with_damage
IP Status
No known IP claims.
Contributors
Robert Bragg
Tapani Pälli
Kristian Høgsberg
Benjamin Franzke
Ian Stewart
James Jones
Contacts
Robert Bragg, Intel (robert.bragg 'at' intel.com)
Status
Published
Version
Version 11, February 20, 2020
Number
EGL Extension #55
Dependencies
Requires EGL 1.4
This extension is written against the wording of the EGL 1.4
Specification.
Overview
This extension provides a means to issue a swap buffers request to
display the contents of the current back buffer and also specify a
list of damage rectangles that can be passed to a system
compositor so it can minimize how much it has to recompose.
This should be used in situations where an application is only
animating a small portion of a surface since it enables the
compositor to avoid wasting time recomposing parts of the surface
that haven't changed.
New Procedures and Functions
EGLBoolean eglSwapBuffersWithDamageEXT (
EGLDisplay dpy,
EGLSurface surface,
const EGLint *rects,
EGLint n_rects);
New Tokens
None
Changes to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
Add the following text to subsection 3.9.1 titled "Posting to a
Window" after the description of eglSwapBuffers.
As an alternative to eglSwapBuffers use:
EGLBoolean eglSwapBuffersWithDamageEXT (
EGLDisplay dpy,
EGLSurface surface,
const EGLint *rects,
EGLint n_rects);
to do the same thing as eglSwapBuffers but additionally report
a list of rectangles that define the region that has truly
changed since the last frame. To be clear; the entire contents
of the back buffer will still be swapped to the front so
applications using this API must still ensure that the entire
back buffer is consistent. The rectangles are only a hint for
the system compositor so it can avoid recomposing parts of the
surface that haven't really changed.
<rects> points to a list of integers in groups of four that
each describe a rectangle in screen coordinates in this
layout: {x, y, width, height}. The rectangles are specified
relative to the bottom-left of the surface and the x and y
components of each rectangle specify the bottom-left position
of that rectangle. <n_rects> determines how many groups of 4
integers can be read from <rects>. It is not necessary to
avoid overlaps of the specified rectangles.
If <n_rects> is 0 then <rects> is ignored and the entire
surface is implicitly damaged and the behaviour is equivalent
to calling eglSwapBuffers.
The error conditions checked for are the same as for the
eglSwapBuffers api.
Modify the first paragraph of Section 3.9.1 titled "Native Window
Resizing"
"If the native window corresponding to <surface> has been
resized prior to the swap, <surface> must be resized to match.
<surface> will normally be resized by the EGL implementation
at the time the native window is resized. If the
implementation cannot do this transparently to the client,
then eglSwapBuffers and eglSwapBuffersWithDamageEXT must
detect the change and resize surface prior to copying its
pixels to the native window. In this case the meaningfulness
of any damage rectangles forwarded by
eglSwapBuffersWithDamageEXT to the native window system is
undefined."
Modify the following sentences in Section 3.9.3, page 51 (Posting
Semantics)
Paragraph 2, first sentence:
"If <dpy> and <surface> are the display and surface for the
calling thread's current context, eglSwapBuffers,
eglSwapBuffersWithDamageEXT, and eglCopyBuffers perform an
implicit flush operation on the context (glFlush for OpenGL or
OpenGL ES context, vgFlush for an OpenVG context)."
Paragraph 3, first sentence:
"The destination of a posting operation (a visible window, for
eglSwapBuffers or eglSwapBuffersWithDamageEXT, or a native
pixmap, for eglCopyBuffers) should have the same number of
components and component sizes as the color buffer it's being
copied from."
Paragraph 6, first two sentences:
"The function
EGLBoolean eglSwapInterval(EGLDisplay dpy, EGLint
interval);
specifies the minimum number of video frame periods per color
buffer post operation for the window associated with the
current context. The interval takes effect when eglSwapBuffers
or eglSwapBuffersWithDamageEXT is first called subsequent to
the eglSwapInterval call."
Modify the following sentences in Section 3.9.4, page 52 (Posting
Errors)
Paragraph 1, first sentence:
"eglSwapBuffers, eglSwapBuffersWithDamageEXT, and
eglCopyBuffers return EGL_FALSE on failure."
Paragraph 1, seventh sentence:
"If eglSwapBuffers or eglSwapBuffersWithDamageEXT are called
and the native window associated with <surface> is no longer
valid, an EGL_BAD_NATIVE_WINDOW error is generated. If
eglSwapBuffersWithDamageEXT is called and <n_rects>, is less
than zero or <n_rects> is greater than zero but <rects> is
NULL, EGL_BAD_PARAMETER is generated."
Dependencies on OpenGL ES
None
Dependencies on OpenVG
None
Issues
1) Do applications have to make sure the rectangles don't overlap?
RESOLVED: No, that would be inconvenient for applications and we
see no difficulty for implementations to supporting overlapping
rectangles.
2) Would it be valid for an implementation to discard the list of
rectangles internally and work just in terms of the
eglSwapBuffers api?
RESOLVED: Yes, the rectangles are only there for optimization
purposes so although it wouldn't be beneficial to applications if
it was convenient at times then it would be compliant for an
implementation to discard the rectangles and just call
eglSwapBuffers instead. The error conditions that should be
checked for are compatible with the requirements for
eglSwapBuffers.
3) What origin should be used for damage rectangles?
RESOLVED: Bottom left since this is consistent with all other
uses of 2D window coordinates in EGL and OpenGL that specify a
bottom left origin.
Originally this specification was written with a top-left origin
for the damage rectangles even though it was known to be
inconsistent and that was because most window systems use a
top-left origin and there are some awkward semantic details
related to handling native window resizing that we had hoped to
simplify.
This extension and also several other existing EGL extensions
struggle to guarantee a reliable behaviour in response to native
window resizing which can happen asynchronously on some platforms
and this can make it difficult for applications to avoid certain
visual artefacts.
The crux of the problem is that when a native window is
asynchronously resized then the window system may maintain the old
buffer contents with respect to a different origin than EGL's
bottom left origin. For this extension that means that EGL damage
rectangles that are intended to map to specific surface contents
may end up mapping to different contents when a native window is
resized because the rectangles and buffer contents will be moved in
different directions in relation to the new window size.
In the end we decided that this issue isn't simply solved by
choosing to use a top-left origin and so we can instead aim for
consistency and clarify what guarantees we offer in relation to
native window resizing separate from this issue.
4) What guarantees do we provide about the meaningfulness of EGL
damage rectangles that are forwarded to the native window system
when presenting to a native window that has been resized?
RESOLVED: The meaningfulness of those forwarded damage rectangles
is undefined since this simplifies the implementation requirements
and we saw very little benefit to applications from providing
stricter guarantees.
The number of applications that would be able to avoid fully
redrawing the contents of a window in response to a window resize
is expected to be so low that there would be almost no benefit to
defining strict guarantees here.
Since EGL already states that the contents of window surface
buffers become undefined when a native window has been resized,
this limitation doesn't introduce any new issue for applications
to consider. Applications should already fully redraw buffer
contents in response to a native window resize, unless they are
following some platform specific documentation that provides
additional guarantees.
For an example of the implementation details that make this an
awkward issue to provide guarantees for we can consider X11 based
platforms where native windows can be resized asynchronously with
respect to a client side EGL surface:
With X11 there may be multiple "gravity" transformations that can
affect how surface buffer content is positioned with respect to a
new native window size; there is the core X "bit gravity" and
there is the EGL driver gravity that determines how a surface's
contents with one size should be mapped to a native window with a
different size. Without very careful cooperation between the EGL
driver and the core X implementation and without the right
architecture to be able to do transforms atomically with respect
to different clients that may enact a window resize then it is not
possible to reliably map EGL damage rectangles to native window
coordinates.
The disadvantage of a driver that is not able to reliably map EGL
damage rectangles to native window coordinates is that a native
compositor may re-compose the wrong region of window. This may
result in a temporary artefact until the full window gets redrawn
and then re-composed. X11 already suffers other similar transient
artefacts when resizing windows.
The authors of this spec believe that even if a driver can't do
reliable mappings of EGL damage rectangles then compositors would
be able mitigate the majority of related artefacts by ignoring
sub-window damage during an interactive window resize.
The authors of this spec believe that that if an X11 driver did
want to reliably map EGL damage rectangles to the native window
coordinates then that may be technically feasible depending on the
driver architecture. For reference one approach that had been
considered (but not tested) is as follows:
1) When eglSwapBuffersWithDamageEXT is called, send EGL damage
rectangles from the client to a driver component within the
xserver un-transformed in EGL window surface coordinates with a
bottom-left origin.
2) Within the X server the driver component should look at the
bit-gravity of a window and use the bit-gravity convention to
copy EGL surface content to the front-buffer of a native window.
3) Within the X server the driver component should use the same
gravity transform that was used to present the surface content
to also transform the EGL damage rectangle coordinates.
Note that because this transform is done in the xserver then
this is implicitly synchronized with all clients that would
otherwise be able to enact an asynchronous window resize.
Revision History
Version 1, 29/07/2011
- First draft
Version 2, 03/08/2011
- Clarify that the rectangles passed may overlap
Version 3, 01/09/2011
- Fix a missing '*' in prototype to make rects a pointer
Version 4, 11,02,2012
- Clarify that implementing in terms of eglSwapBuffers would be
compliant.
Version 5, 11,02,2012
- Tweak the cases where we report BAD_PARAMETER errors
Version 6, 05/02/2013
- Specify more thorough updates across the EGL 1.4 spec
wherever it relates to the eglSwapBuffers api
- Clarify that passing <n_rects> of 0 behaves as if
eglSwapBuffers were called.
Version 7, 14/02/2013
- Specify that a bottom-left origin should be used for rectangles
Version 8, 19/03/2013
- Add Ian and James as contributors
- Add an issue explaining why we changed to a bottom-left origin
- Clarify that the behaviour is undefined when presenting to a
native window that has been resized.
- Document the awkward details that would be involved in
providing more strict guarantees when presenting to a native
window that has been resized.
Version 9, 12/06/2013, Chad Versace <chad.versace@intel.com>
- Remove the "all rights reserved" clause from the copyright notice. The
removal does not change the copyright notice's semantics, since the
clause is already implied by any unadorned copyright notice. But, the
removal does diminish the likelihood of unwarranted caution in readers
of the spec.
- Add "IP Status" section to explicitly state that this extension has no
knonw IP claims.
Version 10, 23/10/2014, Jon Leech
- Remove copyright after signoff from Intel.
Version 11, 20/02/2020, Jon Leech
- Constify rects parameter (EGL-Registry issue 98).
extensions/EXT/EGL_EXT_sync_reuse.txt
+376
View File
@@ -0,0 +1,376 @@
Name
EXT_sync_reuse
Name Strings
EGL_EXT_sync_reuse
Contributors
Daniel Kartch
Jeff Vigil
Ray Smith
Contacts
Daniel Kartch, NVIDIA Corporation (dkartch 'at' nvidia.com)
Status
Complete
Version
Version 4, May 16, 2018
Number
EGL Extension #128
Extension type
EGL display extension
Dependencies
Requires EGL 1.5 or EGL 1.4 with EGL_KHR_fence_sync
Interacts with EGL_KHR_reusable_sync
Interacts with EGL_ANDROID_native_fence_sync
Interacts with EGL_NV_cuda_event
This extension is written against the wording of the EGL 1.5
Specification.
Overview
The original EGLSync extensions separated sync objects into two
types: fence sync objects signaled by one time events in an
API command pipeline; and reusable sync objects signaled by commands
which can be issued again and again. However, this conflates
reusability of the event triggering a sync object with the EGLSync
object itself.
Although the event associated with a fence sync object will only
occur once, there is no reason that it can't be replaced with a new
event. Doing so would avoid unnecessary allocation and free
operations in an application that repeatedly waits for events. With
the current interfaces, such applications must constantly create and
destroy new EGLSync objects.
This extension allows all sync objects to be reusable. When a sync
object is in the signaled state, it can be reset back to an
unsignaled state, regenerating or reevaluating the events that
trigger them. For fence sync objects, this means generating a new
fence in the current API. For OpenCL event sync objects, this means
waiting for a new OpenCL event handle. This mechanism also allows
sync objects to be created in the signaled state with no associated
fence/event, and have one applied later. Thus all EGLSyncs required
by an application can be allocated up front, before any rendering
operations have begun.
New Types
None
New Tokens
None
New Procedures and Functions
EGLBoolean eglUnsignalSyncEXT(
EGLDisplay dpy,
EGLSync sync,
const EGLAttrib *attrib_list);
Replace text of subsections of 3.8.1 through 3.8.1.2 of EGL 1.5
Specification. Existing tables are preserved.
3.8.1 Sync Objects
In addition to the aforementioned synchronization functions, which
provide an efficient means of serializing client and native API
operations within a thread, <sync objects> are provided to enable
synchronization of client API operations between threads and/or
between API contexts. Sync objects may be tested or waited upon by
application threads.
Sync objects have a status with two possible states: <signaled> and
<unsignaled>, and may initially be in either state. EGL may be asked
to wait for a sync object to become signaled, or a sync object’s
status may be queried.
Depending on the type of a sync object, its status may be changed
either by an external event, or by explicitly signaling and/or
unsignaling the sync. All sync objects are reusable. Once they enter
the signaled state, they may be changed back to unsignaled, possibly
replacing the associated external event that signals them.
Sync objects are associated with an EGLDisplay when they are
created, and have <attributes> defining additional aspects of the
sync object. All sync objects include attributes for their type and
their status. Additional attributes are discussed below for
different types of sync objects. If a sync object is created in the
signaled state, its initial attribute list may be incomplete, with
attributes necessary for its type provided when it is changed to
unsignaled.
<Fence sync objects> have an associated fence command in a client
API. A new fence command is generated whenever the sync object
enters the unsignaled state. When the client API executes the fence
command, an event is generated which signals the corresponding fence
sync object. Fence sync objects may not be explicitly signaled.
Fence sync objects may be used to wait for partial completion of a
client API command stream, as a more flexible form of glFinish or
vgFinish.
An <OpenCL event sync object> reflects the status of a corresponding
OpenCL event object to which the sync object is linked. This
provides another method of coordinating sharing of images between
EGL and OpenCL (see Chapter 9 of the OpenCL 1.0 Specification and
the cl_khr_egl_image extension). Waiting on such a sync object is
equivalent to waiting for completion of the linked OpenCL event
object.
The command
EGLSync eglCreateSync(EGLDisplay dpy, EGLenum type, const
EGLAttrib *attrib_list);
creates a sync object of the specified <type> associated with the
specified display <dpy>, and returns a handle to the new object.
<attrib list> is NULL or an attribute-value list specifying other
attributes of the sync object, terminated by an attribute entry
EGL_NONE. Attributes not specified in the list will be assigned
their default values.
The EGL_SYNC_STATUS attribute is defined for all sync types, but may
only be specified explicitly at creation time for some types of sync
objects, as discussed below. Other attributes are only allowed as
indicated below for the sync type.
Errors
eglCreateSync returns EGL_NO_SYNC on failure.
If <dpy> is not the name of a valid, initialized EGLDisplay, an
EGL_BAD_DISPLAY error is generated.
If <attrib_list> contains an attribute name not defined or not
allowed for the type of sync object being created, an
EGL_BAD_ATTRIBUTE error is generated.
If <type> is not a supported type of sync object, an
EGL_BAD_PARAMETER error is generated.
If <type> is EGL_SYNC_FENCE, the EGL_SYNC_STATUS attribute is
set to EGL_UNSIGNALED, and any of the following are true of the
current context for the bound API (the context returned by
eglGetCurrentContext), an EGL_BAD_MATCH error is generated:
* There is no current context (i.e., eglGetCurrentContext
returns EGL_NO_CONTEXT).
* <dpy> does not match the EGLDisplay of the context (the
EGLDisplay returned by eglGetCurrentDisplay).
* The context does not support fence commands.
While in the unsignaled state, the synchronization event associated
with a sync object cannot be changed. When the <condition> of a sync
object in the unsignaled state is satisfied, the sync is signaled,
causing any eglClientWaitSync or eglWaitSync commands (see below)
blocking on the sync to unblock.
Once signaled, a sync object may be reused for a new synchronization
event by switching it back to unsignaled. The command
EGLBoolean eglUnsignalSyncEXT(EGLDisplay dpy, EGLSync sync,
const EGLAttrib *attrib_list);
can be used to change the <sync> associated with display <dpy> from
the signaled state to the unsignaled state. The attribute list may
be used to provide or replace attributes specific to the sync type
as discussed below. The sync object's type and condition may not be
changed.
Errors
eglUnsignalSyncEXT returns EGL_FALSE on failure, and has no
effect on <sync>.
If <dpy> is not the name of a valid, initialized EGLDisplay, an
EGL_BAD_DISPLAY error is generated.
If <sync> is not a valid sync object associated with <dpy>, an
EGL_BAD_PARAMETER error is generated.
If <attrib_list> contains an attribute name not defined for the
type of <sync>, an EGL_BAD_ATTRIBUTE error is generated.
If <sync> is already in the unsignaled state, an EGL_BAD_ACCESS
error is generated.
If <sync>'s type is EGL_SYNC_FENCE and any of the following are
true of the current context for the bound API (the context
returned by eglGetCurrentContext), an EGL_BAD_MATCH error is
generated:
* There is no current context (i.e., eglGetCurrentContext
returns EGL_NO_CONTEXT).
* <dpy> does not match the EGLDisplay of the context (the
EGLDisplay returned by eglGetCurrentDisplay).
* The context does not support fence commands.
If <sync>'s type is EGL_SYNC_CL_EVENT and EGL_CL_EVENT_HANDLE
is not specified in <attrib_list>, then an EGL_BAD_ATTRIBUTE
error is generated.
3.8.1.1 Creating and Signaling Fence Sync Objects
If type is EGL_SYNC_FENCE, a fence sync object is created. The
EGL_SYNC_STATUS attribute may be specified as either EGL_UNSIGNALED
or EGL_SIGNALED, and will default to EGL_UNSIGNALED. No other
attributes may be specified for a fence sync object, either with
eglCreateSync or eglUnsignalSyncEXT. Queriable attributes of the
fence sync object are set as shown in table 3.7.
When a fence sync object is created in the unsignaled state, or
switched to that state with eglUnsignalSyncEXT, a fence command is
inserted into the command stream of the bound client API’s current
context (i.e., the context returned by eglGetCurrentContext), and is
associated with the sync object.
The only condition supported for fence sync objects is
EGL_SYNC_PRIOR_COMMANDS_COMPLETE, which is satisfied by completion
of the fence command corresponding to the sync object, and all
preceding commands in the associated client API context’s command
stream. The sync object will not be signaled until all effects from
these commands on the client API’s internal and framebuffer state
are fully realized. No other state is affected by execution of the
fence command.
Generation of fence commands for fence sync objects requires support
from the bound client API, and will not succeed unless the client
API satisfies one of the following properties. Note that eglWaitSync
(see section 3.8.1.3) also requires satisfying these conditions.
* client API is OpenGL, and either the OpenGL version is 3.2 or
greater, or the GL_ARB_sync extension is supported.
* client API is OpenGL ES, and either the OpenGL ES version is 3.0
or greater, or the GL_OES_EGL_sync extension is supported.
* client API is OpenVG, and the VG_KHR_EGL_sync extension is
supported.
3.8.1.2 Creating and Signaling OpenCL Event Sync Objects
If type is EGL_SYNC_CL_EVENT, an OpenCL event sync object is
created. The EGL_SYNC_STATUS attribute may not be explicitly
specified during creation of this type of sync object. If no
EGL_CL_EVENT_HANDLE attribute is specified at creation time, the
sync object will be created in the signaled state. Otherwise its
status will be determined by the provided OpenCL event, as described
below. An EGL_CL_EVENT_HANDLE must always be specified for
eglUnsignalSyncEXT.
To use an OpenCL event sync object, the EGL_SYNC_CL_EVENT attribute
must be set to a valid OpenCL <event> handle returned by a call to
clEnqueueReleaseGLObjects or clEnqueueReleaseEGLObjects; other types
of OpenCL event handles are not supported. Implementations are not
required to validate the OpenCL event, and passing an invalid event
handle in <attrib_list> may result in undefined behavior up to and
including program termination. Note that EGL_CL_EVENT_HANDLE is not
a queriable property of a sync object. Queriable attributes of the
OpenCL event sync object are set as shown in table 3.8.
The status of such a sync object depends on <event>. When the status
of <event> is CL_QUEUED, CL_SUBMITTED, or CL_RUNNING, the status of
the linked sync object will be EGL_UNSIGNALED. When the status of
<event> changes to CL_COMPLETE, the status of the linked sync object
will become EGL_SIGNALED.
The only condition supported for OpenCL event sync objects is
EGL_SYNC_CL_EVENT_COMPLETE, which is satisfied when the status of
the OpenCL event associated with the sync object changes to
CL_COMPLETE.
Associating an OpenCL event handle with a sync object places a
reference on the linked OpenCL object. When the sync object is
deleted or the event handle is replaced, the reference will be
removed from the OpenCL object.
If EGL_KHR_reusable_sync is present, then for sync objects of type
EGL_SYNC_REUSABLE_KHR, the initial value of EGL_SYNC_STATUS may be
set to either EGL_UNSIGNALED or EGL_SIGNALED, and will default to
EGL_UNSIGNALED.
If EGL_ANDROID_native_fence_sync is present, then for native fence sync
objects, the EGL_SYNC_NATIVE_FENCE_FD_ANDROID attribute may be specified
in eglUnsignalSyncEXT as well as eglCreateSync. If it is set to anything
other than EGL_NO_NATIVE_FENCE_FD_ANDROID at creation time, then its
initial EGL_SYNC_STATUS will reflect the current status of the provided
fence FD, and it is an error to specifically set the status. If it is
set to EGL_NO_NATIVE_FENCE_FD_ANDROID, then its EGL_SYNC_STATUS may be
set to either EGL_UNSIGNALED (the default) or EGL_SIGNALED. If the
status is signaled, then no native fence will be generated until after
it is switched to unsignaled. If eglUnsignalSyncEXT is called for a
native fence sync object with an FD of EGL_NO_NATIVE_FENCE_FD_ANDROID,
then a new native fence will be generated at the next Flush(), as
described for eglCreateSync.
If EGL_NV_cuda_event is present, then for CUDA event sync objects, the
EGL_CUDA_EVENT_HANDLE_NV may be specified in eglUnsignalSyncEXT as well
as eglCreateSync. The current CUDA event handle is evaluated at the time
the EGL sync object becomes unsignaled, and subsequent modification of
the CUDA object with cudaEventRecord has no effect on the sync object
until it is signaled. Subsequently restoring the sync object to
unsignaled will cause the CUDA object to be reevaluated.
Issues
1. Should a new attribute be required to specify a sync object as
reusable?
RESOLVED: No. The presence of this extension is sufficient to
indicate reusability of all sync objects. This will not create
any incompatibilities with existing applications that use sync
objects only once.
2. Can we leverage the existing eglSignalSyncKHR function from
EGL_KHR_reusable_sync for this extension?
RESOLVED: No. Some types of sync objects require attributes
which are themselves single-use objects, and must be replaced
for the sync object to be reused. Therefore a new function which
takes an attribute list is required.
3. Should the function for unsignaling be based on eglSignalSyncKHR
from the KHR_reusable_sync extension, and take a mode parameter
to distinguish signaling/unsignaling?
RESOLVED: No. While all sync objects will support unsignaling,
the reusable sync object is the only known one that supports
direct signaling, rather than signaling through some condition
being achieved. Therefore it is simplest to have the new
function only support unsignaling, and continue to use the old
extension for the one case where signaling is required.
4. If the initial attribute list is incomplete (e.g. an OpenCL
event handle is not provided during creation of an OpenCL event
sync object), should the EGL_SYNC_STATUS default to EGL_SIGNALED
rather than generating an error if it is left unspecified?
RESOLVED: Handling of allowed/default values for EGL_SYNC_STATUS
is based on the sync type. For fence syncs, either value is
allowed, defaulting to EGL_UNSIGNALED. For OpenCL event syncs,
the value may not be specified, and instead is determined by
whether an OpenCL event is provided at creation time, and if so
by the status of that event.
Revision History
#4 (May 16, 2018) Daniel Kartch
- Minor corrections to wording
#3 (April 20, 2018) Daniel Kartch
- Renamed to EXT
- Fixed grammatical errors and prepared for publication
#2 (January 23, 2018) Daniel Kartch
- Rewrote some sections for clarity, and fixed typos
- Changed default/allowed behavior for signal state at creation
time to be determined by the sync type and other attributes.
- Simplified interaction with EGL_KHR_reusable_sync.
- Refined interaction with EGL_ANDROID_native_fence_sync to
clarify allowed initial states for the sync status and fix the
description of when new native fences are generated.
#1 (January 16, 2018) Daniel Kartch
- Initial draft as XXX
extensions/EXT/EGL_EXT_yuv_surface.txt
+393
View File
@@ -0,0 +1,393 @@
Name
EXT_yuv_surface
Name Strings
EGL_EXT_yuv_surface
Contributors
Matt Trusten
Jeff Vigil
Arshad Bebal
Mohan Maiya
Amit Bansal
Tom Longo
Eric Engestrom
Contacts
Jeff Vigil, Qualcomm (jvigil 'at' qualcomm.com)
Notice
Copyright (c) 2014 Qualcomm Technologies, Inc. All Rights Reserved.
Qualcomm Technologies Proprietary and Confidential
Status
Complete
Version
Version 9, May 4th, 2017
Number
EGL Extension #86
Dependencies
EGL 1.4 is required.
This extension is written against the wording of the EGL 1.4
Specification.
Overview
This extension defines a set of new EGL configuration attributes and values
which allows EGL to create and use YUV surfaces.
YUV formats can be described using a few simple parameters, and every format
can be given with these six parameters. These parameters include the color
order, the number of planes, subsample, plane depth, color conversion and
depth range.
This extension describes how EGL will handle YUV surfaces, but requires that
the client API describe how to fill such a surface. An example of such an
extension would be GL_EXT_yuv_target.
New Types
None
New Procedures and Functions
None
New Tokens
A new set of EGLConfig attributes are available:
EGL_YUV_ORDER_EXT 0x3301
EGL_YUV_NUMBER_OF_PLANES_EXT 0x3311
EGL_YUV_SUBSAMPLE_EXT 0x3312
EGL_YUV_DEPTH_RANGE_EXT 0x3317
EGL_YUV_CSC_STANDARD_EXT 0x330A
EGL_YUV_PLANE_BPP_EXT 0x331A
Accepted as a new value for the EGL_COLOR_BUFFER_TYPE attribute:
EGL_YUV_BUFFER_EXT 0x3300
Accepted values for the EGL_YUV_ORDER_EXT attribute:
EGL_YUV_ORDER_YUV_EXT 0x3302
EGL_YUV_ORDER_YVU_EXT 0x3303
EGL_YUV_ORDER_YUYV_EXT 0x3304
EGL_YUV_ORDER_UYVY_EXT 0x3305
EGL_YUV_ORDER_YVYU_EXT 0x3306
EGL_YUV_ORDER_VYUY_EXT 0x3307
EGL_YUV_ORDER_AYUV_EXT 0x3308
Accepted values for the EGL_YUV_SUBSAMPLE_EXT attribute:
EGL_YUV_SUBSAMPLE_4_2_0_EXT 0x3313
EGL_YUV_SUBSAMPLE_4_2_2_EXT 0x3314
EGL_YUV_SUBSAMPLE_4_4_4_EXT 0x3315
Accepted values for the EGL_YUV_DEPTH_RANGE_EXT attribute:
EGL_YUV_DEPTH_RANGE_LIMITED_EXT 0x3318
EGL_YUV_DEPTH_RANGE_FULL_EXT 0x3319
Accepted values for the EGL_YUV_CSC_STANDARD_EXT attribute:
EGL_YUV_CSC_STANDARD_601_EXT 0x330B
EGL_YUV_CSC_STANDARD_709_EXT 0x330C
EGL_YUV_CSC_STANDARD_2020_EXT 0x330D
Accepted values for the EGL_YUV_PLANE_BPP_EXT attribute:
EGL_YUV_PLANE_BPP_0_EXT 0x331B
EGL_YUV_PLANE_BPP_8_EXT 0x331C
EGL_YUV_PLANE_BPP_10_EXT 0x331D
Additions to Chapter 2 of the EGL 1.4 Specification (EGL Operation)
Change the options of paragraph 6 from section 2.2: Rendering Contexts and
Drawing Surfaces
A context can be used with any EGLSurface that it is compatible with
(subject to the restrictions discussed in the section on address space). A
surface and context are compatible if
* They support the same type of color buffer (RGB or luminance)
To the following:
A context can be used with any EGLSurface that it is compatible with
(subject to the restrictions discussed in the section on address space). A
surface and context are compatible if
* They support the same type of color buffer (RGB, YUV, or luminance)
Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
Change the section marked from Buffer Descriptions and Attributes in Section 3.4
to:
The Color Buffer
The color buffer contains pixel color values, and is shared by all
client APIs rendering to a surface.
EGL_COLOR_BUFFER_TYPE indicates the color buffer type, and must be
either EGL_RGB_BUFFER for an RGB color buffer, EGL_LUMINANCE_BUFFER for a
luminance color buffer, or EGL_YUV_BUFFER_EXT for a YUV color buffer. For
an RGB buffer, EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE must be non-zero,
and EGL_LUMINANCE_SIZE must be zero. For a luminance buffer, EGL_RED_SIZE,
EGL_GREEN_SIZE, EGL_BLUE_SIZE must be zero, and EGL_LUMINANCE_SIZE must be
non-zero. For both RGB and luminance color buffers, EGL_ALPHA_SIZE may be
zero or non-zero (the latter indicates the existence of a destination alpha
buffer). For a YUV buffer, all of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_-
SIZE, EGL_LUMINANCE_SIZE, and EGL_ALPHA_SIZE must be zero. Instead, the
depth in bits per pixel for YUV is described using EGL_YUV_PLANE_BPP_EXT,
which describes the size of a single pixel in the Y plane, and the other
plane depths are derived from this.
EGL_YUV_ORDER_EXT is used to describe the plane order.
EGL_YUV_NUMBER_OF_PLANES_EXT describes the number of planes that will
be used for this surface. The allowed values for EGL_YUV_NUMBER_OF_PLANES_-
EXT must be greater than zero and not more than three.
EGL_YUV_SUBSAMPLE_EXT allows the user to decide how the surface will be
subsampled.
Valid combinations are:
EGL_YUV_SUBSAMPLE_EXT EGL_YUV_NUMBER_OF_PLANES_EXT EGL_YUV_ORDER_EXT EGL_YUV_PLANE_BPP_EXT
------------------------- ----------------------------- ------------------ ------------------------
EGL_YUV_SUBSAMPLE_4_2_0_EXT 2 or 3 EGL_YUV_ORDER_YUV_EXT or EGL_YUV_PLANE_BPP_8_EXT or
EGL_YUV_ORDER_YVU_EXT EGL_YUV_PLANE_BPP_10_EXT
EGL_YUV_SUBSAMPLE_4_2_2_EXT 1 EGL_YUV_ORDER_YUYV_EXT or EGL_YUV_PLANE_BPP_8_EXT or
EGL_YUV_ORDER_YVYU_EXT or EGL_YUV_PLANE_BPP_10_EXT
EGL_YUV_ORDER_UYVY_EXT or
EGL_YUV_ORDER_VYUY_EXT
EGL_YUV_SUBSAMPLE_4_2_2_EXT 2 or 3 EGL_YUV_ORDER_YUV_EXT or EGL_YUV_PLANE_BPP_8_EXT or
EGL_YUV_ORDER_YVU_EXT EGL_YUV_PLANE_BPP_10_EXT
EGL_YUV_SUBSAMPLE_4_4_4_EXT 1 EGL_YUV_ORDER_AYUV_EXT EGL_YUV_PLANE_BPP_8_EXT or
EGL_YUV_PLANE_BPP_10_EXT
Usage examples:
Format Combination
------------------ --------------------------------------------------------------
NV12 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT
- YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2
- 2 Planes : Y + UV EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUV_EXT
- 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT
NV21 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT
- YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2
- 2 Planes : Y + VU EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YVU_EXT
- 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT
YV12 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT
- YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 3
- 3 Planes : Y + V + U EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YVU_EXT
- 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT
YUY2 EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_2_EXT
- YUV422 EGL_YUV_NUMBER_OF_PLANES_EXT = 1
- 1 Plane : Y + U + Y + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUYV_EXT
- 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT
AYUV EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_4_4_EXT
- YUV444 EGL_YUV_NUMBER_OF_PLANES_EXT = 1
- 1 Plane : A + Y + U + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_AYUV_EXT
- 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_8_EXT
YUV420 Semi-Planar 10 Bit EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_0_EXT
- YUV420 EGL_YUV_NUMBER_OF_PLANES_EXT = 2
- 2 Planes : Y + UV EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUV_EXT
- 10 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_10_EXT
YUV422 Interleaved 10 Bit EGL_YUV_SUBSAMPLE_EXT = EGL_YUV_SUBSAMPLE_4_2_2_EXT
- YUV422 EGL_YUV_NUMBER_OF_PLANES_EXT = 1
- 1 Plane : Y + U + Y + V EGL_YUV_ORDER_EXT = EGL_YUV_ORDER_YUYV_EXT
- 8 bit depth EGL_YUV_PLANE_BPP_EXT = EGL_YUV_PLANE_BPP_10_EXT
EGL_YUV_PLANE_BPP_EXT describes the bit depth for the different
planes of a YUV surface. The available options are EGL_YUV_PLANE_BPP_0_-
EXT, EGL_YUV_PLANE_BPP_8_EXT and EGL_YUV_PLANE_BPP_10_EXT. If EGL_YUV_-
PLANE_BPP_0_EXT is specified, no color buffer will be created for the
surface.
EGL_YUV_DEPTH_RANGE_EXT describes the range of the pixel value and is
dependent on the EGL_YUV_PLANE_BPP_EXT setting:
EGL_YUV_PLANE_BPP_EXT EGL_YUV_DEPTH_RANGE_LIMITED_EXT EGL_YUV_DEPTH_RANGE_FULL_EXT
(Inclusive) (Inclusive)
------------------------- -------------------------------- -----------------------------
EGL_YUV_PLANE_BPP_8_EXT or Y: 16 to 235, UV: 16 to 240 Y: 0 to 255, UV: 0 to 255
EGL_YUV_PLANE_BPP_10_EXT Y: 64 to 940, UV: 64 to 960 Y: 0 to 1023, UV: 0 to 1023
If OpenGL or OpenGL ES rendering is supported for a luminance color
buffer (as described by the value of the EGL_RENDERABLE_TYPE attribute,
described below), it is treated as RGB rendering with the value of
GL_RED_BITS equal to EGL_LUMINANCE_SIZE and the values of GL_GREEN_BITS and
GL_BLUE_BITS equal to zero. The red component of fragments is written to the
luminance channel of the color buffer, the green and blue components are
discarded, and the alpha component is written to the alpha channel of the
color buffer (if present).
When rendering to the YUV surface, if EGL_YUV_ORDER_EXT is not EGL_-
YUV_ORDER_AYUV_EXT, the alpha channel will always be fully opaque.
Otherwise it is defined by the value provided to the alpha sample.
EGL_BUFFER_SIZE gives the total of the color component bits of the color
buffer for EGL_RGB_BUFFER or for EGL_LUMINANCE_BUFFER. For an RGB color
buffer, the total is the sum of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE,
and EGL_ALPHA_SIZE. For a luminance color buffer, the total is the sum of
EGL_LUMINANCE_SIZE and EGL_ALPHA_SIZE. When EGL_COLOR_BUFFER_TYPE is of type
EGL_YUV_BUFFER_EXT, this will reflect the enumeration provided
as an integer) for EGL_YUV_PLANE_BPP_EXT, giving a value of 0, 8 or 10.
Other EGLConfig Attribute Descriptions
EGL_YUV_CSC_STANDARD_EXT can be set to either EGL_YUV_CSC_STANDARD_-
601_EXT, EGL_YUV_CSC_STANDARD_709_EXT, or EGL_YUV_CSC_2020_EXT. If the
standard chosen is EGL_YUV_CSC_STANDARD_709_EXT, then the color conversion
follows the ITU-R BT.709 standard. If EGL_YUV_CSC_STANDARD_EXT is set to
EGL_YUV_CSC_2020_EXT, then the color conversion will be processed based on
ITU-R BT.2020.
Change option 2 in the section marked as 3.4.1.2 Sorting of EGLConfigs to:
2. Special: by EGL_COLOR_BUFFER_TYPE where the precendence is EGL_RGB_-
BUFFER, EGL_LUMINANCE_BUFFER, EGL_YUV_BUFFER_EXT.
Change option 3 in the section marked as 3.4.1.2 Sorting of EGLConfigs to:
3. Special: by larger total number of color bits (for an RGB color buffer,
this is the sum of EGL_RED_SIZE, EGL_GREEN_SIZE, EGL_BLUE_SIZE, and
EGL_ALPHA_SIZE; for a luminance color buffer, the sum of EGL_LUMINANCE_SIZE
and EGL_ALPHA_SIZE; for YUV color buffers, this returns the integer value
with respect to the enumeration provided for EGL_YUV_PLANE_BPP_EXT) If the
requrested number of bits in attrib_list for a particular color component
is 0 or EGL_DONT_CARE, then the number of bits for the component is not
considered. Due to this, YUV color buffers are always last based on this
rule.
The following options should be added between options 9 and 10 in section
3.4.1.2 (EGL_ALPHA_MASK_SIZE and EGL_NATIVE_VISUAL_TYPE):
10. Special: EGL_YUV_ORDER_EXT will be sorted in the following order:
EGL_NONE, EGL_YUV_ORDER_YUV_EXT, EGL_YUV_ORDER_YVU_EXT, EGL_YUV_ORDER_-
YUYV_EXT, EGL_YUV_ORDER_YVYU_EXT, EGL_YUV_ORDER_UYVY_EXT, EGL_YUV_ORDER_-
VYUY_EXT, and EGL_YUV_ORDER_AYUV_EXT.
Change option 10 in section 3.4.1.2 (EGL_NATIVE_VISUAL_TYPE) to:
11. Special: by EGL_NATIVE_VISUAL_TYPE (the actual sort order is
implementation-defined, depending on the meaning of native visual types).
New State
Add to table 3.1 (EGLConfig Attributes):
Attribute Type Notes
----------------------------- ---- --------------------------------------------
EGL_YUV_ORDER_EXT enum The order in which the samples will be found
inside the surface
EGL_YUV_NUMBER_OF_PLANES_EXT integer Number of planes for the surface, in the range of [1,3]
EGL_YUV_SUBSAMPLE_EXT enum Describes the sampling rate of the different planes.
EGL_YUV_DEPTH_RANGE_EXT enum Luma plane range. limited is [16,240] and
full range is [0,255]
EGL_YUV_CSC_STANDARD_EXT enum The standard used for color conversion.
EGL_YUV_PLANE_BPP_EXT enum How many bits are used for each plane of
the YUV surface
Add to table 3.4 (Default values and match criteria for EGLConfig
attributes):
Attribute Default Selection Sort Sort
Criteria Order Priority
------------------------- -------------------------------- --------- ------- --------
EGL_YUV_ORDER_EXT EGL_DONT_CARE Exact Special 10
EGL_YUV_NUMBER_OF_PLANES_EXT 0 At least None
EGL_YUV_SUBSAMPLE_EXT EGL_DONT_CARE Exact None
EGL_YUV_DEPTH_RANGE_EXT EGL_DONT_CARE Exact None
EGL_YUV_CSC_STANDARD_EXT EGL_DONT_CARE Exact None
EGL_YUV_PLANE_BPP_EXT EGL_DONT_CARE Exact None
Issues
1. How will a EGL surface created with a YUV config properly detect that
valid values were used when filling pixel data?
This problem occurs in situations when a specification which defines
rendering to the YUV surface cannot guarantee values that conform to the
configuration attributes. One possible situation for this is when a
the GL client is using GL_EXT_yuv_target and the EGL YUV surface is the
draw buffer. The shader can transform the values inside the shader, and
there is no guarantee that the values will fall into the EGL_YUV_DEPTH_-
RANGE_EXT value chosen. Other client specifications could have similar
issues and it may not be performant for some hardware to detect this
discrepancy. This includes interactions with extensions such as EGL_-
lock_surface, or any others that provide a mechanism to change the
contents of the YUV surface.
One of the problems that can occur in situations like this will be
compound mathematical error should operations need to take place on the
buffer data.
Proposal: Due to the performance problems or inability in some hardware
to deal with this issue, the pixel contents will be undefined and any
further operations to the pixel contents will also be undefined.
Therefore it is up to the application to guarantee the correct values
are stored within the surface. The EGL implementation need not attempt
any form of verification on the pixel data of the YUV surface, nor does
it have to guarantee the pixel data, even with communicating the surface
to other modules through a post or any other operation EGL performs.
2. Should an EGL_COLOR_BUFFER_TYPE = EGL_DONT_CARE request enumerate all
YUV configs?
Resolved: Revision #9 changes the default values and selection criteria
to allow for full enumeration of all YUV configs. The default value of
EGL_COLOR_BUFFER_TYPE remains EGL_RGB_BUFFER, so this change only
affects explicit EGL_DONT_CARE requests.
Example Configuration for NV12:
const EGLint config_attribs[] =
{
EGL_SURFACE_TYPE, EGL_WINDOW_BIT,
EGL_RENDERABLE_TYPE, EGL_OPENGL_ES2_BIT,
EGL_COLOR_BUFFER_TYPE, EGL_YUV_BUFFER_EXT,
EGL_YUV_ORDER_EXT, EGL_ORDER_YUV_EXT,
EGL_YUV_NUMBER_OF_PLANES_EXT, 2,
EGL_YUV_SUBSAMPLE_EXT, EGL_YUV_SUBSAMPLE_4_2_0_EXT,
EGL_YUV_DEPTH_RANGE_EXT, EGL_YUV_DEPTH_RANGE_LIMITED_EXT,
EGL_YUV_CSC_STANDARD_EXT, EGL_YUV_CSC_STANDARD_601_EXT,
EGL_YUV_PLANE_BPP_EXT, EGL_YUV_PLANE_BPP_8_EXT,
EGL_NONE
};
Revision History
#1 March 12th, 2014 Initial Draft.
#2 March 25th, 2014 Reformated and added more detail.
#3 March 26th, 2014 Added usage examples.
Added memory layout definitions.
#4 March 26th, 2014 Fixed some typos and formatting.
#5 May 21st, 2014 Fixed some inconsistencies.
Added EGL_YUV_PLANE_DEPTH_0_QCOM.
#6 May 27th, 2014 Relaxed some requirements.
Changed EGL_YUV_PLANE_DEPTH_<0,8,10>_QCOM to
EGL_YUV_PLANE_BPP_<0,8,10>_QCOM.
Added more detail.
#7 October 7th, 2014 Issue (1) added.
Minor updates made (EXT_yuv_target)
#8 October 24th, 2014 Updated for EXT and token values.
#9 April 26th, 2017 Changed attributes default values and selection
criteria (see issue #2).
Changed status from Draft to Complete.
extensions/HI/EGL_HI_clientpixmap.txt
+144
View File
@@ -0,0 +1,144 @@
Name
HI_clientpixmap
Name Strings
EGL_HI_clientpixmap
Contributors
Guillaume Portier
Contacts
HI support. (support_renderion 'at' hicorp.co.jp)
Status
Shipping (Revision 3).
Version
Last Modified Date: June 7, 2010
Revision 3
Number
EGL Extension #24
Dependencies
This extension is written against the wording of the EGL 1.4
Specification.
Overview
The extension specified in this document provide a mechanism for
using memory allocated by the application as a color-buffer.
New Types
EGLClientPixmapHI : specifies the width, height, stride, format
and memory pointer of the pixmap to be used by the function
eglCreatePixmapSurfaceHI to create the PixmapSurface.
Members:
void* pData;
Pointer to a memory buffer allocated by the application
that will contain the result of the drawing operations.
It is up to the application to ensure that the buffer
size corresponds to iHeight * iStride * sizeof(pixel).
EGLint iWidth;
Width of the buffer in pixels.
EGLint iHeight;
Height of the buffer in pixels. The height of the buffer
can be negative; in that case the result of the
drawing operations will be vertically swapped. When
positive, pData will point at the bottom-left corner
of the image; when negative, to the top-left corner.
EGLint iStride;
Stride of the buffer, in pixels. It is important to note
that each row of the buffer must start on 32-bit
boundaries.
New Procedures and Functions
eglCreatePixmapSurfaceHI : creates an EGL ClientPixmap from
an EGLClientPixmapHI structure. eglCreatePixmapSurfaceHI usage
is identical to eglCreatePixmapSurface. In addition the ordering
of the color components in the color buffer can be specified by
the surface attribute described in the EGL_HI_colorformats
extension.
In order to update the pointer to the data of the surface, the application
can call eglSurfaceAttrib with the EGL_CLIENT_PIXMAP_POINTER_HI attribute.
See below for an example.
New Tokens
None.
Example
EGLClientPixmapHI pixmap;
EGLint attrib_list[] = {
EGL_RED_SIZE, 8,
EGL_GREEN_SIZE, 8,
EGL_BLUE_SIZE, 8,
EGL_ALPHA_SIZE, 8,
EGL_SURFACE_TYPE, EGL_PIXMAP_BIT,
// Specifying ARGB as a color format
EGL_COLOR_FORMAT_HI, EGL_COLOR_ARGB_HI,
EGL_NONE
};
// ‘access' being the memory to render into.
pixmap.pData = framebuffer.access;
pixmap.iWidht = framebuffer.width;
pixmap.iHeight = framebuffer.height;
pixmap.iStride = framebuffer.stride;
//Get Config ARGB8
eglChooseConfig(dpy, attrib_list, &config, 1, &num_config);
// Create the pixmap
#ifdef EGL_EGLEXT_PROTOTYPES
eglCreatePixmapSurfaceHI(eglDisplay, ppkConfig[0], &gHiPixmap);
#else
pfCreatePixmap = (PFNEGLCREATEPIXMAPSURFACEHIPROC)
eglGetProcAddress("eglCreatePixmapSurfaceHI");
pfCreatePixmap(eglDisplay, ppkConfig[0], &gHiPixmap);
#endif /* EGL_EGLEXT_PROTOTYPES */
// Update the surface data pointer, from now we will render into the
// memory pointed by 'access2'.
eglSurfaceAttrib(eglDisplay, eglSurface, EGL_CLIENT_PIXMAP_POINTER_HI,
offscreen.access2);
Issues
None
Revision History
June 7, 2010 (r3)
- Allow updating the pixmap data pointer using eglSurfaceAttrib with
the EGL_CLIENT_PIXMAP_POINTER_HI attribute.
June 16, 2009 (r2)
- Split HI_clientpixmap into two different extensions:
- HI_colorformats
- HI_clientpixmap
March 3, 2009 (r1)
extensions/HI/EGL_HI_colorformats.txt
+138
View File
@@ -0,0 +1,138 @@
Name
HI_colorformats
Name Strings
EGL_HI_colorformats
Contributors
Guillaume Portier
Contacts
HI support. (support_renderion 'at' hicorp.co.jp)
Status
Shipping (Revision 2)
Version
Last Modified Date: June 7, 2010
Revision 2.1
Number
EGL Extension #25
Dependencies
These extensions are written against the wording of the EGL 1.4
Specification.
Overview
The extensions specified in this document provide a mechanism for
creating ARGB color-buffers, as opposed to the default RGBA
format used by other EGL configurations.
New Types
None.
New Procedures and Functions
None.
New Tokens
Accepted in the <attrib_list> parameter of eglChooseConfig.
EGL_COLOR_FORMAT_HI 0x8F70
Accepted as a value for the EGL_COLOR_FORMAT_HI token:
EGL_COLOR_RGB_HI 0x8F71
EGL_COLOR_RGBA_HI 0x8F72
EGL_COLOR_ARGB_HI 0x8F73
The default value for EGL_COLOR_FORMAT_HI is EGL_DONT_CARE.
If EGL_COLOR_FORMAT_HI is used with a value other than
EGL_DONT_CARE, EGL_COLOR_RGB_HI, EGL_COLOR_RGBA_HI or
EGL_COLOR_ARGB_HI then an EGL_BAD_ATTRIBUTE is generated.
EGL_COLOR_RGB_HI, EGL_COLOR_RGBA_HI and EGL_COLOR_ARGB_HI
specify the order of the color components in the color-buffer.
EGL_COLOR_RGB_HI must be used only with configurations having no
alpha component, currently only 565.
EGL_COLOR_RGBA_HI and EGL_COLOR_ARGB_HI must be used with
configurations having an alpha component. Currently available
configurations are:
- 4444
- 5551
- 8888
Currently EGL_COLOR_ARGB_HI can be used only with the
8888 configuration.
If the value used for EGL_COLOR_FORMAT_HI does not match
the other specified attributes of the EGL config then an
EGL_BAD_MATCH is generated.
When EGL_COLOR_FORMAT_HI is unspecified or equals EGL_DONT_CARE,
eglChooseConfig returns configurations having all kinds of color
component ordering.
If eglCreatePixmapSurface is called with a configuration that
does not match the pixmap's native ordering then an EGL_BAD_MATCH
is generated. To be sure to call eglCreatePixmapSurface with a
compatible configuration, the application should either parse
the <configs> list returned by eglChooseConfig or explicitly specify
EGL_COLOR_FORMAT_HI to match the pixmap native format.
Example
EGLint attrib_list[] = {
EGL_RED_SIZE, 8,
EGL_GREEN_SIZE, 8,
EGL_BLUE_SIZE, 8,
EGL_ALPHA_SIZE, 8,
EGL_SURFACE_TYPE, EGL_PIXMAP_BIT,
#ifdef USE_ARGB // Specifying ARGB as a color format
EGL_COLOR_FORMAT_HI, EGL_COLOR_ARGB_HI,
#else // Specifying RGBA as a color format
EGL_COLOR_FORMAT_HI, EGL_COLOR_RGBA_HI,
#endif
EGL_NONE
};
// Get one of the configuration matching the config_list
eglChooseConfig(dpy, attrib_list, &config, 1, &num_config);
// Create the pixmap
eglCreatePixmapSurface(dpy, config[0], pixmap, NULL);
Issues
None.
Revision History
June 7, 2010 (r2.1)
- Corrected mistaken description of EGL_COLOR_FORMAT_HI as
attribute for eglCreatePixmapSurface. Clarified other text.
June 16, 2009 (r2)
- Split HI_clientpixmap into two different extensions:
- HI_colorformats
- HI_clientpixmap
March 3, 2009 (r1)
extensions/IMG/EGL_IMG_context_priority.txt
+166
View File
@@ -0,0 +1,166 @@
Name
IMG_context_priority
Name Strings
EGL_IMG_context_priority
Contributors
Ben Bowman, Imagination Techonologies
Graham Connor, Imagination Techonologies
Contacts
Ben Bowman, Imagination Technologies (benji 'dot' bowman 'at'
imgtec 'dot' com)
Status
Complete
Version
Version 1.1, 8 September 2009
Number
EGL Extension #10
Dependencies
Requires EGL 1.0.
This extension is written against the wording of the EGL 1.4
Specification - May 2, 2008 (but may be implemented against earlier
versions).
Overview
This extension allows an EGLContext to be created with a priority
hint. It is possible that an implementation will not honour the
hint, especially if there are constraints on the number of high
priority contexts available in the system, or system policy limits
access to high priority contexts to appropriate system privilege
level. A query is provided to find the real priority level assigned
to the context after creation.
New Types
None
New Procedures and Functions
None
New Tokens
New attributes accepted by the <attrib_list> argument of
eglCreateContext
EGL_CONTEXT_PRIORITY_LEVEL_IMG 0x3100
New attribute values accepted in the <attrib_list> argument
of eglCreateContext:
EGL_CONTEXT_PRIORITY_HIGH_IMG 0x3101
EGL_CONTEXT_PRIORITY_MEDIUM_IMG 0x3102
EGL_CONTEXT_PRIORITY_LOW_IMG 0x3103
Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
Modify the list of attributes supported by eglCreateContext in
section 3.7.1 (Creating Rendering Contexts) on p. 42:
"<attrib_list> specifies a list of attributes for the context.
The list has the same structure as described for
eglChooseConfig. The only attributes that can be specified in
<attrib_list> are EGL_CONTEXT_CLIENT_VERSION and
EGL_CONTEXT_PRIORITY_LEVEL_IMG. The EGL_CONTEXT_CLIENT_VERSION
attribute may only be specified when creating a OpenGL ES
context (e.g. when the current rendering API is
EGL_OPENGL_ES_API).
<attrib_list> may be NULL or empty (first attribute is
EGL_NONE), in which case attributes assume their default values
as described below.
EGL_CONTEXT_CLIENT_VERSION determines which version of an OpenGL
ES context to create. An attribute value of 1 specifies creation
of an OpenGL ES 1.x context. An attribute value of 2 specifies
creation of an OpenGL ES 2.x context. The default value for
EGL_CONTEXT_CLIENT_VERSION is 1.
EGL_CONTEXT_PRIORITY_LEVEL_IMG determines the priority level of
the context to be created. This attribute is a hint, as an
implementation may not support multiple contexts at some
priority levels and system policy may limit access to high
priority contexts to appropriate system privilege level. The
default value for EGL_CONTEXT_PRIORITY_LEVEL_IMG is
EGL_CONTEXT_PRIORITY_MEDIUM_IMG."
Modify the list of attributes supported by eglQueryContext in
section 3.7.4 (Context Queries) on p. 46:
"eglQueryContext returns in <value> the value of attribute for
<ctx>. <attribute> must be set to EGL_CONFIG_ID,
EGL_CONTEXT_CLIENT_TYPE, EGL_CONTEXT_CLIENT_VERSION,
EGL_RENDER_BUFFER, or EGL_CONTEXT_PRIORITY_LEVEL_IMG.
...
Querying EGL_CONTEXT_PRIORITY_LEVEL_IMG returns the priority
this context was actually created with. Note: this may not be
the same as specified at context creation time, due to
implementation limits on the number of contexts that can be
created at a specific priority level in the system."
ISSUES:
1) Should the context priority be treated as a hint or a requirement
RESOLVED: The context priority should be a hint. System policy may
limit high priority contexts to appropriate system privilege level.
Implementations may have a limit on the number of context supported
at each priority, and may require all contexts within a process to
have the same priority level.
2) Can an application find out what priority a context was assigned?
RESOLVED: Provide a query to find the assigned priority for a
context. An application may find that it has a lower (or higher)
priority than requested (although it probably cannot do much with
the information).
3) How many priority levels should be defined?
RESOLVED: Three seems appropriate, as the highest provides the
largest GPU timeslice and reduced latency. It might be useful to
specify a low priority context which has a small timeslice and high
latency. It is possible that a request for LOW will actually return
MEDIUM on an implementation that doesn't differentiate between the
lower two levels.
4) What should the default priority level be if not specified?
OPTION 1: HIGH - This allows applications that are unaware of
this extension to get the highest priority possible.
OPTIONS 2: MEDIUM - This allows truly high priority applications
to differentiate themselves from applications which are unaware
of this extension.
RESOLVED:
OPTION 2: MEDIUM - Allow truly high priority applications to
differentiate themselves.
Revision History
Version 1.1, 08/09/2009 (Jon Leech) Assign extension number and
publish in the Registry. Formatting cleanup.
Version 1.0, 30/04/2009 - Final clean up. Marked issues as resolved,
take out draft status
Version 0.3, 22/04/2009 - enums assigned from Khronos registry.
Version 0.2, 02/04/2009 - feedback from gdc.
Version 0.1, 31/03/2009 - first draft.
extensions/IMG/EGL_IMG_image_plane_attribs.txt
+156
View File
@@ -0,0 +1,156 @@
Name
IMG_image_plane_attribs
Name Strings
EGL_IMG_image_plane_attribs
Contributors
Ben Bowman
Alistair Strachan
Contacts
Tobias Hector, Imagination Technologies (tobias 'dot' hector 'at'
imgtec 'dot' com)
Status
Complete
Version
Version 0.4, October 18, 2015
Number
EGL Extension #95
Dependencies
EGL_KHR_image_base is required.
One of EGL_KHR_image, EGL_KHR_image_pixmap or
EGL_ANDROID_image_native_buffer is required.
This extension is written against the wording of the EGL 1.2
Specification as modified by EGL_KHR_image_base,
EGL_ANDROID_image_native_buffer and EGL_KHR_image_pixmap.
This extension interacts with GL_OES_EGL_image and GL_EXT_texture_rg.
Overview
This extension allows creating an EGLImage from a single plane of a
multi-planar Android native image buffer (ANativeWindowBuffer) or
a native pixmap (EGLNativePixmap).
New Types
None
New Procedures and Functions
None
New Tokens
Accepted by the <attrib_list> parameter of eglCreateImageKHR:
EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG 0x3105
EGL_NATIVE_BUFFER_PLANE_OFFSET_IMG 0x3106
Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation)
Add to section 2.5.1 "EGLImage Specification" (as defined by the
EGL_KHR_image_base specification), in the description of
eglCreateImageKHR:
Add the following to Table bbb (Legal attributes for eglCreateImageKHR
<attr_list> parameter), Section 2.5.1 (EGLImage Specification)
+-----------------------------+-------------------------+---------------------------+---------------+
| Attribute | Description | Valid <target>s | Default Value |
+-----------------------------+-------------------------+---------------------------+---------------+
| EGL_NATIVE_BUFFER_MULTI | Whether a multiplane | EGL_NATIVE_BUFFER_ANDROID | EGL_FALSE |
| PLANE_SEPARATE_IMG | native buffer should be | EGL_NATIVE_PIXMAP_KHR | |
| | treated as separate | | |
| | buffers | | |
| | | | |
| EGL_NATIVE_BUFFER_ | Which plane of a multi- | EGL_NATIVE_BUFFER_ANDROID | 0 |
| PLANE_OFFSET_IMG | plane native buffer is | EGL_NATIVE_PIXMAP_KHR | |
| | used as the EGLImage | | |
| | source | | |
+-----------------------------+-------------------------+---------------------------+---------------+
Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> parameter
...
If <target> is EGL_NATIVE_BUFFER_ANDROID or EGL_NATIVE_PIXMAP_KHR, and
<buffer> is a handle to a valid multi-planar surface, such as a YUV420 2 or
3 planar video surface, an EGLImage will be created from only one of the
planes, as opposed to a single image representing all of the planes as is
normally the case. The intention of this extension is that a call to
glEGLImageTargetTexture2DOES or EGLImageTargetRenderbufferStorageOES with an
EGLImage created from a single plane of a multiplanar buffer will result in
a GL_RED or GL_RG texture or renderbuffer, depending on the format of the
multiplanar buffer. This allows an application to work directly in the YUV
colorspace, rather than forcing a conversion to the linear RGB colorspace,
potentially losing precision.
The size of each image will represent the actual size of the data buffer
for that plane which may mean that the size of an EGLImage created from
plane 0 of a multi-planar buffer may not be the same as that of one
created from plane 1, which is determined by the YUV's sampling ratio (e.g.
a 420 will have planes 1 and 2, if present, represented by an image of half
the width).
Add to the list of error conditions for eglCreateImageKHR:
"* If EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG is EGL_TRUE, and <target>
is not EGL_NATIVE_BUFFER_ANDROID or EGL_NATIVE_PIXMAP_KHR, the error
EGL_BAD_PARAMETER is generated.
* If EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG is EGL_TRUE, and
EGL_NATIVE_BUFFER_PLANE_OFFSET_IMG is greater than or equal to the
number of planes in <buffer>, the error EGL_BAD_MATCH is generated.
* If EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG is EGL_FALSE, and
EGL_NATIVE_BUFFER_PLANE_OFFSET_IMG is greater than 0, the error
EGL_BAD_PARAMETER is generated.
* If EGL_NATIVE_BUFFER_MULTIPLANE_SEPARATE_IMG is EGL_TRUE, and the
format of <buffer> is not supported by the implementation,
EGL_BAD_PARAMETER is generated."
Dependencies on EGL_KHR_image_pixmap or EGL_KHR_image
If neither of these extensions are supported, remove all references to
native pixmaps and EGL_NATIVE_PIXMAP_KHR.
Dependencies on EGL_ANDROID_image_native_buffer
If this extension is not supported, remove all references to
ANativeWindowBuffer and EGL_NATIVE_BUFFER_ANDROID.
Issues
None
Revision History
#0.4 (Tobias Hector, October, 2015)
- Add interactions with EGL_KHR_image_pixmap/EGL_KHR_image
- Added error language for unsupported formats
#0.3 (Jon Leech, June 13, 2013)
- Add a "Valid Targets" column to table bbb for new attributes, matching
proposed changes in EGL_KHR_image_base (Bug 10151). Note that this
change implies a new error will be generated when <target> is not
EGL_NATIVE_BUFFER_ANDROID and EGL_NATIVE_BUFFER_PLANE_OFFSET_IMG is
specified in <attrib_list>; this falls out from the generic
target-attribute matching error added to EGL_KHR_image_base.
#0.2 (Ben Bowman, May 30, 2012)
- Fixed some typos
#0.1 (Ben Bowman, May 30, 2012)
- First draft of extension .
extensions/KHR/EGL_KHR_cl_event.txt
+278
View File
@@ -0,0 +1,278 @@
Name
KHR_cl_event
Name Strings
EGL_KHR_cl_event
Contributors
Jon Leech, Khronos
Alon Or-bach, Samsung Electronics
Contact
Jon Leech (jon 'at' alumni.caltech.edu)
IP Status
No known claims.
Notice
Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
This extension is obsolete and has been replaced by EGL_KHR_cl_event2.
Khronos recommends implementers who support this extension also
implement cl_event2, and begin transitioning developers to using that
extension. See issue 17 for the reason.
Complete. Approved by the EGL Working Group on 2013/05/15.
Approved by the Khronos Board of Promoters on 2013/07/19.
Version
Version 10, December 4, 2013
Number
EGL Extension #60
Dependencies
EGL 1.4 and the EGL_KHR_fence_sync extension are required.
This extension is written against the language added to EGL 1.2 by
the EGL_KHR_fence_sync extension.
An OpenCL implementation supporting sharing OpenCL event objects
with EGL is required.
Overview
This extension allows creating an EGL fence sync object linked to an
OpenCL event object, potentially improving efficiency of sharing
images between the two APIs. The companion cl_khr_egl_event
extension provides the complementary functionality of creating an
OpenCL event object from an EGL fence sync object.
New Types
None. However, event handles of type cl_event, defined in the OpenCL
header files, may be included in the attribute list passed to
eglCreateSyncKHR.
New Procedures and Functions
None
New Tokens
Accepted as attribute names in the <attrib_list> argument
of eglCreateSyncKHR:
EGL_CL_EVENT_HANDLE_KHR 0x309C
Returned in <values> for eglGetSyncAttribKHR <attribute>
EGL_SYNC_TYPE_KHR:
EGL_SYNC_CL_EVENT_KHR 0x30FE
Returned in <values> for eglGetSyncAttribKHR <attribute>
EGL_SYNC_CONDITION_KHR:
EGL_SYNC_CL_EVENT_COMPLETE_KHR 0x30FF
Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
Add following the description of fence sync objects in section 3.8.1
(e.g. following the paragraph beginning "<Fence sync objects> are
created..."
"A <CL event sync object> reflects the status of a corresponding
OpenCL event object to which the sync object is linked. This
provides another method of coordinating sharing of images between
EGL and OpenCL (see Chapter 9 of the OpenCL 1.0 Specification and
the cl_khr_egl_sharing extension). Waiting on such a sync object is
equivalent to waiting for completion of the linked CL event object."
Add following the description of fence sync objects (prior to the
"Errors" section for eglCreateSyncKHR):
"If <type> is EGL_SYNC_CL_EVENT_KHR, a CL event sync object is
created. In this case <attrib_list> must contain the attribute
EGL_CL_EVENT_HANDLE_KHR, set to a valid OpenCL event. Note that
EGL_CL_EVENT_HANDLE_KHR is not a queriable property of a sync
object. Attributes of the CL event sync objects are set as follows:
Attribute Name Initial Attribute Value(s)
------------- --------------------------
EGL_SYNC_TYPE_KHR EGL_SYNC_CL_EVENT_KHR
EGL_SYNC_STATUS_KHR Depends on status of <event>
EGL_SYNC_CONDITION_KHR EGL_SYNC_CL_EVENT_COMPLETE_KHR
The status of such a sync object depends on <event>. When the status
of <event> is CL_QUEUED, CL_SUBMITTED, or CL_RUNNING, the status of
the linked sync object will be EGL_UNSIGNALED_KHR. When the status
of <event> changes to CL_COMPLETE, the status of the linked sync
object will become EGL_SIGNALED_KHR.
Creating a linked sync object places a reference on the linked
OpenCL event object. When the sync object is deleted, the reference
will be removed from the event object.
However, implementations are not required to validate the OpenCL
event, and passing an invalid event handle in <attrib_list> may
result in undefined behavior up to and including program
termination."
Add to the "Errors" section for eglCreateSyncKHR:
"* If <type> is EGL_SYNC_CL_EVENT_KHR then
** If EGL_CL_EVENT_HANDLE_KHR is not specified in <attrib_list>
or is not a valid OpenCL event handle returned by a call to
clEnqueueReleaseGLObjects or clEnqueueReleaseEGLObjects, then
EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is
generated.
Replace the EGL_SYNC_CONDITION_KHR row of table 3.cc with:
"Attribute Description Supported Sync Objects
----------------- ----------------------- ----------------------
EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR or
EGL_SYNC_CL_EVENT_KHR
Table 3.cc Attributes Accepted by eglGetSyncAttribKHR Command"
Replace the second paragraph describing eglDestroySync with:
"If any eglClientWaitSyncKHR commands are blocking on <sync> when
eglDestroySyncKHR is called, <sync> is flagged for deletion and will
be deleted when the associated fence command or CL event object has
completed, and <sync> is no longer blocking any eglClientWaitSyncKHR
command. Otherwise, the sync object is destroyed immediately."
Sample Code
None
Conformance Tests
None yet
Issues
1) Does this extension need to introduce eglWaitSync
functionality?
RESOLVED: The EGL_KHR_wait_sync extension introduces this, to allow
server-side synchronization, without blocking the client from issuing
commands. Whilst this is not a required dependency, GPU-to-GPU
synchronization is the most likely use of this extension.
2) What should the command to create a sync object linked to an
OpenCL event look like?
RESOLVED: We reuse the general attribute list mechanism rather than
having a constructor specific to CL events. This was intended in the
sync object design from the start.
3) How will the OpenCL header dependencies interact with
specifying the API for this extension?
DISCUSSION: To use this extension, OpenCL event handles of type cl_event
are specified in the attribute lists passed to eglCreateSyncKHR. Because
no formal parameters are of type cl_event, the EGL headers do not need
to define this type. Applications must #include the appropriate OpenCL
header files as well as <EGL/eglext.h> when using this extension.
This issue resolution is consistent with the equivalent issue for
GL_ARB_cl_event.
4) Should all possible statuses of the CL event be reflected through to the
state of the sync object?
DISCUSSION: CL event objects have four execution statuses:
CL_QUEUED, CL_SUBMITTED, CL_RUNNING, and CL_COMPLETE. GL sync
objects have only two statuses: UNSIGNALED and SIGNALED. The
cl_khr_gl_event extension maps UNSIGNALED into CL_SUBMITTED, and
SIGNALED into CL_COMPLETE.
RESOLVED: Invert the cl_khr_egl_event mapping. CL_QUEUED,
CL_SUBMITTED, and CL_RUNNING all map into UNSIGNALED.
CL_COMPLETE maps into SIGNALED.
This issue resolution is consistent with the equivalent issue for
GL_ARB_cl_event.
5) Are there any restrictions on the use of a sync object linked to a CL
event object?
RESOLVED: No restrictions.
6) How are sync object lifetimes defined?
RESOLVED: A sync object linked to a CL event object places a single
reference on the event. Deleting the sync object removes that reference.
eglDestroySync has a dependency on the completion of the linked event
object, and will not delete the sync objectwhile the event object has not
yet completed. This is equivalent to behavior of deleting a fence sync
object, where deletion of the object will be deferred until the underlying
fence command has completed.
This issue resolution is consistent with the equivalent issue for
GL_ARB_cl_event.
7) Should all OpenCL events be supported?
RESOLVED: No. Only events returned by clEnqueueReleaseGLObjects, or
clEnqueueReleaseEGLObjects since those are the only known use cases for
this extension.
8) Why has this extension been obsoleted and replaced by
EGL_KHR_cl_event2?
RESOLVED: Starting with the December 4, 2013 release of EGL 1.4, EGLint
is defined to be the same size as the native platform "int" type. Handle
and pointer attribute values *cannot* be represented in attribute lists
on platforms where sizeof(handle/pointer) > sizeof(int). Existing
extensions which assume this functionality are being replaced with new
extensions specifying new entry points to work around this issue. See
the latest EGL 1.4 Specification for more details.
Revision History
Version 10, 2013/12/04 (Jon Leech) - add issue 8 explaining that OpenCL
event handles cannot be safely passed in attribute lists on 64-bit
platforms, and suggest using EGL_KHR_cl_event2 instead.
Version 9, 2013/08/12 (Jon Leech) - remove unused cl_event type from the
extension and from <EGL/eglext.h> (Bug 10661).
Version 8, 2013/07/19 (Jon Leech) - assign extension number and
missing enum value, and clean up a few typos for publication.
Version 7, 2013/07/08 (Jon Leech) - assign enums (Bug 10490).
Version 6, 2013/06/11 (Alon Or-bach) - typo correction
Version 5, 2013/05/30 (Alon Or-bach) - wording cleanup
Version 4, 2013/05/15 (Alon Or-bach) - updated issue resolutions as agreed,
consistent with GL_ARB_cl_event, including using typedef for cl_event
Version 3, 2013/04/25 (Alon Or-bach) - remove use of CL context,
accept events from clEnqueueAcquireEGLObjects and minor cleanup
Version 2, 2012/06/26 (Jon Leech) - update link to complementary CL
extension.
Version 1, 2010/05/18 (Jon Leech) - initial version based on
equivalent GL_ARB_cl_event extension.
extensions/KHR/EGL_KHR_cl_event2.txt
+364
View File
@@ -0,0 +1,364 @@
Name
KHR_cl_event2
Name Strings
EGL_KHR_cl_event2
Contributors
Jon Leech, Khronos
Alon Or-bach, Samsung Electronics
Tom Cooksey, ARM
Contact
Jon Leech (jon 'at' alumni.caltech.edu)
IP Status
No known claims.
Notice
Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete.
Approved by the EGL Working Group on December 4, 2013.
Version
Version 5, December 4, 2013
Number
EGL Extension #65
Dependencies
EGL 1.4 and the EGL_KHR_fence_sync extension are required.
This extension is written against the language added to EGL 1.2 by
the EGL_KHR_fence_sync extension.
An OpenCL implementation supporting sharing OpenCL event objects
with EGL is required.
Khronos recommends obsoleting and replacing implementations of
EGL_KHR_cl_event with this extension as soon as possible.
Overview
This extension allows creating an EGL sync object linked to an OpenCL
event object, potentially improving efficiency of sharing images between
the two APIs. The companion cl_khr_egl_event extension provides the
complementary functionality of creating an OpenCL event object from an
EGL sync object.
This extension is functionally identical to EGL_KHR_cl_event, but is
intended to replace that extension. It exists only to address an
implementation issue on 64-bit platforms where passing OpenCL event
handles in an EGLint attribute list value is impossible, because the
implementations use a 32-bit type for EGLint.
This extension also incorporates some required functionality from the
EGL_KHR_fence_sync extension, similarly modified for 64-bit platforms.
New Types
/*
* EGLAttribKHR is a integer type used to pass arrays of attribute
* name/value pairs which may include pointer and handle attribute
* values.
*/
#include <khrplatform.h>
typedef intptr_t EGLAttribKHR;
Event handles of type cl_event, defined in the OpenCL header files, may
be included in the attribute list passed to eglCreateSync64KHR.
New Procedures and Functions
EGLSyncKHR eglCreateSync64KHR(
EGLDisplay dpy,
EGLenum type,
const EGLAttribKHR *attrib_list);
New Tokens
Accepted as attribute names in the <attrib_list> argument
of eglCreateSync64KHR:
EGL_CL_EVENT_HANDLE_KHR 0x309C
Returned in <values> for eglGetSyncAttribKHR <attribute>
EGL_SYNC_TYPE_KHR:
EGL_SYNC_CL_EVENT_KHR 0x30FE
Returned in <values> for eglGetSyncAttribKHR <attribute>
EGL_SYNC_CONDITION_KHR:
EGL_SYNC_CL_EVENT_COMPLETE_KHR 0x30FF
Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
Modify the language in section 3.8.1 (Sync Objects) starting at the
sixth paragraph, describing commands to create sync objects:
"The commands
EGLSyncKHR eglCreateSync64KHR(
EGLDisplay dpy,
EGLenum type,
const EGLAttribKHR *attrib_list);
and
EGLSyncKHR eglCreateSyncKHR(
EGLDisplay dpy,
EGLenum type,
const EGLint *attrib_list);
create a sync object ...
... When a fence sync object is created, eglCreateSyncKHR and
eglCreateSync64KHR also insert a fence command into... "
Add following the eigth paragraph (the paragraph beginning "<Fence sync
objects> are created..."):
"A <CL event sync object> reflects the status of a corresponding OpenCL
event object to which the sync object is linked. This provides another
method of coordinating sharing of images between EGL and OpenCL (see
Chapter 9 of the OpenCL 1.0 Specification and the cl_khr_egl_sharing
extension). Waiting on such a sync object is equivalent to waiting for
completion of the linked CL event object.
CL event sync objects may only be created using the command
eglCreateSync64KHR, because they require an attribute which may not be
representable in the attrib_list argument of eglCreateSyncKHR."
Add following the description of fence sync objects (prior to the
"Errors" section for eglCreateSyncKHR):
"If <type> is EGL_SYNC_CL_EVENT_KHR, a CL event sync object is
created. In this case <attrib_list> must contain the attribute
EGL_CL_EVENT_HANDLE_KHR, set to a valid OpenCL event. Note that
EGL_CL_EVENT_HANDLE_KHR is not a queriable property of a sync
object. Attributes of the CL event sync objects are set as follows:
Attribute Name Initial Attribute Value(s)
------------- --------------------------
EGL_SYNC_TYPE_KHR EGL_SYNC_CL_EVENT_KHR
EGL_SYNC_STATUS_KHR Depends on status of <event>
EGL_SYNC_CONDITION_KHR EGL_SYNC_CL_EVENT_COMPLETE_KHR
The status of such a sync object depends on <event>. When the status
of <event> is CL_QUEUED, CL_SUBMITTED, or CL_RUNNING, the status of
the linked sync object will be EGL_UNSIGNALED_KHR. When the status
of <event> changes to CL_COMPLETE, the status of the linked sync
object will become EGL_SIGNALED_KHR.
Creating a linked sync object places a reference on the linked
OpenCL event object. When the sync object is deleted, the reference
will be removed from the event object.
However, implementations are not required to validate the OpenCL
event, and passing an invalid event handle in <attrib_list> may
result in undefined behavior up to and including program
termination."
The command eglCreateSync64KHR must be used to create a CL event sync
object[fn1].
[fn1] If the implementation also supports the older EGL_KHR_cl_event
extension, then eglCreateSyncKHR may also be used to create a CL
event sync object. However, this use is not recommended because it
is not portable to platforms where OpenCL event handles are larger
than 32 bits."
Modify the ninth and tenth paragraphs, starting "When the condition":
"When the condition of the sync object is satisfied, the sync is
signaled by the associated client API context, causing any
eglClientWaitSyncKHR commands (see below) blocking on <sync> to unblock.
The only condition supported for fence sync objects is
EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR, which is satisfied by completion
of the fence command corresponding to the sync object, and all preceding
commands in the associated client API context's command stream. The sync
object will not be signaled until all effects from these commands on the
client API's internal and framebuffer state are fully realized. No other
state is affected by execution of the fence command.
Each client API which supports fence commands indicates this support
in the form of a client API extension. If the GL_OES_EGL_sync
extension is supported by OpenGL ES (either version 1.x or 2.0), a
fence sync object may be created when the currently bound API is
OpenGL ES. If the VG_KHR_EGL_sync extension is supported by OpenVG,
a fence sync object may be created when the currently bound API is
OpenVG.
The only condition supported for CL event sync objects is
EGL_SYNC_CL_EVENT_COMPLETE_KHR, which is satisfied when the status of
the OpenCL event associated with the sync object changes to CL_COMPLETE."
Add to the "Errors" section for eglCreateSyncKHR and eglCreateSync64KHR:
"* If <type> is EGL_SYNC_CL_EVENT_KHR then
** If eglCreateSyncKHR was called, then EGL_NO_SYNC_KHR is returned and
an EGL_BAD_ATTRIBUTE error is generated.
** If eglCreateSync64KHR was called and EGL_CL_EVENT_HANDLE_KHR is not
specified in <attrib_list>, or its attribute value is not a valid
OpenCL event handle returned by a call to clEnqueueReleaseGLObjects
or clEnqueueReleaseEGLObjects, then EGL_NO_SYNC_KHR is returned and
an EGL_BAD_ATTRIBUTE error is generated."
Replace the EGL_SYNC_CONDITION_KHR row of table 3.cc with:
"Attribute Description Supported Sync Objects
----------------- ----------------------- ----------------------
EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR or
EGL_SYNC_CL_EVENT_KHR
Table 3.cc Attributes Accepted by eglGetSyncAttribKHR Command"
Replace the second paragraph describing eglDestroySync with:
"If any eglClientWaitSyncKHR commands are blocking on <sync> when
eglDestroySyncKHR is called, <sync> is flagged for deletion and will
be deleted when the associated fence command or CL event object has
completed, and <sync> is no longer blocking any eglClientWaitSyncKHR
command. Otherwise, the sync object is destroyed immediately."
Sample Code
None
Conformance Tests
None yet
Issues
Note that some issues from the EGL_KHR_cl_event and EGL_KHR_fence_sync
extensions also apply to this extension, which incorporates
functionality from both of those extensions while making it usable on a
64-bit architecture. Issues specific to this extension are below.
1) Why does this extension exist?
The existence of this extension is an unfortunate necessity. Khronos did
not define EGLint as a 64-bit type in the version of <khrplatform.h> we
provided, assuming that vendors on those platforms would do so. By the
time we discovered that not all vendors had done this, it was too late
to fix, because ABI considerations made it impossible for those vendors
to change to a 64-bit EGLint type. Our only option was to define new
extensions and commands using a new attribute type, EGLAttribKHR, which
is explicitly large enough to hold a pointer or handle.
2) What is the relationship of this extension to EGL_KHR_cl_event?
RESOLVED: The only functional difference is that the new
eglCreateSync64KHR command must be used to create CL event sync objects.
This is necessary because some 64-bit platforms define EGLint as a
32-bit type, making it impossible to pass an arbitrary OpenCL event
handle in the EGLint *attrib_list passed to eglCreateSyncKHR.
3) How are pointer- and handle-sized attributes represented?
RESOLVED: Using the new type EGLAttribKHR, which is explicitly defined
as an integer type large enough to hold a pointer.
EGLAttribKHR is defined as an alias of the ISO C intptr_t type, rather
than using one of the explicitly-sized types from khrplatform.h.
Requiring this means that khrplatform.h must make sure to include the
appropriate header file (probably <stdint.h>) and that a C compiler
supporting intptr_t must be used. In the past we were concerned about
older C/C++ compilers, but this seems an acceptable choice in 2013.
We could choose to use intptr_t as the base type of attribute lists,
instead of the EGLAttribKHR alias. As Ian Romanick has pointed out
passionately in ARB discussions, modern C compilers are required to
support a well-defined set of scalar types. There is no requirement to
use API-specific scalar types when explicitly defining a C API.
However, there is some value in semantically tagging parameters with EGL
types. Also, using 'intptr_t *attrib_list' would be cosmetically
objectionable due to mixing EGL* and C native scalar types in EGL APIs.
We probably want to wait until there's an EGL API compatibility break -
a hypothetical "EGL 2.0" - before moving to native ISO C types in our
interfaces.
4) Why is the new fence sync creation function defined here, instead of
in a separate EGL_KHR_fence_sync2 extension?
RESOLVED: eglCreateSync64KHR is defined here because this is the only
functionality requiring it, and we expect this extension to be a stopgap
for 64-bit platforms until the time that EGL 1.5 is defined. The EGL 1.5
core will presumably include only the EGLAttribKHR-based version of this
command.
If there are any new extensions using handle or pointer attributes in
the meantime, they should copy the EGLAttribKHR and eglCreateSync64KHR
language here as required. There is no harm in defining the same type or
command in multiple extensions, so long as the definitions are
compatible.
5) Why is the new command called eglCreateSync64KHR?
UNRESOLVED: For consistency with OpenGL, which has '64'-suffixed
commands for representing 64-bit integers and arbitrary offsets into GPU
memory. If we ever support EGL on 128-bit platforms this would be a
silly naming convention, but that time is probably many decades away and
by then EGL 1.5 should be defined and widely supported. The name
eglCreateSync2KHR was originally suggested.
6) Why is there no command for querying EGLAttribKHR attributes from
sync objects?
RESOLVED: Because the only sync attribute which requires the extra bits
in an EGLAttribKHR type is EGL_CL_EVENT_HANDLE_KHR, which is not
queryable. Sync attributes which are queryable will all fit into the
EGLint returned by eglGetSyncAttribKHR.
NOTE: It's unfortunate that this name is used, since it uses the
"AttribKHR" name for command returning EGLints. In EGL 1.5 we should use
a different name for the query.
7) Does this extension replace EGL_KHR_fence_sync and EGL_KHR_cl_event?
RESOLVED: It does not replace EGL_KHR_fence_sync, but extends it to
support creation of a new type of sync object, the CL event sync object.
RESOLVED: It is intended to replace EGL_KHR_cl_event; this extension
must be used for OpenCL interop on 64-bit platforms, and we hope all
vendors will implement it even on 32-bit platforms, for maximum code
portability.
Revision History
Version 5, 20130/12/04 (Jon Leech) - minor cleanup for public release.
Version 4, 20130/10/16 (Jon Leech) - add Dependencies and Overview text
noting that this extension obsoletes and should replace
EGL_KHR_cl_event.
Version 3, 20130/10/15 (Jon Leech) - change type of EGLAttribKHR from
uintptr to intptr (Bug 11027).
Version 2, 20130/10/12 (Jon Leech) - merge EGL_KHR_fence_sync2 with this
extension, change the naming scheme, define EGLAttribKHR as uintptr_t,
and add a new issues list.
Version 1, 2010/10/02 (Tom Cooksey) - initial version based on
EGL_KHR_cl_event and adding 64-bit EGLAttrKHR variants.
extensions/KHR/EGL_KHR_config_attribs.txt
+234
View File
@@ -0,0 +1,234 @@
Name
KHR_config_attribs
Name Strings
EGL_KHR_config_attribs
Contributors
Jon Leech
Contacts
Jon Leech (jon 'at' alumni.caltech.edu)
Notice
Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete
Version
Version 5, April 5, 2007
Number
EGL Extension #1
Dependencies
Requires EGL 1.2
Some of the extended config attributes defined by this extension are
only relevant when specific client APIs are supported.
This extension is written against the wording of the EGL 1.2
Specification. It exists for backwards compatibility with
functionality introduced in EGL 1.3.
Overview
This extension adds new EGL config attributes and attribute bits
that express limitations of configs on a per-API basis, including
whether client APIs created with respect to a config are expected to
pass conformance, and which optional OpenVG color space and alpha
mask format attributes are valid at surface creation time.
New Types
None
New Procedures and Functions
None
New Tokens
New EGLConfig bitmask attribute name:
EGL_CONFORMANT_KHR 0x3042
Valid bitfields in the EGL_SURFACE_TYPE bitmask attribute
of EGLConfig:
EGL_VG_COLORSPACE_LINEAR_BIT_KHR 0x0020
EGL_VG_ALPHA_FORMAT_PRE_BIT_KHR 0x0040
Additions to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
Add to table 3.1, "EGLConfig attributes":
Attribute Type Notes
--------- ---- -----
EGL_CONFORMANT_KHR bitmask whether contexts created with
this config are conformant
Add to table 3.2, "Types of surfaces supported by an EGLConfig":
EGL Token Name Description
-------------- -----------
EGL_VG_COLORSPACE_LINEAR_BIT_KHR EGLConfig supports OpenVG rendering
in linear colorspace
EGL_VG_ALPHA_FORMAT_PRE_BIT_KHR EGLConfig supports OpenVG rendering
with premultiplied alpha
Add following the second paragraph of "Other EGLConfig Attribute
Descriptions" in section 3.4 on p. 16:
"If EGL_VG_COLORSPACE_LINEAR_BIT_KHR is set in EGL_SURFACE_TYPE,
then the EGL_COLORSPACE attribute may be set to
EGL_COLORSPACE_LINEAR when creating a window, pixmap, or pbuffer
surface (see section 3.5)."
"If EGL_VG_ALPHA_FORMAT_PRE_BIT_KHR is set in EGL_SURFACE_TYPE,
then the EGL_ALPHA_FORMAT attribute may be set to
EGL_ALPHA_FORMAT_PRE when creating a window, pixmap, or pbuffer
surface (see section 3.5)."
Add at the end of the fourth paragraph (description of
EGL_CONFIG_CAVEAT) on p. 17:
"... required OpenGL ES conformance tests (note that
EGL_NON_CONFORMANT_CONFIG is obsolete, and the same information
can be obtained from the EGL_CONFORMANT_KHR attribute on a
per-client-API basis, not just for OpenGL ES."
"EGL_CONFORMANT_KHR is a mask indicating if a client API context
created with respect to the corresponding EGLConfig will pass
the required conformance tests for that API. The valid bit
settings are the same as for EGL_RENDERABLE_TYPE, as defined in
table 3.3, but the presence or absence of each client API bit
determines whether the corresponding context will be conformant
or non-conformant(fn1)."
"(fn1) most EGLConfigs should be conformant for all supported
client APIs. Conformance requirements limit the number of
non-conformant configs that an implementation can define."
Add to the last paragraph of section 3.5.1 on p. 24 (describing
eglCreateWindowSurface):
"If <config> does not support the colorspace or alpha format
attributes specified in <attrib_list> (e.g. if EGL_COLORSPACE is
specified as EGL_COLORSPACE_LINEAR but the EGL_SURFACE_TYPE
attribute of <config> does not include
EGL_VG_COLORSPACE_LINEAR_BIT_KHR, or if EGL_ALPHA_FORMAT is
specified as EGL_ALPHA_FORMAT_PRE but EGL_SURFACE_TYPE does not
include EGL_VG_ALPHA_FORMAT_PRE_BIT_KHR), an EGL_BAD_MATCH error
is generated."
Add to the next-to-last paragraph of section 3.5.2 on p. 26
(describing eglCreatePbufferSurface):
"If <config> does not support the colorspace or alpha format
attributes specified in <attrib_list> (as defined for
eglCreateWindowSurface), an EGL_BAD_MATCH error is generated."
Add to the last paragraph of section 3.5.4 on p. 29 (describing
eglCreatePixmapSurface):
"If <config> does not support the colorspace or alpha format
attributes specified in <attrib_list> (as defined for
eglCreateWindowSurface), an EGL_BAD_MATCH error is generated."
Issues
1) How should colorspace and alpha format restrictions be specified?
OpenVG implementations may not allow linear colorspace or
premultiplied alpha rendering to all configs they support.
RESOLVED: To maximize compatibility with EGL 1.3, we continue to
specify the desired colorspace and alpha format at surface
creation time. However, surface creation may fail if if the
specified colorspace or alpha format are not supported.
To allow apps to detect this situation, this extension adds
EGLConfig attributes specifying *if* linear colorspace and/or
premultiplied alpha formats are supported. If they are not
supported, surface creation with the corresponding attributes
set will fail with an EGL_BAD_MATCH error.
2) How should the colorspace and alpha format capabilities be
exposed in EGLConfigs?
RESOLVED: as bitfields of the existing EGL_SURFACE_TYPE bitmask
attribute.
A separate bitmask might be more orthogonal, but there are
plenty of unused bits in EGL_SURFACE_TYPE and this minimizes API
and programming complexity.
3) Are support for linear colorspace and and premultiplied alpha
formats orthogonal?
RESOLVED: Yes, according to the OpenVG Working Group. If they
were not orthogonal, we could not specify them as independent
bitfields.
4) Should information about conformance be specified on a
per-client-API basis?
RESOLVED: Yes. This is needed for conformance testing and cannot
be expressed by the EGL_CONFIG_CAVEAT attribute, which is OpenGL
ES-specific.
5) Should there also be a config attribute which specifies whether
EGL_RENDER_BUFFER will be respected?
UNRESOLVED: it would be consistent to add this attribute. but
it's not clear if there's a requirement for doing so yet.
6) Does this extension introduce a regression against EGL 1.2?
RESOLVED: Yes. This is unavoidable, since we're allowing failure
of surface creation that was required to succeed in the past.
However, implementations that could not support the required
colorspace or alpha mask format were effectively non-conformant
(e.g. broken) in any event. The new EGL_SURFACE_TYPE attributes
at least allow apps to know that their request will not be
satisfied.
Dependencies on OpenGL ES
If OpenGL ES is not supported, the EGL_OPENGL_ES_BIT in the
EGL_CONFORMANT_KHR is irrelevant.
Dependencies on OpenVG
If OpenVG is not supported, the EGL_OPENVG_BIT bit in
EGL_CONFORMANT_KHR, and the EGL_VG_COLORSPACE_LINEAR_BIT_KHR and
EGL_VG_ALPHA_FORMAT_PRE_BIT_KHR bits in EGL_SURFACE_TYPE, are
irrelevant.
Revision History
Version 5, 2007/04/05 - add enum values corresponding to EGL 1.3
core features.
Version 4, 2006/10/24 - prefix the bitfield names with "VG" to
clarify that they only apply to OpenVG rendering to surfaces
(although the corresponding core EGL_COLORSPACE and
EGL_ALPHA_FORMAT attribute names do not currently include this
prefix). Use "KHR" suffix instead of "OES".
Version 3, 2006/10/15 - add new config attribute to express whether
configs are conformant on a per-API basis. Correct sRGB
terminology to linear (sRGB is the default, linear colorspace
rendering may not be supported). Change extension name
accordingly.
Version 2, 2006/09/26 - add _OES extension suffix to bitfield names.
Version 1, 2006/09/26 - first draft.
extensions/KHR/EGL_KHR_create_context.txt
+648
View File
@@ -0,0 +1,648 @@
Name
KHR_create_context
Name Strings
EGL_KHR_create_context
Contact
Jon Leech (jon 'at' alumni.caltech.edu)
Notice
Copyright (c) 2010-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
IP Status
No known IP claims.
Status
Approved by the Khronos Board of Promoters on February 3, 2012
Updated in version 14 to add ES3 context creation bit - see Issue 8
Version
Version 16, 2015/01/15
Number
EGL Extension #39
Dependencies
EGL 1.4 is required.
Some of the capabilities of these extensions are only available when
OpenGL and OpenGL ES contexts supporting specific versions, specific
profiles, or specific extensions can be created. All such restrictions
are documented in the body of this extension specification.
Overview
With the advent of new versions of OpenGL which deprecate features
and/or break backward compatibility with older versions, there is a need
and desire to indicate at context creation which interface will be used.
This extension adds a new context creation routine with attributes
specifying the OpenGL version, context properties, and profile requested
for the context. It also allows making an OpenGL 3.0 or later context
(or other client API context supporting the ability) current without
providing a default framebuffer. The new context creation attributes
are also defined to work for OpenGL ES context creation when that
makes sense, and the extension has been augmented to allow configs to
advertise support for creating OpenGL ES 3.0 contexts.
New Procedures and Functions
None.
New Tokens
Accepted as an attribute name in the <*attrib_list> argument of
eglCreateContext:
EGL_CONTEXT_MAJOR_VERSION_KHR 0x3098
(this token is an alias for EGL_CONTEXT_CLIENT_VERSION)
EGL_CONTEXT_MINOR_VERSION_KHR 0x30FB
EGL_CONTEXT_FLAGS_KHR 0x30FC
EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR 0x30FD
EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_KHR 0x31BD
Accepted as a bitfield value in the EGL_RENDERABLE_TYPE config
attribute to eglChooseConfig:
EGL_OPENGL_ES3_BIT_KHR 0x0040
Accepted as attribute values for
EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_KHR:
EGL_NO_RESET_NOTIFICATION_KHR 0x31BE
EGL_LOSE_CONTEXT_ON_RESET_KHR 0x31BF
Accepted as bits in the attribute value for EGL_CONTEXT_FLAGS_KHR in
<*attrib_list>:
EGL_CONTEXT_OPENGL_DEBUG_BIT_KHR 0x00000001
EGL_CONTEXT_OPENGL_FORWARD_COMPATIBLE_BIT_KHR 0x00000002
EGL_CONTEXT_OPENGL_ROBUST_ACCESS_BIT_KHR 0x00000004
Accepted as bits in the attribute value for
EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR in <*attrib_list>:
EGL_CONTEXT_OPENGL_CORE_PROFILE_BIT_KHR 0x00000001
EGL_CONTEXT_OPENGL_COMPATIBILITY_PROFILE_BIT_KHR 0x00000002
Additions to the OpenGL / WGL / GLX Specifications
None. This specification is written for EGL.
Additions to the EGL 1.4 Specification
Add to table 3.3 "Types of client APIs supported by an EGLConfig"
"EGL Token Name Client API and Version Supported
---------------------- --------------------------------
EGL_OPENGL_ES3_BIT_KHR OpenGL ES 3.x"
Modify the last sentence of section 3.5.2 "Creating Off-Screen
Rendering Surfaces"
"Finally, an EGL_BAD_ATTRIBUTE error is generated if ... <config> does
not support OpenGL ES rendering (e.g. the EGL_RENDERABLE_TYPE
attribute does not include at least one of EGL_OPENGL_ES_BIT,
EGL_OPENGL_ES2_BIT, or EGL_OPENGL_ES3_BIT_KHR."
Modify section 3.7 "Rendering Contexts" in the paragraph near
the top of page 42:
"Only one OpenGL or OpenGL ES context may be current to a particular
thread, even if the implementation supports OpenGL and one or more
versions of OpenGL ES in the same runtime [fn12]."
Replace section 3.7.1 "Creating Rendering Contexts" from the
sixth paragraph through the end of the subsection with:
"<attrib_list> specifies a list of attributes for the context. The
list has the same structure as described for eglChooseConfig. If an
attribute is not specified in <attrib_list>, then the default value
specified below is used instead. Most attributes are only meaningful
for specific client APIs, and will generate an error when specified
to create for another client API context.
OpenGL and OpenGL ES Context Versions
-------------------------------------
The values for attributes EGL_CONTEXT_MAJOR_VERSION_KHR and
EGL_CONTEXT_MINOR_VERSION_KHR specify the requested client API
version. They are only meaningful for OpenGL and OpenGL ES contexts,
and specifying them for other types of contexts will generate an
error.
When the current rendering API is EGL_OPENGL_ES_API or
EGL_OPENGL_API, the values of EGL_CONTEXT_MAJOR_VERSION_KHR (the
<major version> and EGL_CONTEXT_MINOR_VERSION_KHR (the <minor
version>) request creation of an OpenGL ES or OpenGL context,
respectively, supporting the specified version (<major>.<minor>) of
that client API.
[fn: the EGL 1.4 token EGL_CONTEXT_CLIENT_VERSION is an alias for
EGL_CONTEXT_MAJOR_VERSION_KHR, and the tokens may be used
interchangeably.]
If successful, the context returned must be <backwards compatible>
with the requested version. Backwards compatibility is determined as
follows:
If the current rendering API is EGL_OPENGL_ES_API, then:
* If version 1.0 is requested, the context returned may implement
either OpenGL ES 1.0 or OpenGL ES 1.1.
* If version 1.1 is requested, the context returned must implement
OpenGL ES 1.1.
* If version 2.0, version 3.0, or a later version (when later
versions are defined by Khronos) is requested, the context
returned must implement the requested OpenGL ES version, or any
later version which is backwards compatible with the requested
version.
If the current rendering API is EGL_OPENGL_API, then:
* If a version less than or equal to OpenGL 3.0 is requested, the
context returned may implement any of the following versions:
* Any version no less than that requested and no greater than
3.0.
* Version 3.1, if the GL_ARB_compatibility extension is also
implemented.
* The compatibility profile of version 3.2 or greater.
* If OpenGL 3.1 is requested, the context returned may implement
any of the following versions:
* Version 3.1. The GL_ARB_compatibility extension may or may
not be implemented, as determined by the implementation.
* The core profile of version 3.2 or greater.
* If OpenGL 3.2 or greater is requested, the context returned may
implement any of the following versions:
* The requested profile (see
EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR below) of the requested
version.
* The requested profile of any later version, so long as no
features have been removed from that later version and
profile.
Typically, the implementation will return the most recent version of
OpenGL it supports which is backwards compatible with the requested
version.
Querying the GL_VERSION string with glGetString in either OpenGL or
OpenGL ES (or the GL_MAJOR_VERSION and GL_MINOR_VERSION values with
glGetIntegerv, in an OpenGL 3.0 or later context) will return the
actual version supported by a context.
The default values for EGL_CONTEXT_MAJOR_VERSION_KHR and
EGL_CONTEXT_MINOR_VERSION_KHR are 1 and 0 respectively.
OpenGL Context Profiles
-----------------------
The value for attribute EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR
specifies a <profile> of the OpenGL API. This attribute is only
meaningful for OpenGL contexts, and specifying it for other types of
contexts, including OpenGL ES contexts, will generate an error.
When the current rendering API is EGL_OPENGL_API, the value of
EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR requests an OpenGL context
supporting the corresponding profile. If the
EGL_CONTEXT_OPENGL_CORE_PROFILE_BIT_KHR bit is set in the attribute
value, then a context implementing the <core> profile of OpenGL is
returned. If the EGL_CONTEXT_OPENGL_COMPATIBILITY_PROFILE_BIT_KHR
bit is set, then a context implementing the <compatibility> profile
is returned. If the requested OpenGL version is less than 3.2,
EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR is ignored and the functionality
of the context is determined solely by the requested version.
Querying the value of GL_CONTEXT_PROFILE_MASK with glGetIntegerv
will return the profile mask used to create the context. This query
is only supported in an OpenGL 3.2 or later context.
The default value for EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR is
EGL_CONTEXT_OPENGL_CORE_PROFILE_BIT_KHR. All OpenGL 3.2 and later
implementations are required to implement the core profile, but
implementation of the compatibility profile is optional.
If the core profile is requested, then the context returned cannot
implement functionality defined only by the compatibility profile.
OpenGL and OpenGL ES Context Flags
----------------------------------
The value for attribute EGL_CONTEXT_FLAGS_KHR specifies a set of flag
bits affecting the context. Flag bits are only meaningful when creating
certain types of contexts, as described for each bit below, and
specifying such a flag bit when creating another type of context will
generate an error.
If the EGL_CONTEXT_OPENGL_DEBUG_BIT_KHR flag bit is set in
EGL_CONTEXT_FLAGS_KHR, then a <debug context> will be created. Debug
contexts are intended for use during application development, to
provide additional runtime checking, validation, and logging
functionality while possibly incurring performance penalties. The
additional functionality provided by debug contexts may vary
according to the implementation(fn). In some cases a debug context
may be identical to a non-debug context. This bit is supported for
OpenGL and OpenGL ES contexts.
[fn: Khronos is still defining the expected and required
features of debug contexts, so implementations are
currently free to implement "debug contexts" with little or
no debug functionality. However, OpenGL and OpenGL ES
implementations supporting the GL_KHR_debug extension
should enable it when this bit is set.]
[fn2: See issue 9 below for discussion of backwards
compatibility issues with the debug bit and OpenGL ES
contexts.]
If the EGL_CONTEXT_OPENGL_FORWARD_COMPATIBLE_BIT_KHR flag bit is set
in EGL_CONTEXT_FLAGS_KHR, then a <forward-compatible> context will
be created. Forward-compatible contexts are defined only for OpenGL
versions 3.0 and later. They must not support functionality marked
as <deprecated> by that version of the API, while a
non-forward-compatible context must support all functionality in
that version, deprecated or not. This bit is supported for OpenGL
contexts, and requesting a forward-compatible context for OpenGL
versions less than 3.0 will generate an error.
If the EGL_CONTEXT_OPENGL_ROBUST_ACCESS_BIT_KHR bit is set in
EGL_CONTEXT_FLAGS_KHR, then a context supporting <robust buffer
access> will be created. Robust buffer access is defined in the
GL_ARB_robustness extension specification, and the resulting context
must also support either the GL_ARB_robustness extension, or a
version of OpenGL incorporating equivalent functionality. This bit
is supported for OpenGL contexts.
The default value of EGL_CONTEXT_FLAGS_KHR is zero.
OpenGL Context Reset Notification
---------------------------------
The attribute name
EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_KHR specifies the
<reset notification behavior> of the rendering context. This
attribute is only meaningful for OpenGL contexts, and specifying it
for other types of contexts, including OpenGL ES contexts, will
generate an error.
Reset notification behavior is defined in the GL_ARB_robustness
extension specification, and the resulting context must also support
either the GL_ARB_robustness extension, or a version of OpenGL or
incorporating equivalent functionality. The attribute value may be
either EGL_NO_RESET_NOTIFICATION_KHR or
EGL_LOSE_CONTEXT_ON_RESET_KHR, which respectively result in reset
notification behavior of GL_NO_RESET_NOTIFICATION_ARB and
GL_LOSE_CONTEXT_ON_RESET_ARB, as described by GL_ARB_robustness. The
default value for EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_KHR
is EGL_NO_RESET_NOTIFICATION_KHR.
Errors
------
On failure eglCreateContext returns EGL_NO_CONTEXT and generates an
EGL error with extended error information. Conditions that cause
failure include:
* If an attribute is specified that is not meaningful for the
client API type determined by the current rendering API, an
EGL_BAD_ATTRIBUTE error is generated.
* If the current rendering api is EGL_NONE, then an EGL_BAD_MATCH
error is generated (this situation can only arise in an
implementation which does not support OpenGL ES 1.x, and prior to
the first call to eglBindAPI).
* If share_context is neither EGL_NO_CONTEXT nor a valid context
of the same client API type as the newly created context, then
an EGL_BAD_CONTEXT error is generated.
* If <config> is not a valid EGLConfig, or does not support the
requested client API, then an EGL_BAD_CONFIG error is generated
(this includes requesting creation of an OpenGL ES 1.x, 2.0, or
3.0 context when the EGL_RENDERABLE_TYPE attribute of <config>
does not contain EGL_OPENGL_ES_BIT, EGL_OPENGL_ES2_BIT, or
EGL_OPENGL_ES3_BIT_KHR respectively).
* If <config> does not support a client API context compatible
with the requested API major and minor version, context flags,
and context reset notification behavior (for client API types
where these attributes are supported), then an EGL_BAD_MATCH
error is generated.
* If an OpenGL context is requested, the requested version is
greater than 3.2, and the value for attribute
EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR has no bits set; has any
bits set other than EGL_CONTEXT_OPENGL_CORE_PROFILE_BIT_KHR and
EGL_CONTEXT_OPENGL_COMPATIBILITY_PROFILE_BIT_KHR; has more than
one of these bits set; or if the implementation does not support
the requested profile, then an EGL_BAD_MATCH error is generated.
* If an OpenGL or OpenGL ES context is requested and the server
context state for <share_context> exists in an address space
that cannot be shared with the newly created context, if
<share_context> was created on a different display than the one
referenced by <config>, if the reset notification behavior of
<share_context> and the newly created context are different, or
if the contexts are otherwise incompatible (for example, one
context being associated with a hardware device driver and the
other with a software renderer), then an EGL_BAD_MATCH error is
generated.
* If the server does not have enough resources to allocate the new
context, then an EGL_BAD_ALLOC error is generated.
* If an OpenGL context is requested and the values for attributes
EGL_CONTEXT_MAJOR_VERSION_KHR and EGL_CONTEXT_MINOR_VERSION_KHR,
when considered together with the value for attribute
EGL_CONTEXT_OPENGL_FORWARD_COMPATIBLE_BIT_KHR, specify an OpenGL
version and feature set that are not defined, than an
EGL_BAD_MATCH error is generated.
The defined versions of OpenGL at the time of writing are OpenGL
1.0, 1.1, 1.2, 1.3, 1.4, 1.5, 2.0, 2.1, 3.0, 3.1, 3.2, 4.0, 4.1,
4.2, and 4.3. Feature deprecation was introduced with OpenGL
3.0, so forward-compatible contexts may only be requested for
OpenGL 3.0 and above. Thus, examples of invalid combinations of
attributes include:
- Major version < 1 or > 4
- Major version == 1 and minor version < 0 or > 5
- Major version == 2 and minor version < 0 or > 1
- Major version == 3 and minor version < 0 or > 2
- Major version == 4 and minor version < 0 or > 3
- Forward-compatible flag set and major version < 3
Because the purpose of forward-compatible contexts is to allow
application development on a specific OpenGL version with the
knowledge that the app will run on a future version, context
creation will fail if
EGL_CONTEXT_OPENGL_FORWARD_COMPATIBLE_BIT_KHR is set and the
context version returned cannot implement exactly the requested
version.
* If an OpenGL ES context is requested and the values for
attributes EGL_CONTEXT_MAJOR_VERSION_KHR and
EGL_CONTEXT_MINOR_VERSION_KHR specify an OpenGL ES version that
is not defined, than an EGL_BAD_MATCH error is generated.
The defined versions of OpenGL ES at the time of writing are
OpenGL ES 1.0, 1.1, 2.0, and 3.0. Examples of invalid
combinations of attributes include:
- Major version < 1 or > 3
- Major version == 1 and minor version < 0 or > 1
- Major version == 2 and minor version != 0
- Major version == 3 and minor version != 0
* If an attribute name or attribute value in <attrib_list> is not
recognized (including undefined or unsupported bits in bitmask
attributes), then an EGL_BAD_ATTRIBUTE error is generated."
In section 3.7.3, replace the following two error conditions in the
list of eglMakeCurrent errors:
" * If <ctx> is not a valid context, an EGL_BAD_CONTEXT error is
generated.
* If either <draw> or <read> are not valid EGL surfaces, an
EGL_BAD_SURFACE error is generated."
with the following error conditions:
" * If <ctx> is not a valid context and is not EGL_NO_CONTEXT, an
EGL_BAD_CONTEXT error is generated.
* If either <draw> or <read> are not valid EGL surfaces and are
not EGL_NO_SURFACE, an EGL_BAD_SURFACE error is generated.
* If <ctx> is EGL_NO_CONTEXT and either <draw> or <read> are not
EGL_NO_SURFACE, an EGL_BAD_MATCH error is generated.
* If either of <draw> or <read> is a valid surface and the other
is EGL_NO_SURFACE, an EGL_BAD_MATCH error is generated.
* If <ctx> does not support being bound without read and draw
surfaces, and both <draw> and <read> are EGL_NO_SURFACE, an
EGL_BAD_MATCH error is generated."
Replace the paragraph starting "If <ctx> is EGL_NO_CONTEXT and
<draw> and <read> are not EGL_NO_SURFACE..." with
"If both <draw> and <read> are EGL_NO_SURFACE, and <ctx> is an OpenGL
context supporting version 3.0 or later of the OpenGL API, then no
error is generated and the context is made current without a
<default framebuffer>. The meaning of this is defined in chapter 4
of the OpenGL 3.0 Specification."
Append to the paragraph starting "The first time an OpenGL or OpenGL
ES context is made current..." with
"If the first time <ctx> is made current, it is without a default
framebuffer (e.g. both <draw> and <read> are EGL_NO_SURFACE), then
the viewport and scissor regions are set as though
glViewport(0,0,0,0) and glScissor(0,0,0,0) were called."
Errors
EGL errors for eglCreateContext as described in the body of the
specification.
eglMakeCurrent error behavior is relaxed to allow making an OpenGL
3.0 or later context current without a default read or draw
framebuffer.
Conformance Tests
TBD
Sample Code
TBD
Issues
Non-window-system dependent issues described in the
WGL_ARB_create_context extension specification in the OpenGL
Registry apply to EGL_KHR_create_context.
1) Do enumerant values need to be shared with the equivalent WGL / GLX
extensions?
Mostly not. The only case where it's fairly important that the
values be identical is the EGL_CONTEXT_FLAGS_KHR attribute bitmask
values, which are also exposed through an OpenGL query.
2) Why are some attribute values named EGL_CONTEXT_OPENGL_*?
It is possible that context flags and profiles will eventually be
defined for client APIs other than OpenGL. To allow for this
possibility, the names of the corresponding attribute values are
distinguished. For example, EGL_CONTEXT_FLAGS_KHR currently only has
flags defined for OpenGL context creation, and those flags are named
EGL_CONTEXT_OPENGL_*_BIT_KHR, but in time OpenVG context creation
might allow flags as well. Such flags would be named
EGL_CONTEXT_OPENVG_*_BIT_KHR.
3) Why does EGL_CONTEXT_MAJOR_VERSION_KHR have a distinct numeric token
value when it is functionally equivalent to
EGL_CONTEXT_CLIENT_VERSION?
It no longer has a distinct token value; see issue 1.
4) How will future versions of OpenGL ES interact with this extension?
Later context versions which are backwards compatibile with the
requested version can be returned, just as with OpenGL contexts.
5) What happens when requesting a context requiring OpenGL functionality
that cannot be supported by the underlying GL implementation, such as
requesting lost context reset notification and/or robust buffer access
when the implementation does not support the functionality defined by
GL_ARB_robustness?
Context creation will fail and an EGL_BAD_MATCH error will be
generated. This case is included under the general language of the
fifth bullet point under "Errors" but this issue is added to for
clarity.
6) How is robust buffer access and reset notification supported under
OpenGL ES?
RESOLVED: It is an error to request robust buffer access and/or reset
notification for OpenGL ES contexts. Exposing robust buffer access and
reset notification for OpenGL ES contexts may be defined in a future EGL
extension.
7) Future support for OpenGL ES context creation.
If and when features available for OpenGL context creation are defined
for OpenGL ES context creation in the future, debug contexts, forward
compatible contexts, and robust buffer access contexts may be specified
using separate attributes rather than bitmasks. The reset notification
behavior attribute may be extended to cover OpenGL ES as well as OpenGL.
8) Why was the EGL_OPENGL_ES3_BIT_KHR added in version 13 of the
extension? Doesn't this break backwards compatibility with older
versions of the extension?
Applications need the functionality to be confident that context
creation of an OpenGL ES 3.0 context will succeed (rather than trying
it with different configs until one that succeeds is found).
If this bit is passed into eglChooseConfig and the implementation
supports only an older version of the extension, an EGL_BAD_ATTIBUTE
error should be generated. Since no matching configs will be found, a
robustly-written application will fail (or fall back to an ES 2.0
rendering path) at this point. This is the same application behavior
that should result from not finding a matching config on an
implementation supporting version 13 of the extension, even though the
failure mode is different (EGL error vs. returning no matching
configs). The EGL Working Group considers this sufficiently benign
behavior, and the functionality important enough, to make the change.
9) Why was OpenGL ES support for EGL_CONTEXT_OPENGL_DEBUG_BIT_KHR added
in version 15 of the extension? Doesn't this break backwards
compatibility with older versions of the extension?
Now that the GL_KHR_debug extension is ratified and available,
OpenGL ES implementers needed a way to enable debug functionality,
and wanted to use the same mechanism as OpenGL. There is no
discovery mechanism for this capability, so an application creating
a OpenGL ES context with the debug bit set and running against an
older EGL driver should generate an error. The OpenGL ES Working
Group considers this benign behavior.
10) Which error should be generated if robust buffer access or reset
notifications are requested under OpenGL ES?
As per Issue 6, this extension does not support creating robust contexts
for OpenGL ES. This is only supported via the EGL_EXT_create_context_-
robustness extension.
Attempting to use this extension to create robust OpenGL ES context
will generate an EGL_BAD_ATTRIBUTE error. This specific error is generated
because this extension does not define the EGL_CONTEXT_OPENGL_ROBUST_-
ACCESS_BIT_KHR and EGL_CONTEXT_OPENGL_RESET_NOTIFICATION_STRATEGY_KHR bits
for OpenGL ES contexts. Thus, use of these bits fall under condition
described by: "If an attribute is specified that is not meaningful for
the client API type.." in the above specification.
Revision History
Version 16, 2015/01/15
- Add issue 10.
Version 15, 2013/03/27
- Add OpenGL ES support for debug contexts (Bug 10035).
Version 14, 2012/09/19
- Assign enum value to new bit and published updated extension.
Version 13, 2012/07/29
- Add EGL_OPENGL_ES3_BIT_KHR to table 3.3 and sections 3.5.2, 3.7,
and 3.7.1. Add issue 8 explaining the addition.
Version 12, 2012/07/25
- Explicitly describe new OpenGL 4.3 and OpenGL ES 3.0 versions.
This is not a behavior change (Khronos Bug 9136).
- Make spec consistent so that asking for a forward-compatible GL
context for versions less than 3.0 is an error (Bug 9314).
- Change nonexistent EGL_BAD_PROFILE_KHR error generated when
asking for an unsupported or nonexistent GL profile to an
EGL_BAD_MATCH error (Bug 9314).
- Fix typos in spec body for several new tokens of form
"EGL_CONTEXT_OPENGL_*" which were missing the "OPENGL_" part
(Bug 9314).
Version 11, 2012/07/09 - change nonexistent EGL_BAD_VALUE error
to EGL_BAD_ATTRIBUTE (Khronos Bug 9269).
Version 10, 2011/11/22 - fix typo.
Version 9, 2011/11/09 - resolve issue 6 and add issue 7, limiting
various context creation attributes to apply only to OpenGL and not
to OpenGL ES.
Version 8, 2011/10/20 - change spec body to match BAD_MATCH error
returned in issue 5 when specifying context version and attributes
that collectively cannot be satisfied.
Version 7, 2011/10/19 - add issue 5 clarifying context creation
failures when requesting functionality that cannot be supported by a
GL or ES context, and issue 6 discussing the meaning of "equivalent
to GL_ARB_robustness".
Version 6, 2011/10/19 - minor cleanup & clarification of OpenGL ES
version requests.
Version 5, 2010/09/22 - add context reset notification strategy
attributes from GLX/WGL context creation extensions.
Version 4, 2010/09/22 - fix typo. Assign enumerant values and update
issue 1 to match. Add caveat to errors section so that invalid
attribute values for EGL_CONTEXT_OPENGL_PROFILE_MASK_KHR only raise
errors when requesting an OpenGL context of version 3.2 or greater
(bug 6374). Add issue 4 and allow ES 2.0 context creation requests
to return later versions that are backwards-compatible (bug 6374).
Version 3, 2010/07/21 - remove surfaceless bit in favor of separate
per-client-API extensions which promise that contexts of a given
client API type can be bound without surfaces on that display. Add
robust buffer access bit from equivalent WGL/GLX context creation
extensions. Rename EGL_CONTEXT_FLAGS_KHR so it's not specific to
OpenGL.
Version 2, 2010/06/29 - add EGL_CONTEXT_OPENGL_SURFACELESS_BIT_KHR
context flag bit (bug 6082).
Version 1, 2010/06/29 - Initial version based on equivalent
WGL_ARB_create_context and GLX_ARB_create_context extensions.
extensions/KHR/EGL_KHR_create_context_no_error.txt
+142
View File
@@ -0,0 +1,142 @@
Name
KHR_create_context_no_error
Name Strings
EGL_KHR_create_context_no_error
Contributors
Maurice Ribble
Dominik Witczak
Christophe Riccio
Piers Daniell
Jon Leech
James Jones
Daniel Kartch
Steve Hill
Jan-Harald Fredriksen
Contact
Maurice Ribble (mribble 'at' qti.qualcomm.com)
Status
Complete.
Approved by the Khronos Board of Promoters on May 8, 2015.
Version
Version 6, May 8, 2015
Number
EGL Extension #91
Dependencies
Requires EGL 1.4.
Written against the EGL 1.4 specification.
This spec interacts with GL_KHR_no_error (or equivalent) extension.
Overview
This extension allows the creation of an OpenGL or OpenGL ES context that
doesn't generate errors if the context supports a no error mode. The
implications of this feature are discussed in the GL_KHR_no_error
extension.
New Procedures and Functions
None
New Tokens
Accepted as an attribute name in the <*attrib_list> argument to
eglCreateContext:
EGL_CONTEXT_OPENGL_NO_ERROR_KHR 0x31B3
Additions to the EGL 1.4 Specification
Add the following to section 3.7.1 "Creating Rendering Contexts":
EGL_CONTEXT_OPENGL_NO_ERROR_KHR indicates whether a faster and lower power
mode should be enabled for the OpenGL ES context. In this mode instead of
GL errors occurring as defined in the OpenGL ES spec those errors will
result in undefined behavior. The default value of
EGL_CONTEXT_OPENGL_NO_ERROR_KHR is EGL_FALSE.
Errors
BAD_MATCH is generated if the value of EGL_CONTEXT_OPENGL_NO_ERROR_KHR
used to create <share_context> does not match the value of
EGL_CONTEXT_OPENGL_NO_ERROR_KHR for the context being created.
BAD_MATCH is generated if the EGL_CONTEXT_OPENGL_NO_ERROR_KHR is TRUE at
the same time as a debug or robustness context is specified.
New State
None
Conformance Tests
TBD
Issues
(1) How does this extension interact with debug and robust contexts?
RESOLVED: We decided it is an error in EGL if these bits were set at the same
time.
(2) Can a EGL_CONTEXT_OPENGL_NO_ERROR_KHR contexts share resources with
normal contexts?
RESOLVED: To join a share group all the contexts in that share group must
have this set the same or creation of the context fails.
(3) Can we also do this on GLX/WGL?
RESOLVED: This is an EGL extension. GLX/WGL should be handled with separate
extensions.
(4) Should this extension also expose a "no thread safety" mode? For example
to do the rendering on one thread but uploading data or compiling shaders
from others threads without having the cost of threaded safety kicking in
because none of these tasks overlap so we can handle with sync objects.
Compiling shaders, loading data and rendering are areas that removed
threading may help.
RESOLVED: No, this should be done as a separate extension.
(5) Should this be GL specific?
RESOLVED: Yes, because other context creation tokens have been API specific.
This is also the safer path since it's unknown if other APIs might want to do
this slightly differently.
(6) Should creating a context fail if the context created context does not
support a no error mode?
RESOLVED: No. Expect context creation to succeed even if the implementation
can't honor the request for a no error context. This reduces the number of
reasons creating a context can fail and seems to be a more forward looking
resolution considering context flags allow GL apps to query what context
flags are set.
Revision History
Rev. Date Author Changes
---- ------------ --------- ----------------------------------------
1 Jan 28, 2015 ribble Initial version
2 Jan 29, 2015 ribble Added issues list
3 Jan 30, 2015 ribble Split into separate GL and EGL extensions
4 Feb 18, 2015 ribble Resolved issues and cleanup
5 Feb 25, 2015 ribble Rename, better define errors and cleanup
6 May 8, 2015 Jon Leech Assign enum value and release.
extensions/KHR/EGL_KHR_debug.txt
+573
View File
@@ -0,0 +1,573 @@
Name
KHR_debug
Name Strings
EGL_KHR_debug
Contributors
Jeff Vigil, Qualcomm
Brian Ellis, Qualcomm
(Original contributors of Gl_KHR_debug extension for OpenGL/GL_ES)
Mark Callow, HI
John Leech, Khronos
Ray Smith, ARM
Prabindh Sundareson, Texas Instruments
James Jones, NVIDIA
Jesse Hall, Google
Contact
Jeff Vigil (jvigil 'at' qualcomm.com)
Notice
Copyright (c) 2012-2015 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete. Approved by the EGL Working Group on 2015/04/24.
Approved by the Khronos Board of Promoters on 2015/06/26.
Version
Version 18, Modified Date: September 28, 2016
Number
EGL Extension #92
Extension Type
EGL client extension
Dependencies
Applicable to any version of EGL 1.x, but written in relationship
to EGL 1.5.
Overview
This extension allows EGL to notify applications when various events
occur that may be useful during application development and debugging.
These events are represented in the form of debug messages with a
human-readable string representation. Examples of debug events include
errors due to incorrect use of the EGL API, warnings of undefined behavior,
and performance warnings.
The "type" of the message roughly identifies the nature of the event that
caused the message. Examples include input errors, performance
information, or warnings about undefined behavior.
Messages are communicated to the application through an application-
defined callback function that is called by the EGL implementation on
each debug message. The motivation for the callback routine is to free
application developers from actively having to query whether an EGL error,
or any other debuggable event has happened after each call to a EGL
function. With a callback, developers can keep their code free of debug
checks, set breakpoints in the callback function, and only have to react
to messages as they occur. The callback also offers much more information
than just an error code.
To control the volume of debug output, types of messages can be enabled or
disabled. The mechanism is controlled by attributes passed to EGL. The
state of the message type control can be queried.
Debug output can be enabled and disabled by changing the callback function.
NULL will disable the feature while a valid function pointer will enable
it.
Finally, this extension defines a mechanism for EGL applications to
label their objects (contexts, surfaces, syncs, etc.) with a pointer
to an application provided structure. This pointer can be a descriptive
string, identifier or pointer to a structure. This enables the application
to associate the EGL object with application information. EGL will not
interpret this pointer as a string or any other meaning - just attach to
the object and pass back in the callback when that object is the primary
object of an event.
IP Status
No known IP claims.
New Procedures and Functions
EGLint eglDebugMessageControlKHR(
EGLDEBUGPROCKHR callback,
const EGLAttrib* attrib_list);
EGLBoolean eglQueryDebugKHR(
EGLint attribute,
EGLAttrib* value);
EGLInt eglLabelObjectKHR(
EGLDisplay display,
EGLenum objectType,
EGLObjectKHR object,
EGLLabelKHR label);
New Types
A general type to identify EGL objects, such as EGLSurface or EGLContext.
typedef void* EGLObjectKHR;
A label is a string, ID or pointer to a structure that the application
can attach to an EGL object.
typedef void* EGLLabelKHR;
The callback function that applications can define, and is accepted by
eglDebugMessageControlKHR, is defined as:
typedef void (APIENTRY *EGLDEBUGPROCKHR)(
EGLenum error,
const char *command,
EGLint messageType,
EGLLabelKHR threadLabel,
EGLLabelKHR objectLabel,
const char* message);
New Tokens
Tokens accepted by the <objectType> parameter of function
eglLabelObjectKHR:
EGL_OBJECT_THREAD_KHR 0x33B0
EGL_OBJECT_DISPLAY_KHR 0x33B1
EGL_OBJECT_CONTEXT_KHR 0x33B2
EGL_OBJECT_SURFACE_KHR 0x33B3
EGL_OBJECT_IMAGE_KHR 0x33B4
EGL_OBJECT_SYNC_KHR 0x33B5
EGL_OBJECT_STREAM_KHR 0x33B6
Tokens provided by the <messageType> parameter of EGLDEBUGPROCKHR
or the attributes input to eglControlDebugMessageKHR or attribute
of eglQueryDebugKHR:
EGL_DEBUG_MSG_CRITICAL_KHR 0x33B9
EGL_DEBUG_MSG_ERROR_KHR 0x33BA
EGL_DEBUG_MSG_WARN_KHR 0x33BB
EGL_DEBUG_MSG_INFO_KHR 0x33BC
Tokens provided by the input attribute to eglQueryDebugKHR:
EGL_DEBUG_CALLBACK_KHR 0x33B8
Additions to Chapter 3 of the EGL 1.5 Specification
(EGL Functions and Errors)
Add new Section 3.13:
"3.13 - Debug Output
Application developers can obtain more information from EGL runtime in
the form of debug output. This information can include details about EGL
errors, undefined behavior, implementation-dependent performance warnings,
or other useful hints.
This information is communicated through a stream of debug messages that
are generated as EGL commands are executed. The application can
receive these messages through a callback routine.
Controls are provided for disabling classes of messages that the
application does not care about.
Debug output functionality is controlled with:
EGLint eglDebugMessageControlKHR(
EGLDEBUGPROCKHR callback,
const EGLAttrib* attrib_list);
If the <callback> parameter is NULL, then no messages are sent to the
callback function and the debug message generation is disabled. If the
<callback> parameter is a pointer to a valid callback function, as defined
by EGLDEBUGPROCKHR, then messages will be sent to that callback function.
The attribute list <attrib_list> contains a set of message type enums,
and each has a value of EGL_TRUE to enable that class of messages,
or value EGL_FALSE to disable that class of message.
If the <attrib_list> contains an unknown attribute or value the function
will return a EGL_BAD_ATTRIBUTE error.
If there is no error, then the function will set the updated callback,
set the updated message types and return EGL_SUCCESS.
The messages types, their purpose and initial states are given in
table 13.1 below. The parameter <attrib_list> needs only contain the
attributes to change; an application can call eglDebugMessageControl more
than once with a valid callback, and change the message type states as
desired.
When the callback is set to NULL; the attributes are reset to their
default values.
Debug Output Message Type Informs about Initial/Default state
------------------------- ------------- ---------------------
EGL_DEBUG_MSG_CRITICAL_KHR Internal EGL driver failures ENABLED
i.e. EGL_BAD_ALLOC,
EGL_CONTEXT_LOST
EGL_DEBUG_MSG_ERROR_KHR Input and bad match errors ENABLED
i.e. EGL_BAD_CONTEXT,
EGL_BAD_PARAMETER...
EGL_DEBUG_MSG_WARN_KHR Warnings, code is EGL_SUCCESS, DISABLED
but message indicates
deprecated or inefficient
operation.
EGL_DEBUG_MSG_INFO_KHR Verbose operation DISABLED
Messages such as object
creation and destruction
or change in state.
---------------------------------------------------------------------------
Table 13.1: Types of debug output messages. Each debug message is associated
with one of these types that describes the nature or class of the message.
3.13.1 - Debug Message Callback
Applications must provide a callback function for receiving debug messages
of the following type:
typedef void (APIENTRY *EGLDEBUGPROCKHR)(
EGLenum error,
const char *command,
EGLint messageType,
EGLLabelKHR threadLabel,
EGLLabelKHR objectLabel,
const char* message);
The function's prototype must follow the type definition of EGLDEBUGPROCKHR.
Only one debug callback can be in-use for the application, and
further calls overwrite the previous callback. Specifying NULL as the
value of <callback> clears the current callback and disables message
output.
The callback will receive the following in its parameters:
<error> will contain an EGL error code, or EGL_SUCCESS, as applicable.
<command> will contain a pointer to a string. Example "eglBindApi".
<messageType> will contain one of the debug message types listed in
table 13.1.
<threadLabel> will contain the label attached to the current thread.
The <threadLabel> will be NULL if not set by the application. If the
message is from an internal thread, the label will be NULL.
<objectLabel> will contain the label attached to the primary object
of the message; Labels will be NULL if not set by the application.
The primary object should be the object the function operates on, see
table 13.2 which provides the recommended mapping between functions and
their primary object. This <objectLabel> may be NULL even though the
application labeled the object. This is because it is possible an error
was raised while executing the command before the primary object was
validated, therefore its label cannot be included in the callback.
<message> will contain a platform specific debug string message;
This string should provide added information to the application
developer regarding the condition that generated the message.
The format of a message is implementation-defined, although it should
represent a concise description of the event that caused the message
to be generated. Message strings can be NULL and should not be assumed
otherwise.
EGL Command Primary object
------------------------- -------------
eglBindAPI thread
eglBindTexImage surface
eglChooseConfig display
eglClientWaitSync sync
eglCopyBuffers surface
eglCreateContext display
eglCreateImage display
eglCreatePbufferFromClientBuffer display
eglCreatePbufferSurface display
eglCreatePixmapSurface display
eglCreatePlatformWindowSurface display
eglCreatePlatformPixmapSurface display
eglCreateSync display
eglCreateWindowSurface display
eglDestroyContext context
eglDestroyImage image
eglDestroySurface surface
eglDestroySync sync
eglGetConfigAttrib display
eglGetConfigs display
eglGetCurrentContext context
eglGetCurrentDisplay display
eglGetCurrentSurface surface
eglGetDisplay thread
eglGetError thread
eglGetPlatformDisplay thread
eglGetSyncAttrib sync
eglInitialize display
eglMakeCurrent context
eglQueryAPI context
eglQueryContext context
eglQueryString display
eglQuerySurface surface
eglReleaseTexImage surface
eglReleaseThread thread
eglSurfaceAttrib surface
eglSwapBuffers surface
eglSwapInterval surface
eglTerminate display
eglWaitClient context
eglWaitGL context
eglWaitNative thread
eglWaitSync sync
eglDebugMessageControlKHR -none-
eglQueryDebugKHR -none-
eglLabelObjectKHR labeled object
---------------------------------------------------------------------------
Table 13.2: Recommendation of primary object in a callback as result
of various EGL commands.
If the application has specified a <callback> function for receiving debug
output, the implementation will call that function whenever any enabled
message is generated. A message must be posted for every error since
debug messages can be used as an alternative to eglGetError() for error
detection and handling. Specifying a callback function does not affect the
behavior of eglGetError; errors are reported through both mechanisms.
Applications that specify a callback function must be aware of certain
special conditions when executing code inside a callback when it is
called by EGL. The memory for <message> is read-only, owned and managed
by EGL, and should only be considered valid for the duration of the
function call. Likewise the <command> string is read-only EGL managed
memory and should be considered valid only for the duration of the
callback.
Setting the label for EGL objects is optional and only intended for
applications to correlate application structures with EGL objects.
All object labels are initially NULL.
The behavior of calling any EGL operation, its client APIs, or window system
functions from within the callback function is undefined and may lead
to program termination. It should not be considered reentrant.
Only one debug callback may be registered at a time; registering a new
callback will replace the previous callback. The callback is used by any
thread that calls EGL, so if the application calls into EGL concurrently
from multiple threads it must ensure the callback is thread-safe.
EGL may employ internal threads to execute EGL commands. These threads can
post debug messages to the callback function. The labels for these
internal threads will be NULL.
3.13.2 Debug Labels:
Debug labels provide a method for annotating any object (context, surface,
sync, etc.) with an application provided label. These labels may then be
used by the debug output or an external tool such as a debugger or profiler
to describe labeled objects.
The command
EGLint eglLabelObjectKHR(
EGLDisplay display,
EGLenum objectType,
EGLObjectKHR object,
EGLLabelKHR label);
enables the application to attach a label to a specified object.
The <display>, <objectType>, and <object> identify the object to be
labeled.
The <label> contains a pointer sized variable to attach to the
object. This label can be a integer identifier, string or pointer to a
application defined structure. EGL will not interpret this value;
it will merely provide it when the object is involved in a callback
message. The label for any object will initially be NULL until set by
the application.
An EGL_BAD_PARAMETER error is returned by eglLabelObjectKHR if <objectType>
doesn't match one of the object type enums. An EGL_BAD_PARAMETER is also
returned if the <objectType> is not a supported type; such as no support
for streams.
An EGL_BAD_PARAMETER error is returned by eglLabelObjectKHR if <object> is
invalid, unknown, NULL, or is not an object created with
EGLDisplay <display>.
When the <objectType> is EGL_OBJECT_THREAD_KHR, the <object> parameter
will be ignored by EGL. The thread is implicitly the active thread. It is
recommended that the application pass a NULL for the <object> parameter in
this case.
When the <objectType> is EGL_OBJECT_DISPLAY_KHR, the <object> parameter
must be the same as the <display> parameter - the Display to label. If
these do not match, in this case, a EGL_BAD_PARAMETER is generated.
The <display> does not need to be initialized for <objectType>
EGL_OBJECT_THREAD_KHR, or EGL_OBJECT_DISPLAY_KHR; However for all other
types it must be initialized in order to validate the <object> for
attaching a label.
If there is no error, then the function will set the label and return
EGL_SUCCESS.
3.13.3 Debug Queries:
The command
EGLBoolean eglQueryDebugKHR(
EGLint attribute,
EGLAttrib* value);
enables the application to query the current value for the debug
attributes. On success the function returns EGL_TRUE.
If <attribute> is a message type enum, the value returned will
be either EGL_TRUE or EGL_FALSE to indicate whether the specified types of
messages are enabled or disabled respectively.
Querying for attribute EGL_DEBUG_CALLBACK_KHR will return the current
callback pointer. This feature is intended to enable layering of the
callback with helper libraries.
Querying for an unknown attribute will result in an EGL_BAD_ATTRIBUTE error
and a return of EGL_FALSE.
Usage Examples
This example shows starting debug messaging and attaching string labels to
newly created objects.
void MyCallBack(EGLenum error,
const char *command,
EGLint messageType,
EGLLabelKHR threadLabel,
EGLLabelKHR objectLabel,
const char* message)
{
printf("Error: %x, With command %s, Type: %d,"
"Thread: %s, Object: %s, Message: %s.",
error, command, messageType, threadLabel, objectLabel, message);
}
EGLint result;
// DEBUG_MSG_ERROR and CRITICAL are enabled by default
EGLAttrib debugAttribs = {EGL_DEBUG_MSG_WARN_KHR, EGL_TRUE, EGL_NONE};
// Start up debug messaging:
result = eglDebugMessageControl(MyCallBack, debugAttribs);
// Label for the rendering thread.
EGLLabelKHR renderThreadLabel = (EGLLabelKHR)"Render thread";
result = eglLabelObject(NULL, EGL_OBJECT_THREAD_KHR, NULL, renderThreadLabel);
EGLDisplay dpy = eglGetDisplay(EGL_DEFAULT_DISPLAY);
EGLLabelKHR myDisplay = (EGLLabelKHR)"Default display";
result = eglLabelObject(dpy, EGL_OBJECT_DISPLAY_KHR, dpy, myDisplay);
eglInitialize(dpy);
EGLLabelKHR renderContextLabel = (EGLLabelKHR)"Render context";
EGLContext ctx = eglCreateContext(dpy, config, NULL, contextAttribs);
result = eglLabelObject(dpy, EGL_OBJECT_CONTEXT_KHR, ctx, renderContextLabel);
Issues
1. Why not use GL_KHR_debug?
RESOLVED: Most EGL use and object creation happens before creating a
GL context. And since EGL operations are thread related - the debug
messages should be too.
2. Is the callback expected only to be called from the thread which it's
registered?
RESOLVED: In most cases when an application thread calls an EGL function,
it is expected that EGL upon detecting an error will callback using that
application thread. However, EGL may have internal helper threads that
execute operations. These threads can callback but will have no
threadLabel. It is the responsibility of EGL to ensure that if these
threads are blocked in the application's callback by a breakpoint; that
EGL does not fail. Internal threads are an implementation detail and
are not required.
Revision History
Revision 18, 2016-07-28 (Jeff Vigil)
- Clarify return values/error codes.
Revision 17, 2015-09-23 (Jeff Vigil)
- Correct type name to "EGLDEBUGPROCKHR". Updated example code.
Revision 16, 2015-04-15 (Jeff Vigil)
- Clarified that <objectLabel> maybe NULL in the callback, if an error
is raised before the primary object handle is validated.
Revision 15, 2015-03-30 (Jeff Vigil)
- Further details to labeling of EGL_OBJECT_DISPLAY_KHR.
Revision 14, 2015-03-27 (Jeff Vigil)
- Further clarification of returns and errors. Add further details to
labeling of EGL_OBJECT_THREAD_KHR and EGL_OBJECT_DISPLAY_KHR.
Revision 13, 2015-03-26 (Jeff Vigil)
- Clarified returns and errors.
Revision 12, 2015-03-24 (Jeff Vigil)
- Improve readability. Add assigned enum values.
Revision 11, 2015-03-02 (Jeff Vigil)
- Clarify text regarding parameter attribute_list and its persistence.
Revision 10, 2015-02-25 (Jeff Vigil)
- Clarify text regarding callback blocking.
- The implementation must provide errors and success in callbacks so
that the callback replaces the use of eglGetError.
- <command> strings are read-only EGL memory.
- Specify default values for attributes.
- Fix typos.
Revision 9, 2015-02-03 (Jeff Vigil)
- Updated contributors.
- Add extension type.
- Add "KHR" to token and function names.
- Fix typos.
- Add query to get current callback pointer.
Revision 8, 2014-12-03 (Jeff Vigil)
- Add table containing recommendation for primary object in the callback.
Revision 7, 2014-10-21 (Jeff Vigil)
- Remove configs as a label-able object.
- Remove redundant text.
- Simplify to one callback per process, not per thread.
Revision 6, 2014-10-17 (Jeff Vigil)
- Add issues.
- Address internal EGL threads posting messages.
Revision 5, 2014-05-27 (Jeff Vigil)
- Add missing text for eglQueryDebug.
- Clarify threading model.
Revision 4, 2014-04-14 (Jeff Vigil)
- Fix due to feedback from EGL WG face-to-face conference.
Revision 3, 2014-04-10 (Jeff Vigil)
- Refinements.
Revision 2, 2014-02-21 (Jeff Vigil)
- Simplify API.
Revision 1, 2013-09-08 (Jeff Vigil)
- Work in progress for F2F, Based on GL_KHR_debug, replace GL with EGL
and remove GL spec specific text.
extensions/KHR/EGL_KHR_display_reference.txt
+242
View File
@@ -0,0 +1,242 @@
Name
KHR_display_reference
Name Strings
EGL_KHR_display_reference
Contributors
James Jones
Daniel Kartch
Contacts
James Jones, NVIDIA (jajones 'at' nvidia.com)
Status
Complete
Ratified by the Khronos Board of Promoters on March 31, 2017.
Version
Version 4 - March 15, 2018
Number
EGL Extension #126
Extension Type
EGL client extension
Dependencies
Written based on the wording of the EGL 1.5 specification.
Requires EGL_EXT_platform_base or EGL 1.5
Interacts with EGL platform extensions.
Interacts with the EGL_EXT_device_query extension.
Overview
The existing semantics of EGLDisplay object lifetimes work well for
applications in which one module manages all EGL usage, and in which
EGL displays are expected to remain available until application
termination once they are instantiated. However, EGL does not
provide reasonable semantics in the case where applications rely on
toolkit libraries which use EGL independently from the application
itself.
This issue can be solved by adding a per-EGLDisplay reference
counter which is incremented by eglInitialize calls. Resource
destruction can then be deferred until a corresponding number of
eglTerminate calls is made. However, switching to this behavior
universally could cause backwards incompatibility problems with
existing applications that assume a single eglTerminate will
immediately free resources regardless of how many times the display
has been initialized.
We therefore must support both behaviors. A new attribute specified
when the EGLDisplay is obtained will indicate whether or not
reference counting is enabled. If an application requests the
EGLDisplay multiple times with different values for this attribute,
two separate displays will be returned. The one potential drawaback
is that these displays will have independent resource spaces, so
objects allocated from one cannot be used by the other. However, the
goal here is to support modules that access EGL independently. In
such a use case, they are not likely to need to share resources with
another module, particularly one that uses a different method for
accessing the display.
New Types
None
New Functions
EGLBoolean eglQueryDisplayAttribKHR(EGLDisplay dpy,
EGLint name,
EGLAttrib *value);
New Tokens
Accepted as an attribute in the <attrib_list> parameter of
eglGetPlatformDisplay and the <name> parameter of
eglQueryDisplayAttribKHR:
EGL_TRACK_REFERENCES_KHR 0x3352
In section "3.2 Initialization":
Remove the sentence in the description of eglGetPlatformDisplay
indicating no valid attribute names are defined, and add the following:
The EGL_TRACK_REFERENCES_KHR attribute may be set to EGL_TRUE or
EGL_FALSE to indicate whether or not an EGLDisplay that tracks
reference counts for eglInitialize and eglTerminate calls (as
described below) is desired. If not specified, the default is
platform dependent. Implementations are not required to support both
EGL_TRUE and EGL_FALSE for this attribute. If separate successful
calls are made to eglGetPlatformDisplay requesting default and non-
default behavior for reference counting, two independent EGLDisplays
will be returned.
Also add to the Errors section:
An EGL_BAD_ATTRIBUTE error is generated if the requested value for
EGL_TRACK_REFERENCES_KHR is not supported.
Replace the first sentence of the second paragraph of the description of
eglInitialize with:
When a previously uninitialized display is initialized, its
reference count will be set to one. Initializing an already-
initialized display is allowed, and will return EGL_TRUE and update
the EGL version numbers, but has no other effect except to increment
the display's reference count if its EGL_TRACK_REFERENCES_KHR
attribute is EGL_TRUE.
Insert after the declaration of eglTerminate:
If the specified display's EGL_TRACK_REFERENCES_KHR attribute is
EGL_FALSE, eglTerminate will immediately set its reference count
to zero. Otherwise, its reference count will be decremented if it
is above zero. When an initialized display's reference count reaches
zero, termination will occur.
Replace the second sentence of the last paragraph with:
All displays start out uninitialized with a reference count of zero.
Add to the end of section "3.3 EGL Queries".
To query non-string attributes of an initialized display, use:
EGLBoolean eglQueryDisplayAttribKHR(EGLDisplay dpy,
EGLint name,
EGLAttrib *value);
On success, EGL_TRUE is returned, and the value of the attribute
specified by <name> is returned in the space pointed to by <value>.
On failure, EGL_FALSE is returned. An EGL_NOT_INITIALIZED error
is generated if EGL is not initialized for <dpy>. An
EGL_BAD_ATTRIBUTE error is generated if <name> is not a valid
value. Currently, the only valid attribute name is
EGL_TRACK_REFERENCES_KHR.
Interactions with EGL_KHR_platform_android:
If eglGetPlatformDisplay() is called with <platform> set to
EGL_PLATFORM_ANDROID_KHR, the default value of
EGL_TRACK_REFERENCES_KHR is EGL_TRUE.
Interactions with EGL_EXT_platform_device, EGL_KHR_platform_gbm,
EGL_KHR_platform_x11, and EGL_KHR_platform_wayland:
If eglGetPlatformDisplay() is called with <platform> set to
EGL_PLATFORM_DEVICE_EXT, EGL_PLATFORM_GBM_KHR, EGL_PLATFORM_X11_KHR,
or EGL_PLATFORM_WAYLAND_KHR, the default value of
EGL_TRACK_REFERENCES_KHR is EGL_FALSE.
Interactions with EGL_EXT_device_query:
The eglQueryDisplayAttribKHR function defined here is equivalent to
eglQueryDisplayAttribEXT defined by EGL_EXT_device_query, and the
attribute names supported are a superset of those provided by both
extensions and any others which rely on them.
Issues
1. What is the default value for EGL_TRACK_REFERENCES_KHR?
RESOLUTION: For backwards compatibility reasons, the default
value is platform-specific. The Android platform has
historically implemented the behavior of
EGL_TRACK_REFERENCES_KHR = EGL_TRUE, while other platforms
defaulted to the opposite behavior. Application components
capable of supporting either behavior will be able to query
the value to determine how to proceed.
2. Should the value of EGL_TRACK_REFERENCES_KHR affect whether
eglGetPlatformDisplay returns a new display handle or an
existing one given otherwise identical parameters?
RESOLUTION: Yes. For any given combination of platform display
handle and other attributes, calling eglGetPlatformDisplay
with different values for EGL_TRACK_REFERENCES_KHR will result
in two different EGLDisplay handles being returned.
Resources created with respect to one of these EGLDisplays will
not be accessible to the other. This restriction is unlikely to
cause issues, because the reference counting is added primarily
to support independent toolkits. Application components which
independently initialize and terminate the display are not
likely to share resources, particularly if they use different
methods for that initialization.
3. Should the new display attribute be queryable?
RESOLUTION: Yes. Not all implemenations will support both TRUE
and FALSE for this attribute. Application components capable of
supporting either value will allow the default to be chosen, and
then query the value to determine how to handle termination.
4. Should implementations which support this extension be required
to support both TRUE and FALSE for the attribute?
RESOLUTION: No. Lack of refcounting in the core specification is
considered by many to be a flaw, and some implementations/platforms
will choose to always provide refcounting behavior. This technically
makes them non-compliant. The addition of this extension should allow
that deviation.
Revision History
#4 (March 15, 2018) Jon Leech
- Change extension number from 118 to 126 to avoid an accidental
collision.
#3 (January 12, 2017) Daniel Kartch
- Change to KHR.
- Allocate enum value.
#2 (November 15, 2016) Daniel Kartch
- Full termination portion split off into separate extension
EGL_XXX_full_termination.
- Update reference counting to have separate EGLDisplays for
the same native display, one with reference counting and
one without.
- Add query function to determine attribute value.
#1 (October 28, 2014) James Jones
- Initial draft as EGL_XXX_display_reference
extensions/KHR/EGL_KHR_fence_sync.txt
+562
View File
@@ -0,0 +1,562 @@
Name
KHR_fence_sync
Name Strings
EGL_KHR_fence_sync
GL_OES_EGL_sync
VG_KHR_EGL_sync
Contributors
Acorn Pooley
Gary King
Gregory Prisament
Jon Leech
Contacts
Acorn Pooley, NVIDIA Corporation (apooley 'at' nvidia.com)
Gary King, NVIDIA Corporation (gking 'at' nvidia.com)
Gregory Prisament, NVIDIA Corporation (gprisament 'at' nvidia.com)
Jon Leech (jon 'at' alumni.caltech.edu)
Notice
Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete. Approved by the EGL Working Group on March 3, 2010.
Approved by the Khronos Board of Promoters on April 30, 2010.
Version
Version 24, January 31, 2014
Number
EGL Extension #20
OpenGL ES Extension #75
OpenVG Extension #7
Dependencies
Requires EGL 1.1
This extension is written against the wording of the EGL 1.2
Specification.
Overview
This extension introduces the concept of "sync objects" into EGL.
Sync objects are a synchronization primitive, representing events
whose completion can be tested or waited upon. This extension
borrows heavily from the GL_ARB_sync extension and introduces a type
of sync object known as a "fence sync object" comparable to the
OpenGL fence sync object. The specification is designed to allow
additional types of sync objects to be easily introduced in later
extensions.
Fence sync objects have corresponding fence commands, which are
inserted into a client API command stream at the time the fence sync
is created. A fence sync object is used to wait for completion of
the corresponding fence command. This allows applications to request
a partial Finish of an API command stream, wherein all commands
issued in a particular client API context will be forced to complete
before control is returned to the calling thread.
This document describes three different extension strings
collectively. The "EGL_KHR_fence_sync" string indicates that fence
syncs and the corresponding interfaces (to create and place a fence,
destroy, query, and wait on) are supported.
The remaining extensions list valid client APIs for fence syncs. The
"GL_OES_EGL_sync" string indicates that a fence sync object can be
created in association with a fence command placed in the command
stream of a bound OpenGL ES context. The "VG_KHR_EGL_sync" string
indicates the same thing for a bound OpenVG context.
New Types
/*
* EGLSyncKHR is an opaque handle to an EGL sync object
*/
typedef void* EGLSyncKHR;
/*
* EGLTimeKHR is a 64-bit unsigned integer representing intervals
* in nanoseconds.
*/
#include <khrplatform.h>
typedef khronos_utime_nanoseconds_t EGLTimeKHR;
New Procedures and Functions
EGLSyncKHR eglCreateSyncKHR(
EGLDisplay dpy,
EGLenum type,
const EGLint *attrib_list);
EGLBoolean eglDestroySyncKHR(
EGLDisplay dpy,
EGLSyncKHR sync);
EGLint eglClientWaitSyncKHR(
EGLDisplay dpy,
EGLSyncKHR sync,
EGLint flags,
EGLTimeKHR timeout);
EGLBoolean eglGetSyncAttribKHR(
EGLDisplay dpy,
EGLSyncKHR sync,
EGLint attribute,
EGLint *value);
New Tokens
Accepted by the <type> parameter of eglCreateSyncKHR, and returned
in <value> when eglGetSyncAttribKHR is called with <attribute>
EGL_SYNC_TYPE_KHR:
EGL_SYNC_FENCE_KHR 0x30F9
Accepted by the <attribute> parameter of eglGetSyncAttribKHR:
EGL_SYNC_TYPE_KHR 0x30F7
EGL_SYNC_STATUS_KHR 0x30F1
EGL_SYNC_CONDITION_KHR 0x30F8
Returned in <value> when eglGetSyncAttribKHR is called with
<attribute> EGL_SYNC_STATUS_KHR:
EGL_SIGNALED_KHR 0x30F2
EGL_UNSIGNALED_KHR 0x30F3
Returned in <value> when eglGetSyncAttribKHR is called with
<attribute> EGL_SYNC_CONDITION_KHR:
EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR 0x30F0
Accepted in the <flags> parameter of eglClientWaitSyncKHR:
EGL_SYNC_FLUSH_COMMANDS_BIT_KHR 0x0001
Accepted in the <timeout> parameter of eglClientWaitSyncKHR:
EGL_FOREVER_KHR 0xFFFFFFFFFFFFFFFFull
Returned by eglClientWaitSyncKHR:
EGL_TIMEOUT_EXPIRED_KHR 0x30F5
EGL_CONDITION_SATISFIED_KHR 0x30F6
Returned by eglCreateSyncKHR in the event of an error:
EGL_NO_SYNC_KHR ((EGLSyncKHR)0)
Changes to Chapter 3 of the EGL 1.2 Specification (EGL Functions and Errors)
Add a new subsection at the end of Section 3.8, page 43
(Synchronization Primitives)
"3.8.1 Sync Objects
In addition to the aforementioned synchronization functions, which
provide an efficient means of serializing client and native API
operations within a thread, <sync objects> are provided to enable
synchronization of client API operations between threads and/or
between API contexts. Sync objects may be tested or waited upon by
application threads.
Sync objects have a status with two possible states: <signaled> and
<unsignaled>. Initially, sync objects are unsignaled. EGL may be
asked to wait for a sync object to become signaled, or a sync
object's status may be queried.
Depending on the type of a sync object, its status may be changed
either by an external event, or by explicitly signaling and
unsignaling the sync.
Sync objects are associated with an EGLDisplay when they are
created, and have <attributes> defining additional aspects of the
sync object. All sync objects include attributes for their type and
their status. Additional attributes are discussed below
for different types of sync objects.
<Fence sync objects> are created in association with a <fence
command> in a client API. When the client API executes the fence
command, an event is generated which signals the corresponding fence
sync object. Fence sync objects may not be explicitly signaled, and
may only change their status once, from the initial unsignaled
status to signaled. Fence sync objects may be used to wait for
partial completion of a client API command stream, as a more
flexible form of glFinish / vgFinish.
The command
EGLSyncKHR eglCreateSyncKHR(
EGLDisplay dpy,
EGLenum type,
const EGLint *attrib_list);
creates a sync object of the specified <type> associated with the
specified display <dpy>, and returns a handle to the new object.
<attrib_list> is an attribute-value list specifying other attributes
of the sync object, terminated by an attribute entry EGL_NONE.
Attributes not specified in the list will be assigned their default
values.
If <type> is EGL_SYNC_FENCE_KHR, a fence sync object is created. In
this case <attrib_list> must be NULL or empty (containing only
EGL_NONE). Attributes of the fence sync object are
set as follows:
Attribute Name Initial Attribute Value(s)
--------------- --------------------------
EGL_SYNC_TYPE_KHR EGL_SYNC_FENCE_KHR
EGL_SYNC_STATUS_KHR EGL_UNSIGNALED_KHR
EGL_SYNC_CONDITION_KHR EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR
When a fence sync object is created, eglCreateSyncKHR also inserts a
fence command into the command stream of the bound client API's
current context (i.e., the context returned by
eglGetCurrentContext), and associates it with the newly created sync
object.
When the condition of the sync object is satisfied by the fence
command, the sync is signaled by the associated client API context,
causing any eglClientWaitSyncKHR commands (see below) blocking on
<sync> to unblock. The only condition currently supported is
EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR, which is satisfied by
completion of the fence command corresponding to the sync object,
and all preceding commands in the associated client API context's
command stream. The sync object will not be signaled until all
effects from these commands on the client API's internal and
framebuffer state are fully realized. No other state is affected by
execution of the fence command.
Each client API which supports fence commands indicates this support
in the form of a client API extension. If the GL_OES_EGL_sync
extension is supported by OpenGL ES (either version 1.x or 2.0), a
fence sync object may be created when the currently bound API is
OpenGL ES. If the VG_KHR_EGL_sync extension is supported by OpenVG,
a fence sync object may be created when the currently bound API is
OpenVG.
Errors
------
* If <dpy> is not the name of a valid, initialized EGLDisplay,
EGL_NO_SYNC_KHR is returned and an EGL_BAD_DISPLAY error is
generated.
* If <attrib_list> is neither NULL nor empty (containing only
EGL_NONE), EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE
error is generated.
* If <type> is not a supported type of sync object,
EGL_NO_SYNC_KHR is returned and an EGL_BAD_ATTRIBUTE error is
generated.
* If <type> is EGL_SYNC_FENCE_KHR and no context is current for
the bound API (i.e., eglGetCurrentContext returns
EGL_NO_CONTEXT), EGL_NO_SYNC_KHR is returned and an
EGL_BAD_MATCH error is generated.
* If <type> is EGL_SYNC_FENCE_KHR and <dpy> does not match the
EGLDisplay of the currently bound context for the currently
bound client API (the EGLDisplay returned by
eglGetCurrentDisplay()) then EGL_NO_SYNC_KHR is returned and an
EGL_BAD_MATCH error is generated.
* If <type> is EGL_SYNC_FENCE_KHR and the currently bound client
API does not support the client API extension indicating it can
place fence commands, then EGL_NO_SYNC_KHR is returned and an
EGL_BAD_MATCH error is generated.
The command
EGLint eglClientWaitSyncKHR(
EGLDisplay dpy,
EGLSyncKHR sync,
EGLint flags,
EGLTimeKHR timeout);
blocks the calling thread until the specified sync object <sync> is
signaled, or until <timeout> nanoseconds have passed.
More than one eglClientWaitSyncKHR may be outstanding on the same
<sync> at any given time. When there are multiple threads blocked on
the same <sync> and the sync object is signaled, all such threads
are released, but the order in which they are released is not
defined.
If the value of <timeout> is zero, then eglClientWaitSyncKHR simply
tests the current status of <sync>. If the value of <timeout> is the
special value EGL_FOREVER_KHR, then eglClientWaitSyncKHR does not
time out. For all other values, <timeout> is adjusted to the closest
value allowed by the implementation-dependent timeout accuracy,
which may be substantially longer than one nanosecond.
eglClientWaitSyncKHR returns one of three status values describing
the reason for returning. A return value of EGL_TIMEOUT_EXPIRED_KHR
indicates that the specified timeout period expired before <sync>
was signaled, or if <timeout> is zero, indicates that <sync> is
not signaled. A return value of EGL_CONDITION_SATISFIED_KHR
indicates that <sync> was signaled before the timeout expired, which
includes the case when <sync> was already signaled when
eglClientWaitSyncKHR was called. If an error occurs then an error is
generated and EGL_FALSE is returned.
If the sync object being blocked upon will not be signaled in finite
time (for example, by an associated fence command issued previously,
but not yet flushed to the graphics pipeline), then
eglClientWaitSyncKHR may wait forever. To help prevent this behavior
(footnote1), if the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR bit is set in
<flags>, and <sync> is unsignaled when eglClientWaitSyncKHR is
called, then the equivalent of Flush() will be performed for the
current API context (i.e., the context returned by
eglGetCurrentContext()) before blocking on <sync>. If no context is
current for the bound API, the EGL_SYNC_FLUSH_COMMANDS_BIT_KHR bit
is ignored.
[footnote 1: The simple Flush behavior defined by
EGL_SYNC_FLUSH_COMMANDS_BIT_KHR will not help when waiting for a
fence command issued in a different context's command stream.
Applications which block on a fence sync object must take
additional steps to ensure that the context from which the
associated fence command was issued has flushed that command to
the graphics pipeline.]
Errors
------
* If <sync> is not a valid sync object for <dpy>, EGL_FALSE is
returned and an EGL_BAD_PARAMETER error is generated.
* If <dpy> does not match the EGLDisplay passed to
eglCreateSyncKHR when <sync> was created, the behaviour is
undefined.
The command
EGLBoolean eglGetSyncAttribKHR(
EGLDisplay dpy,
EGLSyncKHR sync,
EGLint attribute,
EGLint *value);
is used to query attributes of the sync object <sync>. Legal values
for <attribute> depend on the type of sync object, as shown in table
3.cc. Assuming no errors are generated, EGL_TRUE is returned and the
value of the queried attribute is returned in <value>.
Attribute Description Supported Sync Objects
----------------- ----------------------- ----------------------
EGL_SYNC_TYPE_KHR Type of the sync object All
EGL_SYNC_STATUS_KHR Status of the sync object All
EGL_SYNC_CONDITION_KHR Signaling condition EGL_SYNC_FENCE_KHR only
Table 3.cc Attributes Accepted by eglGetSyncAttribKHR Command
Errors
------
* If <sync> is not a valid sync object for <dpy>, EGL_FALSE is
returned and an EGL_BAD_PARAMETER error is generated.
* If <dpy> does not match the display passed to eglCreateSyncKHR
when <sync> was created, the behaviour is undefined.
* If <attribute> is not one of the attributes in table 3.cc,
EGL_FALSE is returned and an EGL_BAD_ATTRIBUTE error is
generated.
* If <attribute> is not supported for the type of sync object
passed in <sync>, EGL_FALSE is returned and an EGL_BAD_MATCH
error is generated.
If any error occurs, <*value> is not modified.
The command
EGLBoolean eglDestroySyncKHR(
EGLDisplay dpy,
EGLSyncKHR sync);
is used to destroy an existing sync object.
If any eglClientWaitSyncKHR commands are blocking on <sync> when
eglDestroySyncKHR is called, <sync> is flagged for deletion and will
be deleted when it is no longer associated with any fence command
and is no longer blocking any eglClientWaitSyncKHR command.
If no errors are generated, EGL_TRUE is returned, and <sync> will no
longer be the handle of a valid sync object.
Errors
------
* If <sync> is not a valid sync object for <dpy>, EGL_FALSE is
returned and an EGL_BAD_PARAMETER error is generated.
* If <dpy> does not match the display passed to eglCreateSyncKHR
when <sync> was created, the behaviour is undefined.
Issues
Note about the Issues
---------------------
The wording for this extension was originally written as a single
extension defining two types of sync object; a "reusable sync
object" and a "fence sync object". That extension was split to
produce standalone extensions for each type of sync object, and
references to the other type removed from the specification
language. This issues list has been simplied to remove references to
reusable sync objects but is otherwise very similar to the
EGL_KHR_reusable_sync extension issues list.
1. [REMOVED - found in the reusable_sync extension.]
2. [REMOVED - found in the reusable_sync extension.]
3. What does this extension provide that can not be accomplished
with the existing, more efficient eglWaitClient and eglWaitNative
API functions?
RESPONSE: eglWaitClient and eglWaitNative may be implemented in
extremely lightweight manners, in some cases not blocking the
calling thread at all; however, they can not be used to synchronize
between client API contexts and native APIs executing in separate
threads (or simply between client API contexts executing in separate
threads), such as between a thread with an active OpenGL context and
a second thread performing video decode.
4. What does this extension provide that could not be accomplished
with native platform synchronization primitives and the existing
client API Finish commands?
RESPONSE: This extension provides a lighter-weight mechanism for
synchronizing an application with client API command streams than
the all-or-nothing Finish commands, enabling applications to block
until a subset of issued client API commands have completed.
5. [REMOVED - found in the reusable_sync extension.]
6. Please provide a more detailed description of how
eglClientWaitSyncKHR behaves.
RESOLVED: eglClientWaitSyncKHR blocks until the status of the sync
object transitions to the signaled state. Sync object status is
either signaled or unsignaled. More detailed rules describing
signalling follow (these may need to be imbedded into the actual
spec language):
* A fence sync object has two possible status values: signaled or
unsignaled.
* When created, the status of the sync object is unsignaled.
* A fence command is inserted into a command stream. A fence sync
object is not.
* A fence command, once its condition has been met, will set its
associated sync object to the signaled state. The only condition
currently supported is EGL_SYNC_PRIOR_COMMANDS_COMPLETE_KHR.
* A wait function, such as ClientWaitSyncKHR, waits on a fence
sync object, not on a fence command.
* A wait function called on a sync object in the unsignaled state
will block. It unblocks (note, not "returns to the application")
when the sync object transitions to the signaled state.
* A wait function called on a sync object in the signaled state
will return immediately.
7. [REMOVED - found in the reusable_sync extension.]
8. [REMOVED - found in the reusable_sync extension.]
9. Should eglDestroySyncKHR release all WaitSyncs placed on a fence
sync object?
RESOLVED: No. (note that this behavior differs from reusable syncs.)
Fence sync objects are intended to be signalled by the graphics
driver within a short period of time (typically less than 1 second
after creation) and so should not cause waiting threads to hang
forever. To reduce implementation complexity, fence sync objects are
defined to not release waiting threads; waiting threads are released
normally when their condition is satisfied or their timeout expires.
The handle to a fence sync object immediately becomes invalid
following a call to eglDestroySyncKHR.
Revision History
#24 (Jon Leech, January 31, 2014)
- Clarify return value of ClientWaitSyncKHR when called with <timeout>
of zero for an unsignaled <sync> (Bug 11576).
#23 (Jon Leech, April 23, 2013)
- Simplify issues list to remove issues specific to reusable sync
objects and general sync object design issues.
#22 (Jon Leech, June 15, 2010)
- Correct minor typos in GL/VG extension names.
#21 (Jon Leech, May 5, 2010)
- Correct minor typos, assign extension numbers for EGL, OpenGL ES,
and OpenVG, and publish in the registry,
#20 (Robert Palmer, July 14, 2009)
- Branch wording from draft KHR_sync specification. Remove ability
to create "reusable sync objects and all tokens/wording specific
to them.
#19 (Robert Palmer, July 22, 2009)
- Replace specific eglCreateSyncKHR error cases for bad <type>
argument with extensible catch-all case.
#18 (Robert Palmer, July 8, 2009)
- Issues 8 and 9 declared resolved in EGL meeting 2009-07-08
#17 (Robert Palmer, July 8, 2009)
- Update eglDestroySyncKHR to special-case deletion of fence sync
objects. This is explained in issue 9.
- Corrected EGL_REUSABLE_SYNC_KHR -> EGL_SYNC_REUSABLE_KHR
- Define value for EGL_SYNC_REUSABLE_KHR
- Fix typo and whitespace
#16 (Jon Leech, July 7, 2009)
- Update description of new tokens to match changes to the
eglCreateSyncKHR entry point in revision 15.
#15 (Jon Leech, June 16, 2009)
- Define separate one-time fence sync and reusable sync extensions
and corresponding extension strings. Remove AUTO_RESET and
eglFenceKHR. Rename eglCreateFenceSyncKHR to eglCreateSyncKHR and
change initial status of reusable syncs to unsignaled. Clarify
which functions apply to which types of sync objects. Update
issues list.
#14 (Jon Leech, April 29, 2009)
- Clarify that all waiters are woken up on signalling a sync.
Remove tabs to cleanup some formatting issues.
#13 (Acorn Pooley, April 2, 2009)
- Renamed
GL_OES_egl_sync -> GL_OES_EGL_sync
VG_KHR_egl_sync -> VG_KHR_EGL_sync
#12 (Jon Leech, April 1, 2009)
- Changed sync flags type from EGLuint to EGLint and add issue 7.
#11 (Acorn Pooley, February 4, 2009)
- add error case to eglGetSyncAttribKHR.
- fix year on rev 8-10 (2008->2009)
#10 (Acorn Pooley, February 4, 2009)
- clarify some error message descriptions
#9 (Greg Prisament, January 15, 2009)
- Destroy now wakes up all waits (eglClientWaitSyncKHR)
- Add EGLDisplay <dpy> as first parameter to all commands
- Split into 3 extension strings, EGL_KHR_sync, GL_OES_egl_sync,
VG_KHR_egl_sync, all described in this document.
- Add attribute AUTO_RESET_KHR
- Time type uses the type from khrplatform.h
- Remove EGL_ALREADY_SIGNALLED
#8 (Jon Leech, November 11, 2009)
- Assign enum values
#7 (Acorn Pooley, October 30, 2008)
- Fix typos
- remove obsolete wording about Native sync objects (see issue 5)
- formatting: remove tabs, 80 columns
#6 (Acorn Pooley, October 27, 2008)
- Corrected 'enum' to 'EGLenum' in prototypes.
#5 (Jon Leech, September 9, 2008)
- Removed native sync support (eglCreateNativeSyncKHR and
EGL_SYNC_NATIVE_SYNC_KHR), and re-flowed spec to fit in 80 columns.
#4 (Jon Leech, November 20, 2007)
- Corrected 'enum' to 'EGLenum' in prototypes.
#3 (Jon Leech, April 5, 2007)
- Added draft Status and TBD Number
#2 (November 27, 2006)
- Changed OES token to KHR
extensions/KHR/EGL_KHR_get_all_proc_addresses.txt
+206
View File
@@ -0,0 +1,206 @@
Names
KHR_get_all_proc_addresses
KHR_client_get_all_proc_addresses
Name Strings
EGL_KHR_get_all_proc_addresses
EGL_KHR_client_get_all_proc_addresses
Contributors
Jon Leech
Marcus Lorentzon
Robert Palmer
Acorn Pooley
Greg Prisament
Chad Versace
Contacts
James Jones, NVIDIA (jajones 'at' nvidia.com)
Notice
Copyright (c) 2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete. Approved by the EGL Working Group on April 3, 2013.
Ratified by the Khronos Board of Promoters on July 19, 2013.
Version
Version 3 - July 31, 2013
Number
EGL Extension #61
Extension Types
EGL_KHR_get_all_proc_addresses is an EGL display extension
EGL_KHR_client_get_all_proc_addresses is an EGL client extension
Dependencies
EGL 1.2 is required.
This extension is written based on the wording of the EGL 1.4
specification.
Interacts with EGL_EXT_client_extensions.
Overview
eglGetProcAddress is currently defined to not support the querying
of non-extension EGL or client API functions. Non-extension
functions are expected to be exposed as library symbols that can
be resolved statically at link time, or dynamically at run time
using OS-specific runtime linking mechanisms.
With the addition of OpenGL and OpenGL ES 3 support to EGL, the
definition of a non-extension function becomes less clear. It is
common for one OpenGL library to implement many versions of
OpenGL. The suggested library name for OpenGL ES 3 is the same as
that of OpenGL ES 2. If OpenGL ES 3 applications linked
statically to OpenGL ES 3 functions are run on a system with only
OpenGL ES 2 support, they may fail to load. Similar problems
would be encountered by an application linking statically to
various OpenGL functions.
To avoid requiring applications to fall back to OS-specific
dynamic linking mechanisms, this extension drops the requirement
that eglGetProcAddress return only non-extension functions. If
the extension string is present, applications can query all EGL
and client API functions using eglGetProcAddress.
To allow users to query this extension before initializing a display, and
to also allow vendors to ship this extension without
EGL_EXT_client_extensions, two names are assigned to this extension: one
a display extension and the other a client extension. Identical
functionality is exposed by each name, but users query each name using
different methods. Users query EGL_KHR_get_all_proc_addresses in the
usual way; that is, by calling eglQueryString(dpy, EGL_EXTENSIONS) on an
initialized display. To query EGL_KHR_client_get_all_proc_addresses,
users must use a different method which is described below in the section
concerning EGL_EXT_client_extensions.
New Types
None
New functions
None
New Tokens
None
Rename section "3.10 Obtaining Extension Function Pointers" to "3.10
Obtaining Function Pointers", and replace its content with the
following:
"The client API and EGL extensions and versions which are available to a
client may vary at runtime, depending on factors such as the rendering
path being used (hardware or software), resources available to the
implementation, or updated device drivers. Therefore, the address of
functions may be queried at runtime. The function
void (*eglGetProcAddress(const char *procname))(void);
returns the address of the function named by <procName>. <procName> must
be a NULL-terminated string. The pointer returned should be cast to a
function pointer matching the function's definition in the corresponding
API or extension specification. A return value of NULL indicates that
the specified function does not exist for the implementation.
A non-NULL return value for eglGetProcAddress does not guarantee that a
function is actually supported at runtime. The client must also make a
corresponding query, such as glGetString(GL_EXTENSIONS) for OpenGL and
OpenGL ES extensions; vgGetString(VG_EXTENSIONS) for OpenVG extensions;
eglQueryString(dpy, EGL_EXTENSIONS) for EGL extensions; or query the
corresponding API's version for non-extension functions, to determine if
a function is supported by a particular client API context or display.
Client API function pointers returned by eglGetProcAddress are
independent of the display and the currently bound client API context,
and may be used by any client API context which supports the function.
eglGetProcAddress may be queried for all EGL and client API extension
and non-extension functions supported by the implementation (whether
those functions are supported by the current client API context or not).
For functions that are queryable with eglGetProcAddress, implementations
may also choose to export those functions statically from the object
libraries implementing them. However, portable clients cannot rely on
this behavior."
Interactions with EGL_EXT_client_extensions
The EGL specification describes the behavior of eglGetProcAddress as
independent of any display. Therefore, this extension's functionality
falls under the classification 'client extension' rather than 'display
extension'. Accordingly, users may wish to query this extension before
initializing a display.
If the EGL_EXT_client_extensions is supported, then users can query this
extension by checking for the name EGL_KHR_client_get_all_proc_addresses
in the extension string of EGL_NO_DISPLAY.
The EGL implementation must expose the name
EGL_KHR_client_get_all_proc_addresses if and only if it exposes
EGL_KHR_get_all_proc_addresses and supports EGL_EXT_client_extensions.
This requirement eliminates the problematic situation where, if an EGL
implementation exposed only one name, then an EGL client would fail to
detect the extension if it queried only the other name.
Despite having two names assigned to this extension, the restrictions
described in EGL_EXT_client_extensions still apply. As
EGL_KHR_client_get_all_proc_addresses is defined as a client extension,
its name can appear only in the extension string of EGL_NO_DISPLAY and
not in the extension string of any valid display. The converse applies
to EGL_KHR_get_all_proc_addresses, as it is defined as a display
extension.
Issues
1. What should this spec be called?
PROPOSED: KHR_get_all_proc_addresses
2. Should this extension be classified as a client extension, as defined
by EGL_EXT_client_extensions?
DISCUSSION: Yes and no.
Yes, because this extension exposes functionality that is solely
a property of the EGL library itself, independent of any display.
Such functionality falls under the classification of 'client
extension'.
No, because classifying it as a client extension would create
a dependency on EGL_EXT_client_extensions, and there exists no
precedent for a KHR extension that depends on an EXT extension.
RESOLUTION: Expose this extension under two names, one a client
extension and the other a display extension.
Revision History
#3 (July 31, 2013) Chad Versace
- Assign additional name, EGL_KHR_client_get_all_proc_addresses.
- Add section "Extension Types", section "Interactions with
EGL_EXT_client_extensions", and issue #2.
#2 (March 6, 2013) Jon Leech
- Bring into sync with latest EGL 1.4 spec update and simplify
language describing which functions may be queried. Minor
formatting changes for greater consistency with other KHR
extension specs.
#1 (February 4, 2013) James Jones
- Initial draft
extensions/KHR/EGL_KHR_gl_colorspace.txt
+197
View File
@@ -0,0 +1,197 @@
Name
KHR_gl_colorspace
Name Strings
EGL_KHR_gl_colorspace
Contact
Jon Leech (jon 'at' alumni.caltech.edu)
IP Status
No known IP claims.
Status
Complete.
Version 3 approved by the EGL Working Group on September 13, 2013.
Ratified by the Khronos Board of Promoters on December 13, 2013.
Version
Version 5, 2014/07/15
Number
EGL Extension #66
Dependencies
EGL 1.4 is required.
Some of the capabilities of these extensions are only available via
OpenGL or OpenGL ES contexts supporting sRGB default framebuffers,
as defined below.
Overview
Applications may wish to use sRGB format default framebuffers to
more easily achieve sRGB rendering to display devices. This
extension allows creating EGLSurfaces which will be rendered to in
sRGB by OpenGL contexts supporting that capability.
New Procedures and Functions
None.
New Tokens
Accepted as an attribute name by eglCreateWindowSurface,
eglCreatePbufferSurface and eglCreatePixmapSurface
EGL_GL_COLORSPACE_KHR 0x309D
Accepted as attribute values for EGL_GL_COLORSPACE_KHR by
eglCreateWindowSurface, eglCreatePbufferSurface and
eglCreatePixmapSurface
EGL_GL_COLORSPACE_SRGB_KHR 0x3089
EGL_GL_COLORSPACE_LINEAR_KHR 0x308A
(these enums are aliases of the corresponding VG colorspace
attribute values from EGL 1.3)
Additions to the EGL 1.4 Specification
Modify the 2nd paragraph on page 29 in section 3.5.1 "Creating
On-Screen Rendering Surfaces:
"Note that the EGL_GL_COLORSPACE_KHR attribute is used only by OpenGL
and OpenGL ES contexts supporting sRGB framebuffers. EGL itself does
not distinguish multiple colorspace models. Refer to the ``sRGB
Conversion'' sections of the OpenGL 4.3 and OpenGL ES 3.0
specifications for more information."
Add preceding the 4th paragraph on this page:
"EGL_GL_COLORSPACE_KHR specifies the color space used by OpenGL and
OpenGL ES when rendering to the surface[fn1]. If its value is
EGL_GL_COLORSPACE_SRGB_KHR, then a non-linear, perceptually uniform
color space is assumed, with a corresponding
GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of GL_SRGB. If its value
is EGL_GL_COLORSPACE_LINEAR_KHR, then a linear color space is assumed,
with a corresponding GL_FRAMEBUFFER_ATTACHMENT_COLOR_ENCODING value of
GL_LINEAR. The default value of EGL_GL_COLORSPACE_KHR is
EGL_GL_COLORSPACE_LINEAR_KHR.
[fn1] Only OpenGL and OpenGL ES contexts which support sRGB
rendering must respect requests for EGL_GL_COLORSPACE_SRGB_KHR, and
only to sRGB formats supported by the context (normally just SRGB8)
Older versions not supporting sRGB rendering will ignore this
surface attribute. Applications using OpenGL must additionally
enable GL_FRAMEBUFFER_SRGB to perform sRGB rendering, even when an
sRGB surface is bound; this enable is not required (or supported)
for OpenGL ES."
Modify the 4th paragraph on page 30 in section 3.5.2,
"Creating Off-Screen Rendering Surfaces":
"... Attributes that can be specified in <attrib_list> include ...
EGL_GL_COLORSPACE_KHR, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_FORMAT."
Add preceding the second paragraph on page 31 in section 3.5.2:
"EGL_GL_COLORSPACE_KHR has the same meaning and default values as when
used with eglCreateWindowSurface."
Modify the next to last paragraph on page 34 in section 3.5.4,
"Creating Native Pixmap Rendering Surfaces":
"... Attributes that can be specified in <attrib_list> include
EGL_GL_COLORSPACE_KHR, EGL_VG_COLORSPACE, and EGL_VG_ALPHA_FORMAT."
Add preceding the second paragraph on page 35 in section 3.5.4:
"EGL_GL_COLORSPACE_KHR has the same meaning and default values as when
used with eglCreateWindowSurface."
Add to table 3.5 on page 37:
"Attribute Type Description
-------------------- ---- -----------
EGL_GL_COLORSPACE_KHR enum Color space for OpenGL and OpenGL ES"
Errors
New EGL errors as described in the body of the specification (to be
enumerated here in a later draft).
Conformance Tests
TBD
Sample Code
TBD
Issues
1) How about premultiplied alpha?
DISCUSSION: OpenGL doesn't expose this a property of the API, so there's
no point in exposing it through EGL as a hint to GL. Shaders deal with
premultiplied alpha.
2) Do we need to determine EGL_GL_COLORSPACE_KHR from client buffer
attributes in section 3.5.3?
DISCUSSION: probably. Not done yet.
3) How should EGL_GL_COLORSPACE_SRGB_KHR be capitalized?
DISCUSSION: Daniel prefers SRGB. The VG token uses sRGB which is a
rare case of an enum name containing a lower case letter. Currently
the spec uses SRGB.
4) Explain differences in surface creation semantics vs.
EGL_VG_COLORSPACE.
DISCUSSION: The EGL 1.4 spec allows surface creation to fail with a
BAD_MATCH error when requesting an unsupported VG sRGB format. This
is relatively easy to detect since all OpenVG implementations must
support sRGB rendering to specified formats. It is trickier with
OpenGL and OpenGL ES for two reasons:
- Some GL/ES contexts may support sRGB rendering while other
contexts in the same runtime may not.
- Some contexts may support a broader range of sRGB formats than
others.
Possibly we should add EGL_GL_COLORSPACE_SRGB_BIT_KHR to
EGL_SURFACE_TYPE, but we've been deemphasizing EGLConfigs going
forward, and hopefully we can get away without doing this.
Revision History
Version 1, 2013/04/26
- Initial draft based on proposal in bug 9995.
Version 2, 2013/04/26
- GL ES doesn't require GL_FRAMEBUFFER_SRGB enable.
Version 3, 2013/05/15
- Capitalize SRGB in token name, change reference from VG to GL/ES
in section 3.5.1, note that ES does not require FRAMEBUFFER_SRGB
enable, add issue 4, and fix typos (bug 9995).
Version 4, 2013/09/16
- Assign enum values.
Version 5, 2014/07/15
- Fix New Tokens section to include all relevant commands (Bug 12457).
extensions/KHR/EGL_KHR_gl_image.txt
+432
View File
@@ -0,0 +1,432 @@
Name
KHR_gl_texture_2D_image
KHR_gl_texture_cubemap_image
KHR_gl_texture_3D_image
KHR_gl_renderbuffer_image
Name Strings
EGL_KHR_gl_texture_2D_image
EGL_KHR_gl_texture_cubemap_image
EGL_KHR_gl_texture_3D_image
EGL_KHR_gl_renderbuffer_image
Contributors
Aaftab Munshi
Barthold Lichtenbelt
Gary King
Jeff Juliano
Jon Leech
Jonathan Grant
Acorn Pooley
Contacts
Gary King, NVIDIA Corporation (gking 'at' nvidia.com)
Notice
Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete.
Approved by the Khronos Board of Promoters on February 11, 2008.
Version
Version 13, October 9, 2013
Number
EGL Extension #5
Dependencies
All extensions require EGL 1.2 and the EGL_KHR_image extension
These extensions are written against the wording of the EGL 1.2
Specification.
KHR_gl_texture_2D_image requires an OpenGL or OpenGL ES client API (any
version of either API).
KHR_gl_texture_cubemap_image requires an OpenGL or OpenGL ES client API
supporting texture cube maps, either in the core API or via extensions.
KHR_gl_texture_3D_image requires KHR_gl_texture_2D_image to be supported
by the EGL implementation. It also requires an OpenGL or OpenGL ES
client API supporting three-dimensional textures, either in the core API
or via extensions.
KHR_gl_renderbuffer_image requires KHR_gl_texture_2D_image to be
supported by the EGL implementation. It also requires an OpenGL or
OpenGL ES client API supporting renderbuffers, either in the core API or
via extensions.
Overview
The extensions specified in this document provide a mechanism for
creating EGLImage objects from OpenGL and OpenGL ES (henceforth referred
to collectively as 'GL') API resources, including two- and three-
dimensional textures, cube maps and render buffers. For an overview of
EGLImage operation, please see the EGL_KHR_image specification.
Due to the number of available extensions for the OpenGL ES 1.1 and
OpenGL ES 2.0 APIs, this document is organized as 4 separate extensions,
described collectively. These extensions are separated based on the
required underlying GL functionality (described in the dependencies
section).
New Types
None
New Procedures and Functions
None
New Tokens
Accepted in the <target> parameter of eglCreateImageKHR:
EGL_GL_TEXTURE_2D_KHR 0x30B1
Accepted as an attribute in the <attr_list> parameter of
eglCreateImageKHR:
EGL_GL_TEXTURE_LEVEL_KHR 0x30BC
Added by KHR_gl_texture_cubemap_image:
Accepted in the <target> parameter of eglCreateImageKHR:
EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X_KHR 0x30B3
EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X_KHR 0x30B4
EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y_KHR 0x30B5
EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y_KHR 0x30B6
EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z_KHR 0x30B7
EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z_KHR 0x30B8
Added by KHR_gl_texture_3D_image:
Accepted in the <target> parameter of eglCreateImageKHR:
EGL_GL_TEXTURE_3D_KHR 0x30B2
Accepted as an attribute in the <attr_list> parameter of
eglCreateImageKHR:
EGL_GL_TEXTURE_ZOFFSET_KHR 0x30BD
Added by KHR_gl_renderbuffer_image:
Accepted in the <target> parameter of eglCreateImageKHR:
EGL_GL_RENDERBUFFER_KHR 0x30B9
Additions to the EGL Image (EGL_KHR_image) Specification:
Add the following to Table aaa (Legal values for eglCreateImageKHR
<target> parameter), Section 2.5.1 (EGLImage Specification)
+-------------------------------------+---------------------------------+
| <target> | Notes |
+-------------------------------------+---------------------------------+
| EGL_GL_TEXTURE_2D_KHR | Used for GL 2D texture images |
+-------------------------------------+---------------------------------+
If KHR_gl_texture_cubemap_image is supported:
+-----------------------------------------+-----------------------------+
| <target> | Notes |
+-----------------------------------------+-----------------------------+
| EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X_KHR | Used for the +X face of |
| | GL cubemap texture images |
+-----------------------------------------+-----------------------------+
| EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X_KHR | Used for the -X face of |
| | GL cubemap texture images |
+-----------------------------------------+-----------------------------+
| EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y_KHR | Used for the +Y face of |
| | GL cubemap texture images |
+-----------------------------------------+-----------------------------+
| EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y_KHR | Used for the -Y face of |
| | GL cubemap texture images |
+-----------------------------------------+-----------------------------+
| EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z_KHR | Used for the +Z face of |
| | GL cubemap texture images |
+-----------------------------------------+-----------------------------+
| EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z_KHR | Used for the -Z face of |
| | GL cubemap texture images |
+-----------------------------------------+-----------------------------+
If KHR_gl_texture_3D_image is supported:
+-------------------------------------+---------------------------------+
| <target> | Notes |
+-------------------------------------+---------------------------------+
| EGL_GL_TEXTURE_3D_KHR | Used for GL 3D texture images |
+-------------------------------------+---------------------------------+
If KHR_gl_renderbuffer_image is supported:
+-------------------------------------+---------------------------------+
| <target> | Notes |
+-------------------------------------+---------------------------------+
| EGL_GL_RENDERBUFFER_KHR | Used for GL renderbuffer images|
+-------------------------------------+---------------------------------+
Add the following to Table bbb (Legal attributes for eglCreateImageKHR
<attr_list> parameter), Section 2.5.1 (EGLImage Specification)
+---------------------------+-------------------------------+----------------------------+---------+
| | | Valid | Default |
| Attribute | Description | <target>s | Value |
+---------------------------+-------------------------------+----------------------------+---------+
| EGL_GL_TEXTURE_LEVEL_KHR | Specifies the mipmap level | EGL_GL_TEXTURE_2D_KHR, | 0 |
| | used as the EGLImage source. | EGL_GL_TEXTURE_CUBE_MAP_*, | |
| | Must be part of the complete | EGL_GL_TEXTURE_3D_KHR | |
| | texture object <buffer> | | |
+---------------------------+-------------------------------+----------------------------+---------+
If KHR_gl_texture_3D_image is supported:
+----------------------------+------------------------------+----------------------------+---------+
| | | Valid | Default |
| Attribute | Description | <target>s | Value |
+----------------------------+------------------------------+----------------------------+---------+
| EGL_GL_TEXTURE_ZOFFSET_KHR | Specifies the depth offset | EGL_GL_TEXTURE_3D_KHR | 0 |
| | of the image to use as the | | |
| | EGLImage source. Must be | | |
| | part of the complete texture| | |
| | object <buffer> | | |
+----------------------------+------------------------------+----------------------------+---------+
Insert the following text after paragraph 3 ("If <target> is
NATIVE_PIXMAP_KHR...") of Section 2.5.1 (EGLImage Specification)
"If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_3D_KHR,
EGL_GL_RENDERBUFFER_KHR,
EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_X_KHR,
EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_X_KHR,
EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Y_KHR,
EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Y_KHR,
EGL_GL_TEXTURE_CUBE_MAP_POSITIVE_Z_KHR, or
EGL_GL_TEXTURE_CUBE_MAP_NEGATIVE_Z_KHR,
<dpy> must be a valid EGLDisplay,
and <ctx> must be a valid GL API context on that display.
If <target> is EGL_GL_TEXTURE_2D_KHR, <buffer> must be the name of a
nonzero, GL_TEXTURE_2D target texture object, cast into
the type EGLClientBuffer. <attr_list> should specify the mipmap level
which will be used as the EGLImage source (EGL_GL_TEXTURE_LEVEL_KHR); the
specified mipmap level must be part of <buffer>. If not specified, the
default value listed in Table bbb will be used, instead. Additional
values specified in <attr_list> are ignored. The texture must be complete
unless the mipmap level to be used is 0, the texture has mipmap level 0
specified, and no other mipmap levels are specified.
If <target> is one of the EGL_GL_TEXTURE_CUBE_MAP_* enumerants, <buffer>
must be the name of a cube-complete, nonzero, GL_TEXTURE_CUBE_MAP (or
equivalent in GL extensions) target texture object, cast into the type
EGLClientBuffer. <attr_list> should specify the mipmap level which will
be used as the EGLImage source (EGL_GL_TEXTURE_LEVEL_KHR); the specified
mipmap level must be part of <buffer>. If not specified, the default
value listed in Table bbb will be used, instead. Additional values
specified in <attr_list> are ignored. The texture must be cube-complete
unless the mipmap level to be used is 0, the texture has mipmap level 0
specified for all faces, and no other mipmap levels are specified for any
faces.
If <target> is EGL_GL_TEXTURE_3D_KHR, <buffer> must be the name of a
complete, nonzero, GL_TEXTURE_3D (or equivalent in GL extensions) target
texture object, cast
into the type EGLClientBuffer. <attr_list> should specify the mipmap
level (EGL_GL_TEXTURE_LEVEL_KHR) and z-offset (EGL_GL_TEXTURE_ZOFFSET_KHR)
which will be used as the EGLImage source; the specified mipmap level must
be part of <buffer>, and the specified z-offset must be smaller than the
depth of the specified mipmap level. If a value is not specified, the
default value listed in Table bbb will be used, instead. Additional
values specified in <attr_list> are ignored. The texture must be
complete unless the mipmap level to be used is 0, the texture has mipmap
level 0 specified, and no other mipmap levels are specified.
If <target> is EGL_GL_RENDERBUFFER_KHR, <buffer> must be the name of a
complete, nonzero, non-multisampled GL_RENDERBUFFER (or equivalent in
extensions) target object, cast into the type EGLClientBuffer. Values
specified in <attr_list> are ignored."
Add the following errors to the end of the list in Section 2.5.1 (EGLImage
Specification):
" * If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR,
EGL_GL_RENDERBUFFER_KHR or EGL_GL_TEXTURE_3D_KHR, and <dpy> is not a
valid EGLDisplay, the error EGL_BAD_DISPLAY is generated.
* If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR,
EGL_GL_RENDERBUFFER_KHR or EGL_GL_TEXTURE_3D_KHR, and <ctx> is not a
valid EGLContext, the error EGL_BAD_CONTEXT is generated.
* If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR,
EGL_GL_RENDERBUFFER_KHR or EGL_GL_TEXTURE_3D_KHR, and <ctx> is not a
valid GL context, or does not match the <dpy>, the error
EGL_BAD_MATCH is generated.
* If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR
or EGL_GL_TEXTURE_3D_KHR and <buffer> is not the name of a
texture object of type <target>, the error EGL_BAD_PARAMETER
is generated.
* If <target> is EGL_GL_RENDERBUFFER_KHR and <buffer> is not the
name of a renderbuffer object, or if <buffer> is the name of a
multisampled renderbuffer object, the error EGL_BAD_PARAMETER is
generated.
* If EGL_GL_TEXTURE_LEVEL_KHR is nonzero, <target> is
EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR or
EGL_GL_TEXTURE_3D_KHR, and <buffer> is not the name of a complete
GL texture object, the error EGL_BAD_PARAMETER is generated.
* If EGL_GL_TEXTURE_LEVEL_KHR is 0, <target> is
EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR or
EGL_GL_TEXTURE_3D_KHR, <buffer> is the name of an incomplete GL
texture object, and any mipmap levels other than mipmap level 0
are specified, the error EGL_BAD_PARAMETER is generated.
* If EGL_GL_TEXTURE_LEVEL_KHR is 0, <target> is
EGL_GL_TEXTURE_2D_KHR or EGL_GL_TEXTURE_3D_KHR, <buffer> is not
the name of a complete GL texture object, and mipmap level 0 is
not specified, the error EGL_BAD_PARAMETER is generated.
* If EGL_GL_TEXTURE_LEVEL_KHR is 0, <target> is
EGL_GL_TEXTURE_CUBE_MAP_*_KHR, <buffer> is not the name of a
complete GL texture object, and one or more faces do not have
mipmap level 0 specified, the error EGL_BAD_PARAMETER is
generated.
* If <target> is EGL_GL_TEXTURE_2D_KHR,
EGL_GL_TEXTURE_CUBE_MAP_*_KHR, EGL_GL_RENDERBUFFER_KHR or
EGL_GL_TEXTURE_3D_KHR and <buffer> refers to the default GL
texture object (0) for the corresponding GL target, the error
EGL_BAD_PARAMETER is generated.
* If <target> is EGL_GL_TEXTURE_2D_KHR, EGL_GL_TEXTURE_CUBE_MAP_*_KHR,
or EGL_GL_TEXTURE_3D_KHR, and the value specified in <attr_list>
for EGL_GL_TEXTURE_LEVEL_KHR is not a valid mipmap level for the
specified GL texture object <buffer>, the error EGL_BAD_MATCH is
generated.
* If <target> is EGL_GL_TEXTURE_3D_KHR, and the value specified in
<attr_list> for EGL_GL_TEXTURE_ZOFFSET_KHR exceeds the depth
of the specified mipmap level-of-detail in <buffer>, the error
EGL_BAD_PARAMETER is generated."
Issues
1. What should happen if an application attempts to create an
EGLImage from a default OpenGL object (i.e., objects with
a name of 0)?
SUGGESTION: Disallow this operation, and generate an error.
2. What happens when one of
glTexImage2D
glCopyTexImage2D
glCompressedTexImage2D
glTexImage3D
glCopyTexImage3D
glCompressedTexImage3D
is called on a texture which has a mipmap level which is an EGLImage
sibling?
RESOLVED: the EGLImage sibling is orphaned. The mipmap level and the
EGLImage no longer have any connection.
3. What happens when one of
glTexSubImage2D
glCopyTexSubImage2D
glCompressedTexSubImage2D
glTexSubImage3D
glCopyTexSubImage3D
glCompressedTexSubImage3D
is called on a texture which has a mipmap level which is an EGLImage
sibling?
RESOLVED: the EGLImage sibling is NOT orphaned. The mipmap level
remains an EGLImage sibling.
4. What happens when glGenerateMipmaps is called on a texture which has a
mipmap level which is an EGLImage sibling?
RESOLVED: If the texture is already complete, then the EGLImage
sibling is not orphaned, and the mipmap level remains an EGLImage
sibling. However, if the texture was not complete then the
EGLImage sibling IS orphaned. This is because the implementation
will implicitly alter the structure of the mipmap levels.
5. What happens when the GL_GENERATE_MIPMAP bit causes a texture to be
respecified.
RESOLVED: If the texture is already complete, then the EGLImage
sibling is not orphaned, and the mipmap level remains an EGLImage
sibling. However, if the texture was not complete then the
EGLImage sibling IS orphaned. This is because the implementation
will implicitly alter the structure of the mipmap levels.
6. Can an EGLImage be created from a multisampled GL image?
RESOLVED: NO. Attempting to create an EGLImage from a multisampled
GL renderbuffer is now an error. Attempting to create from a
multisampled OpenGL texture image is not possible because none of
the multisampled <target>s are supported.
7. Are all types of two-dimensional GL images which might
be associated with EGLImages allowed?
Not yet. We could add new variants of these extensions to support
other image types such as rectangular and 2D array slice textures,
but haven't yet seen a need to do so.
Revision History
#13 (Jon Leech, October 9, 2013) - Define interactions with and support for
OpenGL and OpenGL ES 3.0, in addition to OpenGL ES 1/2. Add issue 7 (Bug
10728).
#12 (Jon Leech, September 16, 2013) - Add error when specifying a
renderbuffer <target> and passing a multisampled renderbuffer object.
Add issue 6 describing lack of support for multisampled EGLImages (Bug
10728).
#11 (Jon Leech, June 26, 2013) - Add error when specifying a renderbuffer
<target> and not passing a renderbuffer object (Bug 10384).
#10 (Jon Leech, June 13, 2013) - Add a "Valid Targets" column to table bbb
for new attributes, matching proposed changes in EGL_KHR_image_base (Bug
10151).
#9 (Jon Leech, March 28, 2012)
- Fix spelling of *CUBE_MAP* tokens (from CUBEMAP) to agree with
eglext.h.
#8 (Jon Leech, February 4, 2009)
- Change "non-default ... texture object" to "nonzero".
#7 (Bruce Merry, January 20, 2009)
- Minor wording improvements on issues 4 and 5.
#6 (Acorn Pooley, January 13, 2009)
- Modify completion requirement so textures with only mipmap level 0 can
be EGLImage source siblings. Add issues 2-5.
#5 (Jon Leech, October 8, 2008)
- Updated status (approved as part of OpenKODE 1.0)
#4 (Jon Leech, April 7, 2007)
- Assigned enumerant values
- Added OpenKODE 1.0 Provisional disclaimer
#3 (December 14, 2006)
- Changed requirement to egl 1.2 to include EGLClientBuffer type.
- formatting to keep within 80 columns
- added error condition descriptions for <dpy> and <ctx>
- changed error condition for EGL_GL_TEXTURE_ZOFFSET_KHR too big to
be EGL_BAD_PARAMETER
#2 (November 27, 2006)
- Changed OES token to KHR
extensions/KHR/EGL_KHR_image.txt
+140
View File
@@ -0,0 +1,140 @@
Name
KHR_image
Name Strings
EGL_KHR_image
Contributors
Jeff Juliano
Gary King
Jon Leech
Jonathan Grant
Barthold Lichtenbelt
Aaftab Munshi
Acorn Pooley
Chris Wynn
Contacts
Jon Leech (jon 'at' alumni.caltech.edu)
Gary King, NVIDIA Corporation (gking 'at' nvidia.com)
Notice
Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete.
Approved by the Khronos Board of Promoters on February 11, 2008.
Rewritten in terms of split functionality in KHR_image_base and
KHR_image_pixmap, approved by the Khronos Technical Working Group
on November 19, 2008.
Version
Version 11, November 12, 2008
Number
EGL Extension #3
Dependencies
EGL 1.2 is required.
An EGL client API, such as OpenGL ES or OpenVG, is required.
The specifications of EGL_KHR_image_base and EGL_KHR_image_pixmap are
required to determine the specification of this extension, although
those extentions may not be supported.
This extension is written against the wording of the EGL 1.2
Specification.
Overview
This extension defines a new EGL resource type that is suitable for
sharing 2D arrays of image data between client APIs, the EGLImage,
and allows creating EGLImages from EGL native pixmaps.
New Types
As defined by EGL_KHR_image_base.
New Procedures and Functions
As defined by EGL_KHR_image_base.
New Tokens
As defined by EGL_KHR_image_base and EGL_KHR_image_pixmap, with the
exception that EGL_IMAGE_PRESERVED_KHR is not defined by this
extension.
Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation)
EGL_KHR_image is equivalent to the combination of the functionality
defined by EGL_KHR_image_base and EGL_KHR_image_pixmap, with the
exception that if EGL_KHR_image is supported and EGL_KHR_image_base
is not, the attribute EGL_IMAGE_PRESERVED_KHR is not accepted in
<attrib_list>, However, the default value of this attribute is still
EGL_FALSE. In this situation, image preservation is always disabled.
Issues
None (but see the issues lists for EGL_KHR_image_base and
EGL_KHR_image_pixmap).
Revision History
#11 (Jon Leech, November 12, 2008)
- Clarified image preservation behavior when using this extension.
#10 (Jon Leech, October 22, 2008)
- Update description of interactions with EGL_KHR_image_base now
that the default value of EGL_IMAGE_PRESERVED_KHR is always FALSE.
#9 (Jon Leech, October 21, 2008)
- Split functionality into new extensions EGL_KHR_image_base and
EGL_KHR_image_pixmap, and defined legacy non-preserved image behavior
when this extension is supported.
#8 (Jon Leech, October 8, 2008)
- Updated status (approved as part of OpenKODE 1.0)
#7 (Jon Leech, November 20, 2007)
- Corrected 'enum' to 'EGLenum' in prototypes.
#6 (Jon Leech, April 5, 2007)
- Assigned enumerant values
- Added OpenKODE 1.0 Provisional disclaimer
#5 (Jon Leech, February 26, 2007)
- Add eglCreateImageKHR error if native pixmaps are not supported by
EGL.
#4 (December 14, 2006)
- Replaced EGL_OUT_OF_MEMORY error with EGL_BAD_ALLOC
- add "egl" and "EGL" to names to be consistant with spec
- formatting to keep within 80 columns
- Changed requirement to egl 1.2 to include EGLClientBuffer type.
- clarified some unclear error cases
- added some new error cases related to <dpy> and <ctx>
- add <dpy> param to eglCreateImageKHR and eglDestroyImageKHR
#3 (November 27, 2006)
- Converted OES token to KHR token
#2 (October 20, 2006)
- Split out API-specific image source types (VG, GL, etc.) into
individual extensions.
- Merged CreateImage2DOES and CreateImage3DOES functions into
a single CreateImageOES function with an attribute-value list.
- Removed the minimum requirements section (2.5.3), since this
doesn't make sense without the client-API specific extensions.
The minimum requirements should be migrated to the client-API
specific extension specifications.
- Added EGL_NO_IMAGE_OES default object, used as return value for
CreateImage*OES functions in the event of error conditions.
- Reworded issue 5, to clarify that the buffer sub-object (i.e.,
the unique resource specified by <ctx>, <target>, <buffer>,
and <attrib_list>) specified in CreateImage may not already be
an EGLImage sibling (either EGLImage source or EGLImage target).
#1 Original release
extensions/KHR/EGL_KHR_image_base.txt
+755
View File
@@ -0,0 +1,755 @@
Name
KHR_image_base
Name Strings
EGL_KHR_image_base
Contributors
Jeff Juliano
Gary King
Jon Leech
Jonathan Grant
Barthold Lichtenbelt
Aaftab Munshi
Acorn Pooley
Chris Wynn
Contacts
Jon Leech (jon 'at' alumni.caltech.edu)
Gary King, NVIDIA Corporation (gking 'at' nvidia.com)
Notice
Copyright (c) 2008-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete. Functionality approved (as part of KHR_image) by the
Khronos Board of Promoters on February 11, 2008.
Split into KHR_image_base and KHR_image_pixmap approved by the
Khronos Technical Working Group on November 19, 2008. Update to
version 5 approved on December 10, 2008.
Version
Version 8, August 27, 2014
Number
EGL Extension #8
Dependencies
EGL 1.2 is required.
An EGL client API, such as OpenGL ES or OpenVG, is required.
This extension is written against the wording of the EGL 1.2
Specification.
Overview
This extension defines a new EGL resource type that is suitable for
sharing 2D arrays of image data between client APIs, the EGLImage.
Although the intended purpose is sharing 2D image data, the
underlying interface makes no assumptions about the format or
purpose of the resource being shared, leaving those decisions to
the application and associated client APIs.
Glossary
EGLImage: An opaque handle to a shared resource created by EGL
client APIs, presumably a 2D array of image data
EGLImage source: An object or sub-object originally created in
a client API (such as a mipmap level of a texture object
in OpenGL-ES, or a VGImage in OpenVG) which is used as
the <buffer> parameter in a call to eglCreateImageKHR.
EGLImage target: An object created in a client API (such as a
texture object in OpenGL-ES or a VGImage in OpenVG)
from a previously-created EGLImage
EGLImage sibling: The set of all EGLImage targets (in all
client API contexts) which are created from the
same EGLImage object, and the EGLImage source resouce
which was used to create that EGLImage.
Orphaning: The process of respecifying and/or deleting an EGLImage
sibling resource (inside a client API context) which
does not result in deallocation of the memory associated
with the EGLImage or affect rendering results using other
EGLImage siblings.
Referencing: The process of creating an EGLImage target resource
(inside a client API context) from an EGLImage.
Respecification: When the size, format, or other attributes of an
EGLImage sibling are changed via client API calls such as
gl*TexImage*. Respecification usually will result in
orphaning the sibling. Note that changing the pixel values of
the sibling (e.g. by rendering to it or by calling
gl*TexSubImage*) does not constitute respecification.
New Types
/*
* EGLImageKHR is an object which can be used to create EGLImage
* target resources (inside client APIs).
*/
typedef void* EGLImageKHR;
New Procedures and Functions
EGLImageKHR eglCreateImageKHR(
EGLDisplay dpy,
EGLContext ctx,
EGLenum target,
EGLClientBuffer buffer,
const EGLint *attrib_list)
EGLBoolean eglDestroyImageKHR(
EGLDisplay dpy,
EGLImageKHR image)
New Tokens
Returned by eglCreateImageKHR:
EGL_NO_IMAGE_KHR ((EGLImageKHR)0)
Accepted as an attribute in the <attrib_list> parameter of
eglCreateImageKHR:
EGL_IMAGE_PRESERVED_KHR 0x30D2
Additions to Chapter 2 of the EGL 1.2 Specification (EGL Operation)
Add a new section "EGLImages" after section 2.4:
"2.5 EGLImages
As described in section 2.4, EGL allows contexts of the same client
API type to share significant amounts of state (such as OpenGL-ES
texture objects and OpenVG paths); however, in some cases it may
be desirable to share state between client APIs - an example would be
using a previously-rendered OpenVG image as an OpenGL-ES texture
object.
In order to facilitate these more complicated use-cases, EGL is capable
of creating EGL resources that can be shared between contexts of
different client APIs (called "EGLImages") from client API resources
such as texel arrays in OpenGL-ES texture objects or OpenVG VGImages
(collectively, the resources that are used to create EGLImages are
referred to as "EGLImage sources").
The EGL client APIs each provide mechanisms for creating appropriate
resource types (such as complete texture arrays or OpenVG VGImages) from
EGLImages through a API-specific mechanisms. Collectively, resources
which are created from EGLImages within client APIs are referred to as
"EGLImage targets." Each EGLImage may have multiple associated EGLImage
targets. Collectively, the EGLImage source and EGLImage targets
associated with an EGLImage object are referred to as "EGLImage
siblings."
2.5.1 EGLImage Specification
The command
EGLImageKHR eglCreateImageKHR(
EGLDisplay dpy,
EGLContext ctx,
EGLenum target,
EGLClientBuffer buffer,
const EGLint *attrib_list)
is used to create an EGLImage from an existing image resource <buffer>.
<dpy> specifies the EGL display used for this operation.
<ctx> specifies the EGL client API context
used for this operation, or EGL_NO_CONTEXT if a client API context is not
required. <target> specifies the type of resource being used as the
EGLImage source (examples include two-dimensional textures in OpenGL ES
contexts and VGImage objects in OpenVG contexts). <buffer> is the name
(or handle) of a resource to be used as the EGLImage source, cast into the
type EGLClientBuffer. <attrib_list> is an list of attribute-value pairs
which is used to select sub-sections of <buffer> for use as the EGLImage
source, such as mipmap levels for OpenGL ES texture map resources, as well as
behavioral options, such as whether to preserve pixel data during creation. If
<attrib_list> is non-NULL, the last attribute specified in the list must
be EGL_NONE.
The resource specified by <dpy>, <ctx>, <target>, <buffer>, and
<attrib_list> must not itself be an EGLImage sibling, or bound to an EGL
PBuffer resource (eglBindTexImage, eglCreatePbufferFromClientBuffer).
Values accepted for <target> are listed in Table aaa, below(fn1).
(fn1) No values are defined by this extension. All functionality
to create EGLImages from other types of resources, such as
native pixmaps, GL textures, and VGImages, is layered in other
extensions.
+-------------------------+--------------------------------------------+
| <target> | Notes |
+-------------------------+--------------------------------------------+
+-------------------------+--------------------------------------------+
Table aaa. Legal values for eglCreateImageKHR <target> parameter
Attribute names accepted in <attrib_list> are shown in Table bbb,
together with the <target> for which each attribute name is valid, and
the default value used for each attribute if it is not included in
<attrib_list>.
+-------------------------+----------------------+-----------+---------------+
| Attribute | Description | Valid | Default Value |
| | | <target>s | |
+-------------------------+----------------------+-----------+---------------+
| EGL_NONE | Marks the end of the | All | N/A |
| | attribute-value list | | |
| EGL_IMAGE_PRESERVED_KHR | Whether to preserve | All | EGL_FALSE |
| | pixel data | | |
+-------------------------+----------------------+-----------+---------------+
Table bbb. Legal attributes for eglCreateImageKHR <attrib_list> parameter
This command returns an EGLImageKHR object corresponding to the image
data specified by <dpy>, <ctx>, <target>, <buffer> and <attrib_list> which
may be referenced by client API operations, or EGL_NO_IMAGE_KHR in the
event of an error.
If the value of attribute EGL_IMAGE_PRESERVED_KHR is EGL_FALSE (the
default), then all pixel data values associated with <buffer> will be
undefined after eglCreateImageKHR returns.
If the value of attribute EGL_IMAGE_PRESERVED_KHR is EGL_TRUE, then all
pixel data values associated with <buffer> are preserved.
Errors
If eglCreateImageKHR fails, EGL_NO_IMAGE_KHR will be returned, the
contents of <buffer> will be unaffected, and one of the following
errors will be generated:
* If <dpy> is not the handle of a valid EGLDisplay object, the error
EGL_BAD_DISPLAY is generated.
* If <ctx> is neither the handle of a valid EGLContext object on
<dpy> nor EGL_NO_CONTEXT, the error EGL_BAD_CONTEXT is
generated.
* If <target> is not one of the values in Table aaa, the error
EGL_BAD_PARAMETER is generated.
* If an attribute specified in <attrib_list> is not one of the
attributes listed in Table bbb, the error EGL_BAD_PARAMETER is
generated.
* If an attribute specified in <attrib_list> is not a valid attribute
for <target>, as shown in Table bbb, the error EGL_BAD_MATCH is
generated.
* If the resource specified by <dpy>, <ctx>, <target>, <buffer> and
<attrib_list> has an off-screen buffer bound to it (e.g., by a
previous call to eglBindTexImage), the error EGL_BAD_ACCESS is
generated.
* If the resource specified by <dpy>, <ctx>, <target>, <buffer> and
<attrib_list> is bound to an off-screen buffer (e.g., by a previous
call to eglCreatePbufferFromClientBuffer), the error
EGL_BAD_ACCESS is generated.
* If the resource specified by <dpy>, <ctx>, <target>, <buffer> and
<attrib_list> is itself an EGLImage sibling, the error
EGL_BAD_ACCESS is generated.
* If insufficient memory is available to complete the specified
operation, the error EGL_BAD_ALLOC is generated.
* If the call to eglCreateImageKHR fails for multiple reasons, the
generated error must be appropriate for one of the reasons,
although the specific error returned is undefined.
* If the value specified in <attrib_list> for EGL_IMAGE_PRESERVED_KHR
is EGL_TRUE, and an EGLImageKHR handle cannot be created from the
specified resource such that the pixel data values in <buffer> are
preserved, the error EGL_BAD_ACCESS is generated.
Note that the success or failure of eglCreateImageKHR should not affect
the ability to use <buffer> in its original API context (or context
share group) (although the pixel data values will be undefined if
EGL_IMAGE_PRESERVED_KHR is not EGL_TRUE).
2.5.2 Lifetime and Usage of EGLImages
Once an EGLImage is created from an EGLImage source, the memory associated
with the EGLImage source will remain allocated (and all EGLImage siblings
in all client API contexts will be useable) as long as either of the
following conditions is true:
A) Any EGLImage siblings exist in any client API context
B) The EGLImage object exists inside EGL
The semantics for specifying, deleting and using EGLImage siblings are
client API-specific, and are described in the appropriate API
specifications.
If an application specifies an EGLImage sibling as the destination for
rendering and/or pixel download operations (e.g., as an OpenGL-ES
framebuffer object, glTexSubImage2D, etc.), the modified image results
will be observed by all EGLImage siblings in all client API contexts.
If multiple client API contexts access EGLImage sibling resources
simultaneously, with one or more context modifying the image data,
rendering results in all contexts accessing EGLImage siblings are
undefined.
Respecification and/or deletion of any EGLImage sibling (i.e., both
EGLImage source and EGLImage target resources) inside a client API
context (e.g., by issuing a subsequent call to
gl{Copy,Compressed}TexImage, glDeleteTextures, with the EGLImage
sibling resource as the target of the operation) affects only that
client API context and other contexts within its share group. The
specific semantics for this behavior are defined by each client API,
and generally results in orphaning of the EGLImage, and may also
include allocation of additional memory for the respecified resource
and/or copying of the EGLImage pixel data.
Operations inside EGL or any client API context which may affect the
lifetime of an EGLImage (or the memory allocated for the EGLImage),
such as respecifying and/or deleting an EGLImage sibling inside a
client API context, must be atomic.
Applications may create client API resources from an EGLImageKHR using
client API extensions outside the scope of this document (such as
GL_OES_EGL_image, which creates OpenGL ES texture and renderbuffer
objects). If the EGLImageKHR used to create the client resource was
created with the EGL_IMAGE_PRESERVED_KHR attribute set to EGL_TRUE, then
the pixel data values associated with the image will be preserved after
creating the client resource; otherwise, the pixel data values will be
undefined. If the EGLImageKHR was created with the
EGL_IMAGE_PRESERVED_KHR attribute set to EGL_TRUE, and EGL is unable to
create the client resource without modifying the pixel values, then
creation will fail and the pixel data values will be preserved.
The command
EGLBoolean eglDestroyImageKHR(
EGLDisplay dpy,
EGLImageKHR image)
is used to destroy the specified EGLImageKHR object <image>. Once
destroyed, <image> may not be used to create any additional EGLImage
target resources within any client API contexts, although existing
EGLImage siblings may continue to be used. EGL_TRUE is returned
if DestroyImageKHR succeeds, EGL_FALSE indicates failure.
* If <dpy> is not the handle of a valid EGLDisplay object, the error
EGL_BAD_DISPLAY is generated.
* If <image> is not a valid EGLImageKHR object created with respect
to <dpy>, the error EGL_BAD_PARAMETER is generated."
Add a new error to the list at the bottom of Section 3.5.3 (Binding
Off-Screen Rendering Surfaces to Client Buffers):
"* If the buffers contained in <buffer> consist of any EGLImage
siblings, an EGL_BAD_ACCESS error is generated."
Issues
1. What resource types should be supported by this extension?
RESOLVED: This specification is designed to support the
sharing of two-dimensional image resources between client APIs,
as these resources are a fundamental component of all modern
graphics APIs.
Other resources types (e.g., buffer objects) will not be directly
supported by this specification, due to a variety of reasons:
a. An absense of use cases for this functionality
b. Handling the semantics for some of these resources
(e.g., glMapBuffer) would significantly complicate
and delay this specification.
c. A desire to address the image-sharing use cases
as quickly as possible.
Should additional resource-sharing functionality be desired
in the future, the framework provided by this specification
should be extendable to handle more general resource
sharing.
2. Should this specification address client API-specific resources
(OpenGL texture maps, OpenVG VGImages), or should that
functionality be provided by layered extensions?
SUGGESTION: Use layered extensions, even for for sharing image
data with native rendering APIs (the EGL_KHR_image_pixmap
extension).
There are two major arguments for using layered extensions:
1. The two client APIs which are defined at the time of this
specification (OpenVG, OpenGL ES) may not always be
deployed on a device; many devices may choose to implement
just one of these two APIs. However, even single-API
devices may benefit from the ability to share image data
with native rendering APIs (provided in this specification)
or with the OpenMAX API.
2. OpenGL ES defines a number of optional resource types
(cubemaps, renderbuffers, volumetric textures) which this
framework should support; however, implementations may not.
By layering each of these resource types in individual
extensions, implementations which are limited to just the
core OpenGL ES 1.1 (or OpenGL ES 2.0) features will not
need to add EGLImage enumerant support for unsupported
resource types.
The original EGL_KHR_image extension included native pixmap
functionality. We have now split the abstract base functionality
(the egl{Create,Destroy}ImageKHR APIs) from the native pixmap
functionality, and redefined EGL_KHR_image as the combination of
EGL_KHR_image_base and EGL_KHR_image_pixmap.
3. Should attributes (width, height, format, etc.) for EGLImages
be queriable?
SUGGESTION: No. Given the wealth of attributes that we would
need to specify all possible EGLImages (and possible
memory layout optimizations performed by implementations), we
can dramatically simplify the API without loss of key
functionality by making EGLImages opaque and allowing
implementations to make the correct decisions internally.
4. Should this specification allow the creation of EGLImages from
client API resources which are themselves EGLImage targets?
RESOLVED: No. This can make memory garbage collection and
reference counting more difficult, with no practical benefit.
Instead, generate an error if an application attempts to
create an EGLImage from an EGLImage target resource.
5. Should this specification allow multiple EGLImages to be created
from the same EGLImage source resource?
RESOLVED: No. The resource <buffer> specified to
eglCreateImageKHR may include multiple sub-objects; examples are
mipmapped images and cubemaps in the OpenGL-ES API. However, the
EGLImage source is defined as the specific sub-object that is defined
by: <ctx>, <target>, <buffer>, and <attrib_list>. This sub-object must
not be an EGLImage sibling (either EGLImage source or EGLImage target)
when eglCreateImageKHR is called; however, other sub-objects in
<buffer> may be EGLImage siblings. This allows applications to share
individual cubemap faces, or individual mipmap levels of detail across
all of the supported APIs.
Note that the EGLImage source and any EGLImage target resources
will still be EGLImage siblings, even if the EGLImage object
is destroyed by a call to DestroyImageKHR.
6. If an EGLImage sibling is respecified (or deleted), what
should happen to the EGLImage and any other EGLImage
siblings?
RESOLVED: The principle of least surprise would dictate that
respecification and/or deletion of a resource in one client API
should not adversely affect operation in other client APIs
(such as introducing errors).
Applying this to EGLImages, respecification and/or deletion
of one EGLImage sibling should not respecify/delete other
EGLImage siblings. Each client API will be responsible for
defining appropriate semantics to meet this restriction;
however, example behaviors may include one or more of:
allocating additional memory for the respecified resource,
deleting the EGLImage sibling resource without deallocating
the associated memory ("orphaning") and/or copying the
existing EGLImage pixel data to an alternate memory location.
The memory associated with EGLImage objects should remain
allocated as long as any EGLImage sibling resources exist
in any client API context.
7. Should this specification address synchronization issues
when multiple client API contexts simultaneously access EGLImage
sibling resources?
RESOLVED: No. Including error-producing lock and synchronization
semantics would introduce additional (undesirable) validation
overhead in numerous common operations (e.g., glBindTexture,
glDrawArrays, etc.). Rather than burdening implementations (and
applications) with this overhead, a separate synchronization
mechanism should be exposed to applications.
8. Should eglCreatePbufferFromClientBuffer accept buffer parameters
which are EGLImage siblings?
RESOLVED: No. Allowing this behavior creates very complex
circular dependency possibilities (CreateImage / DeriveImage /
CreatePbufferFromClientBuffer / BindTexImage /
CreateImage / ...) with no practical benefit. Therefore,
attempting to create a Pbuffer from a client buffer which
is an EGLImage sibling should generate an error.
9. Should CreateImage accept client buffers which are bound to
Pbuffers (through eglBindTexImage)?
RESOLVED: No, for the same reasons listed in Issue 8.
10. Should implementations be allowed to modify the pixel data in the
EGLImage source buffers specified to eglCreateImageKHR?
SUGGESTION: By allowing previously-existing image data to become
undefined after calls to eglCreateImageKHR, implementations are able
to perform any necessary reallocations required for cross-API
buffer compatibility (and/or performance), without requiring
copy-aside functionality. Because applications are able to
respecify the pixel data through mechanisms such as vgSubImage
and glTexSubImage, no use-cases are restricted by this.
Therefore, the current suggestion is to allow implementations
to leave pixel data undefined after calls to eglCreateImageKHR
functions. The current spec revision has been written in
this way.
11. What is the correct mechanism for specifying the EGLImage source
resources used to create an EGLImage object?
RESOLVED: Three different mechanisms were discussed while
defining this extension:
A) Providing resource-specific creation functions, such as
eglCreateImage2DKHR, eglCreateImage3DKHR, etc.
B) Providing a single creation function which returns a
"NULL" EGLImage object, and requiring client APIs to
define additional functions which would allow client API
resources to be "bound" to the EGLImage object.
C) Provide a single resource creation function, and use
an attribute-value list with attributes specific to the
"target" image resource.
Initial specifications were written using Option (A); however,
it was believed that this structure would result in an increase
in the number of entry points over time as additional client APIs
and client API resource targets were added. Furthermore, reuse
of these functions was resulting in cases where parameters were
required to have modal behavior: a 2D image creation function
was required to have a mipmap level of detail parameter for
OpenGL ES texture maps, but this same parameter would need to be
0 for OpenVG.
Option (B) provided some nice characteristics: as client APIs
continue to evolve, any extensions needed to allow EGLImage
creation could be isolated in the individual client API, rather
than necessitating an EGL extension. However, the creation of
"NULL" images created additional semantic complexity and error
conditions (e.g., attempting to derive an EGLImage target from a
"NULL" image), and every client API would need to provide a
function for every unique resource type; instead of one common
API function for pixmap, OpenGL 2D textures, and OpenVG VGImages,
three would be required.
This specification is written using Option (C). There is a
single CreateImage function, with a <target> parameter defining
the EGLImage source type, and an attribute-value list allowing
for additional selection of resource sub-sections. This
maximizes entry-point reuse, and minimizes the number of
redundant parameters an application may be required to send.
This framework allows for layered extensions to be easily
written, so little churn is expected as client APIs evolve.
12. Should a context be explicitly provided to eglCreateImageKHR,
or should the context be deduced from the current thread's
bound API?
SUGGESTION: For clarity (both in usage and spec language), the
context containing the EGLImage source should be provided by the
application, rather than inferring the context from EGL state.
13. Why does this extension define a new EGL object type, rather
than using the existing EGLSurface objects?
RESOLVED: Although controversial, the creation of a new,
opaque image object type removes several fundamental problems
with the EGLSurface (and Pbuffer) API:
1) The tight compatibility requirements of EGLSurfaces
and EGLConfigs necessitated applications creating
(and calling MakeCurrent) for every unique pixel
format used during rendering. This has already caused
noticeable performance problems in OpenGL-ES (and
desktop OpenGL), and is the primary reason that
framebuffer objects were created.
2) Application use-cases are centered around sharing of
color image data, although unique "sundry" buffers
(such as depth, stencil and alpha mask) may be used
in each client API.
3) Extending the CreatePbuffer interface to support fully-
specifying all possible buffer attributes in all client
APIs will become unwieldy, particularly as new EGL
client APIs and pixel formats are introduced.
The EGLImage proposal addresses all three of these restrictions:
1) is addressed by placing the burden of framebuffer management
inside the client API, and allowing EGLImages to be accessed
inside client APIs using an appropriate resource type (such
as OpenGL-ES renderbuffers). This follows the example provided
by the GL_OES_framebuffer_object specification.
2) is addressed by defining EGLImages to be "trivial" two-
dimensional arrays of pixel data. Implementations may choose
to support creation of EGLImages from any type of pixel data,
and the association of multiple EGLImages and/or sundry
buffers into a single framebuffer is the responsibility of the
application and client API, using a mechanism such as
GL_OES_framebuffer_object.
3) is addressed by defining EGLImages as opaque and
non-queriable. Although this introduces potential portability
problems (addressed separately in issue 15), it avoids the
ever-expanding problem of defining buffer compatibility as the
cartesian product of all possible buffer attributes.
14. Since referencing EGLImages is the responsibility of the client
API, and may fail for implementation-dependent reasons,
doesn't this result in a potential portability problem?
UNRESOLVED: Yes, this portability problem (where referencing
succeeds on one platform but generates errors on a different
one) is very similar to the implementation-dependent
failure introduced in the EXT_framebuffer_object specification,
discussed (at length) in Issues (12), (37), (46), (48) and (61)
of that specification. Similar to that specification, this
specification should include some "minimum requirements"
language for EGLImage creation and referencing.
Since there are numerous references to an upcoming
"format restriction" API in the EXT_framebuffer_object
specification, it may be valuable to wait until that API is
defined before attempting to define a similar API for
EGLImages.
15. Should creation of an EGLImage from an EGLImage source
introduce the possibility for errors in the EGLImage source's
owning context?
RESOLVED: No; although image data may be undefined (issue 11),
the (successful or unsuccessful) creation of an EGLImage should
not introduce additional error conditions in the EGLImage
source's owning context. Text added to the end of section
2.5.1 describing this.
16. Is it reasonable to require that when a preserved EGLImage is
used by layered extensions to create client API siblings of that
image, pixel data values are preserved?
UNRESOLVED: There are at least two extensions that reference
EGLImages to create EGLImage targets, VG_KHR_EGL_image and
GL_OES_EGL_image.
Each of these extensions makes provision for failing the creation of
the EGLImage target due to "an implementation-dependent reason".
This could include that the pixel data has been marked as preserved,
and that the implementation is not able to create the EGLImage
target without causing the pixel data of the original EGLImage
source <buffer> to become undefined.
Issue 14 of EGL_KHR_image also discusses the consequences of failure
for implementation-dependent reasons. This implies that all
extensions for referencing an EGLImage need to make provision for
implementation-dependent failure.
PROPOSED: Yes, this is reasonable. We should add "EGL_KHR_image_base
affects the behavior of this extension" sections to the ES and VG
extensions. Implementations can continue to export EGL_KHR_image if
they are unable to support preserved image functionality.
17. Do EGLImage Target creation extensions such as VG_KHR_EGL_image and
GL_OES_EGL_image also need to be extended?
UNRESOLVED: The problem here is that both these extensions
explicitly state that pixel data becomes undefined when they
reference an EGLImage to create an EGLImage target.
One solution would be to allow this extension to do the defining on
behalf of these extensions. For example, the VG_KHR_EGL_image
extension on its own leaves the status of the pixel data undefined,
but when VG_KHR_EGL_image is combined with this extension, then the
status becomes defined (by this extension).
When combined with the reasons given in Issue 1, this means it is
possible to leave EGLImage Target creation extensions unchanged.
PROPOSED: Yes, augment these extensions as described in issue 16.
18. Is it reasonable for developers to want to preserve pixel data upon
creation of EGLImage and EGLImage targets?
RESOLVED: Yes. This is necessary for composition implementations
using EGLImages as an encapsulation mechanism for moving data
between producer application, composition API, and composition
implementation(s).
19. Should we really change the default value of EGL_IMAGE_PRESERVED_KHR
when EGL_KHR_image is supported?
RESOLVED: No. This is a subtle and hard to diagnose source of
errors, and the only way to write a portable app would still be
to explicitly specify the attribute value. By making the default
value FALSE no matter which of the two extension(s) are
supported, compatibility with EGL_KHR_image is preserved, and
apps must explicitly ask for preservation if they need it.
20. Why is EGL_NO_DISPLAY not supported as the <dpy> argument for
creating and destroying images, unlike the original version of the
EGL_KHR_image specification?
RESOLVED: There are no defined use cases for this at present, so
there is no way to legally pass in EGL_NO_DISPLAY. If in the future,
a layered extension allows creation of images not associated with
any display, this behavior can be reintroduced.
Revision History
#8 (Jon Leech, August 27, 2014)
- Remove leftover comment saying that inapplicable attributes are
ignored (Bug 12585).
#7 (Jon Leech, June 12, 2013)
- Add a column to table bbb specifying which <target>s attributes are
valid for, and a generic error if an attribute doesn't match <target>
(Bug 10151).
#6 (Jon Leech, December 1, 2010)
- Clarify wording of EGL_BAD_CONTEXT error.
#5 (Jon Leech, December 10, 2008)
- Change definition of EGL_NO_IMAGE_KHR to 0 (appropriately cast)
instead of a reference to an extern implementation-defined
variable.
#4 (Jon Leech, November 25, 2008)
- Simplify error conditions for eglDestroyImage.
#3 (Jon Leech, November 12, 2008)
- Added glossary entry for Respecification, updated description of
behavior with preserved images per suggestions from Acorn, and added
issue 20 regarding removal of EGL_NO_DISPLAY as a valid <dpy>.
#2 (Jon Leech, October 22, 2008)
- Change default value of EGL_IMAGE_PRESERVED_KHR to EGL_FALSE.
Update issue 19.
#1 (Jon Leech, October 21, 2008)
- Split abstract functionality from EGL_KHR_image into this extension,
and merged preserved image functionality from
EGL_SYMBIAN_image_preserved.
extensions/KHR/EGL_KHR_image_pixmap.txt
+158
View File
@@ -0,0 +1,158 @@
Name
KHR_image_pixmap
Name Strings
EGL_KHR_image_pixmap
Contributors
Jeff Juliano
Gary King
Jon Leech
Jonathan Grant
Barthold Lichtenbelt
Aaftab Munshi
Acorn Pooley
Chris Wynn
Ray Smith
Contacts
Jon Leech (jon 'at' alumni.caltech.edu)
Gary King, NVIDIA Corporation (gking 'at' nvidia.com)
Notice
Copyright (c) 2008-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
Complete. Functionality approved (as part of KHR_image) by the
Khronos Board of Promoters on February 11, 2008.
Split into KHR_image_base and KHR_image_pixmap approved by the
Khronos Technical Working Group on November 19, 2008.
Version
Version 5, November 13, 2013
Number
EGL Extension #9
Dependencies
EGL 1.2 is required.
EGL_KHR_image_base is required.
The EGL implementation must define an EGLNativePixmapType (although it
is not required either to export any EGLConfigs supporting rendering to
native pixmaps, or to support eglCreatePixmapSurface).
This extension is written against the wording of the EGL 1.4
Specification.
Overview
This extension allows creating an EGLImage from a native pixmap
image.
New Types
None
New Procedures and Functions
None
New Tokens
Accepted by the <target> parameter of eglCreateImageKHR:
EGL_NATIVE_PIXMAP_KHR 0x30B0
Additions to Chapter 2 of the EGL 1.4 Specification (EGL Operation)
Rename section 2.2.2.1 "Native Surface Coordinate Systems" to "Native
Surface and EGLImage Pixmap Coordinate Systems" and add to the end of
the section:
"EGLImages created with target EGL_NATIVE_PIXMAP_KHR share the same
coordinate system as native pixmap surfaces. When that coordinate system
is inverted, client APIs must invert their <y> coordinate when accessing
such images as described above."
Add to section 2.5.1 "EGLImage Specification" (as defined by the
EGL_KHR_image_base specification), in the description of
eglCreateImageKHR:
"Values accepted for <target> are listed in Table aaa, below.
+-------------------------+--------------------------------------------+
| <target> | Notes |
+-------------------------+--------------------------------------------+
| EGL_NATIVE_PIXMAP_KHR | Used for EGLNativePixmapType objects |
+-------------------------+--------------------------------------------+
Table aaa. Legal values for eglCreateImageKHR <target> parameter
...
If <target> is EGL_NATIVE_PIXMAP_KHR, <dpy> must be a valid display, <ctx>
must be EGL_NO_CONTEXT; <buffer> must be a handle to a valid
NativePixmapType object, cast into the type EGLClientBuffer; and
attributes other than EGL_IMAGE_PRESERVED_KHR are ignored."
Add to the list of error conditions for eglCreateImageKHR:
"* If <target> is EGL_NATIVE_PIXMAP_KHR and <buffer> is not a
valid native pixmap handle, or if <buffer> is a native pixmap
whose color buffer format is incompatible with the system's
EGLImage implementation, the error EGL_BAD_PARAMETER is
generated.
* If <target> is EGL_NATIVE_PIXMAP_KHR, and <dpy> is not a valid
EGLDisplay object the error EGL_BAD_DISPLAY is generated.
* If <target> is EGL_NATIVE_PIXMAP_KHR, and <ctx> is not EGL_NO_CONTEXT,
the error EGL_BAD_PARAMETER is generated.
* If <target> is EGL_NATIVE_PIXMAP_KHR, and <buffer> is not a handle
to a valid NativePixmapType object, the error EGL_BAD_PARAMETER
is generated."
Issues
1) Should this specification allow EGLImages to be created from native
pixmaps which already have a pixmap surface associated with them, and
vice versa?
RESOLVED: Yes. There are practical usecases for this, and it is
already the application's responsibility to handle any format
mismatch or synchronization issues that this may allow.
Revision History
#5 (Jon Leech, November 13, 2013)
- Add Issue #1 regarding use cases for multiple EGL consumer/producers
of a native pixmap (Bug 7779).
#4 (Jon Leech, October 16, 2013)
- Add language allowing native pixmap and client API image y coordinate
convention to differ. Re-base extension against EGL 1.4 (Bug 9701).
#3 (Jon Leech, November 25, 2008)
- Remove dependency on EGLConfig in error conditions.
#2 (Jon Leech, November 12, 2008)
- Clarified dependency on EGLNativePixmapType such that pixmap configs
and surfaces are not required.
#1 (Jon Leech, October 21, 2008)
- Split native pixmap functionality from EGL_KHR_image into a layered
extension on EGL_KHR_image_base, and note interaction with the new
EGL_IMAGE_PRESERVED_KHR attribute.
extensions/KHR/EGL_KHR_lock_surface.txt
+727
View File
@@ -0,0 +1,727 @@
Name
KHR_lock_surface
Name Strings
EGL_KHR_lock_surface
Contributors
Gary King
Jon Leech
Marko Lukat
Tim Renouf
Contacts
Jon Leech (jon 'at' alumni.caltech.edu)
Notice
Copyright (c) 2006-2013 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Status
This extension, as well as the layered EGL_KHR_lock_surface2, are
obsolete and have been replaced by EGL_KHR_lock_surface3. Khronos
recommends implementers who support this extension and lock_surface2
also implement lock_surface3, and begin transitioning developers to
using that extension. See issue 17 for the reason.
Complete.
Version 17 approved by the Khronos Board of Promoters on
February 11, 2008.
Version
Version 19, October 15, 2013
Number
EGL Extension #2
Dependencies
Requires EGL 1.0
This extension is written against the wording of the EGL 1.3
Specification.
Overview
This extension allows mapping color buffers of EGL surfaces into the
client address space. This is useful primarily for software
rendering on low-end devices which do not support EGL client
rendering APIs, although it may be implemented efficiently on more
capable devices as well.
There is a newer EGL_KHR_lock_surface2 extension which slightly
modifies and clarifies the semantics of this extension. Vendors
should refer to EGL_KHR_lock_surface2 before deciding to implement
only EGL_KHR_lock_surface.
New Types
None
New Procedures and Functions
EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy, EGLSurface surface,
const EGLint *attrib_list);
EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy,
EGLSurface surface);
New Tokens
Returned in the EGL_SURFACE_TYPE bitmask attribute of EGLConfigs:
EGL_LOCK_SURFACE_BIT_KHR 0x0080
EGL_OPTIMAL_FORMAT_BIT_KHR 0x0100
Accepted as an attribute name in the <attrib_list> argument of
eglChooseConfig, and the <attribute> argument of eglGetConfigAttrib:
EGL_MATCH_FORMAT_KHR 0x3043
Accepted as attribute values for the EGL_MATCH_FORMAT_KHR attribute
of eglChooseConfig:
EGL_FORMAT_RGB_565_EXACT_KHR 0x30C0
EGL_FORMAT_RGB_565_KHR 0x30C1
EGL_FORMAT_RGBA_8888_EXACT_KHR 0x30C2
EGL_FORMAT_RGBA_8888_KHR 0x30C3
Accepted as attribute names in the <attrib_list> argument of
eglLockSurfaceKHR:
EGL_MAP_PRESERVE_PIXELS_KHR 0x30C4
EGL_LOCK_USAGE_HINT_KHR 0x30C5
Accepted as bit values in the EGL_LOCK_USAGE_HINT_KHR bitmask attribute
of eglLockSurfaceKHR:
EGL_READ_SURFACE_BIT_KHR 0x0001
EGL_WRITE_SURFACE_BIT_KHR 0x0002
Accepted by the <attribute> parameter of eglQuerySurface:
EGL_BITMAP_POINTER_KHR 0x30C6
EGL_BITMAP_PITCH_KHR 0x30C7
EGL_BITMAP_ORIGIN_KHR 0x30C8
EGL_BITMAP_PIXEL_RED_OFFSET_KHR 0x30C9
EGL_BITMAP_PIXEL_GREEN_OFFSET_KHR 0x30CA
EGL_BITMAP_PIXEL_BLUE_OFFSET_KHR 0x30CB
EGL_BITMAP_PIXEL_ALPHA_OFFSET_KHR 0x30CC
EGL_BITMAP_PIXEL_LUMINANCE_OFFSET_KHR 0x30CD
Returns in the *<value> parameter of eglQuerySurface when
<attribute> is EGL_BITMAP_ORIGIN_KHR:
EGL_LOWER_LEFT_KHR 0x30CE
EGL_UPPER_LEFT_KHR 0x30CF
Additions to Chapter 2 of the EGL 1.3 Specification (EGL Operation)
Add to the end of section 2.2.2:
Finally, some surfaces may be <locked>, which allows the
implementation to map buffers of that surface into client memory
for use by software renderers(fn). Locked surfaces cannot be
used for any other purpose. When a locked surface is <unlocked>,
any changes to the mapped buffer(s) are reflected in the actual
graphics or system memory containing the surface.
[fn: on implementations not supporting mapping graphics
memory, or which do not wish to take the stability and
security risks that entail, mapping may be done using
copy-out and copy-in behavior.]
Additions to Chapter 3 of the EGL 1.3 Specification (EGL Functions and Errors)
Add to the description of the EGL_BAD_ACCESS error in section 3.1:
"... or, a surface is locked)."
Add to table 3.2 ("Types of surfaces supported by an EGLConfig")
EGL Token Name Description
-------------------- ------------------------------------
EGL_LOCK_SURFACE_BIT_KHR EGLConfig allows locking surfaces
EGL_OPTIMAL_FORMAT_BIT_KHR This format is considered optimal
(preferred) when locking / mapping /
unlocking is being done.
Change the first paragraph under "Other EGLConfig Attribute
Descriptions" on p. 16:
"EGL_SURFACE_TYPE is a mask indicating both the surface types
that can be created by the corresponding EGLConfig (the config
is said to <support> those surface types), and the optional
behaviors such surfaces may allow. The valid bit settings are
shown in Table 3.2."
Add a new paragraph following the second paragraph of the same
section:
"If EGL_LOCK_SURFACE_BIT_KHR is set in EGL_SURFACE_TYPE_KHR, then
a surface created from the EGLConfig may be locked, mapped into
client memory, and unlocked. Locking is described in section
3.5.6. If EGL_OPTIMAL_FORMAT_BIT_KHR is set in
EGL_SURFACE_TYPE_KHR, then the surface is considered optimal (by
the implementation) from a performance standpoint when buffer
mapping is being done.
Replace the second paragraph of section 3.3 "EGL Versioning":
"The EGL_CLIENT_APIS string describes which client rendering APIs
are supported. It is zero-terminated and contains a
space-separated list of API names, which may include
``OpenGL_ES'' if OpenGL ES is supported, and ``OpenVG'' if
OpenVG is supported. If no client APIs are supported, then the
empty string is returned."
Insert a new paragraph and table in section 3.4.1 "Querying
Configurations", following the description of
EGL_MATCH_NATIVE_PIXMAP on page 21:
"If EGL_MATCH_FORMAT_KHR is specified in <attrib_list>, it must
be followed by one of the attribute values EGL_DONT_CARE,
EGL_NONE, or one of the format tokens in table
[locksurf.format].
When EGL_MATCH_FORMAT_KHR has the value EGL_NONE, only configs
which cannot be locked or mapped will match. Such configs must
not have the EGL_LOCK_SURFACE_BIT_KHR set in EGL_SURFACE_TYPE.
When EGL_MATCH_FORMAT_KHR has the value EGL_DONT_CARE, it is
ignored.
When EGL_MATCH_FORMAT_KHR has one of the values in table
[locksurf.format], only EGLConfigs describing surfaces whose
color buffers have the specified format, when mapped with
eglLockSurface, will match this attribute. In this case, the
EGL_<component>_SIZE attributes of resulting configs must agree
with the specific component sizes specified by the format."
Specific Format Name Description
-------------------- -----------
EGL_FORMAT_RGB_565_EXACT_KHR RGB565 fields in order from MSB to LSB within a 16-bit integer
EGL_FORMAT_RGB_565_KHR RGB565 fields in implementation-chosen order within a 16-bit integer
EGL_FORMAT_RGBA_8888_EXACT_KHR RGBA8888 fields in B, G, R, A byte order in memory
EGL_FORMAT_RGBA_8888_KHR RGBA8888 fields in implementation-chosen order within a 32-bit integer
------------------------------------------------------------------------------------------------------
Table [locksurf.format]: Specific formats for mapped pixels.
Add to table 3.4 ("Default values and match critera for EGLConfig
attributes") on page 22:
Attribute Default Selection Sort Sort
Criteria Order Priority
-------------------- ------------- --------- ----- --------
EGL_MATCH_FORMAT_KHR EGL_DONT_CARE Exact None -
Add EGL_MATCH_FORMAT_KHR to the last paragraph in section 3.4.1 on
p. 23, describing attributes not used for sorting EGLConfigs.
Add a new section following the current section 3.5.5:
"3.5.6 Locking and Mapping Rendering Surfaces
A rendering surface may be <locked> by calling
EGLBoolean eglLockSurfaceKHR(EGLDisplay dpy,
EGLSurface surface,
const EGLint *attrib_list);
While a surface is locked, only two operations can be performed
on it. First, the color buffer of the surface may be <mapped>,
giving a pointer into client memory corresponding to the memory
of the mapped buffer, and attributes describing mapped buffers
may be queried. Second, the surface may be unlocked. Any
attempts to use a locked surface in other EGL APIs will fail and
generate an EGL_BAD_ACCESS error.
<attrib_list> specifies additional parameters affecting the locking
operation. The list has the same structure as described for
eglChooseConfig. Attributes that may be defined are shown in table
[locksurf.attr], together with their default values if not specified
in <attrib_list>, and possible values which may be specified for
them in <attrib_list>.
Attribute Name Type Default Value Possible Values
----------------------- ------- ------------- -------------------------
EGL_MAP_PRESERVE_PIXELS_KHR boolean EGL_FALSE EGL_TRUE / EGL_FALSE
EGL_LOCK_USAGE_HINT_KHR bitmask EGL_READ_SURFACE_BIT_KHR | Any combination of
EGL_WRITE_SURFACE_BIT_KHR EGL_READ_SURFACE_BIT_KHR
and EGL_WRITE_SURFACE_BIT_KHR
--------------------------------------------------------------
Table [locksurf.attr]: eglLockSurfaceKHR attribute names,
default values, and possible values.
On failure, the surface is unaffected and eglLockSurfaceKHR
returns EGL_FALSE. An EGL_BAD_ACCESS error is generated if any
of these condition, are true:
* <surface> was created with an EGLConfig whose
EGL_SURFACE_TYPE attribute does not contain
EGL_LOCK_SURFACE_BIT_KHR.
* <surface> is already locked.
* Any client API is current to <surface>.
An EGL_BAD_ATTRIBUTE error is generated if an attribute or
attribute value not described in table [locksurf.attr] is
specified.
Mapping Buffers of a Locked Surface
-----------------------------------
The color buffer of a locked surface can be <mapped> by calling
eglQuerySurface (see section 3.5.7) with <attribute>
EGL_BITMAP_POINTER_KHR(fn). The query returns a pointer to a
buffer in client memory corresponding to the color buffer of
<surface>. In the case of a back-buffered surface, color buffer
refers to the back buffer
[fn: "mapped" only means that the pointer returned is
intended to *correspond* to graphics memory. Implementation
are not required to return an actual pointer into graphics
memory, and often will not.]
The contents of the mapped buffer are initially undefined(fn)
unless the EGL_MAP_PRESERVE_PIXELS_KHR attribute of
eglLockSurfaceKHR is set to EGL_TRUE, in which case the contents
of the buffer are taken from the contents of <surface>'s color
buffer. The default value of EGL_MAP_PRESERVE_PIXELS_KHR is
EGL_FALSE.
[fn: In order to avoid pipeline stalls and readback delays on
accelerated implementations, we do not mandate that the
current contents of a color buffer appear when it's mapped
to client memory, unless the EGL_MAP_PRESERVE_PIXELS_KHR
flag is set. Applications using mapped buffers which are not
preserved must write to every pixel of the buffer before
unlocking the surface. This constraint is considered
acceptable for the intended usage scenario (full-frame
software renderers).]
The EGL_LOCK_USAGE_HINT_KHR attribute of eglLockSurfaceKHR is a
bitmask describing the intended use of the mapped buffer. If the
mask contains EGL_READ_SURFACE_BIT_KHR, data will be read from
the mapped buffer. If the mask contains
EGL_WRITE_SURFACE_BIT_KHR, data will be written to the mapped
buffer. Implementations must support both reading and writing to
a mapped buffer regardless of the value of
EGL_LOCK_USAGE_HINT_KHR, but performance may be better if the
hint is consistent with the actual usage of the buffer. The
default value of EGL_LOCK_USAGE_HINT_KHR hints that both reads
and writes to the mapped buffer will be done.
Other attributes of the mapped buffer describe the format of
pixels it contains, including its pitch (EGL_BITMAP_PITCH_KHR),
origin, pixel size, and the bit width and location of each color
component within a pixel. These attributes may be queried using
eglQuerySurface, and are described in more detail in section
3.5.7.
The EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR attributes
of a locked surface may change following successive calls to
eglLockSurfaceKHR(fn), so they must be queried each time a
buffer is mapped. Other attributes of a mapped buffer are
invariant and need be queried only once following surface
creation.
[fn: The pointer and pitch of a mapped buffer may change due
to display mode changes, for example.]
Mapping will not suceed if client memory to map the surface into
cannot be allocated. In this case, querying eglQuerySurface with
<attribute> EGL_BITMAP_POINTER_KHR will fail and generate an EGL
error.
Unlocking Surfaces
------------------
A rendering surface may be <unlocked> by calling
EGLBoolean eglUnlockSurfaceKHR(EGLDisplay dpy,
EGLSurface surface);
Any mapped buffers of <surface> become unmapped following
eglUnlockSurfaceKHR. Any changes made to mapped buffers of
<surface> which it was locked are reflected in the surface after
unlocking(fn).
[fn: This language enables implementations to either map
video memory, or copy from a separate buffer in client
memory.]
If <surface> was created with an EGLConfig whose
EGL_SURFACE_TYPE attribute contains EGL_OPTIMAL_FORMAT_BIT_KHR,
then the surface is considered optimal (by the implementation)
from a performance standpoint when buffer mapping is being
done(fn).
[fn: This often means that the format of all mapped buffers
corresponds directly to the format of those buffers in
<surface>, so no format conversions are required during
unmapping. This results in a high-performance software
rendering path. But "optimal format" is really just a hint
from EGL that this config is preferred, whatever the actual
reason.]
On failure, eglUnlockSurfaceKHR returns EGL_FALSE. An
EGL_BAD_ACCESS error is generated if any of these conditions are
true:
* <surface> is already unlocked.
* A display mode change occurred while the surface was locked,
and the implementation was unable to reflect mapped buffer
state(fn). In this case, <surface> will still be unlocked.
However, the contents of the previously mapped buffers of
<surface> become undefined, rather than reflecting changes
made in the mapped buffers in client memory.
[fn: Usually this may only occur with window surfaces which
have been mapped. EGL does not have an event mechanism to
indicate display mode changes. If such a mechanism exists
(using native platform events or the OpenKODE event system),
applications should respond to mode changes by regenerating
all visible window content, including re-doing any software
rendering overlapping the mode change.]"
Add to table 3.5 ("Queryable surface attributes and types")
Attribute Type Description
--------- ---- -----------
EGL_BITMAP_POINTER_KHR pointer Address of a mapped color buffer (MCB).
EGL_BITMAP_PITCH_KHR integer Number of bytes between the start of
adjacent rows in an MCB.
EGL_BITMAP_ORIGIN_KHR enum Bitmap origin & direction
EGL_BITMAP_PIXEL_x_OFFSET_KHR integer Bit location of each color buffer
component within a pixel in an MCB.
Add to the description of eglQuerySurface properties in section
3.5.6 (renumbered to 3.5.7) on page 33:
"Properties of a bitmap surface which may be queried include:
* EGL_BITMAP_POINTER_KHR, which maps the color buffer of a
locked surface and returns the address in client memory of
the mapped buffer.
* EGL_BITMAP_PITCH_KHR, which returns the number of bytes
between successive rows of a mapped buffer.
* EGL_BITMAP_ORIGIN_KHR, which describes the way in which a
mapped color buffer is displayed on the screen. Possible
values are either EGL_LOWER_LEFT_KHR or EGL_UPPER_LEFT_KHR,
indicating that the first pixel of the mapped buffer
corresponds to the lower left or upper left of a visible
window, respectively.
* EGL_BITMAP_PIXEL_<x>_OFFSET_KHR, which describes the bit
location of the least significant bit of each color
component of a pixel within a mapped buffer. <x> is one of
RED, GREEN, BLUE, ALPHA, or LUMINANCE.
The offset for a color component should be treated as the
number of bits to left shift the component value to place it
within a 16- (for RGB565 formats) or 32-bit (for RGBA8888
formats) integer containing the pixel(fn). If a color
component does not exist in the mapped buffer, then the bit
offset of that component is zero.
In addition to these attributes, the number of bits for each
color component of a pixel within a mapped buffer is obtained by
querying the EGL_<x>_SIZE attribute of the EGLConfig used to
create the surface, where <x> is <x> is one of RED, GREEN, BLUE,
ALPHA, or LUMINANCE. The size of a pixel in the mapped buffer,
in bytes, can be determined by querying the EGL_BUFFER_SIZE
attribute of the EGLConfig, rounding up to the nearest multiple
of 8, and converting from bits to bytes.
Querying EGL_BITMAP_POINTER_KHR and EGL_BITMAP_PITCH_KHR is only
allowed when <surface> is mapped (see section 3.5.6). Querying
either of these attributes for the first time after calling
eglLockSurfaceKHR causes the color buffer of the locked surface
to be mapped. Querying them again before unlocking the surface
will return the same values as the first time. However, after
calling eglUnlockSurfaceKHR, these properties become undefined.
After a second call to eglLockSurfaceKHR, these properties may
again be queried, but their values may have changed.
Other properties of the mapped color buffer of a surface are
invariant, and need be queried only once following surface
creation. If <surface> was created with an EGLConfig whose
EGL_SURFACE_TYPE attribute does not contain
EGL_LOCK_SURFACE_BIT_KHR, queries of EGL_BITMAP_ORIGIN_KHR and
EGL_BITMAP_PIXEL_<x>_OFFSET_KHR return undefined values."
Add to the description of eglQuerySurface errors in the last
paragraph of section 3.5.6 (renumbered to 3.5.7) on page 34:
"... If <attribute> is either EGL_BITMAP_POINTER_KHR or
EGL_BITMAP_PITCH_KHR, and either <surface> is not locked using
eglLockSurfaceKHR, or <surface> is locked but mapping fails,
then an EGL_BAD_ACCESS error is generated."
Issues
1) What is the rationale for this extension?
Software renderers on low-end implementations need an efficient way
to draw pixel data to the screen. High-end implementations must
support the same interface for compatibility, while not compromising
the accelerability of OpenGL ES and OpenVG client APIs using
dedicated graphics hardware and memory.
Using lock/unlock semantics enables low-end implementations to
expose pointers directly into display memory (as extremely dangerous
as that may be), while high-end implementations may choose to create
backing store in client memory when mapping a buffer, and copy it to
graphics memory when the surface is unlocked. Making the initial
contents of a mapped buffer undefined means that no readbacks from
graphics memory are required, avoiding pipeline stalls.
This extension is not intended to support mixed-mode (client API and
software) rendering. Since mapped buffer contents are undefined,
unless the buffer is explicitly preserved (which may be unacceptably
expensive on many implementations), applications doing software
rendering must touch every pixel of mapped buffers at least once
before unlocking the surface.
2) Do we need to know if locked surfaces are "fast" or "native"?
RESOLVED: Yes. This is indicated with the EGL_OPTIMAL_FORMAT_BIT_KHR
of EGL_SURFACE_TYPE. However, note that there is no way to guarantee
what "fast" or "no format conversions" really means; this is little
more than an implementation hint.
3) Should we be able to map buffers other than the color buffer?
RESOLVED: Not initially. However, the <attrib_list> parameter of
eglLockSurfaceKHR supports this in the future. There is no <buffer>
attribute to eglQuerySurface, so such a layered extension would have
to either create a new naming convention (such as
EGL_BITMAP_{DEPTH,COLOR,STENCIL,ALPHA_MASK}_POINTER), or define an
extended query eglQuerySurfaceBuffer() which takes a <buffer>
parameter. It would also be tricky to support interleaved depth /
stencil formats. But the attribute list offers some future-proofing
at low cost.
4) What properties of mapped buffers can be queried?
RESOLVED: A pointer to the buffer and its pitch, both of which may
change in successive lock/unlock cycles. These may be queried only
while the underlying surface is locked, and are undefined after
unlocking. The first query following locking is the point at which
actual buffer mapping must occur.
RESOLVED: Additionally, the pixel size, origin, and color component
bitfield size and offset for each component, which are invariant
and may be queried at any time.
5) How are mode changes indicated? What happens to the mapped
buffer during a mode change?
RESOLVED: UnlockSurfaceKHR fails and raises an error if a mode
change occurred while the surface was locked (although the surface
still ends up in the unlocked state - this is necessary since
there's no way to clear the error!). If a mode change occurs while a
buffer is mapped, the implementation must still allow the
application to access mapped buffer memory, even though the contents
of the mapped buffer may not be reflected in the changed window
after unmapping.
Note: There's no convenient way to indicate mode changes while
a surface is unlocked, despite that being useful to tell apps they
have to redraw. The problem is that we don't have an event system,
and the power management functionality is overkill since the only
resources which are likely to be damaged by a mode change are
visible window contents. Fortunately, this problem is beyond the
scope of this extension.
6) Does locking a surface imply mapping its buffers?
RESOLVED: No. Locking simply places the surface in that state and
prevents it from being made current / swapped / etc. Buffers are
mapped only when their pointers or pitch are queried using
eglQuerySurface.
An interesting side effect of this resolution is that calling
eglLockSurfaceKHR immediately followed by eglUnlockSurfaceKHR DOES
NOT CHANGE THE CONTENTS OF BUFFERS, since none of them were mapped.
Likewise locking a surface, querying a buffer pointer or pitch, and
then unlocking it without changing the mapped buffer contents causes
the surface contents of the mapper buffer(s) to become undefined.
At the Atlanta F2F, there was a suggestion that eglLockSurfaceKHR
should immediately map the color buffer and return a pointer to it,
on the basis that this would make it harder for applications to
mistakenly use an old buffer pointer from a previous mapping cycle.
At the same time, people working on more powerful GPUs wanted the
lock operation to be lightweight. These are not consistent goals and
we have thus far chosen to separate the lightweight locking, and
more expensive mapping operations.
7) Can buffer contents be preserved in mapping?
RESOLVED: Yes. The default behavior is to discard / leave undefined
the mapped buffer contents, but the EGL_MAP_PRESERVE_PIXELS_KHR flag
may be specified to eglLockSurfaceKHR.
8) Should usage hints be provided during mapping?
RESOLVED: Yes, they may be provided in the EGL_LOCK_USAGE_HINT_KHR
bitmask attribute to eglLockSurfaceKHR. Implementations are required
to behave correctly no matter the value of the flag vs. the
operations actually performed, so the hint may be ignored.
9) Should we be able to lock subrectangles of a surface?
RESOLVED: No. However, the attribute list parameter of
eglLockSurfaceKHR allows a layered extension to implement this
behavior by specifying an origin and size to map within the buffer.
10) Should the BITMAP_PIXEL_<component>_OFFSET attributes belong to the
surface, or the config?
RESOLVED: Part of the surface. Configs supporting a specific format
are matched with config attribute EGL_MATCH_FORMAT_KHR, which
supports specific bit-exact formats such as
EGL_FORMAT_565_EXACT_KHR.
11) Can the pixel size in a mapped buffer be derived from the
EGL_BUFFER_SIZE attribute of the config used to create it?
RESOLVED: Yes. In principle, hardware using padding bytes in its
framebuffer storage could be a problem, and a separate
BITMAP_PIXEL_SIZE surface attribute would be needed. However, we
don't think implementations are likely to waste graphics memory and
bandwidth in this fashion.
12) How are color component locations within a pixel described?
RESOLVED: Each R, G, B, and A component has a queryable bit offset
within an integer. The size of the integer depends on the total size
of the pixel; for the 565 formats, the pixel is a 16-bit integer.
For the 8888 formats, the pixel is a 32-bit integer.
We cannot describe component locations with byte locations, since
the 565 formats have components straddling byte boundaries. However,
this means that offsets for the RGBA8888_EXACT format are different
between little- and big-endian CPUs, since the desired format is B,
G, R, A components laid out as bytes in increasing memory order.
13) Can mapped buffer contents be affected by other EGL operations?
RESOLVED: No. A locked surface only allows two operations:
unlocking, and mapping. No other EGL operations can take place while
the surface is locked (if this were not the case, then
eglSwapBuffers might destroy the contents of a mapped buffer).
It is possible that operations outside the scope of EGL could affect
a mapped color buffer. For example, if a surface's color buffer were
made up of an EGLImage, one of the EGL client APIs could draw to
that image while it was mapped. Responsibility for avoiding this
situation is in the hands of the client.
14) Can EGL_MATCH_FORMAT_KHR be queried for a config?
RESOLVED: Yes. Unlockable configs return EGL_NONE for this
attribute.
15) Is a goal of this extension to support "mixed-mode" rendering (both
software and EGL client API rendering to the same surface)?
RESOLVED: No. An implementation *can* choose to export configs
supporting creation of lockable surfaces which also support
rendering by OpenGL ES, OpenVG, or other client APIs (when the
surface is not locked). But there is nothing in the extension
requiring this, and the motivation for the extension is simply to
support software rendering.
16) Can mapping a locked surface fail?
RESOLVED: Yes, if memory can't be allocated in the client. This is
indicated by queries of EGL_BITMAP_POINTER_KHR and
EGL_BITMAP_PITCH_KHR failing and generating an EGL_BAD_ACCESS error.
17) Why has this extension been obsoleted and replaced by
EGL_KHR_lock_surface3?
RESOLVED: Starting with the December 4, 2013 release of EGL 1.4, EGLint
is defined to be the same size as the native platform "int" type. Handle
and pointer attribute values *cannot* be represented in attribute lists
on platforms where sizeof(handle/pointer) > sizeof(int). Existing
extensions which assume this functionality are being replaced with new
extensions specifying new entry points to work around this issue. See
the latest EGL 1.4 Specification for more details.
Revision History
Version 19, 2013/10/15 - Add issue 17 explaining that the bitmap pointer
cannot be safely queried using this extension on 64-bit platforms,
and suggest EGL_KHR_lock_surface3 instead. Change formal parameter
names from 'display' to 'dpy' to match other EGL APIs.
Version 18, 2010/03/23 - Added introductory remark referring to the
EGL_KHR_lock_surface2 extension. Clarified that it is the back
buffer of a back-buffered surface that is mapped.
Version 17, 2008/10/08 - Updated status (approved as part of
OpenKODE 1.0).
Version 16, 2008/01/24 - Add issue 16 noting that mapping can fail,
and a corresponding new error condition for eglQuerySurface.
Clean up the issues list.
Version 15, 2008/01/09 - Add issue 15 noting that supporting
mixed-mode rendering is not a goal or requirement of the
extension.
Version 14, 2007/11/07 - change ARGB_8888_EXACT back to
RGBA_8888_EXACT, since the offsets are now dependent on the
endianness of the CPU. Add issue 12 describing this, and clarify
that offsets are within a 16- or 32-bit integer depending on the
format. Added issue 13 clarifying that locked buffer contents
are not affected by eglSwapBuffers, because eglSwapBuffers
cannot be issued on a mapped surface. Allow querying
EGL_MATCH_FORMAT_KHR for a config, and added related issue 14.
Version 13, 2007/05/10 - change RGBA_8888_EXACT to ARGB_8888_EXACT
to match hardware layout.
Version 12, 2007/04/06 - clarify that when EGL_MATCH_FORMAT_KHR is
EGL_DONT_CARE, it does not affect component size of selected
configs.
Version 11, 2007/04/05 - add missing KHR suffix to some tokens.
Version 10, 2007/04/05 - assign enumerant values. Add OpenKODE 1.0
Provisional disclaimer.
Version 9, 2007/03/26 - add format tokens to "New Tokens"
section. Correct description of RGBA format tokens.
Version 8, 2007/03/26 - add issue 11 noting theoretical possibility
of EGL_BUFFER_SIZE not directly corresponding to the mapped
pixel size. Add EGL_MATCH_FORMAT_KHR attribute to
eglChooseConfig, and 565 / 8888 formats for it.
Version 7, 2007/03/25 - note in issue 5 that access to a mapped
buffer must continue to work even after a mode change. Add KHR
suffix to new functions and tokens. Remove BITMAP_PIXEL_<x>_BITS
and BITMAP_PIXEL_SIZE tokens, which duplicate information in the
EGLConfig. Add issue 10 asking whether bitmap pixel offset
attributes belong to the config, or to the surface.
Version 6, 2007/02/26 - allow EGL_CLIENT_APIS string to be empty in
implementations supporting only this extension.
Version 5, 2007/02/05 - update contributor list. Changed bit offset
queries to return LSB offset, rather than MSB offset.
Version 4, 2007/02/02 - correct extension name. Change
name of FAST_UNLOCK_BIT_KHR to OPTIMAL_FORMAT_BIT_KHR.
Replace buffer_mask parameter of eglLockSurfaceKHR with an
attribute list. Add the EGL_MAP_PRESERVE_PIXELS_KHR and
EGL_LOCK_USAGE_HINT_KHR attributes per request from Gary. Add issues
7, 8, and 9 describing these attributes and how to support
locking subrects in a layered extension, by extending the
attribute list.
Version 3, 2007/02/01 - the implementation once again controls the
mapped buffer memory. There is no longer a separate bitmap
surface type; any type surface may potentially be mapped, using
lock/unlock semantics.
Version 2, 2006/12/22 - simplify by only supporting drawing from
client memory to EGL surface color buffers. Specify use of
OpenGL DrawPixels terminology. Change name of the extension to
EGL_KHR_draw_pixels, since there is no longer any "bitmap
surface" involved.
Version 1, 2006/12/14 - write up as formal spec language for
external review.

Some files were not shown because too many files have changed in this diff Show More