xref: /third_party/openGLES/extensions/OML/OML_resample.txt

Name

    OML_resample

Name Strings

    GL_OML_resample

Contact

    Jon Leech, Silicon Graphics (ljp 'at' sgi.com)

Status

    Complete. Approved by the Khronos SIG on July 19, 2001.

Version

    Last Modified Date: 07/23/2001
    Author Revision: $Header: //depot/main/doc/registry/extensions/OML/resample.spec#10 $

Number

    241

Dependencies

    OML_subsample is required.
    This extension is written against the OpenGL 1.2.1 Specification,

Overview

    This extension enhances the resampling capabilities of the
    OML_subsample extension. It is loosely based on the SGIX_resample
    extension.

    When converting data from subsampled to uniform sampling, upsampling
    may be performed by one of three methods: component replication,
    zero fill, or adjacent neighbor averaging.

    When converting data from uniform sampling to subsampled form,
    downsampling may be performed only by component decimation (point
    sampling) or averaging.

    Upsampling and downsampling filters other than those defined by this
    extension may be performed by appropriate use of convolution and
    other pixel transfer operations. The zero fill unpacking mode is
    included to assist applications wanting to define their own filters.

Issues

  * Should RESAMPLE_xxx enums be renamed to PIXEL_RESAMPLE_xxx?

IP Status

    No known issues.

New Procedures and Functions

    None.

