xref: /third_party/openGLES/extensions/SGIX/SGIX_subsample.txt

XXX - Not complete.

Name

    SGIX_subsample

Name Strings

    GL_SGIX_subsample

Version

    Last Modified Date: 07/27/1999
    Author Revision: $Header: //depot/main/doc/registry/extensions/SGI/subsample.spec#10 $

Number

    202

Dependencies

	Full support of SGI_ycrcb can be accomplished by using
	SGIX_subsample and GL_COLOR_MATRIX.  In addition, some 
        applications may also choose to invoke GL_CONVOLUTION 
        and GL_COLOR_TABLE to better improve the quality of both 
	the resampling and color conversion.  Note however, that
	this extension, combined with the ycrcbformat.spec
	(SGIX_ycrcba) extension obsoletes the current ycrcb.spec
	(SGIX_ycrcb) extension. 

	EXT_texture3D affects the definition of this extension
	EXT_subtexture affects the definition of this extension
	EXT_histogram affects the definition of this extension
	EXT_convolution affects the definition of this extension
	SGI_color_table affects the definition of this extension
 	SGI_resample affects the definition of this extension
 	SGI_subsample_4224 affects the definition of this extension

Overview

	Many video image formats and compression techniques utilize
	various component subsamplings, so it is necessary to provide a
	mechanism to specify the up- and down-sampling of components as
	pixel data is drawn from and read back to the client. Though
	subsampled components are normally associated with the video
	color space, YCrCb, use of subsampling in OpenGL does not imply
	a specific color space.

	This extension defines new pixel storage modes that are used in
	the conversion of image data to and from component subsampled
	formats on the client side. The extension defines a new pixel
	storage mode to specify these sampling patterns, there are
	three legal values (PIXEL_SUBSAMPLE_4444_SGIX, 
	PIXEL_SUBSAMPLE_4242_SGIX, and 
        PIXEL_SUBSAMPLE_2424_SGIX).

	When pixel data is received from the client and an unpacking
	upsampling mode other than PIXEL_SUBSAMPLE_4444_SGIX is 
        specified, the upsampling is performed via replication, 
        unless otherwise specified by RESAMPLE_SGIX.

	Similarly, when pixel data is read back to the client and a
	packing downsampling mode other than 
        PIXEL_SUBSAMPLE_4444_SGIX is specified, downsampling is 
        performed via simple component decimation (point sampling), 
        unless otherwise specified by RESAMPLE_SGIX.

Issues
	* If we revive the ycrcbformat.spec then support for the old
	  (SGIX_ycrcb) extension can be accomplished using the the 
          SGIX_subsample and SGIX_ycrcba.

	* the enums with names like PIXEL_SUBSAMPLE_4242_SGIX and 
	  PIXEL_SUBSAMPLE_2424_SGIX gives an impression that there 
          are 4 components in the subsampling.  Can there be an 
          alternative name?
	 (Angela suggests: PIXEL_SUBSAMPLE_422_CbYCrY_SGIX and 
          PIXEL_SUBSAMPLE_422_YCbYCr_SGIX.  This is clear, but involves 
          naming the components YCrCb.  However, the term 4:2:2 basically 
          refers to the subcarrier frequency for the YCrCb transmission 
          in video signals, so 4:2:2 in a way already implies 4:2:2)

New Procedures and Functions

	None.

New Tokens

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

		PACK_SUBSAMPLE_RATE_SGIX	0x85A0
		UNPACK_SUBSAMPLE_RATE_SGIX	0x85A1

	Accepted by the <param> parameter of PixelStoref and
	PixelStorei when the <pname> parameter is PACK_SUBSAMPLE_RATE_SGIX or
	UNPACK_SUBSAMPLE_RATE_SGIX:

		PIXEL_SUBSAMPLE_4444_SGIX	0x85A2
		PIXEL_SUBSAMPLE_2424_SGIX	0x85A3
		PIXEL_SUBSAMPLE_4242_SGIX	0x85A4

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

	None.

