1Name 2 3 OES_EGL_image_external_essl3 4 5Name Strings 6 7 GL_OES_EGL_image_external_essl3 8 9Contributors 10 11 Jan-Harald Fredriksen, ARM (jan-harald.fredriksen 'at' arm.com) 12 James Helferty, NVIDIA (jhelferty 'at' nvidia.com) 13 Mark Callow, ArtSpark Holdings Inc (callow.mark 'a' artspark.co.jp) 14 15 Contributors to GL_OES_EGL_image_external. 16 17Contacts 18 19 Jan-Harald Fredriksen, ARM (jan-harald.fredriksen 'at' arm.com) 20 21Notice 22 23 Copyright (c) 2014-2015 The Khronos Group Inc. Copyright terms at 24 http://www.khronos.org/registry/speccopyright.html 25 26Specification Update Policy 27 28 Khronos-approved extension specifications are updated in response to 29 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 30 extensions which have been promoted to a core Specification, fixes will 31 first appear in the latest version of that core Specification, and will 32 eventually be backported to the extension document. This policy is 33 described in more detail at 34 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 35 36Status 37 38 Complete. 39 Approved by the OpenGL ES Working Group. 40 Ratified by the Khronos Board of Promoters on January 23, 2015. 41 42Version 43 44 January 29, 2016 (version 10) 45 46Number 47 48 OpenGL ES Extension #220 49 50Dependencies 51 52 Requires OpenGL ES 3.0 and ESSL 3.0. 53 Requires EGL 1.2 54 Requires either the EGL_KHR_image_base or the EGL_KHR_image extension. 55 Requires OES_EGL_image_external. 56 57 This extension is written based on the wording of the OpenGL ES 3.0.3 58 specification, the OpenGL ES Shading Language version 3.0 rev4, and the 59 OES_EGL_image_external extension. 60 61 This extension interacts with OpenGL ES 3.1. 62 63 This extension interacts with GL_EXT_gpu_shader5 and GL_OES_gpu_shader5. 64 65 This extension borrows concepts and function names from the 66 GL_OES_EGL_image and OES_EGL_image_external extensions. This extension 67 is compatible with GL_OES_EGL_image but does not require it. 68 69Overview 70 71 OES_EGL_image_external provides a mechanism for creating EGLImage texture 72 targets from EGLImages, but only specified language interactions for the 73 OpenGL ES Shading Language version 1.0. This extension adds support for 74 versions 3.x of the OpenGL ES Shading Language. 75 76Glossary 77 78 Please see the EGL_OES_image_base specification for a list of terms 79 used by this specification. 80 81New Types 82 83 * New sampler type allowed by the OpenGL ES Shading Language when 84 * #extension GL_OES_EGL_image_external_essl3 85 * is used. 86 */ 87 samplerExternalOES 88 89New Procedures and Functions 90 91 None. 92 93New Tokens 94 95 None. 96 97Changes to section 3.8.2 ("Sampler Objects") of the OpenGL ES 3.0.3 specification 98 99 - Add to the description BindSampler: 100 101 "If state is present in a sampler object bound to a texture unit that 102 would have been rejected by a call to TexParameter* for the texture 103 bound to that unit, the behavior of the implementation is as if the 104 texture were incomplete. For example, if TEXTURE_WRAP_S or 105 TEXTURE_WRAP_T is set to anything but CLAMP_TO_EDGE on the sampler 106 object bound to a texture unit and the texture bound to that unit is 107 an external texture, the texture will be considered incomplete. 108 109 Sampler object state which does not affect sampling for the type of 110 texture bound to a texture unit, such as TEXTURE_WRAP_R for an external 111 texture, does not affect completeness." 112 113Changes to section 3.7.14 ("External Textures") of the OES_EGL_image_external 114specification 115 116 "It is an INVALID_OPERATION error to set the TEXTURE_BASE_LEVEL 117 to a value other than zero." 118 119[[Only if OpenGL ES 3.1 is supported]] 120Changes to section 8.22 ("Texture Image Loads and Stores") of the 121OpenGL ES 3.1 specification 122 123 On p. 196 in the errors section for BindImageTexture, replace the 124 last error with the following: 125 126 "An INVALID_OPERATION error is generated if <texture> is neither the 127 name of an immutable texture object, nor the name of an external 128 texture object. 129 130 Add to table 8.26 "Mapping of image load, store..." 131 132 Texture target face/ 133 i j k layer 134 -------------------------- -- -- -- ----- 135 TEXTURE_EXTERNAL_OES x y - - 136 137Changes to section 3.7 ("Keywords") of the OpenGL ES Shading Language 138specification 139 140 - Add to the list of keywords: 141 142 "samplerExternalOES" 143 144Changes to section 4.1 ("Basic Types") of the OpenGL ES Shading Language 145specification 146 147 - Add to the list of Floating Point Sampler Types (opaque): 148 149 "samplerExternalOES a handle for accessing an external 2D texture" 150 151 - Add a paragraph at the end of the section: 152 153 "The samplerExternalOES type is optional and must be enabled by 154 155 #extension GL_OES_EGL_image_external_essl3 : enable" 156 157Changes to section 4.5.4 ("Default Precision Qualifiers") of the OpenGL ES 158Shading Language specification 159 160 - Add the following paragraph: 161 162 "All languages have the following predeclared globally scoped default 163 precision statements: 164 165 precision lowp samplerExternalOES;" 166 167Changes to section 8.8 ("Texture Lookup Functions") of the OpenGL ES Shading 168Language specification 169 170 - Add to the table the following sampler functions: 171 172 "highp ivec2 textureSize(samplerExternalOES sampler, int lod) 173 vec4 texture(samplerExternalOES sampler, vec2 P [, float bias] ) 174 vec4 textureProj(samplerExternalOES sampler, vec3 P [, float bias] ) 175 vec4 textureProj(samplerExternalOES sampler, vec4 P [, float bias]) 176 vec4 texelFetch(samplerExternalOES sampler, ivec2 P, int lod)" 177 178Changes to section 9 ("Shading Language Grammar") of the OpenGL ES Shading 179Language specification 180 181 - Add to token list: 182 183 "SAMPLEREXTERNAL" 184 185 - Add following "type_specifier_no_array:" 186 187 "SAMPLEREXTERNAL" 188 189Changes to section 11 ("Counting of Inputs and Outputs") of the OpenGL ES 190Shading Language specification 191 192 - Add a paragraph at the end 193 194 "Part of the storage may be reserved by an implementation for its own 195 use e.g. for conversion of external textures. This reduces the number 196 of uniforms available to the shader. The size of this reduction is 197 undefined but should be minimized. 198 199Dependencies on OpenGL ES 3.1 and ESSL 3.10 200 201 All texture built-in functions added in ESSL 3.10 are excluded from this 202 extension per Issue 4. This extension is expected to work without 203 modification for ESSL 3.10. 204 205 If OpenGL ES 3.1 is not supported, ignore changes to section 8.22 since 206 image load store is not supported. 207 208Interactions with EXT_gpu_shader5 and OES_gpu_shader5 209 210 If either of these extensions is supported, add the following paragraph 211 to the end of section 4.1.7.1 ("Samplers") of the ESSL 3.10 specification: 212 213 "When aggregated into arrays within a shader, external samplers can 214 only be indexed with a constant integral expression. All other sampler 215 types can only be indexed with a dynamically uniform integral 216 expression, otherwise results are undefined." 217 218Issues 219 220 1. Why is this functionality not added as an interaction to the 221 OES_EGL_image_external extension as in interaction with ESSL 3.x? 222 223 RESOLVED. 224 225 Since the built-in texture functions in ESSL were modified going from 226 ESSL 1.0 to 3.x, the original extension does not trivially apply to 227 ESSL 3.x. 228 229 There are also many shipping implementations of OES_EGL_image_external 230 extension that have chosen to not extend support to ESSL 3.x. If we 231 were to amend the original extension, there would be no way for 232 applications to determine whether a particular implementation supported 233 the language extension for ESSL 3.x or not. 234 235 2. Should this extension require OES_EGL_image_external? 236 237 RESOLVED: Yes. 238 239 This extension currently depends on OES_EGL_image_external to define the 240 API extensions. This also implies that an implementation cannot choose 241 to support this extension for ESSL 3.x only. 242 243 3. What should this extension be called? 244 245 RESOLVED: OES_EGL_image_external_essl3 246 247 4. Should built-in functions beyond ESSL1 compatibility be supported in 248 ESSL 3.x shaders? 249 250 RESOLVED: Yes. 251 252 It seems useful to add some of these. The ESSL 3.x built-ins that are 253 only useful for mipmapped textures are excluded since external textures 254 cannot be mipmapped. The ESSL 3.x built-ins that require offsets are 255 excluded since it is not clear how these should work with sub-sampled 256 YUV formats. 257 258 Required for ESSL1 feature compatibility: 259 - texture 260 - textureProj (two versions) 261 262 Also included in this extension: 263 - textureSize 264 - texelFetch 265 266 Excluded from this extension: 267 - textureLod 268 - textureLodOffset 269 - textureProjLod 270 - textureProjLodOffset 271 - textureGrad 272 - textureGradOffset 273 - textureProjGrad 274 - textureProjGradOffset 275 - textureOffset 276 - texelFetchOffset 277 - textureProjOffset 278 - textureGather [for ESSL 3.10] 279 - textureGatherOffset [for ESSL 3.10] 280 281 5. Should external integer textures be supported in ESSL 3.x shaders? 282 283 RESOLVED: No. 284 285 The built-in functions added for ESSL1 always return floating point 286 values, but that's in part because OpenGL ES 2.0 did not support 287 integer textures. For ESSL 3.x, we could allow the same return values 288 for external textures as for regular 2D textures. This would require 289 adding new sampler types, such as samplerExternaliOES and 290 samplerExternaluOES. Since there is no obvious use-case for external 291 integer textures these are not added by this extension. 292 293 6. What token should be used to enable this extension in ESSL 3.x? 294 295 RESOLVED: GL_OES_EGL_image_external_essl3 296 297 The alternatives are a) reuse the GL_OES_image_external token (this 298 should not cause problems since the original extension did not apply 299 to ESSL 3.x), b) use the name of this extension. Option b) is chosen 300 since there is no clear benefit to reusing the old name. 301 302 7. What is the interaction with separate sampler objects? 303 304 RESOLVED: The texture is incomplete if the sampler object state is 305 not compatible with the sampler state. 306 307 The OES_EGL_image_external specifies that the only supported min filter 308 modes for external textures is LINEAR or NEAREST and that the only 309 valid s and t wrap mode is CLAMP_TO_EDGE. TexParameter* will generate 310 errors if these are called while an external texture is bound. In ES3.x 311 it is possible to attach a sampler object that has any wrap mode and 312 min filter. In this case, the external texture will be treated as 313 incomplete if the sampler object state is incompatible with such 314 textures. 315 316 Sampler state that affects completeness of external textures: 317 - TEXTURE_MIN_FILTER 318 - TEXTURE_WRAP_S 319 - TEXTURE_WRAP_T 320 321 Sampler state that has no additional constraints for external textures: 322 - TEXTURE_MAG_FILTER 323 324 Sampler state that does not affect external textures, and thus have 325 no impact on completeness or behavior: 326 - TEXTURE_WRAP_R (3D or 2Darray for external textures) 327 - TEXTURE_COMPARE_MODE (no shadow sampler for external textures) 328 - TEXTURE_COMPARE_FUNC (no shadow sampler for external textures) 329 - TEXTURE_MIN_LOD (no mipmapping for external textures) 330 - TEXTURE_MAX_LOD (no mipmapping for external textures) 331 332 8. What is the interaction with the texture base level? 333 334 RESOLVED: The base level must be zero for external textures. 335 336 External textures do not support mipmap filtering. It is consistent 337 with the behavior for 2D multisampled textures in ES3.1 to make it an 338 error to specify a base level other than zero for external textures. 339 340 This error is not specified in GL_OES_EGL_image_external so adding an 341 error may break existing applications using that extension (in ESSL 1.x) 342 in combination with OpenGL ES 3.x if they set the base level to any 343 other value. 344 345 9. What formats are supported? 346 347 This is implementation defined. GL_OES_EGL_image_external does not 348 require any specific formats, and this extension does not change 349 that. On a given implementation, it is expected that the same set 350 of formats is supported in all shader stages. 351 352 10. Should image / load store be supported? And, if so, how? 353 354 RESOLVED: Yes, in a limited form. 355 356 Allowing image / load store on external textures enables compute 357 shaders to write to these textures. 358 359 A limited set of use-cases is enabled by making glBindImageTexture 360 accept external textures. Shaders can access such external textures 361 using the existing <image2D> sampler type. 362 363 Since the image format must be specified by the shader, no additional 364 format conversion is done for external textures accessed via image 365 load/store. This implies that the shader author must know the format of 366 the external texture in order to do useful work. Also, only the image 367 formats already supported by image load store are available (i.e, there 368 is no automatic conversion to, for example, YUV formats.) 369 370Revision History 371 372 #10 - (Jan 29, 2016) Fixed typo in issue 10. 373 #9 - (Apr 10, 2015) Clarified issue 10. Specified default precision for 374 samplerExternalOES as lowp for all shader stages. 375 #8 - (Feb 6, 2015) Fixed typo in return value of textureSize (vec2->ivec2) 376 #7 - (Oct 15, 2014) Resolved issue 10. Added interaction with EXT_gpu_shader5. 377 #6 - (Oct 10, 2014) Added issue 10 and its tentative resolution. 378 #5 - (Sep 25, 2014) Updated resolution of issue 7. 379 Added issues 8 and 9. 380 Converted to OES. 381 #4 - (Sep 24, 2014) Added issue 7 with proposed resolution. 382 #3 - (Jul 30, 2014) Excluded textureGather from this extension. 383 #2 - (Jul 30, 2014) Updated based feedback. Tentatively resolved issues. 384 Added issue 6. 385 #1 - (Jul 15, 2014) Original draft. 386