xref: /third_party/openGLES/extensions/EXT/EXT_texture_mirror_clamp.txt

Name

    EXT_texture_mirror_clamp

Name Strings

    GL_EXT_texture_mirror_clamp

Contributors

    Walt Donovan
    Dan Ginsburg

Contact

    Mark J. Kilgard, NVIDIA Corporation (mjk 'at' nvidia.com)

Status

    Shipping as of May 2004 for GeForce6.

Version

    Last Modified Date:  2004/05/17
    Version:             4

Number

    298

Issues

    How does EXT_texture_mirror_clamp extend ATI_texture_mirror_once?

        This EXT extension provides the two wrap modes that
        ATI_texture_mirror_once adds but also adds a third new wrap mode
        (GL_MIRROR_CLAMP_TO_BORDER_EXT).  This extension uses the same
        enumerant values for the ATI_texture_mirror_once modes.

    Why is the GL_MIRROR_CLAMP_TO_BORDER_EXT mode more interesting than
    the two other modes?

        Rather than clamp to 100% of the edge of the texture
        (GL_MIRROR_CLAMP_TO_EDGE_EXT) or to 50% of the edge and border
        color (GL_MIRROR_CLAMP), it is preferable to clamp to 100%
        of the border color (GL_MIRROR_CLAMP_TO_BORDER_EXT).  This
        avoids "bleeding" at smaller mipmap levels.

        Consider a texture that encodes a circular fall-off pattern such
        as for a projected spotlight.  A circular pattern is bi-symmetric
        so a "mirror clamp" wrap modes can reduce the memory footprint
        of the texture by a fourth.  Far outside the spotlight pattern,
        you'd like to sample 100% of the border color (typically black
        for a spotlight texture).  The way to achieve this without any
        bleeding of edge texels is with GL_MIRROR_CLAMP_TO_BORDER_EXT.

    Does this extension complete the orthogonality of the current five
    OpenGL 1.5 wrap modes?

         Yes.  There are two ways for repetition to operate (repeated
         & mirrored) and four ways for texture coordinate clamping to
         operate (unclamped, clamp, clamp to edge, & clamp to border).
         The complete table of all 8 modes looks like this:

                          Repeat            Mirror
                         +----------------  ----------------------
         Unclamped       | REPEAT           MIRRORED_REPEAT
         Clamp           | CLAMP            MIRROR_CLAMP
         Clamp to edge   | CLAMP_TO_EDGE    MIRROR_CLAMP_TO_EDGE
         Clamp to border | CLAMP_TO_BORDER  MIRROR_CLAMP_TO_BORDER

         OpenGL 1.0 introduced REPEAT & CLAMP.
         OpenGL 1.2 introduced CLAMP_TO_EDGE
         OpenGL 1.3 introduced CLAMP_TO_BORDER
         OpenGL 1.4 introduced MIRRORED_REPEAT
         ATI_texture_mirror_once introduced MIRROR_CLAMP & MIRROR_CLAMP_TO_EDGE
         EXT_texture_mirror_clamp introduces MIRROR_CLAMP_TO_BORDER

    Do these three new wrap modes work with 1D, 2D, 3D, and cube map
    texture targets?

         RESOLUTION: Yes.

    Do these three new wrap modes work with ARB_texture_non_power_of_two
    functionality?
    
         RESOLUTION: Yes.

    Do these three new wrap modes interact with NV_texture_rectangle?

         RESOLUTION:  Mirroring wrap modes are not supported by
         GL_TEXTURE_RECTANGLE_NV textures.  Conventional mirroring is
         already not supported for texture rectangles so supporting
         clamped mirroring modes should not be supported either.

    Does the specification of MIRROR_CLAMP_EXT & MIRROR_CLAMP_TO_EDGE_EXT
    match the ATI_texture_mirror_once specification?

         I believe yes.  The ATI_texture_mirror_once specification is
         somewhat vague what happens to texture coordinates at or very
         near (within half a texel of) zero.  The presumption is that a
         CLAMP_TO_EDGE behavior is used.  This specification is quite
         explicit that values near zero are clamped to plus or minus
         1/(2*N) respectively so that the CLAMP_TO_EDGE behavior is
         explicit.

    What should this extension be called?

         Calling the extension EXT_texture_mirror_once might cause
         confusion since this extension has additional functionality.
         Also, "once" never appears in the specification.
         EXT_texture_mirror_clamp is a good name because it implies
         support for all the clamped versions of mirroring.

    There is GL_MIRRORED_REPEAT and then GL_MIRROR_CLAMP_EXT,
    GL_MIRROR_CLAMP_TO_EDGE_EXT, and GL_MIRROR_CLAMP_TO_BORDER_EXT.
    Why does the first enumerant name say "MIRRORED" while the other
    three say "MIRROR"?

         This extension follows the naming precedent set by the
         ATI_texture_mirror_once specification.

         Moreover, MIRRORED_REPEAT uses "mirrored" to help that the
         mirroring repeats infinitely.  For the other three modes,
         there is just one mirror that occurs and then a clamp.

