xref: /third_party/openGLES/extensions/ARB/ARB_texture_swizzle.txt (revision 5bd8dead)

Name

    ARB_texture_swizzle

Name Strings

    GL_ARB_texture_swizzle

Contact

    Jeff Bolz, NVIDIA Corporation (jbolz 'at' nvidia.com)

Contributors

    Cass Everitt, Id Software
    Brian Harris, Id Software
    Pat Brown, NVIDIA
    Eric Werness, NVIDIA

Notice

    Copyright (c) 2010-2013 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 at the 2010/01/22 F2F meeting.
    Approved by the Khronos Board of Promoters on March 10, 2010.

Version

    Last Modified Date: December 7, 2009
    Author Revision: 1.0

Number

    ARB Extension #84

Dependencies

     Written based on the wording of the OpenGL 2.1 specification.

Overview

    Classic OpenGL texture formats conflate texture storage and
    interpretation, and assume that textures represent color. In 
    modern applications, a significant quantity of textures don't
    represent color, but rather data like shadow maps, normal maps,
    page tables, occlusion data, etc.. For the latter class of data,
    calling the data "RGBA" is just a convenient mapping of what the
    data is onto the current model, but isn't an accurate reflection
    of the reality of the data.

    The existing texture formats provide an almost orthogonal set of
    data types, sizes, and number of components, but the mappings of 
    this storage into what the shader or fixed-function pipeline 
    fetches is very much non-orthogonal. Previous extensions have
    added some of the most demanded missing formats, but the problem
    has not been solved once and for all.

    This extension provides a mechanism to swizzle the components 
    of a texture before they are applied according to the texture
    environment in fixed-function or as they are returned to the 
    shader.

IP Status

    No known IP claims.

New Procedures and Functions

    None

New Tokens

    Accepted by the <pname> parameters of TexParameteri,
    TexParameterf, TexParameteriv, TexParameterfv,
    GetTexParameterfv, and GetTexParameteriv:

    TEXTURE_SWIZZLE_R                   0x8E42
    TEXTURE_SWIZZLE_G                   0x8E43
    TEXTURE_SWIZZLE_B                   0x8E44
    TEXTURE_SWIZZLE_A                   0x8E45

    Accepted by the <pname> parameters of TexParameteriv, 
    TexParameterfv, GetTexParameterfv, and GetTexParameteriv:

    TEXTURE_SWIZZLE_RGBA                0x8E46


Additions to Chapter 2 of the OpenGL 2.1 Specification (OpenGL Operation)

    Modify Section 2.15.4 (Shader Execution), p. 84:

    Texture Access
    
    ...and converts it to a texture source color Cs according to table 
    3.20 (section 3.8.13), followed by application of the texture swizzle
    as described in section 3.8.13. A four-component vector (Rs,Gs,Bs,As)
    is returned to the vertex shader.

Additions to Chapter 3 of the OpenGL 2.1 Specification (Rasterization)

    Modify Section 3.8.4 (Texture Parameters), p. 168:

    (modify table 3.18, p. 169)
    Name                   Type         Legal Values
    ----                   ----         ------------
    TEXTURE_SWIZZLE_R      enum         RED, GREEN, BLUE, ALPHA, ZERO, ONE
    TEXTURE_SWIZZLE_G      enum         RED, GREEN, BLUE, ALPHA, ZERO, ONE
    TEXTURE_SWIZZLE_B      enum         RED, GREEN, BLUE, ALPHA, ZERO, ONE
    TEXTURE_SWIZZLE_A      enum         RED, GREEN, BLUE, ALPHA, ZERO, ONE

    (append to section 3.8.4, p. 170)

    TEXTURE_SWIZZLE_RGBA sets the same state as the R, G, B, A enums in a 
    single call.

    (append to section 3.8.13, p. 184)
    The values of the texture parameters TEXTURE_SWIZZLE_R, 
    TEXTURE_SWIZZLE_G, TEXTURE_SWIZZLE_B, and TEXTURE_SWIZZLE_A, are applied
    after the swizzling described in Table 3.20 (p. 186). The swizzle 
    parameter TEXTURE_SWIZZLE_R affects the first component of Cs as:

    if (TEXTURE_SWIZZLE_R == RED) {
        Cs'[0] = Cs[0];
    } else if (TEXTURE_SWIZZLE_R == GREEN) {
        Cs'[0] = Cs[1];
    } else if (TEXTURE_SWIZZLE_R == BLUE) {
        Cs'[0] = Cs[2];
    } else if (TEXTURE_SWIZZLE_R == ALPHA) {
        Cs'[0] = As;
    } else if (TEXTURE_SWIZZLE_R == ZERO) {
        Cs'[0] = 0;
    } else if (TEXTURE_SWIZZLE_R == ONE) {
        Cs'[0] = 1; // float or int depending on texture component type
    }

    and similarly for Cs'[1], Cs'[2], and As'.

    Modify Section 3.11.2 (Shader Execution), p. 197:

    Texture Access
    
    ...and converts it to a texture source color Cs according to table 
    3.20 (section 3.8.13), followed by application of the texture swizzle
    as described in section 3.8.13. The GL returns a four-component 
    vector (Rs,Gs,Bs,As) to the fragment shader...

Additions to the AGL/EGL/GLX/WGL Specifications

    None

