OES_draw_texture

GL_OES_draw_texture

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

Copyright (c) 2004-2013 The Khronos Group Inc. Copyright terms at
    http://www.khronos.org/registry/speccopyright.html

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

Ratified by the Khronos BOP, Aug 5, 2004.

Last Modified Date: 21 July 2004
Author Revision 0.96

OpenGL ES Extension #7

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.

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.

No known IP 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.

    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.

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

    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.

    RESOLVED. Moot. Replace with TexParameteriv().

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

    RESOLVED.  Integer only.  Texture crop rect is
    conceptually a subregion of an integer grid, so its
    natural coordinates are integers.

    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.

    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.

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

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

TEXTURE_CROP_RECT_OES        0x8B9D

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.

                                         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

None.

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)