Dependencies

    Written based on the wording of the OpenGL 1.4.

    Extends ATI_texture_mirror_once by adding
    GL_MIRROR_CLAMP_TO_BORDER_EXT.

    NV_texture_rectangle trivially affects the definition of this
    extension.

Overview

    EXT_texture_mirror_clamp extends the set of texture wrap modes to
    include three modes (GL_MIRROR_CLAMP_EXT, GL_MIRROR_CLAMP_TO_EDGE_EXT,
    GL_MIRROR_CLAMP_TO_BORDER_EXT) that effectively use a texture map
    twice as large as the original image in which the additional half
    of the new image is a mirror image of the original image.

    This new mode relaxes the need to generate images whose opposite
    edges match by using the original image to generate a matching
    "mirror image".  This mode allows the texture to be mirrored only
    once in the negative s, t, and r directions.

New Procedure and Functions

    None

New Tokens

    Accepted by the <param> parameter of TexParameteri and TexParameterf,
    and by the <params> parameter of TexParameteriv and TexParameterfv,
    when their <pname> parameter is TEXTURE_WRAP_S, TEXTURE_WRAP_T,
    or TEXTURE_WRAP_R:

      MIRROR_CLAMP_EXT                     0x8742 (same value as MIRROR_CLAMP_ATI)
      MIRROR_CLAMP_TO_EDGE_EXT             0x8743 (same value as MIRROR_CLAMP_TO_EDGE_ATI)
      MIRROR_CLAMP_TO_BORDER_EXT           0x8912

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

    None