New Tokens

    Accepted by the <pname> parameter of PixelStoref, PixelStorei,
    GetBooleanv, GetIntegerv, GetFloatv and GetDoublev:

	PACK_RESAMPLE_OML		    0x8984
	UNPACK_RESAMPLE_OML		    0x8985

    Accepted by the <param> parameter of PixelStoref and PixelStorei
    when the <pname> parameter is UNPACK_RESAMPLE_OML:

	RESAMPLE_REPLICATE_OML		    0x8986
	RESAMPLE_ZERO_FILL_OML		    0x8987
	RESAMPLE_AVERAGE_OML		    0x8988

    Accepted by the <param> parameter of PixelStoref and PixelStorei
    when the <pname> parameter is PACK_RESAMPLE_OML:

	RESAMPLE_DECIMATE_OML		    0x8989
	RESAMPLE_AVERAGE_OML		    0x8988


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

    None.

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

  - (3.6.1, p. 75 "Pixel Storage Modes")

    Add to table 3.1 (p. 76):

    Parameter Name	Type	Initial Value		Valid Range
    --------------	----	-------------		-----------
    UNPACK_RESAMPLE_OML integer RESAMPLE_REPLICATE_OML	RESAMPLE_REPLICATE_OML
							RESAMPLE_ZERO_FILL_OML
							RESAMPLE_AVERAGE_OML

    PACK_RESAMPLE_OML	integer RESAMPLE_DECIMATE_OML	RESAMPLE_DECIMATE_OML
							RESAMPLE_AVERAGE_OML


  - (3.6.4, p. 88 "Rasterization of Pixel Rectangles")

  - Modify the new subsection "Conversion to Uniform Sampling"
    (introduced by OML_subsample) to read:

    Conversion to Uniform Sampling

    This step is applied only to subsampled data. If <format> is
    FORMAT_SUBSAMPLE_24_24_OML, then the number of components per pixel
    is increased from two to three. If <format> is
    FORMAT_SUBSAMPLE_244_244_OML. then the number of components per
    pixel is increased from three to four. The upsampling method used is
    determined by the value of the PixelStore parameter
    UNPACK_RESAMPLE_OML.

    After conversion to uniform sampling (see figure 3.9). pixels are
    thereafter treated as though they were RGB (three component) or RGBA
    (four component) format.

    In the remainder of this section, the j'th component of the i'th
    pixel in a row is denoted by S_i,j (for source pixels in client
    memory) and D_i,j (for destination pixels in the color buffer).

    Replication

    If the value of UNPACK_RESAMPLE_OML is RESAMPLE_REPLICATE_OML (see
    figure 3.9), destination component values are defined as:

    For even pixels ((i mod 2) == 0):

	D_i,0 = S_i,0
	D_i,1 = S_i,1
	D_i,2 = S_i+1,0
	D_i,3 = S_i,2

    For odd pixels ((i mod 2) == 1):

	D_i,0 = S_i-1,0
	D_i,1 = S_i,1
	D_i,2 = S_i,0
	D_i,3 = S_i,2


  - (figure 3.9, introduced by OML_subsample, is unchanged)

    Zero Fill

    If the value of UNPACK_RESAMPLE_OML is RESAMPLE_ZERO_FILL_OML (see
    figure 3.10), destination component values are defined as:

    For even pixels ((i mod 2) == 0):

	D_i,0 = S_i,0
	D_i,1 = S_i,1
	D_i,2 = S_i+1,0
	D_i,3 = S_i,2

    For odd pixels ((i mod 2) == 1):

	D_i,0 = 0
	D_i,1 = S_i,1
	D_i,2 = 0
	D_i,3 = S_i,2

  - Add new figure 3.10, following the new figure 3.9 defined in the
    OML_subsample extension:

    FORMAT_SUBSAMPLE_24_24_OML:
    <Cb0,Y0>	 <Cr0,Y1>     <Cb2,Y2>	  <Cr2, Y3>
      |  |	  |   |        |   |	    |	|
      |  |   ____/    |        |   |   ____/	|
      |  |  /	      |        |   |  /		|
      |  |  |	 0.0  | 0.0    |   |  |    0.0	| 0.0
      |  |  |	  |   |  |     |   |  |     |	|  |
      V  V  V	  V   V  V     V   V  V     V	V  V
    <Cb0,Y0,Cr0> <Cb0,Y1,Cr0> <Cb2,Y2,Cr2> <Cb2,Y3,Cr2>
    < R0,G0,B1 > < R0,G1,B1 > < R2,G2,B3 > < R2,G3,B3 >

    FORMAT_SUBSAMPLE_244_244_OML:
    <Cb0,Y0,A0>     <Cr0,Y1,A1>     <Cb2,Y2,A2>     <Cr2,Y3,A3>
      |  |   \	     |	 |   \	     |	 |   \	     |	 |   \
      |  |   _\_____/	 |    \      |	 |   _\_____/	 |    \
      |  |  /  \	 |     \     |	 |  /  \	 |     \
      |  |  |	\   0.0  | 0.0	\    |	 |  |	\   0.0  | 0.0	\
      |  |  |	|    |	 |  |	|    |	 |  |	|    |	 |  |	|
      V  V  V	V    V	 V  V	V    V	 V  V	V    V	 V  V	V
    <Cb0,Y0,Cr0,A0> <Cb0,Y1,Cr0,A1> <Cb2,Y2,Cr2,A2> <Cb2,Y3,Cr2,A3>
    < R0,G0,B1,A0 > < R0,G1,B1,A1 > < R2,G2,B3,A2 > < R2,G3,B3,A3 >


    Figure 3.10: Upsampling with zero fill of subsampled data from host
    memory to form RGB or RGBA pixels.


    Averaging

    If the value of UNPACK_RESAMPLE_OML is RESAMPLE_AVERAGE_OML (see
    figure 3.11), destination component values are defined as:

    For even pixels:

	D_i,0 = S_i,0
	D_i,1 = S_i,1
	D_i,2 = S_i+1,0
	D_i,3 = S_i,2

	(No special case for D_i,2 can arise when i is the last pixel,
	because of the restriction to even image widths).

    For odd pixels:

	D_i,0 = S_i,0			    i == <width>-1 (last pixel)
	      = 1/2 S_i-1,0 + 1/2 S_i+1,0   otherwise
	D_i,1 = S_i,1
	D_i,2 = S_i,0			    i == <width>-1 (last pixel)
	      = 1/2 S_i,0 + 1/2 S_i+2,0     otherwise
	D_i,3 = S_i,2

  - Add new figure 3.11, following the new figure 3.10:

    FORMAT_SUBSAMPLE_24_24_OML:
    <Cb0,Y0>	 <Cr0,Y1>     <Cb2,Y2>	  <Cr2, Y3>
      |  |	  |   |        |   |	    |	|
      |  |   ____/ \__|__  ____|___|_______/ \__|__  _
      |  |  /	      |  \/    |   |  /		|  \/
      |\_|__|_____  __|__|___ /|\__|__|_____  __|__|__
      |  |  |	  \/  |  |     |   |  |     \/	|  |
      V  V  V	  V   V  V     V   V  V     V	V  V
    <Cb0,Y0,Cr0> <Cb0,Y1,Cr0> <Cb2,Y2,Cr2> <Cb2,Y3,Cr2>
    < R0,G0,B1 > < R0,G1,B1 > < R2,G2,B3 > < R2,G3,B3 >


    FORMAT_SUBSAMPLE_244_244_OML:
    <Cb0,Y0,A0>     <Cr0,Y1,A1>     <Cb2,Y2,A2>     <Cr2,Y3,A3>
      |  |   \	     |	 |   \	     |	 |   \	      |   |   \
      |  |   _\_____/ \__|__  \______|___|____\______/ \__|__  \___
      |  |  /  \	 |  \/ \     |	 |  /  \	  |  \/ \
      |\_|__|___\____  __|__|___\___/|\__|__|___\_____	__|__|___\_
      |  |  |	|    \/  |  |	|    |	 |  |	|     \/  |  |	 |
      V  V  V	V    V	 V  V	V    V	 V  V	V     V   V  V	 V
    <Cb0,Y0,Cr0,A0> <Cb0,Y1,Cr0,A1> <Cb2,Y2,Cr2,A2> <Cb2,Y3,Cr2,A3>
    < R0,G0,B1,A0 > < R0,G1,B1,A1 > < R2,G2,B3,A2 > < R2,G3,B3,A3 >

    Figure 3.11: Upsampling with averaging of subsampled data from host
    memory to form RGB or RGBA pixels.

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

  - Modify the new section "Conversion to Subsampled Form" (introduced
    by OML_subsample) to read:

    Conversion to Subsampled Form

    This step is applied only if <format> is FORMAT_SUBSAMPLE_24_24_OML
    or FORMAT_SUBSAMPLE_244_244_OML. A filter operation specified by the
    value of PACK_RESAMPLE_OML is applied prior to the subsampling step.

    In the remainder of this section, the j'th component of the i'th
    pixel in a row is denoted by S_i,j (for source pixels in the color
    buffer) and D_i,j (for destination pixels in client memory).

    If <format> is FORMAT_SUBSAMPLE_24_24_OML, then the resulting pixels
    have 2 components (see figure 4.3); if <format> is
    FORMAT_SUBSAMPLE_244_244_OML, then the resulting pixels have 3
    components (see figure 4.4).

    Decimation

    If the value of PACK_RESAMPLE_OML is RESAMPLE_DECIMATE_OML, then
    destination component values are defined as:

    For even pixels ((i mod 2) == 0):

	D_i,0 = S_i,0
	D_i,1 = S_i,1
	D_i,2 = S_i,3	(only for FORMAT_SUBSAMPLE_244_244_OML)

    For odd pixels ((i mod 2) == 1):

	D_i,0 = S_i-1,2
	D_i,1 = S_i,1
	D_i,2 = S_i,3	(only for FORMAT_SUBSAMPLE_244_244_OML)

  - Add new figure 4.3 (renumber following figures):

    FORMAT_SUBSAMPLE_24_24_OML:
    <R0,G0,B0,A0> <R1,G1,B1,A1> <R2,G2,B2,A2> <R3,G3,B3,A3>
      |  | |   |   |  |  |  |	 |  |  |  |    |  |  |	|
      |  |  \  *   *  |  *  *	 |  |	\ *    *  |  *	*
      |  |   |	      |		 |  |	 |	  |
      V  V   V	      V		 V  V	 V	  V
    <Cb0,Y0><Cr0,     Y1>	<Cb2,Y2><Cr2,	  Y3>
    <--- pixel pair ---->	<--- pixel pair ---->

    FORMAT_SUBSAMPLE_244_244_OML:
    <R0,G0,B0,A0> <R1,G1,B1,A1> <R2,G2,B2,A2> <R3,G3,B3,A3>
      |  |  |  |   |   |  |  |	  |  |	|  |   |   |  |  |
      |  |  \__|__ *   |  *  |	  |  |	\__|__ *   |  *  |
      |  |     |  \    |     |	  |  |	   |  \    |	 |
      |  |    /    |   |    /	  |  |	  /    |   |	/
      V  V   V	   V   V   V	  V  V	 V     V   V   V
    <Cb0,Y0,A0>   <Cr0,Y1,A1>	<Cb2,Y2,A2>   <Cr2,Y3,A3>
    <--- pixel pair ---->	<--- pixel pair ---->

    Figure 4.3: Downsampling with decimation of RGB or RGBA pixels to
    form subsampled data in host memory.


    Averaging

    If the value of PACK_RESAMPLE_OML is RESAMPLE_AVERAGE_OML, then
    destination component values are defined as:

    For even pixels:

	D_i,0 = 3/4 S_i,0 + 1/4 S_i+1,0     i == 0 (first pixel)
	      = 1/4 S_i-1,0 + 3/4 S_i,0     i == <width>-1 (last pixel)
	      = 1/4 S_i-1,0 +		    otherwise
		1/2 S_i,0 +
		1/4 S_i+1,0
	D_i,1 = S_i,1
	D_i,2 = S_i,3

    For odd pixels:

	D_i,0 = 3/4 S_i-1,2 + 1/4 S_i,2     i == <width>-1 (last pixel)
	      = 1/4 S_i-1,2 +		    otherwise
		1/2 S_i,2 +
		1/4 S_i+1,2
	D_i,1 = S_i,1
	D_i,2 = S_i,3

