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