Additions to Chapter 3 if the OpenGL 1.2.1 Specification (Rasterization):

  - (3.8.4, page 136, as amended by the NV_texture_rectangle extension)

    Add the 3 new wrap modes to the list of wrap modes unsupported for
    the TEXTURE_RECTANGLE_NV texture target.

    "Certain texture parameter values may not be specified for textures
    with a target of TEXTURE_RECTANGLE_NV.  The error INVALID_ENUM
    is generated if the target is TEXTURE_RECTANGLE_NV and the
    TEXTURE_WRAP_S, TEXTURE_WRAP_T, or TEXTURE_WRAP_R parameter is set to
    REPEAT, MIRRORED_REPEAT_IBM, MIRROR_CLAMP_EXT, MIRROR_CLAMP_TO_EDGE_EXT, and
    MIRROR_CLAMP_TO_BORDER_EXT.  The error INVALID_ENUM is generated
    if the target is TEXTURE_RECTANGLE_NV and the TEXTURE_MIN_FILTER is
    set to a value other than NEAREST or LINEAR (no mipmap filtering
    is permitted).  The error INVALID_ENUM is generated if the target
    is TEXTURE_RECTANGLE_NV and TEXTURE_BASE_LEVEL is set to any value
    other than zero."

  - Table 3.19, page 137: Change first three entries in table:

    "TEXTURE_WRAP_S    integer     CLAMP, CLAMP_TO_BORDER, CLAMP_TO_EDGE,
                                   MIRRORED_REPEAT, MIRROR_CLAMP_EXT,
                                   MIRROR_CLAMP_TO_BORDER_EXT,
                                   MIRROR_CLAMP_TO_EDGE_EXT, REPEAT
    TEXTURE_WRAP_T     integer     CLAMP, CLAMP_TO_BORDER, CLAMP_TO_EDGE,
                                   MIRRORED_REPEAT, MIRROR_CLAMP_EXT,
                                   MIRROR_CLAMP_TO_BORDER_EXT,
                                   MIRROR_CLAMP_TO_EDGE_EXT, REPEAT
    TEXTURE_WRAP_R     integer     CLAMP, CLAMP_TO_BORDER, CLAMP_TO_EDGE,
                                   MIRRORED_REPEAT, MIRROR_CLAMP_EXT,
                                   MIRROR_CLAMP_TO_BORDER_EXT,
                                   MIRROR_CLAMP_TO_EDGE_EXT, REPEAT"

  - (3.8.7, page 140) After the last paragraph of the section add:

    "Wrap Mode MIRROR_CLAMP_EXT

    Wrap mode MIRROR_CLAMP_EXT mirrors and clamps the texture coordinate,
    where mirroring and clamping a value f computes

      mirrorClamp(f) = min(1, max(1/(2*N), abs(f)))

    where N is the size of the one-, two-, or three-dimensional texture
    image in the direction of wrapping.

    Wrap Mode MIRROR_CLAMP_TO_EDGE_EXT

    Wrap mode MIRROR_CLAMP_TO_EDGE_EXT mirrors and clamps to edge the
    texture coordinate, where mirroring and clamping to edge a value f
    computes

      mirrorClampToEdge(f) = min(1-1/(2*N), max(1/(2*N), abs(f)))

    where N is the size of the one-, two-, or three-dimensional texture
    image in the direction of wrapping.

    Wrap Mode MIRROR_CLAMP_TO_BORDER_EXT

    Wrap mode MIRROR_CLAMP_TO_BORDER_EXT mirrors and clamps to border the
    texture coordinate, where mirroring and clamping to border a value
    f computes

      mirrorClampToBorder(f) = min(1+1/(2*N), max(1/(2*N), abs(f)))

    where N is the size of the one-, two-, or three-dimensional texture
    image in the direction of wrapping."

  - (3.8.8, page 142) Delete this phrase because it is out of date and
    unnecessary given the current way section 3.8.7 is written:

    "(if the wrap mode for a coordinate is CLAMP or CLAMP_TO_EDGE)"

Additions to Chapter 4:

    None

Additions to Chapter 5:

    None

Additions to Chapter 6:

    None

Additions to the GLX Specification

    None

Dependencies on NV_texture_rectangle

    If NV_texture_rectangle is not supported, ignore the statement that
    the initial value for the S, T, and R wrap modes is CLAMP_TO_EDGE
    for rectangular textures.

    Ignore the error for a texture target of TEXTURE_RECTANGLE_NV.

GLX Protocol

    None

Errors

    INVALID_ENUM is generated when TexParameter is called with
    a target of TEXTURE_RECTANGLE_NV and the TEXTURE_WRAP_S,
    TEXTURE_WRAP_T, or TEXTURE_WRAP_R parameter is set to REPEAT,
    MIRRORED_REPEAT_IBM, MIRROR_CLAMP_EXT, MIRROR_CLAMP_TO_EDGE_EXT,
    or MIRROR_CLAMP_TO_BORDER_EXT.

New State

    (table 6.15, p230) amend the following entries [Z5 changed to Z8]:

    Get Value       Type  Get Command      Initial Value    Description          Sec    Attribute
    --------------  ----  ---------------  ---------------  -------------------  -----  ---------
    TEXTURE_WRAP_S  n*Z8  GetTexParameter  REPEAT except    Texture wrap mode S  3.8.7  texture
                                           for rectangular
                                           which is
                                           CLAMP_TO_EDGE
    TEXTURE_WRAP_T  n*Z8  GetTexParameter  REPEAT except    Texture wrap mode T  3.8.7  texture
                                           for rectangular
                                           which is
                                           CLAMP_TO_EDGE
    TEXTURE_WRAP_R  n*Z8  GetTexParameter  REPEAT except    Texture wrap mode R  3.8.7  texture
                                           for rectangular
                                           which is
                                           CLAMP_TO_EDGE

New Implementation Dependent State

    None