blob: cfdb58734e2170f83a10ced75397a7c2d738a6cf [file] [log] [blame]
Name
ARB_texture_gather
Name Strings
GL_ARB_texture_gather
Contact
Pat Brown, NVIDIA Corporation (pbrown 'at' nvidia.com)
Bill Licea-Kane, AMD ( Bill.Licea-Kane 'at' amd.com )
Eric Werness, NVIDIA Corporation (ewerness 'at' nvidia.com)
Contributors
Pierre Boudier, AMD
Eric Boumaour, AMD
Pat Brown, NVIDIA
Alex Chalfin, AMD
Nick Haemel, AMD
Evan Hart, AMD
Bill Licea-Kane, AMD
Benj Lipchak, AMD
Lijun Qu, AMD
Greg Roth, NVIDIA
Eric Werness, NVIDIA
Notice
Copyright (c) 2009-2014 The Khronos Group Inc. Copyright terms at
http://www.khronos.org/registry/speccopyright.html
Specification Update Policy
Khronos-approved extension specifications are updated in response to
issues and bugs prioritized by the Khronos OpenGL Working Group. For
extensions which have been promoted to a core Specification, fixes will
first appear in the latest version of that core Specification, and will
eventually be backported to the extension document. This policy is
described in more detail at
https://www.khronos.org/registry/OpenGL/docs/update_policy.php
Status
Complete. Approved by the ARB on July 3, 2009.
Version
Last Modified Date: 02/26/2014
Revision: 8
Number
ARB Extension #72
Dependencies
OpenGL 1.1 is required.
OpenGL Shading Language version 1.30 is required.
This extension is written against the OpenGL 3.0 Specification
(Compatibility Profile) and Version 1.30 of the OpenGL Shading Language
Specification.
This extension interacts with the EXT_texture_swizzle and
ARB_texture_swizzle extensions.
Overview
This extension provides a new set of texture functions
(textureGather) to the shading language that determine 2x2 footprint
that are used for linear filtering in a texture lookup, and return a
vector consisting of the first component from each of the four
texels in the footprint.
New Procedures and Functions
None.
New Tokens
Accepted by the <pname> parameter of GetBooleanv, GetIntegerv,
GetFloatv, and GetDoublev:
MIN_PROGRAM_TEXTURE_GATHER_OFFSET_ARB 0x8E5E
MAX_PROGRAM_TEXTURE_GATHER_OFFSET_ARB 0x8E5F
MAX_PROGRAM_TEXTURE_GATHER_COMPONENTS_ARB 0x8F9F
Additions to Chapter 2 of the OpenGL 2.0 Specification (OpenGL Operation)
None.
Additions to Chapter 3 of the OpenGL 2.0 Specification (Rasterization)
Changes to section 3.8.8
In subsection Scale Factor and Level of Detail replace the sentence
beginning "If any of the offset values are outside the range of..."
(P. 204) with
If the value of any non-ignored component of the offset vector
operand is outside implementation-dependent limits, the results of
the texture lookup are undefined. For all instructions except
textureGather, the limits are MIN_PROGRAM_TEXEL_OFFSET_ARB and
MAX_PROGRAM_TEXEL_OFFSET_ARB. For the textureGather instruction,
the limits are MIN_PROGRAM_TEXTURE_GATHER_OFFSET_ARB and
MAX_PROGRAM_TEXTURE_GATHER_OFFSET_ARB.
Add to subsection Coordinate Wrapping and Texel Selection
(P. 208, Prior to "And for a one-dimensional texture"):
The textureGather and textureGatherOffset built-in shader functions
return a vector derived from sampling a 2x2 block of texels in the image
array of level <level_base>. The rules for the LINEAR minification
filter are applied to identify the four selected texels. Each texel is
then converted to a texture source color (Rs,Gs,Bs,As) according to table
3.21 and then swizzled as described in the ARB_texture_swizzle extension.
A four-component vector is then assembled by taking the Rs component from
the swizzled texture source colors of the four texels, in the order
T_i0_j1, T_i1_j1, T_i1_j0, and T_i0_j0. Incomplete textures (section
3.8.10) are considered to return a texture source color of (0,0,0,1) for
all four source texels.
___________________________________________________________________
| |
| 1.0 +---+---+---+---+---+---+---+---+ |
| 7| | | | | | | | | |
| +---+---+---+---+---+---+---+---+ |
| 6| | | | | | X | Y | | |
| +---+---+---+---+---+---+---+---+ |
| 5| | | | | | W | Z | | |
| +---+---+---+---+---+---+---+---+ |
| 4| | | | | | | | | |
| +---+---+---+---+---+---+---+---+ |
| 3| | | | | | | | | |
| +---+---+---+---+---+---+---+---+ |
| 2| | | | | | | | | |
| +---+---+---+---+---+---+---+---+ |
| 1| | | | | | | | | |
| +---+---+---+---+---+---+---+---+ |
| 0| | | | | | | | | |
| 0.0 +---+---+---+---+---+---+---+---+ |
| 0 1 2 3 4 5 6 7 |
| 0.0 1.0 |
| |
| Figure 3.10a. An example of an 8x8 texture image and the |
| components returned for textureGather. The vector (X,Y,Z,W) |
| is returned, where each component is taken from the post- |
| swizzle R component of the corresponding texel. |
|_________________________________________________________________|
Add to Section 3.12.2, Shader Execution, Texture Access
(p. 233) Prior to paragraph beginning "If a fragment shader uses a
sampler..."
Texture lookups using textureGather must only be performed on
textures with supported formats.
MAX_PROGRAM_TEXTURE_GATHER_COMPONENTS_ARB determines what formats
are supported. If the value is one, only RED, ALPHA, LUMINANCE,
INTENSITY, DEPTH, and DEPTH_STENCIL are supported. If the value is
four, all internal formats are supported. When textureGather is
used to sample a texture with an unsupported format, the results
are undefined.
Additions to Chapter 4 of the OpenGL 2.0 Specification (Per-Fragment
Operations and the Frame Buffer)
None.
Additions to Chapter 5 of the OpenGL 2.0 Specification (Special Functions)
None.
Additions to Chapter 6 of the OpenGL 2.0 Specification (State and
State Requests)
None.
Additions to the AGL/GLX/WGL Specifications
None
GLX Protocol
TBD
Errors
None.
New State
None.
New Implementation Dependent State
Minimum
Get Value Type Get Command Value Description Sec. Attrib
-------------------------------- ---- --------------- ------- --------------------- ------ ------
MIN_PROGRAM_TEXTURE_GATHER_OFFSET_ARB Z GetIntegerv -- Min. texel offset 3.8.8 -
for textureGather
MAX_PROGRAM_TEXTURE_GATHER_OFFSET_ARB Z+ GetIntegerv -- Max. texel offset 3.8.8 -
for textureGather
MAX_PROGRAM_TEXTURE_GATHER_COMPONENTS_ARB Z+ GetIntegerv -- Max. format components 3.8.8 -
for textureGather
Modifications to The OpenGL Shading Language Specification, Version 1.10.59
Including the following line in a shader can be used to control the
language features described in this extension:
#extension GL_ARB_texture_gather
A new preprocessor #define is added to the OpenGL Shading Language:
#define GL_ARB_texture_gather 1
Change section 4.3.6 "Varying"
Add to section 8.7 "Texture Lookup Functions"
Syntax:
gvec4 textureGather(gsampler2D sampler, vec2 coord)
gvec4 textureGather(gsampler2DArray sampler, vec3 coord)
gvec4 textureGather(gsamplerCube sampler, vec3 coord)
gvec4 textureGather(gsamplerCubeArray sampler, vec4 coord)
Description:
The textureGather functions use the texture coordinates given by
<coord> to determine a set of four texels to sample from the texture
identified by <sampler>. These functions return a four-component
vector consisting of one component from each texel. As described in
the OpenGL Specification, the vector selects the post-swizzle R
component from each of the four texels, returning:
vec4(T_i0_j1(coord, base).r,
T_i1_j1(coord, base).r,
T_i1_j0(coord, base).r,
T_i0_j0(coord, base).r)
Syntax:
gvec4 textureGatherOffset(gsampler2D sampler, vec2 coord, ivec2 offset)
gvec4 textureGatherOffset(gsampler2DArray sampler, vec3 coord,
ivec2 offset)
Description:
Perform a texture gather operation as in textureGather offset by
<offset> as described in textureOffset except that the
implementation-dependent minimum and maximum offset values are
given by MIN_PROGRAM_TEXTURE_GATHER_OFFSET and
MAX_PROGRAM_TEXTURE_GATHER_OFFSET respectively.
Dependencies on ARB_texture_swizzle and EXT_texture_swizzle
If neither ARB_texture_swizzle nor EXT_texture_swizzle is supported,
remove the swizzling step from the description of the textureGather
functions in the OpenGL specification.
Issues
(1) What about the use of this extension with fixed function?
RESOLVED: The built-in functions are added to the shading
language only. There is no ability to fetch four texels in
fixed function.
(2) What naming convention do we use for the new texture built-in
functions?
RESOLVED: Even though this extension is written against OpenGL
Shading Language 1.20, we use the new texture function naming
convention from OpenGL Shading Language 1.30.
(3) Should we add built-in texture functions for:
* Fetch4 with Absolute LOD?
* Fetch4 with Relative LOD?
* Fetch4 with coordinate offsets?
* Fetch4 with compare?
RESOLVED: No.
(4) If the texture wrap modes are not clamp_to_edge or repeat, is
the texture treated as incomplete, or are the values returned by
the textureGather built-in undefined?
RESOLVED: All wrap modes will be supported and textureGather will
return correct results.
(5) Can both texture *AND* textureGather built-in functions
sample from the same sampler in a shader?
RESOLVED: Yes.
(6) How do the textureGather functions work with sRGB textures?
RESOLVED. Gamma-correction is applied to the texture source color
before "gathering". For each of the four texels sampled, the R, G,
and B components will be gamma-corrected. With a default texture
swizzle, textureGather will always pick the red component from each
of the four texels, so will return a vector with four
gamma-corrected values. If the R texture swizzle is set to ALPHA,
four alpha values will be selected and those values will have no
gamma-correction appplied.
(7) Should textureGather lookups from multiple component formats be
allowed?
RESOLVED: This extension was derived from NV_gpu_shader4_1 (which
supported selecting the R component of multi-component textures)
and AMD_texture_texture4 (which didn't). To accommodate all
implementations, an implementation-dependent query is provided to
indicating the allowed number of components in a gathered texture
is used.
(8) How does texture gather interact with incomplete textures?
RESOLVED: For regular texture lookups, incomplete textures are
considered to return a texel value with RGBA components of (0,0,0,1).
For texture gather operations, each texel in the sampled footprint is
considered to have RGBA components of (0,0,0,1). Since this extension
selects the R texture component of each texel in a four-texel
footprint, a textureGather() function accessing an incomplete texture
will return (0,0,0,0).
Revision History
Rev. Date Author Changes
---- -------- -------- --------------------------------------------
8 02/26/14 Jon Leech Change MIN_PROGRAM_TEXTURE_GATHER_OFFSET_ARB
type from Z+ to Z (Bug 11730).
7 01/27/11 pbrown Add further clarification on the interaction
of texture gather and incomplete textures
bug 7289).
6 09/23/10 pbrown Clarify the interaction of texture gather
with swizzle (bug 5910), fixing conflicts
between API and GLSL spec language.
Consolidate into one copy in the API
spec. Fix incorrect resolution on issue
(5). Minor wording updates to issues.
5 08/02/09 Jon Leech Reformat to 80 columns and assign ARB
extension number.
4 07/20/09 Jon Leech Assign missing enumerant value
3 05/25/09 groth Remove *offset accesses to cubemap textures
2 05/29/09 groth Add query for max gatherable components
remove undefined behavior for wrap modes
1 05/14/09 groth Initial revision