1Name 2 3 ARB_texture_gather 4 5Name Strings 6 7 GL_ARB_texture_gather 8 9Contact 10 11 Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com) 12 Bill Licea-Kane, AMD ( Bill.Licea-Kane 'at' amd.com ) 13 Eric Werness, NVIDIA Corporation (ewerness 'at' nvidia.com) 14 15Contributors 16 17 Pierre Boudier, AMD 18 Eric Boumaour, AMD 19 Pat Brown, NVIDIA 20 Alex Chalfin, AMD 21 Nick Haemel, AMD 22 Evan Hart, AMD 23 Bill Licea-Kane, AMD 24 Benj Lipchak, AMD 25 Lijun Qu, AMD 26 Greg Roth, NVIDIA 27 Eric Werness, NVIDIA 28 29Notice 30 31 Copyright (c) 2009-2014 The Khronos Group Inc. Copyright terms at 32 http://www.khronos.org/registry/speccopyright.html 33 34Specification Update Policy 35 36 Khronos-approved extension specifications are updated in response to 37 issues and bugs prioritized by the Khronos OpenGL Working Group. For 38 extensions which have been promoted to a core Specification, fixes will 39 first appear in the latest version of that core Specification, and will 40 eventually be backported to the extension document. This policy is 41 described in more detail at 42 https://www.khronos.org/registry/OpenGL/docs/update_policy.php 43 44Status 45 46 Complete. Approved by the ARB on July 3, 2009. 47 48Version 49 50 Last Modified Date: 02/26/2014 51 Revision: 8 52 53Number 54 55 ARB Extension #72 56 57Dependencies 58 59 OpenGL 1.1 is required. 60 61 OpenGL Shading Language version 1.30 is required. 62 63 This extension is written against the OpenGL 3.0 Specification 64 (Compatibility Profile) and Version 1.30 of the OpenGL Shading Language 65 Specification. 66 67 This extension interacts with the EXT_texture_swizzle and 68 ARB_texture_swizzle extensions. 69 70 71Overview 72 73 This extension provides a new set of texture functions 74 (textureGather) to the shading language that determine 2x2 footprint 75 that are used for linear filtering in a texture lookup, and return a 76 vector consisting of the first component from each of the four 77 texels in the footprint. 78 79 80New Procedures and Functions 81 82 None. 83 84New Tokens 85 86 Accepted by the <pname> parameter of GetBooleanv, GetIntegerv, 87 GetFloatv, and GetDoublev: 88 89 MIN_PROGRAM_TEXTURE_GATHER_OFFSET_ARB 0x8E5E 90 MAX_PROGRAM_TEXTURE_GATHER_OFFSET_ARB 0x8E5F 91 MAX_PROGRAM_TEXTURE_GATHER_COMPONENTS_ARB 0x8F9F 92 93Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation) 94 None. 95 96Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization) 97 98 Changes to section 3.8.8 99 100 In subsection Scale Factor and Level of Detail replace the sentence 101 beginning "If any of the offset values are outside the range of..." 102 (P. 204) with 103 104 If the value of any non-ignored component of the offset vector 105 operand is outside implementation-dependent limits, the results of 106 the texture lookup are undefined. For all instructions except 107 textureGather, the limits are MIN_PROGRAM_TEXEL_OFFSET_ARB and 108 MAX_PROGRAM_TEXEL_OFFSET_ARB. For the textureGather instruction, 109 the limits are MIN_PROGRAM_TEXTURE_GATHER_OFFSET_ARB and 110 MAX_PROGRAM_TEXTURE_GATHER_OFFSET_ARB. 111 112 Add to subsection Coordinate Wrapping and Texel Selection 113 (P. 208, Prior to "And for a one-dimensional texture"): 114 115 The textureGather and textureGatherOffset built-in shader functions 116 return a vector derived from sampling a 2x2 block of texels in the image 117 array of level <level_base>. The rules for the LINEAR minification 118 filter are applied to identify the four selected texels. Each texel is 119 then converted to a texture source color (Rs,Gs,Bs,As) according to table 120 3.21 and then swizzled as described in the ARB_texture_swizzle extension. 121 A four-component vector is then assembled by taking the Rs component from 122 the swizzled texture source colors of the four texels, in the order 123 T_i0_j1, T_i1_j1, T_i1_j0, and T_i0_j0. Incomplete textures (section 124 3.8.10) are considered to return a texture source color of (0,0,0,1) for 125 all four source texels. 126 127 ___________________________________________________________________ 128 | | 129 | 1.0 +---+---+---+---+---+---+---+---+ | 130 | 7| | | | | | | | | | 131 | +---+---+---+---+---+---+---+---+ | 132 | 6| | | | | | X | Y | | | 133 | +---+---+---+---+---+---+---+---+ | 134 | 5| | | | | | W | Z | | | 135 | +---+---+---+---+---+---+---+---+ | 136 | 4| | | | | | | | | | 137 | +---+---+---+---+---+---+---+---+ | 138 | 3| | | | | | | | | | 139 | +---+---+---+---+---+---+---+---+ | 140 | 2| | | | | | | | | | 141 | +---+---+---+---+---+---+---+---+ | 142 | 1| | | | | | | | | | 143 | +---+---+---+---+---+---+---+---+ | 144 | 0| | | | | | | | | | 145 | 0.0 +---+---+---+---+---+---+---+---+ | 146 | 0 1 2 3 4 5 6 7 | 147 | 0.0 1.0 | 148 | | 149 | Figure 3.10a. An example of an 8x8 texture image and the | 150 | components returned for textureGather. The vector (X,Y,Z,W) | 151 | is returned, where each component is taken from the post- | 152 | swizzle R component of the corresponding texel. | 153 |_________________________________________________________________| 154 155 156 Add to Section 3.12.2, Shader Execution, Texture Access 157 158 (p. 233) Prior to paragraph beginning "If a fragment shader uses a 159 sampler..." 160 161 Texture lookups using textureGather must only be performed on 162 textures with supported formats. 163 MAX_PROGRAM_TEXTURE_GATHER_COMPONENTS_ARB determines what formats 164 are supported. If the value is one, only RED, ALPHA, LUMINANCE, 165 INTENSITY, DEPTH, and DEPTH_STENCIL are supported. If the value is 166 four, all internal formats are supported. When textureGather is 167 used to sample a texture with an unsupported format, the results 168 are undefined. 169 170Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment 171Operations and the Frame Buffer) 172 173 None. 174 175Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions) 176 177 None. 178 179Additions to Chapter 6 of the OpenGL 2.0 Specification (State and 180State Requests) 181 182 None. 183 184Additions to the AGL/GLX/WGL Specifications 185 186 None 187 188GLX Protocol 189 190 TBD 191 192Errors 193 194 None. 195 196New State 197 198 None. 199 200New Implementation Dependent State 201 Minimum 202 Get Value Type Get Command Value Description Sec. Attrib 203 -------------------------------- ---- --------------- ------- --------------------- ------ ------ 204 MIN_PROGRAM_TEXTURE_GATHER_OFFSET_ARB Z GetIntegerv -- Min. texel offset 3.8.8 - 205 for textureGather 206 MAX_PROGRAM_TEXTURE_GATHER_OFFSET_ARB Z+ GetIntegerv -- Max. texel offset 3.8.8 - 207 for textureGather 208 MAX_PROGRAM_TEXTURE_GATHER_COMPONENTS_ARB Z+ GetIntegerv -- Max. format components 3.8.8 - 209 for textureGather 210 211 212Modifications to The OpenGL Shading Language Specification, Version 1.10.59 213 214 Including the following line in a shader can be used to control the 215 language features described in this extension: 216 217 #extension GL_ARB_texture_gather 218 219 A new preprocessor #define is added to the OpenGL Shading Language: 220 221 #define GL_ARB_texture_gather 1 222 223 Change section 4.3.6 "Varying" 224 225 Add to section 8.7 "Texture Lookup Functions" 226 227 Syntax: 228 229 gvec4 textureGather(gsampler2D sampler, vec2 coord) 230 gvec4 textureGather(gsampler2DArray sampler, vec3 coord) 231 gvec4 textureGather(gsamplerCube sampler, vec3 coord) 232 gvec4 textureGather(gsamplerCubeArray sampler, vec4 coord) 233 234 Description: 235 236 The textureGather functions use the texture coordinates given by 237 <coord> to determine a set of four texels to sample from the texture 238 identified by <sampler>. These functions return a four-component 239 vector consisting of one component from each texel. As described in 240 the OpenGL Specification, the vector selects the post-swizzle R 241 component from each of the four texels, returning: 242 243 vec4(T_i0_j1(coord, base).r, 244 T_i1_j1(coord, base).r, 245 T_i1_j0(coord, base).r, 246 T_i0_j0(coord, base).r) 247 248 Syntax: 249 250 gvec4 textureGatherOffset(gsampler2D sampler, vec2 coord, ivec2 offset) 251 gvec4 textureGatherOffset(gsampler2DArray sampler, vec3 coord, 252 ivec2 offset) 253 254 Description: 255 256 Perform a texture gather operation as in textureGather offset by 257 <offset> as described in textureOffset except that the 258 implementation-dependent minimum and maximum offset values are 259 given by MIN_PROGRAM_TEXTURE_GATHER_OFFSET and 260 MAX_PROGRAM_TEXTURE_GATHER_OFFSET respectively. 261 262Dependencies on ARB_texture_swizzle and EXT_texture_swizzle 263 264 If neither ARB_texture_swizzle nor EXT_texture_swizzle is supported, 265 remove the swizzling step from the description of the textureGather 266 functions in the OpenGL specification. 267 268Issues 269 270 (1) What about the use of this extension with fixed function? 271 272 RESOLVED: The built-in functions are added to the shading 273 language only. There is no ability to fetch four texels in 274 fixed function. 275 276 (2) What naming convention do we use for the new texture built-in 277 functions? 278 279 RESOLVED: Even though this extension is written against OpenGL 280 Shading Language 1.20, we use the new texture function naming 281 convention from OpenGL Shading Language 1.30. 282 283 (3) Should we add built-in texture functions for: 284 * Fetch4 with Absolute LOD? 285 * Fetch4 with Relative LOD? 286 * Fetch4 with coordinate offsets? 287 * Fetch4 with compare? 288 289 RESOLVED: No. 290 291 (4) If the texture wrap modes are not clamp_to_edge or repeat, is 292 the texture treated as incomplete, or are the values returned by 293 the textureGather built-in undefined? 294 295 RESOLVED: All wrap modes will be supported and textureGather will 296 return correct results. 297 298 (5) Can both texture *AND* textureGather built-in functions 299 sample from the same sampler in a shader? 300 301 RESOLVED: Yes. 302 303 (6) How do the textureGather functions work with sRGB textures? 304 305 RESOLVED. Gamma-correction is applied to the texture source color 306 before "gathering". For each of the four texels sampled, the R, G, 307 and B components will be gamma-corrected. With a default texture 308 swizzle, textureGather will always pick the red component from each 309 of the four texels, so will return a vector with four 310 gamma-corrected values. If the R texture swizzle is set to ALPHA, 311 four alpha values will be selected and those values will have no 312 gamma-correction appplied. 313 314 (7) Should textureGather lookups from multiple component formats be 315 allowed? 316 317 RESOLVED: This extension was derived from NV_gpu_shader4_1 (which 318 supported selecting the R component of multi-component textures) 319 and AMD_texture_texture4 (which didn't). To accommodate all 320 implementations, an implementation-dependent query is provided to 321 indicating the allowed number of components in a gathered texture 322 is used. 323 324 (8) How does texture gather interact with incomplete textures? 325 326 RESOLVED: For regular texture lookups, incomplete textures are 327 considered to return a texel value with RGBA components of (0,0,0,1). 328 For texture gather operations, each texel in the sampled footprint is 329 considered to have RGBA components of (0,0,0,1). Since this extension 330 selects the R texture component of each texel in a four-texel 331 footprint, a textureGather() function accessing an incomplete texture 332 will return (0,0,0,0). 333 334Revision History 335 336 Rev. Date Author Changes 337 ---- -------- -------- -------------------------------------------- 338 8 02/26/14 Jon Leech Change MIN_PROGRAM_TEXTURE_GATHER_OFFSET_ARB 339 type from Z+ to Z (Bug 11730). 340 341 7 01/27/11 pbrown Add further clarification on the interaction 342 of texture gather and incomplete textures 343 bug 7289). 344 345 6 09/23/10 pbrown Clarify the interaction of texture gather 346 with swizzle (bug 5910), fixing conflicts 347 between API and GLSL spec language. 348 Consolidate into one copy in the API 349 spec. Fix incorrect resolution on issue 350 (5). Minor wording updates to issues. 351 352 5 08/02/09 Jon Leech Reformat to 80 columns and assign ARB 353 extension number. 354 355 4 07/20/09 Jon Leech Assign missing enumerant value 356 357 3 05/25/09 groth Remove *offset accesses to cubemap textures 358 359 2 05/29/09 groth Add query for max gatherable components 360 remove undefined behavior for wrap modes 361 362 1 05/14/09 groth Initial revision 363