xref: /third_party/openGLES/extensions/OES/OES_draw_texture.txt

Name

    OES_draw_texture

Name Strings

    GL_OES_draw_texture

Contact

    Tom Olson (t-olson 'at' ti.com)

Notice

    Copyright (c) 2004-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 ES 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

    Ratified by the Khronos BOP, Aug 5, 2004.

Version

    Last Modified Date: 21 July 2004
    Author Revision 0.96

Number

    OpenGL ES Extension #7

Dependencies

    OES_fixed_point is required.
    EXT_fog_coord affects the definition of this extension.
    This extension is written against the OpenGL 1.3 and
    OpenGL ES 1.0 Specifications.

Overview

    This extension defines a mechanism for writing pixel
    rectangles from one or more textures to a rectangular
    region of the screen.  This capability is useful for
    fast rendering of background paintings, bitmapped font
    glyphs, and 2D framing elements in games.  This
    extension is primarily intended for use with OpenGL ES.

    The extension relies on a new piece of texture state
    called the texture crop rectangle, which defines a
    rectangular subregion of a texture object.  These
    subregions are used as sources of pixels for the texture
    drawing function.

    Applications use this extension by configuring the
    texture crop rectangle for one or more textures via
    ActiveTexture() and TexParameteriv() with pname equal to
    TEXTURE_CROP_RECT_OES.  They then request a drawing
    operation using DrawTex{sifx}[v]OES().  The effect of
    the latter function is to generate a screen-aligned
    target rectangle, with texture coordinates chosen to map
    the texture crop rectangle(s) linearly to fragments in
    the target rectangle.  The fragments are then processed
    in accordance with the fragment pipeline state.

IP Status

    No known IP issues.