XXX Note that the "last pixel" case is only needed for readbacks where
XXX <width> is not even, so may be removable.

  - Add new figure 4.4 (renumber following figures):

    FORMAT_SUBSAMPLE_24_24_OML:
    <R0,G0,B0,A0> <R1,G1,B1,A1> <R2,G2,B2,A2> <R3,G3,B3,A3>
      | _|_|_______/\_|__|______ | _|__|_______/\_|__|_______
      |/ | |	      |  |	\|/ |  \_______   |  |
      |  |  \______  _|_/ \______|__|_________ \ _|_/ \______
      |  |	   \/ |		 |  |	      \|/ |
      V  V	   V  V		 V  V	       V  V
    <Cb0,Y0>	 <Cr0,Y1>      <Cb2,Y2>      <Cr2,Y3>

    FORMAT_SUBSAMPLE_244_244_OML:
    <R0,G0,B0,A0> <R1,G1,B1,A1> <R2,G2,B2,A2> <R3,G3,B3,A3>
      | _|_|___|___/\_|__|___|__ | _|__|___|___/\_|__|___|___
      |/ | |   |      |  |   |	\|/ |  \___|___   |  |	 |
      |  |  \__|___  _|_/ \__|___|__|______|__ \ _|_/ \__|___
      |  |     |   \/ |      |	 |  |	   |  \|/ |	 |
      V  V     V   V  V      V	 V  V	   V   V  V	 V
    <Cb0,Y0,  A0><Cr0,Y1,   A1><Cb2,Y2,   A2><Cr2,Y3,	A3>

    Figure 4.4: Downsampling with averaging of RGB or RGBA pixels to
    form subsampled data in host memory.

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

    None.

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

    None.