Errors

    The error INVALID_OPERATION is generated if TexParameteri,
    TexParameterf, TexParameteriv, or TexParameterfv, parameter <pname> 
    is TEXTURE_SWIZZLE_R, TEXTURE_SWIZZLE_G,  TEXTURE_SWIZZLE_B, 
    or TEXTURE_SWIZZLE_A, and <param> is not RED, GREEN, BLUE, ALPHA, 
    ZERO, or ONE.

    The error INVALID_OPERATION is generated if TexParameteriv, or 
    TexParameterfv, parameter <pname> TEXTURE_SWIZZLE_RGBA, and the four 
    consecutive values pointed to by <param> are not all RED, GREEN, BLUE,
    ALPHA, ZERO, or ONE.

New State

    Changes to table 6.16, p. 277 (Texture, state per texture object)

                                                   Initial
    Get Value              Type   Get Command      Value    Description  Sec.      Attribute
    ---------              ----   -----------      -------  -----------  ----      ---------
    TEXTURE_SWIZZLE_R      Z      GetTexParameter  RED      Red          3.8.4     texture
                                                            component swizzle
    TEXTURE_SWIZZLE_G      Z      GetTexParameter  GREEN    Green        3.8.4     texture
                                                            component swizzle
    TEXTURE_SWIZZLE_B      Z      GetTexParameter  BLUE     Blue         3.8.4     texture
                                                            component swizzle
    TEXTURE_SWIZZLE_A      Z      GetTexParameter  ALPHA    Alpha        3.8.4     texture
                                                            component swizzle

Issues

    1) Why not add more new formats instead?

    RESOLVED: Adding new formats is more implementation burden than
    one might expect. New formats need to be added to the pixel path,
    must be considered for FBO support, etc.. This extension avoids 
    those issues by solely affecting the result of a texture fetch.

    2) What is the demand for this extension?

    RESOLVED: There are several independent demands for this, 
    including:
    - OpenGL 3.0 deprecated support for ALPHA, LUMINANCE, 
      LUMINANCE_ALPHA, and INTENSITY formats. This extension provides
      a simple porting path for legacy applications that used these
      formats.

    - There have been specific requests for (1,1,1,a), or "white alpha"
      formats that allow a "decal" texture to be used in the same shader
      as an RGBA texture. This can be accomplished with an OpenGL 2.1 
      ALPHA texture by doing

        TexParameteri(target, TEXTURE_SWIZZLE_R, ONE);
        TexParameteri(target, TEXTURE_SWIZZLE_G, ONE);
        TexParameteri(target, TEXTURE_SWIZZLE_B, ONE);
        // TEXTURE_SWIZZLE_A is already ALPHA
      or equivalently
        GLint swiz[4] = {ONE, ONE, ONE, ALPHA};
        TexParameteriv(target, TEXTURE_SWIZZLE_RGBA, swiz);

      or in OpenGL 3.0 "preview" contexts where ALPHA internal formats 
      are deprecated by using a RED texture:
        TexParameteri(target, TEXTURE_SWIZZLE_R, ONE);
        TexParameteri(target, TEXTURE_SWIZZLE_G, ONE);
        TexParameteri(target, TEXTURE_SWIZZLE_B, ONE);
        TexParameteri(target, TEXTURE_SWIZZLE_A, RED);
      or equivalently
        GLint swiz[4] = {ONE, ONE, ONE, RED};
        TexParameteriv(target, TEXTURE_SWIZZLE_RGBA, swiz);

    - This functionality is available on Sony PlayStation 3 and can
      simplify porting those applications to OpenGL.

    3) What names should be used for the components, in both the "source"
       (<param>) and "destination" (<pname>) enums? RGBA? XYZW? 0123?

    RESOLVED: RGBA for both source and destination. 0123 could cause 
    confusion with ZERO and ONE. RGBA is a natural choice for source,
    because the spec describes the values returned by textures as "Color"
    and "Alpha." There's no particular precedent for destination to be 
    XYZW as this is still part of texture and not the shader, so RGBA 
    it is.

    4) How does this interact with depth component textures?

    RESOLVED: The swizzle is applied after the DEPTH_TEXTURE_MODE. This 
    naturally falls out of specifying the swizzle in terms of Table 3.20.

    5) How does this interact with sRGB?

    RESOLVED: The swizzle is applied after sRGB conversion.

    6) How does this interact with NV_register_combiners, 
       NV_texture_shader, and other old "shading" extensions that
       predate NV/ARB_fragment_program and define their own "interesting"
       swizzles?

    RESOLVED: Undefined. Core fixed-function shading (texture_env/combine)
    are fully supported, but old proprietary "configurable shading" 
    extensions are not.

    7) How does the swizzle interact with the fixed-function texture 
       environment referencing the base format?

    RESOLVED: Note that, by virtue of being defined in terms of Table 3.20,
    the swizzling occurs *before* the texture environment functions 
    (Table 3.21 and 3.22) are applied. So if you used the first example 
    under Issue (2) with fixed-function, the primary color would "pass 
    through" because the ALPHA base format environment function would 
    still apply. In order to effectively swizzle all four components, an 
    INTENSITY format would give the desired result with the same storage
    requirements.

Revision History

    Revision 1, 2008/08/21
     - Initial draft
    Revision 2, 2009/01/28
     - Add edits to fragment/vertex shader sections to clarify that the 
       swizzle is applied in both.
    Revision 3, 2009/12/07
     - Rename EXT->ARB