• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Name
2
3    ANGLE_iosurface_client_buffer
4
5Name Strings
6
7    EGL_ANGLE_iosurface_client_buffer
8
9Contributors
10
11    Corentin Wallez
12    Geoff Lang
13    James Darpinian
14
15Contacts
16
17    Corentin Wallez, Google Inc. (cwallez 'at' google.com)
18
19Status
20
21    Draft
22
23Version
24    Version 4, Dec 28, 2019
25
26Number
27
28    EGL Extension #??
29
30Dependencies
31
32    This extension is written against the wording of the EGL 1.4
33    Specification.
34
35Overview
36
37    This extension allows creating EGL surfaces from IOSurface objects.
38
39New Types
40
41    None
42
43New Procedures and Functions
44
45    None
46
47New Tokens
48
49    Accepted in the <buftype> parameter of eglCreatePbufferFromClientBuffer:
50
51        EGL_IOSURFACE_ANGLE            0x3454
52        EGL_IOSURFACE_PLANE_ANGLE      0x345A
53        EGL_TEXTURE_RECTANGLE_ANGLE    0x345B
54        EGL_TEXTURE_TYPE_ANGLE         0x345C
55        EGL_TEXTURE_INTERNAL_FORMAT_ANGLE 0x345D
56        EGL_IOSURFACE_USAGE_HINT_ANGLE 0x348A
57
58    Accepted in the <attribute> parameter of
59    eglGetConfigAttrib:
60
61        EGL_BIND_TO_TEXTURE_TARGET_ANGLE 0x348D
62
63Additions to Chapter 3 of the EGL 1.4 Specification (EGL Functions and Errors)
64
65    Replace the last sentence of paragraph 1 of Section 3.5.3 with the
66    following text.
67    "Currently, the only client API resources which may be bound in this
68    fashion are OpenVG VGImage objects and IOSurface objects."
69
70    Replace the third paragraph of Section 3.5.3 with the following text.
71    "<buftype> specifies the type of buffer to be bound. The only allowed values
72    of <buftype> are EGL_OPENVG_IMAGE and EGL_IOSURFACE_ANGLE".
73
74    Append the following text to the fourth paragraph of Section 3.5.3.
75    "When <buftype> is EGL_IOSURFACE_ANGLE, <buffer> must be a valid IOSurface
76    object case into the type EGLClientBuffer."
77
78    Append to the end of Section 3.5.3.
79    "When <buftype> is EGL_IOSURFACE_ANGLE, <attrib_list> must contain all the
80    following attributes otherwise EGL_BAD_PARAMETER is generated. The
81    attributes must satisfy the following constraints otherwise
82    EGL_BAD_ATTRIBUTE is generated:
83      - EGL_TEXTURE_TYPE_ANGLE, and EGL_TEXTURE_INTERNAL_FORMAT_ANGLE followed
84    by OpenGL enums for texture types, and texture internal format
85    respectively.
86      - EGL_TEXTURE_FORMAT with a value of EGL_TEXTURE_RGBA
87      - EGL_WIDTH with a value between 1 and the width of <buffer>.
88      - EGL_HEIGHT with a value between 1 and the height of <buffer>.
89      - EGL_TEXTURE_TARGET with a value that matches the attribute
90      EGL_BIND_TO_TEXTURE_TARGET_ANGLE as queried from eglGetConfigAttrib.
91      - EGL_IOSURFACE_PLANE_ANGLE with a value between 0 and the number of
92    planes of <buffer> (exclusive).
93
94    In addition the EGL_TEXTURE_TYPE_ANGLE and
95    EGL_TEXTURE_INTERNAL_FORMAT_ANGLE attributes must be one of the
96    combinations listed in table egl.iosurface.formats or an
97    EGL_BAD_PARAMETER is generated. The combination must also be a valid
98    combinations for glTexImage2D or EGL_BAD_PARAMETER is generated.
99
100    The attribute EGL_IOSURFACE_USAGE_HINT_ANGLE may optionally be specified as
101    a combination of the bits EGL_IOSURFACE_READ_HINT_ANGLE and
102    EGL_IOSURFACE_WRITE_HINT_ANGLE. On the iOS Simulator platform, where
103    IOSurface support is incomplete, these hints indicate whether the intent is
104    to read from the IOSurface, write to it, or both. Explicitly passing 0 for
105    this attribute is equivalent to setting both the read and write usage
106    bits. This attribute is ignored on other platforms."
107
108    ---------------------------------------------------------------------------
109    Texture Type               Texture Internal Format
110    ---------------------------------------------------------------------------
111    GL_UNSIGNED_BYTE           GL_RED
112    GL_UNSIGNED_SHORT          GL_R16UI
113    GL_UNSIGNED_BYTE           GL_RG
114    GL_UNSIGNED_BYTE           GL_RGB
115    GL_UNSIGNED_BYTE           GL_BGRA_EXT
116    GL_HALF_FLOAT              GL_RGBA
117    ---------------------------------------------------------------------------
118    Table egl.iosurface.formats - Valid combinations of format, type and
119    internal format for IOSurface-backed pbuffers.
120    ---------------------------------------------------------------------------
121
122    Append to the end of Section 3.5.3.
123    "When a pbuffer is created with type EGL_IOSURFACE_ANGLE, the contents
124    of the associcated IOSurface object are undefined while the pbuffer is
125    bound to a client texture."
126
127    Append to the end of Table 3.1.
128    ---------------------------------------------------------------------------
129    Attribute                           Type    Notes
130    ---------------------------------------------------------------------------
131    EGL_BIND_TO_TEXTURE_TARGET_ANGLE    enum    Texture target supported by
132    IOSurface-backed pbuffers.
133    ---------------------------------------------------------------------------
134
135
136Issues
137
138    1. Can RGB formats be supported?
139
140    RESOLVED: Support for RGB internal formats is added in version 3. Surfaces
141    with an RGB format will ensure that the alpha channel of the IOSurface is
142    reset to 1.0 when it is used.
143
144Revision History
145
146    Version 1, 2017/12/06 - first draft.
147    Version 2, 2019/04/01 - Allow MakeCurrent.
148    Version 3, 2019/08/13 - Allow RGB internal formats
149    Version 4, 2019/12/28 - Add usage hint; require TEXTURE_RECTANGLE on macOS
150                            and TEXTURE_2D on iOS
151