1Name 2 3 ARB_shader_texture_image_samples 4 5Name Strings 6 7 GL_ARB_shader_texture_image_samples 8 9Contact 10 11 Piers Daniell, NVIDIA (pdaniell@nvidia.com) 12 Mathias Schott, NVIDIA (mschott@nvidia.com) 13 14Contributors 15 16 Tristan Lorach, NVIDIA (tlorach@nvidia.com) 17 Christophe Riccio, Unity (christophe.riccio@unity3d.com) 18 Evan Hart, NVIDIA (ehart@nvidia.com) 19 Jeannot Breton, NVIDIA (jbreton@nvidia.com) 20 21Notice 22 23 Copyright (c) 2014 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 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 ARB on June 26, 2014. 40 Ratified by the Khronos Board of Promoters on August 7, 2014. 41 42Version 43 44 Last Modified Date: May 28, 2014 45 Revision: 7 46 47Number 48 49 ARB Extension #166 50 51Dependencies 52 53 Either GLSL 1.50 or ARB_texture_multisample is required. 54 55 This extension is written against the OpenGL 4.4 specification and 56 version 4.40 of the OpenGL Shading Language Specification. 57 58 This extension interacts with ARB_shader_image_load_store and GLSL 4.20. 59 60 This extension interacts with NV_gpu_program5, EXT_shader_image_load_store 61 and NV_texture_multisample. 62 63Overview 64 65 This extension provides GLSL built-in functions allowing shaders to query 66 the number of samples of a texture. 67 68New Procedures and Functions 69 70 None. 71 72New Tokens 73 74 None. 75 76Additions to the OpenGL 4.4 (Core Profile) Specification 77 78 None. 79 80Errors 81 82 None. 83 84New State 85 86 None. 87 88New Implementation Dependent State 89 90 None. 91 92Modifications to The OpenGL Shading Language Specification, Version 4.40.08 93 94 Including the following line in a shader can be used to control the 95 language features described in this extension: 96 97 #extension GL_ARB_shader_texture_image_samples 98 99 A new preprocessor #define is added to the OpenGL Shading Language: 100 101 #define GL_ARB_shader_texture_image_samples 1 102 103 Add to table in section 8.9.1 "Texture Query Functions" 104 105 Syntax: 106 107 int textureSamples(gsampler2DMS sampler) 108 int textureSamples(gsampler2DMSArray sampler) 109 110 Description: 111 112 Returns the number of samples of the texture or textures bound to 113 <sampler>. 114 115Add to table in section 8.12 "Image Functions" 116 117 Syntax: 118 119 int imageSamples(gimage2DMS image) 120 int imageSamples(gimage2DMSArray image) 121 122 Description: 123 124 Returns the number of samples of the image or images bound to <image>. 125 126Dependencies on ARB_shader_image_load_store and GLSL 4.20. 127 128 If neither ARB_shader_image_load_store nor GLSL 4.20 is enabled in the 129 shader, then all overloads of imageSamples are removed. 130 131Dependencies on NV_gpu_program5, EXT_shader_image_load_store and 132NV_texture_multisample 133 134 If NV_gpu_program5, EXT_shader_image_load_store and NV_texture_multisample 135 are supported, and "OPTION ARB_shader_texture_image_samples" is specified 136 in an assembly program, the following edits are made to extend the assembly 137 programming model documented in the NV_gpu_program4 extension and extended 138 by NV_gpu_program5, EXT_shader_image_load_store and NV_texture_multisample. 139 140 If NV_gpu_program5, EXT_shader_image_load_store or NV_texture_multisample 141 are not supported, or if "OPTION ARB_shader_texture_image_samples" is not 142 specified in an assembly program, the contents of this dependencies section 143 should be ignored. 144 145 Section 2.X.2, Program Grammar 146 147 (add the following rules to the grammar) 148 149 <ImageInstruction> ::= <IMQSop_instruction> 150 151 <IMQSop_instruction> ::= <IMQSop> <opModifiers> <instResult> "," 152 <imageAccess> 153 154 <IMQSop> ::= "IMQS" 155 156 <TEXop_instruction> ::= <TXQSop> <opModifiers> <instResult> "," 157 <texAccess> 158 159 <TXQSop> ::= "TXQS" 160 161 162 Modify Section 2.X.4, Program Execution Environment 163 164 Instr- Modifiers 165 uction V F I C S H D Out Inputs Description 166 ------- -- - - - - - - --- -------- -------------------------------- 167 IMQS 50 - - - - - S s i image sample query 168 TXQS 50 - - - - - S s t texture sample query 169 170 (Add to "Section 2.X.6, Program Options" of the NV_gpu_program4 extension, 171 as extended by NV_gpu_program5) 172 173 + Texture and image sample query (ARB_shader_texture_image_samples) 174 175 If a program specifies the "ARB_shader_texture_image_samples" option, it 176 may use the instructions TXQS and IMQS. If this option is not specified, 177 a program will fail to compile if it uses one of those two instructions. 178 179 180 Section 2.X.8.Z, IMQS: Image sample query 181 182 The IMQS instruction returns the number of samples of the image unit 183 specified by <imageUnit>. Two image targets are supported: 2DMS and 184 ARRAY2DMS. If the texture bound to the image unit has a TEXTURE_SAMPLES 185 value of 0, the instruction will return 1. IMQS supports no data type 186 modifiers; the result scalar is interpreted as a signed integer. IMQS 187 supports no storage modifier, since the number of sample is independent of 188 the image unit format. 189 190 191 Section 2.X.8.Z, TXQS: Texture sample query 192 193 The TXQS instruction returns the number of samples of the texture image 194 unit specified by <texImageUnit>. Two texture targets are supported: 195 2DMS and ARRAY2DMS. If the texture has a TEXTURE_SAMPLES value of 0, the 196 instruction will return 1. TXQS supports no data type modifiers; the 197 result scalar is interpreted as a signed integer. 198 199 200Conformance Tests 201 202 <TBD> 203 204Issues 205 206 (1) What should we call this extension? 207 208 GL_ARB_shader_image_size added imageSize which apparently was missed 209 from GL_ARB_shader_image_load_store 210 GL_ARB_texture_multisample had textureSize built in, so no precedence 211 212 Ideas: 213 * GL_ARB_shader_sample_count_query 214 * GL_ARB_shader_samples_query 215 * GL_ARB_shader_texture_image_sample_count_query 216 * GL_ARB_shader_texture_image_samples 217 * GL_ARB_shader_texture_image_size_multisample 218 * GL_ARB_shader_texture_image_samples 219 * GL_ARB_shader_texture_samples 220 221 RESOLVED: ARB_shader_texture_image_samples for now to 222 follow the precedent set by GL_ARB_shader_image_size. 223 224 Might change depending on what the final resolution is for Issue (2) 225 226 (2) How should we expose this? 227 228 (A) separate textureSamples/imageSamples functions to query 229 just the number of samples 230 231 orthogonal to other functions, makes it also easy to add non-awkward 232 versions for non MS textures that return 1. 233 234 (B) (like that other API): extend textureSize/imageSize to return another 235 component in the returned (vec) value 236 237 impossible to overload functions based on return type 238 239 (C) textureSizeMS/imageSizeMS functions that return the number 240 of samples in the last component of the returned (vec) value 241 242 Closer to that other API, but ugly and awkward to have non-ms textures 243 as arguments for a *SizeMS function. 244 245 GL_ARB_texture_multisample Issue (5) suggests A) or (C) as options 246 247 RESOLVED: Option A 248 249 (3) Do we need overloads for g*Shadow samplers 250 251 For consistency with textureSize. 252 253 RESOLVED: No, see issue (5). 254 255 (4) What other extensions interact with this 256 257 NV_gpu_program5, EXT_shader_image_load_store, and NV_texture_multisample. 258 259 What's the minimal GL/GLSL version we need to depend on. 260 261 RESOLVED: The functionality added by this extension is 262 perfectly well defined in any shading language version that 263 supports multisample textures. If the shading language, with 264 extensions, does not support images, then imageSamples is not 265 available. 266 267 (5) Do we need overloads for non-MS textures and images 268 269 RESOLVED: No, since the always would return 1. If required, users can create 270 their own overloads that return 1 for non-MS samplers. 271 272 (6) Should we add functions to query the position of a sample 273 274 RESOLVED: No because of the complexity and implementation burden 275 of supporting queries of multisample texture created with 276 fixedsamplelocation as false. In that case each pixel might have 277 different sample locations. If the app really needs to know the 278 sample location inside the shader it can pass in this data as 279 a uniforms initialized from GetMultisamplefv(SAMPLE_POSITION) 280 queries. 281 282Revision History 283 Revision 8, 2015/09/08 (idr) 284 - Add interactions with various GLSL versions and extensions so 285 that this extension can be used with any GLSL version. 286 287 Revision 7, 2014/05/28 (mschott) 288 - Minor cleanups of NV_gpu_program5 dependencies in issue 5 and the introduction 289 290 Revision 6, 2014/05/27 (jbreton) 291 - Add NV_gpu_program5 dependencies 292 293 Revision 5, 2014/04/16 (pdaniell) 294 - Removed textureSamplePosition and imageSamplePosition 295 - Resolved issue 6 296 297 Revision 4, 2014/04/09 (mschott) 298 - added textureSamplePosition and imageSamplePosition 299 - added issue 6 300 301 Revision 3, 2014/03/31 (mschott) 302 - removed non-MS overloads 303 - added issue 5 304 305 Revision 2, 2013/12/13 (mschott) 306 - Renamed to GL_ARB_texture_image_samples 307 - added shadow sampler overloads 308 309 Revision 1, 2013/12/13 (mschott) 310 - First draft 311