1Name 2 3 ARB_texture_storage_multisample 4 5Name Strings 6 7 GL_ARB_texture_storage_multisample 8 9Contact 10 11 Graham Sellers (graham.sellers 'at' amd.com) 12 13Notice 14 15 Copyright (c) 2012-2014 The Khronos Group Inc. Copyright terms at 16 http://www.khronos.org/registry/speccopyright.html 17 18Specification Update Policy 19 20 Khronos-approved extension specifications are updated in response to 21 issues and bugs prioritized by the Khronos OpenGL Working Group. For 22 extensions which have been promoted to a core Specification, fixes will 23 first appear in the latest version of that core Specification, and will 24 eventually be backported to the extension document. This policy is 25 described in more detail at 26 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 27 28Status 29 30 Complete. 31 Approved by the ARB on 2012/06/12. 32 33Version 34 35 Last Modified Date: April 21, 2015 36 Version: 9 37 38Number 39 40 ARB Extension #141 41 42Dependencies 43 44 OpenGL 4.2 or ARB_texture_storage is required. 45 46 EXT_direct_state_access affects the definition of this extension. 47 48 This extension is written against the OpenGL 4.2 (Core) Specification. 49 50Overview 51 52 The ARB_texture_storage extension and OpenGL 4.2 introduced the concept 53 of immutable texture objects. With these objects, once their data store 54 has been sized and allocated, it could not be resized for the lifetime 55 of the objects (although its content could be updated). OpenGL 56 implementations may be able to take advantage of the knowledge that the 57 underlying data store of certain objects cannot be deleted or otherwise 58 reallocated without destruction of the whole object (normally, a much 59 heavier weight and less frequent operation). Immutable storage 60 for all types of textures besides multisample and buffer textures was 61 introduced by ARB_texture_storage. For completeness, this extension 62 introduces immutable storage for multisampled textures. 63 64IP Status 65 66 No known IP claims. 67 68New Procedures and Functions 69 70 void TexStorage2DMultisample(enum target, 71 sizei samples, 72 enum internalformat, 73 sizei width, 74 sizei height, 75 boolean fixedsamplelocations); 76 77 void TexStorage3DMultisample(enum target, 78 sizei samples, 79 enum internalformat, 80 sizei width, 81 sizei height, 82 sizei depth, 83 boolean fixedsamplelocations); 84 85 (the following two functions are provided if and only if 86 EXT_direct_state_access is supported) 87 88 void TextureStorage2DMultisampleEXT(uint texture, 89 enum target, 90 sizei samples, 91 enum internalformat, 92 sizei width, 93 sizei height, 94 boolean fixedsamplelocations); 95 96 void TextureStorage3DMultisampleEXT(uint texture, 97 enum target, 98 sizei samples, 99 enum internalformat, 100 sizei width, 101 sizei height, 102 sizei depth, 103 boolean fixedsamplelocations); 104 105New Tokens 106 107 None. 108 109Additions to Chapter 2 of the OpenGL 4.2 (Core Profile) Specification 110(OpenGL Operation) 111 112 None. 113 114Additions to Chapter 3 of the OpenGL 4.2 (Core Profile) Specification 115(Rasterization) 116 117 Modifications to Section 3.9.8, "Texture Parameters": 118 119 Add TEXTURE_2D_MULTISAMPLE and TEXTURE_2D_MULTISAMPLE_ARRAY to the 120 texture targets accepted by TexParameter*. 121 122 At the end of Section 3.9.8, modify the last sentence to be: 123 124 An INVALID_OPERATION error is generated if TEXTURE_BASE_LEVEL is set 125 to any value other than zero. 126 127 Add the following paragraph to the end of Section 3.9.8: 128 129 When <target> is TEXTURE_2D_MULTISAMPLE or 130 TEXTURE_2D_MULTISAMPLE_ARRAY, certain texture parameters may not be 131 specified. In this case, an INVALID_OPERATION error is generated if the 132 parameter is any sampler state value from table 6.18. An 133 INVALID_OPERATION error is generated if TEXTURE_BASE_LEVEL is set to any 134 value other than zero. 135 136 In Subsection 3.9.16, "Immutable-Format Texture Images", add the following, 137 after the discussion of TexStorage3D on p. 260: 138 139 void TexStorage2DMultisample(enum target, 140 sizei samples, 141 enum internalformat, 142 sizei width, 143 sizei height, 144 boolean fixedsamplelocations); 145 146 specifies a two-dimensional multisample texture (or proxy). <target> must 147 be TEXTURE_2D_MULTISAMPLE or PROXY_TEXTURE_2D_MULTISAMPLE. The 148 pseudo-code is equivalent to calling TexImage2DMultisample with the 149 equivalently named parameters set to the same values. 150 151 void TexStorage3DMultisample(enum target, 152 sizei samples, 153 enum internalformat, 154 sizei width, 155 sizei height, 156 sizei depth, 157 boolean fixedsamplelocations); 158 159 specifies a two-dimensional multisample array texture (or proxy). <target> 160 must be TEXTURE_2D_MULTISAMPLE_ARRAY or PROXY_TEXTURE_2D_MULTISAMPLE_ARRAY. 161 The pseudo-code is equivalent to calling TexImage3DMultisample with the 162 equivalently named parameters set to the same values. 163 164 The functions 165 166 void TextureStorage2DMultisampleEXT(uint texture, 167 enum target, 168 sizei samples, 169 enum internalformat, 170 sizei width, 171 sizei height, 172 boolean fixedsamplelocations); 173 174 and 175 176 void TextureStorage3DMultisampleEXT(uint texture, 177 enum target, 178 sizei samples, 179 enum internalformat, 180 sizei width, 181 sizei height, 182 sizei depth, 183 boolean fixedsamplelocations); 184 185 behave similarly to TexStorage2DMultisample and TexStorage3DMultisample, 186 respectively, except that the texture whose storage to allocate is given 187 by the <texture> parameter rather than being retrieved from the binding of the 188 active texture unit specified by <target>. <name> must be a name previously 189 reserved by a call to GenTextures and not subsequently deleted. If 190 <texture> is not the name of an existing texture object, then one is 191 created with that name. 192 193Additions to Chapter 4 of the OpenGL 4.2 (Core Profile) Specification 194(Per-Fragment Operations and the Frame Buffer) 195 196 None. 197 198Additions to Chapter 5 of the OpenGL 4.2 (Core Profile) Specification 199(Special Functions) 200 201 None. 202 203Additions to Chapter 6 of the OpenGL 4.2 (Core Profile) Specification 204(State and State Requests) 205 206 Modifications to Section 6.1.3, "Enumerated Queries" 207 208 Modify the paragraph describing the <target> parameter to of 209 GetTexParameter* as follows: 210 211 <target> may be one of TEXTURE_1D, TEXTURE_2D, TEXTURE_3D, 212 TEXTURE_1D_ARRAY, TEXTURE_2D_ARRAY, TEXTURE_RECTANGLE, TEXTURE_CUBE_MAP, 213 TEXTURE_CUBE_MAP_ARRAY, TEXTURE_2D_MULTISAMPLE or 214 TEXTURE_2D_MULTISAMPLE_ARRAY, indicating the currently bound one-, two-, 215 three-dimensional, one- or two-dimensional array, rectangular, cube map, 216 cube map array, two-dimensional multisample, or two-dimensional 217 multisample array texture object, respectively. 218 219Errors 220 221 INVALID_OPERATION is generated by TexStorage2DMultisample and 222 TexStorage3DMultisample if <samples> is greater than the maximum number 223 of samples supported for the specified <target> and <internalformat> 224 combination. 225 226 INVALID_OPERATION is generated by TexStorage2DMultisample or 227 TexStorage3DMultisample if the value of TEXTURE_IMMUTABLE_FORMAT for the 228 texture currently bound to <target> on the active texture unit is TRUE. 229 230 INVALID_OPERATION is generated by TextureStorage2DMultisampleEXT and 231 TextureStorage3DMultisampleEXT if <target> does not match the target 232 of the texture object named by the <texture> parameter. 233 234 INVALID_VALUE is generated by TexStorage2DMultisample and 235 TexStorage3DMultisample if <width> or <height> is greater than the value 236 of MAX_TEXTURE_SIZE. 237 238 INVALID_VALUE is generated by TexStorage3DMultisample if <depth> is 239 greater than the value of MAX_ARRAY_TEXTURE_LAYERS. 240 241 INVALID_OPERATION is generated by TexParameter* if <target> is 242 TEXTURE_RECTANGLE, <pname> is TEXTURE_BASE_LEVEL, and <value> is not 243 zero. 244 245 INVALID_OPERATION is generated by TexParameter* if <target> is either 246 TEXTURE_2D_MULTISAMPLE or TEXTURE_2D_MULTISAMPLE_ARRAY, <pname> is 247 TEXTURE_BASE_LEVEL, and <value> is not zero. 248 249 INVALID_ENUM is generated by TexStorage2DMultisample if <target> is not 250 TEXTURE_2D_MULTISAMPLE or PROXY_TEXTURE_2D_MULTISAMPLE. 251 252 INVALID_ENUM is generated by TexStorage3DMultisample if <target> is not 253 TEXTURE_2D_MULTISAMPLE_ARRAY or PROXY_TEXTURE_2D_MULTISAMPLE_ARRAY. 254 255 INVALID_OPERATION is generated by TexParameter* if <target> is either 256 TEXTURE_2D_MULTISAMPLE or TEXTURE_2D_MULTISAMPLE_ARRAY and <pname> 257 is sampler state value from table 6.18. 258 259New State 260 261 None. 262 263Conformance Tests 264 265 TBD 266 267Dependencies on EXT_direct_state_access 268 269 If the EXT_direct_state_access extension is not supported, remove all 270 references to TextureStorage2DMultisampleEXT and TextureStorage3DMultisampleEXT. 271 272Issues 273 274 1) Should TexStorage3DMultisample generate INVALID_VALUE if the 275 <depth> parameter exceeds the allowed limits? Which limit to use? 276 277 DISCUSSION: We do generate errors if <width> or <height> are 278 greater than the value of MAX_TEXTURE_SIZE but it is unclear 279 whether MAX_3D_TEXTURE_SIZE or MAX_ARRAY_TEXTURE_LAYERS should 280 be used. Currently, only MAX_ARRAY_TEXTURE_LAYERS would make 281 sense, but we can also specify the error checking behavior to 282 be based on the <target> parameter. 283 On the other hand, TexImage3DMultisample does not generate 284 any errors based on the value of the <depth> parameter. 285 286 RESOLVED: Match the behavior of TexImage3DMultisample. 287 288Revision History 289 290 Rev. Date Author Changes 291 ---- ---------- -------- ------------------------------------------------ 292 9 04/21/2015 Jon Leech Change texture size limits for <depth> parameter 293 of TexImage3DMultisample to the value of 294 MAX_ARRAY_TEXTURE_LAYERS (Bug 11135). 295 8 02/28/2014 Jon Leech Change texture size limits for 296 TexImage3DMultisample to the value of 297 MAX_3D_TEXTURE_SIZE (Bugs 11134, 11135). 298 7 06/28/2012 pdaniell Update the error conditions again based on 299 our agreement in today's ARB meeting. 300 6 06/27/2012 Jon Leech Clean up new error conditions for 2D MS 301 targets with TexParameter*. 302 5 06/21/2012 gsellers Allow multisample targets to be used with 303 TexParameter* and GetTexParameter*. 304 4 05/29/2012 Jon Leech Finish fixing typos with <fixedsamplelocations>. 305 3 05/14/2012 pbrown Fix typos in <internalformat> parameter names; 306 change the <internalformat> and 307 <fixedsamplelocations> parameters to use lower 308 case for consistency with existing APIs. 309 2 05/02/2012 drakos Added EXT suffix to TextureStorage*Multisample 310 where it was missing. 311 Added issue #1. 312 Removed error condition based on the value 313 of <depth>. 314 1 04/19/2012 gsellers Initial draft 315