Additions to Chapter 3 of the 1.1 Specification (Rasterization)

	3.6.1 Pixel Storage Modes
	
	The following is added to Table 3.1:
	
	Parameter Name               Type     Initial Value                   Valid Range
	--------------               ----     -------------                   -----------
	UNPACK_SUBSAMPLE_RATE_SGIX   integer  PIXEL_SUBSAMPLE_4444_SGIX  PIXEL_SUBSAMPLE_4444_SGIX
									      PIXEL_SUBSAMPLE_4242_SGIX
									      PIXEL_SUBSAMPLE_2424_SGIX

	PACK_SUBSAMPLE_RATE_SGIX     integer  PIXEL_SUBSAMPLE_4444_SGIX  PIXEL_SUBSAMPLE_4444_SGIX
									      PIXEL_SUBSAMPLE_4242_SGIX
									      PIXEL_SUBSAMPLE_2424_SGIX


	3.6.3 Rasterization of Pixel Rectangles

	<at the end of the paragraph before the Unpacking section>
	
	If the PixelStore parameter UNPACK_SUBSAMPLE_RATE_SGIX is set to
	PIXEL_SUBSAMPLE_4242_SGIX or PIXEL_SUBSAMPLE_2424_SGIX, then the 
	<format> needs to be set to a corresponding 3- or 4- component 
	pixel format or the error INVALID_OPERATION occurs.  If a
	4-component pixel format is used, the alpha is assumed to be
	of constant value 1.0)

	If the PixelStore parameter UNPACK_SUBSAMPLE_RATE_SGIX is set to
	PIXEL_SUBSAMPLE_4242_SGIX or PIXEL_SUBSAMPLE_2424_SGIX, then the 
	<width> needs to be set to a multiple of 2 pixels or the error 
	INVALID_OPERATION occurs.

	<following "to form groups." at the end of the first paragraph
	in the Unpacking section>

	If the PixelStore parameter UNPACK_SUBSAMPLE_RATE_SGIX is set to
	something other than PIXEL_SUBSAMPLE_4444_SGIX then these elements
	are grouped into sets of one, two, three or four values,
	depending on the value of UNPACK_SUBSAMPLE_RATE_SGIX, to form
	groups.

	<at the and of the paragraph>

	Table 3.5.1 summarizes the layout of groups obtained from
	memory depending on the value of UNPACK_SUBSAMPLE_RATE_SGIX.

	Table 3.5.1:

	Value of                   Number of     Number of     Order of
	UNPACK_SUBSAMPLE    	   Components    Values/Group  components
	_RATE_SGIX					       in a seq of
							       groups in memory
	--------------------       ----------    -------       ----------
	PIXEL_SUBSAMPLE_4444_SGIX  n             n
	PIXEL_SUBSAMPLE_4242_SGIX  3 CbYCr(rgb)  2             YCb,YCr,YCb,YCr
	PIXEL_SUBSAMPLE_2424_SGIX  3 CbYCr(rgb)  2             CbY,CrY,CbY,CrY

	note: Cb, Y, and Cr are used to illustrate the in-memory
	packing of pixels in the YCrCb color space. Normally, 2,3, and
	4 component groups are labeled LA, RGB, RGBA.

	<A new section is inserted before "Conversion to RGB">

	Conversion to UNIFORM Sampling
	------------------------------

	This step is applied only if the PixelStore parameter
	UNPACK_SUBSAMPLE_RATE_SGIX is set to something other than
	PIXEL_SUBSAMPLE_4444_SGIX. If UNPACK_SUBSAMPLE_RATE_SGIX 
        is set to PIXEL_SUBSAMPLE_4242_SGIX or 
        PIXEL_SUBSAMPLE_2424_SGIX then the number 
	of components per pixel is increased from two to three.  
	After upsampling, the data is treated as though it were RGB.

	2424:

	< R0,G0>     < B1,G1>     < R2,G2>    < B3, G3>
	<Cb0,Y0>     <Cr0,Y1>     <Cb2,Y2>    <Cr2, Y3>
	  |  |        |   |        |   |        |   |
	  |  |  o-----o---+--o     |   |  o-----o---+--o
	  |  |  |         |  |     |   |  |         |  |
	  o--+--+-----o   |  |     o---+--+-----o   |  |
	  |  |  |     |   |  |     |   |  |     |   |  |
	  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 >

	
	4242:
	< G0,R0>      <G1,B1 >     <G2,R2 >    < G3,B3 >
	<Y0,Cb0>      <Y1,Cr0>     <Y2,Cb2>     <Y3,Cr2>
	  |  |         |   |        |   |        |   |
          \ / \_____ __\__/ \       \ / \_____ __\__/ \
           X     ___X   \    |       X     ___X   \    |
          / \   /    \   \   |      / \   /    \   \   |
	  |  |  |     |   |  |      |  |  |     |   |  |
	  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 >

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

	4.3.2 Reading Pixels
		
	The following is added to Table 4.5:
	
	Parameter Name            Type     Initial Value		Valid Range
	--------------            ----     -------------		-----------
	PACK_SUBSAMPLE_RATE_SGIX  integer  PIXEL_SUBSAMPLE_4444_SGIX	PIXEL_SUBSAMPLE_4444_SGIX
									PIXEL_SUBSAMPLE_4242_SGIX
									PIXEL_SUBSAMPLE_2424_SGIX
	
	<A new section is inserted before "Final Conversion">

	Conversion to Subsampled Form
	------------------------------

	This step is applied only if the PixelStore parameter
	PACK_SUBSAMPLE_RATE_SGIX is set to something other than
	PIXEL_SUBSAMPLE_4444_SGIX. If this step is carried out its
	operation is controlled by the values of PACK_SUBSAMPE_RATE_SGIX.

	If a filter operation is specified by RESAMPLE_SGIX, the
	resampling filter is applied prior to the subsampling step.

	The pack mode involves dropping chroma samples. For users who
	like to perform arbitrary filtering other than those specifiable
	using RESAMPLE_SGIX, it could also be done prior to packing with 
	user calls to convolution function.

	If PACK_SUBSAMPLE_RATE_SGIX is set to PIXEL_SUBSAMPLE_4242_SGIX or 
	PIXEL_SUBSAMPLE_2424_SGIX then the resulting pixels has an average
	of 2 component values per pixel.  Each pixel pair are constructed 
	as follows:
	The first destination pixel of a pair is made up of the 
	first and second component of the first source pixel.
	The second destination pixel of a pair is made up of the 
	third component	of the first source pixel, and the second 
	component of the second source pixel.

	2424:

	<R0,G0,B0,A0> <R1,G1,B1,A1> <R2,G2,B2,A2> <R3,G3,B3,A3>
          |  |  |  |   |  |  |  |    |  |  |  |    |  |  |  |
          |  |  |  *   *  |  *  *    |  |  |  *    *  |  *  *
          |  |  |         |          |  |  |          |
          V  V  V         V          V  V  V          V
	<R0,G0><B0        G1>       <R2,G2><B2,       G3>
	<--- pixel pair ---->       <--- pixel pair ---->

	4242:

	<R0,G0,B0,A0> <R1,G1,B1,A1> <R2,G2,B2,A2> <R3,G3,B3,A3>
          |  |  |  *   *  |  *  *     |  |  |  *   *  |  *  *    
          \ /   |____ ____|           \ /   |____ ____|          
           X     ____X____             X     ____X____
          / \   |         |           |  |  |         |
          V  V  V         V           V  V  V         V
	<G0,R0><G1        B0>       <G2,R2><G3,       B2>
	<--- pixel pair ---->       <--- pixel pair ---->

	<toward the end of the paragraph "Placement in Client Memory">

	If the PixelStore parameter PACK_SUBSAMPLE_RATE_SGIX is set to
	PIXEL_SUBSAMPLE_RATE_4242_SGIX or PIXEL_SUBSAMPLE_RATE_2424_SGIX
	then only the corresponding two elements are written.  That is,
	only the first two components of each group are written to memory.

Additions to Chapter 5 of the 1.1 Specification (Special Functions)

	None.

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

	XXX

Additions to the GLX Specification


Errors

	XXX
	

New State

    Get Value			Get Command	Type	Initial Value			Attribute
    ---------			-----------	----	-------------			---------
    UNPACK_SUBSAMPLE_RATE_SGIX	GetIntegerv	Z4	PIXEL_SUBSAMPLE_4444_SGIX	client
    PACK_SUBSAMPLE_RATE_SGIX	GetIntegerv	Z4	PIXEL_SUBSAMPLE_4444_SGIX	client	

New Implementation Dependent State

	None.