Issues

    (1) Should we pass a texture name to the draw function,
        or use the currently bound texture?

        RESOLVED. Use the textures bound to currently
        enabled texture units.  This makes it easy for
        drivers to implement DrawTex*() using existing
        texture hardware.  If we didn't do this, they would
        have to save and restore the state of the texture
        unit(s).

    (2) Doesn't DrawPixels make this extension unnecessary?

        RESOLVED.  No.  DrawPixels is hard to support 
        efficiently in hardware because the source pixels
        are in application memory.  Also, the pixel setup
        pipeline (PixelTransfer, PixelMap etc.) is redundant
        for the intended applications.  Also, PixelZoom 
        looks ugly when the zoom factors are large, and there
        is no way to control filtering.  Using textures and
        texture units solves all of these problems.

    (3) Doesn't ARB_point_sprite make this extension unnecessary?

        RESOLVED. No.  Key differences include:
        * ARB_point_sprite uses the entire source texture to
          paint a point, i.e. its texture coordinates range
          from 0.0 to 1.0.  This extension allows a
          subregion of a texture to be used as the source.
        * ARB_point_sprite sprites are limited by the
          maximum point size, which may be small.  This
          extension is limited only by the maximum supported
          texture size and the screen size.
        * ARB_point_sprite sprites are square.  This
          extension supports general rectangles as sprite
          shapes.
        * ARB_point_sprite sprites are clipped as points, so
          if the center of a sprite falls outside the
          frustrum, nothing is drawn.  This extension draws
          any portion of a sprite that lies within the
          viewing frustrum.  (There is a well-known
          work-around for this, but it's ugly.)

    (4) How is the texture sampled?  

        RESOLVED.  It is sampled like a normal texture, and
        not like an image sent to DrawPixels.  This
        facilitates implementing with texture hardware.

    (5) How does this work when multisampling is enabled?

        RESOLVED. Implementations should generate
        multisample texture coordinates using the same
        method they use in normal texture mapping.
        Approximations are acceptable, e.g. they may use the
        same texture value for all samples associated with a
        fragment generated by DrawTex*(), even if they use
        another policy for multisampled triangle rendering.

    (6) Do we really want the full fragment pipeline to be
        active?

        RESOLVED. Yes, on grounds of orthogonality and
        simplicity.  Again, this makes it easy for existing
        hardware to implement the extension.

    (7) How does this interact with user clip planes?

        RESOLVED.  User clip planes are ignored. This is a
        screen-level operation, so geometric entities like
        clip planes are irrelevant.

    (8) How does this interact with mip-mapping?

        RESOLVED.  It behaves exactly as in texturing.
        This is really easy to do as LOD is a constant
        across the target rectangle.
 
    (9) What happens when multiple texture units are
        enabled?

        RESOLVED. All enabled texture units participate in
        generating the final fragment color.  Each unit
        generates its own s,t based on its texture's crop
        rectangle.

   (10) Should the target location be specified by the
        current raster position (RasterPos or WindowPos), 
        or by arguments to DrawTex*OES()?

        RESOLVED.  Use arguments passed to DrawTex*. In the
        intended uses, the target will be set once per call,
        so using arguments saves one inner loop function
        call.

   (11) Do we want stretch-blt capability?

        RESOLVED. Yes.  Supply a window size as well as
        window position to DrawTex*()

   (12) OpenGL ES issue: WindowPos (if we use it) adds 16
        entry points ({23}{sifd}[v]), which seems like a lot
        even if they are trivial.  Can we live with a
        subset?  (Note that the 'd' versions go away, but
        they are replaced by 'x' versions.)

        RESOLVED. Moot, as we do not use WindowPos.  But the
        intent was to add only 3{si}[v] versions (four entry
        points).  This is not orthogonal and may be
        surprising.  But there is no intent to support
        sub-pixel placement of rectangles, so the {fx}
        versions are superfluous.  {2} versions are easy to
        express using {3} versions.  Vector and individual
        argument versions are kept to reduce the surprise
        factor, and because constructing calls to a v-type
        function is a huge pain if you don't already have
        the data in vector format.

   (13) TexCropRect*OES adds eight entry points.  Can we live
        with a subset?  For the intended use, integer values
        suffice, so the {fx} versions are superfluous.  But
        orthogonality and 'least-astonishment' are virtues
        too.

        RESOLVED. Moot. Replace with TexParameteriv().

   (14) Would it be better to remove the texture crop
        rectangle from the state, and instead pass
        parameters to DrawTextureOES()?

        RESOLVED. No.  Drawing the same pixel pattern multiple
        times is a plausible usage scenario.

   (15) Should texture crop rect parameters be stored internally
        as integers, or as float/fixed?  I.e. should we allow
        the crop rect to include fractional texels?  This is
        more flexible, but is not the intended use.  Software
        implementations would have to add a test for the (normal)
        special case of integer bounds.
        
        RESOLVED.  Integer only.  Texture crop rect is
        conceptually a subregion of an integer grid, so its
        natural coordinates are integers.

   (16) Should we have a single global crop rect, or one per
        texture unit?  

        RESOLVED.  Neither.  We should have one per texture,
        with TexParameter setting the rect for the currently
        active texture.  It isn't a lot of state, it
        attaches the rect to a specific texture (which makes
        sense) rather than a texture unit (which doesn't),
        it is more orthogonal, and it allows tex coords to
        be meaningful (if not actually useful) when multiple
        texture units are enabled.

   (17) Should the destination rectangle specified by
        DrawTex*() be defined as integer only like the crop
        rectangle, or should its parameters be real-valued?

        RESOLVED.  Real-valued.  Since we now support
        stretch-blit, we want the ability to animate the
        scaling factor smoothly.  If the destination rectangle
        size is rounded to an integer, you won't get smooth
        animation.

New Procedures and Functions 

  Added to OpenGL 1.3 and OpenGL ES 1.0:

    void DrawTex{sifx}OES(T X, T Y, T Z, T W, T H);
    void DrawTex{sifx}vOES(T* coords);

  Added to OpenGL ES 1.0:

    void TexParameter{ifx}v(enum target, enum pname, T param);


New Types

  None


New Tokens

  Accepted by the <pname> parameter of TexParameter()
  and GetTexParameter():

    TEXTURE_CROP_RECT_OES        0x8B9D


Additions to Chapter 2 of the OpenGL 1.3 Specification
(OpenGL Operation):

  None


Additions to Chapter 3 of the OpenGL 1.3 Specification
(Rasterization): 

  In Table 3.19: Texture parameters and their values, p. 133,
  add this line at the end of the table:

  Name                     Type             Legal Values
  --------------------------------------------------------
  TEXTURE_CROP_RECT_OES    4 integers       any value


  In section 3.8.4, Texture Parameters, after paragraph 3
  (page 132) insert new paragraph:

  The texture parameter TEXTURE_CROP_RECT_OES controls the
  operation of DrawTex{sifx}[v]OES(), as described in
  section 5.7.  It has no effect on the rasterization of
  other primitives.

  
Additions to Chapter 4 of the OpenGL 1.3 Specification
(Per-Fragment Operations and the Frame Buffer): 

  None


Additions to Chapter 5 of the OpenGL 1.3 Specification
(Special Functions):

  In Chapter 5, paragraph one, replace the last two words
  ("and hints.") with the words "hints, and texture
  rectangle drawing."

  After section 5.6, p. 196, insert:

  5.7 Texture Rectangle Drawing

    OpenGL supports drawing sub-regions of a texture to
    rectangular regions of the screen using the texturing
    pipeline.  Source region size and content are determined
    by the texture crop rectangle(s) of the enabled
    texture(s) (see section 3.8.14).

    The functions 

    void DrawTex{sifx}OES(T Xs, T Ys, T Zs, T Ws, T Hs);
    void DrawTex{sifx}vOES(T *coords);

    draw a texture rectangle to the screen.  Xs, Ys, and Zs
    specify the position of the affected screen rectangle.
    Xs and Ys are given directly in window (viewport)
    coordinates.  Zs is mapped to window depth Zw as follows:

                 { n,                 if z <= 0
            Zw = { f,                 if z >= 1
                 { n + z * (f - n),   otherwise

    where <n> and <f> are the near and far values of
    DEPTH_RANGE.  Ws and Hs specify the width and height of
    the affected screen rectangle in pixels.  These values
    may be positive or negative; however, if either (Ws <=
    0) or (Hs <= 0), the INVALID_VALUE error is generated.

    Calling one of the DrawTex functions generates a
    fragment for each pixel that overlaps the screen
    rectangle bounded by (Xs, Ys) and (Xs + Ws), (Ys + Hs).
    For each generated fragment, the depth is given by Zw
    as defined above, and the color by the current color.
    
    If EXT_fog_coord is supported, and FOG_COORDINATE_SOURCE_EXT
    is set to FOG_COORINATE_EXT, then the fragment distance for
    fog purposes is set to CURRENT_FOG_COORDINATE. Otherwise,
    the fragment distance for fog purposes is set to 0.
    
    Texture coordinates for each texture unit are computed
    as follows:

    Let X and Y be the screen x and y coordinates of each
    sample point associated with the fragment.  Let Wt and
    Ht be the width and height in texels of the texture
    currently bound to the texture unit.  (If the texture is
    a mipmap, let Wt and Ht be the dimensions of the level
    specified by TEXTURE_BASE_LEVEL.)  Let Ucr, Vcr, Wcr and
    Hcr be (respectively) the four integers that make up the
    texture crop rectangle parameter for the currently bound
    texture.  The fragment texture coordinates (s, t, r, q)
    are given by

    s = (Ucr + (X - Xs)*(Wcr/Ws)) / Wt
    t = (Vcr + (Y - Ys)*(Hcr/Hs)) / Ht
    r = 0
    q = 1

    In the specific case where X, Y, Xs and Ys are all
    integers, Wcr/Ws and Hcr/Hs are both equal to one, the
    base level is used for the texture read, and fragments
    are sampled at pixel centers, implementations are
    required to ensure that the resulting u, v texture
    indices are also integers.  This results in a one-to-one
    mapping of texels to fragments.

    Note that Wcr and/or Hcr can be negative.  The formulas
    given above for s and t still apply in this case.  The
    result is that if Wcr is negative, the source rectangle
    for DrawTex operations lies to the left of the reference
    point (Ucr, Vcr) rather than to the right of it, and
    appears right-to-left reversed on the screen after a
    call to DrawTex.  Similarly, if Hcr is negative, the
    source rectangle lies below the reference point (Ucr,
    Vcr) rather than above it, and appears upside-down on
    the screen.

    Note also that s, t, r, and q are computed for each
    fragment as part of DrawTex rendering.  This implies
    that the texture matrix is ignored and has no effect on
    the rendered result.


Additions to Chapter 6 of the OpenGL 1.3 Specification
(State and State Requests):

  None


Additions to Appendix A of the OpenGL 1.3 Specification
(Invariance):

  None


Additions to the AGL/GLX/WGL Specifications:

  None


Additions to Chapter 2 of the OpenGL ES 1.0 Specification
(OpenGL Operation):

  None


Additions to Chapter 3 of the OpenGL ES 1.0 Specification
(Rasterization):

  After the fourth paragraph of section 3.8, Texturing,
  p. 17, insert a new paragraph:

  DrawTexOES is supported.

  In the (unnamed) table of supported texture functions,
  p. 19, delete the entry for TexParameter{i[v] fv}(), and
  replace the entry for TexParameterf() with the following:

  OpenGL 1.3                                           Common    Common-Lite
  ------------------------------------------------     ------    -----------
  TexParameter{if}[v](enum target, enum param, T param)
    target = TEXTURE_2D, pname = TEXTURE_CROP_RECT_OES (check)     (check)
    target = TEXTURE_1D, TEXTURE_3D, TEXTURE_CUBE_MAP     -           -
    pname = TEXTURE_MIN_FILTER, TEXTURE_MAG_FILTER     (check)     (check)
    pname = TEXTURE_WRAP_S, TEXTURE_WRAP_T             (check)     (check)
    pname = TEXTURE_BORDER_COLOR                          -           -
    pname = TEXTURE_MIN_LOD, TEXTURE_MAX_LOD              -           -
    pname = TEXTURE_BASE_LEVEL, TEXTURE_MAX_LEVEL         -           -
    pname = TEXTURE_WRAP_R                                -           -
    pname = TEXTURE_PRIORITY                              -           -

  In the same table, modify the entry for
  GetTexParameter{if}v() to read as follows:

  OpenGL 1.3                                               Common   Common-Lite
  -------------------------------------------------------  ------   -----------
  GetTexParameter{if}v(enum target, enum param, T *params) (check)   (dagger)


Additions to Chapter 4 of the OpenGL ES 1.0 Specification
(Per-Fragment Operations and the Frame Buffer):

  None


Additions to Chapter 5 of the OpenGL ES 1.0 Specification
(Special Functions):

  None


Additions to Chapter 6 of the OpenGL ES 1.0 Specification
(State and State Requests):

  At the end of table 6.15, Texture Objects (cont.), p. 36,
  insert a new entry:

  State                                           Exposed   Queriable
  -------------------------------------------     -------   ---------
  TEXTURE_CROP_RECT_OES                           (check)    (check)


  Replace the fourth paragraph of Chapter 7, Core Additions and
  Extensions, p. 46, with the following:

  The Common and Common-Lite profiles add subsets of the
  OES_byte_coordinates, OES_fixed_point, and
  OES_single_precision ES-specific extensions as core
  additions; OES_readFormat and
  OES_compressed_paletted_texture as required profile
  extensions; and OES_query_matrix and OES_draw_texture as
  optional profile extensions.


Additions to Chapter 7 of the OpenGL ES 1.0 Specification
(Core Additions and Extensions):

  At the end of Table 7.1: OES Extension Disposition, add a
  new entry:

  Extension Name                     Common            Common-Lite
  ------------------------     ------------------  ------------------
  OES_draw_texture             optional extension  optional extension    


  After section 7.6, Query Matrix, insert


  7.7 Draw Texture

  The optional OES_draw_texture extension allows rectangular
  subregions of a texture to be written to the screen using
  the fragment pipeline.  Texture coordinates are generated
  for each fragment in the destination rectangle, such that
  texels in the source texture are mapped linearly to pixels
  on the screen.


GLX Protocol

  None


Errors

  None


Dependencies on OES_fixed_point

  The DrawTex{sifx}[v]() function makes use of the 'x'
  suffix and (in that form) accepts parameters of type fixed,
  as defined in OES_fixed_point.


Dependencies on EXT_fog_coord
  
  EXT_fog_coord affects the distance that is used in the fog
  equations for fragments generated by DrawTex{sifx}[v]().
  If EXT_fog_coord is not supported, the fog distance for
  each fragment is set to zero.  If EXT_fog_coord is
  supported, the fog distance depends on the value of
  FOG_COORDINATE_SOURCE_EXT.  If the latter is set to
  FRAGMENT_DEPTH_EXT, the fog distance is again set to zero.
  If FOG_COORDINATE_SOURCE_EXT is set to FOG_COORDINATE_EXT,
  the distance is set to CURRENT_FOG_COORDINATE.


New State

  (table 6.16, Texture Objects (cont.), p. 224):

                                             Initial
  Get Value         Type   Get Command       Value       Description   Sec   Attribute
  ---------         ----   -----------       ---------   -----------   ---   ---------
  TEXTURE_CROP_RECT  4xZ   GetTexParameteriv 0,0,0,0     texture crop  5.7   texture
                                                         rectangle

New Implementation Dependent State

    None.


Revision History

    July 21, 2004 (v0.96)
        - Modified to say that if Ws or Hs < 0 then an 
          INVALID_VALUE error is generated

    July  16, 2004 (v0.95)
        - Corrected a bug in the text description of DrawTex
          with negative crop rectangle width or height.  Thanks
          to Petri Kero for the catch.

    July  14, 2004 (v0.9)
        - added a Zs parameter to the destination rectangle
          location specification.  This allows applications
          to control the depth coordinate of fragments generated
          by DrawTex().
        - Removed DOS-mode carriage returns.  

    June  29, 2004 (v0.8)
        - Corrected dependencies to comply with ARB recommended
          practice for extensions.
        - Restructured the "Additions to the OpenGL ES 1.0 Spec"
          sections to separate changes by chapter, following
          ARB recommended practice for OpenGL and
          GLX specifications.
        - Modified TexParameter usage to be consistent with
          OpenGL ES 1.1.
        - Added a dependency on EXT_fog_coord.
        - Inserted enumerant value.

    June  16, 2004 (v0.7)
        - Modified to make texture crop rectangle part of
          texture state (set by TexParameter) rather than by
          an ad hoc function (TexCropRectOES).
        - Modified to provide stretch-blit functionality.

    May   28, 2004 (v0.6)
        - Formalized changes to 1.3 and ES 1.0 specs.
          Modified to take screen coordinate arguments
          rather than using the current raster position.
          
    May   19, 2004 (v0.5)
        - Simplified to support only one-to-one source
          blit.  Sprite functionality was moved to a
          separate proposal.

    May    4, 2004 (v0.4)
        - Rewrote to use explicit source and destination
          rectangles instead of overloading PixelZoom.
          Made current raster rectangle explicit and 
          provided both screen space and object space
          ways to define it.

    April 13, 2004
        - Initial version (v0.3)