Additions to the GLX 1.3 Specification

    None.

Errors

    See above.

New State

(table 6.17, p. 207)
    Get Value		Type	Get Command Initial Value
    ---------		----	----------- -------------
    UNPACK_RESAMPLE_OML Z3	GetIntegerv RESAMPLE_REPLICATE_OML
    PACK_RESAMPLE_OML	Z2	GetIntegerv RESAMPLE_DECIMATE_OML

(continued columns)
    Get Value		Description		Sec Attribute
    ---------		-----------		--- ---------
    UNPACK_RESAMPLE_OML Pixel upsampling mode	3.6 pixel-store
    PACK_RESAMPLE_OML	Pixel downsampling mode 4.3 pixel-store

New Implementation Dependent State

    None.

Revision History

  * Revision 10, 07/24/2001 - Finalized Status for OpenML 1.0.
  * Revision 9, 07/16/2001 - Remove erroneous redefinition of
    RESAMPLE_AVERAGE enumerant value.
  * Revisions 7-8, 07/11/2001 - Assign enum values and extension number
    for the registry.
  * Revision 6 - Correct errors in the equations describing subsampling.
  * Revision 5 - formatting changes for OpenML Specification
  * Revision 4, 03/27/2001 - Rewrite to use the <format> parameter,
    rather than a pixel storage mode, to specify subsampled data.
  * Revision 3 - Removed support for YC component orders. Renamed CY and
    CYA enumerants more sensibly. Added Discreet's RESAMPLE_AVERAGE
    resampling mode. Changed text descriptions of sampling to equations.
    Made enum values undefined until we've determined if this extension
    is backwards compatible with SGIX_resample.
  * Revision 2 - corrected 4224 upsampling and downsampling figures.
    Moved discussion of errors for non-even image widths to the
    OML_subsample specification.
  * Revision 1 - derived from SGIX_resample.