1Name 2 3 OES_texture_storage_multisample_2d_array 4 5Name Strings 6 7 GL_OES_texture_storage_multisample_2d_array 8 9Contact 10 11 Nick Hoath, Imagination Technologies Ltd (nick 'dot' hoath 'at' imgtec 12 'dot' com) 13 14Contributors 15 16 Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com) 17 Jon Leech (oddhack 'at' sonic.net) 18 Graham Sellers (graham.sellers 'at' amd.com) 19 Dominik Witczak (dominik.witczak 'at' mobica.com) 20 Tobias Hector (tobias.hector 'at' imgtec.com) 21 22Notice 23 24 Copyright (c) 2014-2019 The Khronos Group Inc. Copyright terms at 25 http://www.khronos.org/registry/speccopyright.html 26 27Specification Update Policy 28 29 Khronos-approved extension specifications are updated in response to 30 issues and bugs prioritized by the Khronos OpenGL ES Working Group. For 31 extensions which have been promoted to a core Specification, fixes will 32 first appear in the latest version of that core Specification, and will 33 eventually be backported to the extension document. This policy is 34 described in more detail at 35 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 36 37Status 38 39 Complete. 40 Ratified by the Khronos Board of Promoters on 2014/03/14. 41 42Version 43 44 Last Modified Date: January 11, 2019 45 Revision: 8 46 47Number 48 49 OpenGL ES Extension #174 50 51Dependencies 52 53 This extension is written against the OpenGL ES 3.1 (2015/04/29) 54 specification. 55 56Overview 57 58 This extension provides support for a new type of immutable texture, 59 two-dimensional multisample array textures. It depends on functionality 60 introduced in OpenGL ES 3.1 to support two-dimensional multisample 61 (non-array) textures. 62 63New Procedures and Functions 64 65 void TexStorage3DMultisampleOES(enum target, 66 sizei samples, 67 enum internalformat, 68 sizei width, 69 sizei height, 70 sizei depth, 71 boolean fixedsamplelocations); 72 73New Tokens 74 75 Accepted by the <target> parameter of BindTexture, 76 TexStorage3DMultisampleOES, GetInternalformativ, TexParameter{if}*, 77 GetTexParameter{if}v and GetTexLevelParameter{if}v. Also, the texture 78 object indicated by the <texture> argument to FramebufferTextureLayer 79 can be TEXTURE_2D_MULTISAMPLE_ARRAY_OES 80 81 TEXTURE_2D_MULTISAMPLE_ARRAY_OES 0x9102 82 83 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 84 and GetFloatv: 85 86 TEXTURE_BINDING_2D_MULTISAMPLE_ARRAY_OES 0x9105 87 88 Returned by the <type> parameter of GetActiveUniform: 89 90 SAMPLER_2D_MULTISAMPLE_ARRAY_OES 0x910B 91 INT_SAMPLER_2D_MULTISAMPLE_ARRAY_OES 0x910C 92 UNSIGNED_INT_SAMPLER_2D_MULTISAMPLE_ARRAY_OES 0x910D 93 94 95Additions to Chapter 7 of the OpenGL ES 3.1 Specification (Programs and Shaders) 96 97 Add to table 7.3 "OpenGL ES Shading Language type tokens" on p. 86: 98 99 Type Name Token Keyword Attrib Xfb Buffer 100 --------------------------------------------- ----------------- ------- ------- ------- 101 SAMPLER_2D_MULTISAMPLE_ARRAY_OES sampler2DMSArray (empty) (empty) (empty) 102 INT_SAMPLER_2D_MULTISAMPLE_ARRAY_OES isampler2DMSArray (empty) (empty) (empty) 103 UNSIGNED_INT_SAMPLER_2D_MULTISAMPLE_ARRAY_OES usampler2DMSArray (empty) (empty) (empty) 104 105 106Additions to Chapter 8 of the OpenGL ES 3.1 Specification (Textures and 107Samplers) 108 109 Modify Section 8.1, Texture Objects 110 111 Modify first paragraph of the section on p. 130, adding 2Dms array 112 textures: 113 114 Textures in GL are represented by ... The default texture object is 115 bound to each of ... and TEXTURE_2D_MULTISAMPLE_ARRAY_OES targets during 116 context initialization. 117 118 119 Modify second to last paragraph of section on p. 132: 120 121 The texture object name space, including the initial ... and 122 two-dimensional multisample array texture objects, is shared among all 123 texture units. ... 124 125 126 Modify Section 8.5.3, Texture Image Specification (p. 157) 127 128 Add the new target to MAX_TEXTURE_SIZE description: 129 130 In a similar fashion, the maximum allowable width and height of a texel 131 array for a ... or two-dimensional multisample array texture must each 132 be at least 2^(k-lod) ... 133 134 135 Modify the introduction of section 8.8 "Multisample Textures": 136 sections.) 137 138 In addition to the texture types described in previous sections, two 139 additional type of textures are supported. Multisample textures are 140 similar to two-dimensional or two-dimensional array texture, except they 141 contains multiple samples per texel. Multisample textures do not have 142 multiple image levels, and are immutable. 143 144 The commands 145 146 void TexStorage2DMultisample ... 147 void TexStorage3DMultisampleOES(enum target, sizei samples, 148 enum internalformat, 149 sizei width, sizei height, sizei depth, 150 boolean fixedsamplelocations); 151 152 establish ... For TexStorage3DMultisampleOES <target> must be 153 TEXTURE_2D_MULTISAMPLE_ARRAY_OES. <width> and <height> are the 154 dimensions in texels of the texture. 155 156 157 Modify the second paragraph on p. 172: 158 159 Upon success of TexStorage*MultisampleOES the contents of texels for 160 <target> are undefined. TEXTURE_WIDTH, TEXTURE_HEIGHT, ... 161 162 163 Modify the Errors section to specify existing errors as specific to 164 TexStorage2DMultisample only (for <target>, and for <width> and <height> 165 being too large); other existing errors are taken to apply to both 166 commands. Then add new errors for TexStorage3DMultisample: 167 168 Errors 169 170 ... 171 172 An INVALID_ENUM error is generated by TexStorage3DMultisample if 173 <target> is not TEXTURE_2D_MULTISAMPLE_ARRAY. 174 175 An INVALID_VALUE error is generated if <width>, <height> or <depth> is 176 less than 1. 177 178 An INVALID_VALUE error is generated by TexStorage3DMultisample if 179 <width> or <height> is greater than the value of MAX_TEXTURE_SIZE. 180 181 An INVALID_VALUE error is generated by TexStorage3DMultisample if 182 <depth> is greater than the value of MAX_ARRAY_TEXTURE_LAYERS. 183 184 185 Modifications to Section 8.9, "Texture Parameters", p. 173: 186 187 Add TEXTURE_2D_MULTISAMPLE_ARRAY_OES to the texture targets accepted by 188 TexParameter* in the first paragraph. 189 190 191 Add to the Errors section on p. 174/175: 192 193 Add TEXTURE_2D_MULTISAMPLE_ARRAY to the list of <target>s for which an 194 INVALID_ENUM error is *not* generated. 195 196 An INVALID_ENUM error is generated if <target> is 197 TEXTURE_2D_MULTISAMPLE_ARRAY, and <pname> is any sampler state from 198 table 6.13. 199 200 An INVALID_OPERATION error is generated if <target> is 201 TEXTURE_2D_MULTISAMPLE_ARRAY, and <pname> TEXTURE_BASE_LEVEL is set to a 202 value other than zero. 203 204 Modifications to Section 8.10.2, "Texture Parameter Queries" 205 206 Modify the second paragraph of that section on p. 175 describing the 207 <target> parameter of GetTexParameter*: 208 209 <target> may be one of ... or TEXTURE_2D_MULTISAMPLE_ARRAY_OES, 210 indicating the current ... or two-dimensional multisample array texture 211 object, respectively. 212 213 214 Modify Section 8.10.3 "Texture Level Parameter Queries" in the description 215 of GetTexLevelParameter{if}v on p. 175: 216 217 <target> may be one of ... or TEXTURE_2D_MULTISAMPLE_ARRAY_OES, 218 indicating the ... or two-dimensional multisample array target. 219 220Additions to Chapter 9 of the OpenGL ES 3.1 Specification (Framebuffers and 221Framebuffer Objects) 222 223 Modify Section 9.2.2, Attaching Images to Framebuffer Objects, p. 210: 224 225 The command 226 227 void FramebufferTextureLayer(enum target, enum attachment, 228 uint texture, int level, int layer); 229 230 operates similarly to FramebufferTexture2D, except that it 231 attaches a single layer of a ... 232 or two-dimensional multisample array texture level. 233 234 ... 235 236 If <texture> is a two-dimensional multisample array texture then <level> 237 must be zero. 238 239 Errors 240 241 ... 242 243 An INVALID_VALUE error is generated if <layer> is larger than the value 244 of MAX_ARRAY_TEXTURE_LAYERS minus one (for two-dimensional array 245 textures). 246 247 Add two-dimensional multisample arrays to the list of texture types for 248 which an INVALID_OPERATION error is *not* generated. 249 250Additions to Chapter 19 of the OpenGL ES 3.1 Specification (Context State 251Queries) 252 253 Modifications to Section 19.3, "Internal Format Queries" 254 255 Add to table 19.1 "Possible targets that <internalformat> can be used 256 with ..." 257 258 Target Usage 259 -------------------------------- ---------------------------- 260 TEXTURE_2D_MULTISAMPLE_ARRAY_OES 2D multisample array texture 261 262Errors 263 264 Errors are described in the base 3.1 spec which this extension modified, 265 or inline above. They are not summarized here. 266 267New State 268 269 (add to table 20.8, Textures (selector, state per texture unit) p. 365) 270 271 Initial 272 Get Value Type Get Command Value Description Sec. 273 ---------------------------------------- ---- ----------- ------ -------------------------------- ------ 274 TEXTURE_BINDING_2D_MULTISAMPLE_ARRAY_OES 32*xZ+ GetIntegerv 0 Texture object bound to 8.1 275 TEXTURE_2D_MULTISAMPLE_ARRAY_OES 276 277Modifications to the OpenGL ES Shading Language Specification, Version 3.10 278 279 Including the following line in a shader can be used to control the 280 language featured described in this extension: 281 282 #extension GL_OES_texture_storage_multisample_2d_array : <behavior> 283 284 where <behavior> is as specified in section 3.4. 285 286 A new preprocessor #define is added to the OpenGL ES Shading Language: 287 288 #define GL_OES_texture_storage_multisample_2d_array 1 289 290 Add to section 3.7 "Keywords" 291 292 The following new sampler types are added: 293 294 sampler2DMSArray, isampler2DMSArray, usampler2DMSArray 295 296 297 Add to section 4.1 "Basic Types" 298 299 Add the following sampler type to the "Floating Point Sampler Types (opaque)" 300 table: 301 302 sampler2DMSArray handle for accessing a 2D multisample array 303 texture 304 305 Add the following sampler type to the "Unsigned Integer Sampler 306 Types (opaque)" table: 307 308 usampler2DMSArray handle for accessing an unsigned integer 2D 309 multisample array texture 310 311 Add the following sampler type to the "Integer Sampler Types" table: 312 313 isampler2DMSArray handle for accessing an integer 2D multisample 314 array texture 315 316 317 Add to section 8.9.2 "Texel Lookup Functions" 318 319 Add new functions to the set of allowed texture lookup functions: 320 321 Syntax: 322 323 gvec4 texelFetch(gsampler2DMSArray sampler, ivec3 P, int sample) 324 325 Description: 326 327 Use integer texture coordinate <P> to lookup a single sample 328 <sample> on the texture bound to <sampler> as described in section 329 2.11.9.3 of the OpenGL ES specification "Multisample Texel Fetches". 330 331 Syntax: 332 333 ivec3 textureSize(gsampler2DMSArray sampler) 334 335 Description: 336 337 Returns the dimensions, width and height of level 0 for the 338 texture bound to <sampler>, as described in section 2.11.9.4 of 339 the OpenGL ES specification section "Texture Size Query". 340 341Examples 342 343Issues 344 345 (1) Should mutable multisample texture support be kept? 346 347 Resolution: No - only immutable multisample textures should be support by 348 this extension 349 350 (2) What should the minimum number of samples be? 351 352 Resolution: The minimum is one, but there is no requirement to implement 353 support for one, as this would be an unusual requirement. 354 355 (3) Should the new sampler types have OES suffixes? 356 357 RESOLVED: No. The non-suffixed names are reserved keywords in OpenGL ES 358 Shading Language 3.10, and can be used here. 359 360Revision History 361 362 Rev. Date Author Changes 363 ---- ---------- --------- -------------------------------------------- 364 8 2019/01/11 Jon Leech Change 'int sizedinternalformat' parameter 365 to 'enum internalformat', to follow 366 changes to the ES 3.2 specification 367 (KhronosGroup/OpenGL-API issue 30). 368 7 2016/05/03 Tobias Hector Fixed INVALID_OPERATION error message for 369 TexStorage3DMultisample to match desktop and 370 ES 3.2 371 Rebased against release version of ES 3.1 372 spec. 373 6 2015/04/16 Jon Leech Remove texture border width term b_t, which 374 doesn't exist in OpenGL ES. 375 5 2014/03/26 Jon Leech Add missing GL_ prefix to the name string. 376 4 2014/03/06 Jon Leech Change limit on TexStorage3DMultisampleOES 377 <depth> parameter to the value of 378 MAX_ARRAY_TEXTURE_LAYERS (Bug 11135). 379 3 2014/02/04 Jon Leech Remove OES suffix from sampler keywords 380 since they're reserved in GLSL-ES 3.10 381 (Bug 11636). 382 2 2014/01/30 Jon Leech Remove 2D multisample non-array textures, 383 and all common language already in the ES 384 3.1 specification draft. 385 1 2014/01/30 Jon Leech Branch from internal XXX_texture_multisample 386 spec. 387