Name
ATI_array_rev_comps_in_4_bytes
Name Strings
GL_ATI_array_rev_comps_in_4_bytes
Contributors
Dan Abrahams-Gessel, ATI Research, Inc., (dgessel 'at' ati.com)
Bob Beretta, Apple Computer (beretta 'at' apple.com)
Thomas Fortier, ATI Research, Inc., (tfortier 'at' ati.com)
Contact
Jeremy Sandmel, ATI Research, Inc., (jsandmel 'at' ati.com)
Status
Shipping (on MacOSX version 10.3 and later)
Version
Last Modified Date: December 5, 2003
Author Revision: 0.05
Number
???
Dependencies
OpenGL 1.1 is required.
GL_APPLE_vertex_array_object affects the definition of this
extension.
GL_APPLE_vertex_array_range affects the definition of this
extension.
GL_APPLE_element_array affects the definition of this
extension.
The extension is written against the OpenGL 1.4 Specification.
Overview
In order to achieve optimal performance during the processing
of vertex array data, certain ATI hardware can benefit from
having the vertex pre-arranged in a particular format
by the application. This extension provides an interface
both for the GL to request that the application pre-arrange
the data, and for the application to inform the GL the
application has complied with the request.
When this extension is used, within the collection of arrays
dereferenced by a glDrawArrays call, for each array of data
(position, color, normal, texture coordinates, etc) in which the
components (R,G,B,A, or S,T,R,Q, etc) of the array element
are less than 4 bytes in size, then the components are
reordered by the application to achieve optimal performance.
The reordering is simple in practice. For every group of
4 bytes, the component ordering needs to be reversed.
If the components are 1 byte each, then all 4 bytes are
reversed. If the components are 2 bytes each (i.e. a short),
then each pair of shorts within the array elements is reversed
within the pair.
The intended usage model is that this extension string
is only exported if needed. That is, if the extension
string is not exported, then no re-ordering is required.
Note that this requirement also affects arrays of vertex
indices if the APPLE_element_array extension
is used and the indices are less than 4 bytes per index.
IP Status
There are no known IP related issues with this extension
at the time of writing this specification.
Issues
1. Should there be a way for the GL to request special treatment
of individual arrays instead of treating all arrays uniformly?
That is, should there be extension strings or some other
query mechanisms for independently asking if each of the
color, normal, texcoord, etc, arrays need different
re-formatting?
RESOLUTION: No.
The particular hardware issue here is
that all arrays need the same re-formatting so it's not
worth creating a more complicated API than necessary.
This api, as it stands, is quite simple.
(Though arguably the actual format of the data is
a little weird.)
2. This extension only makes sense if the for
all of the arrays is a multiple of 4 when
GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI is set to TRUE.
If the is not a multiple of 4 then, what should happen?
Should we say the results of rendering are undefined or
should an INVALID_OPERATION error be generated at
render time?
RESOLUTION: unresolved.
Ideally, an INVALID_OPERATION error would be thrown
at render time if an attempt was made to render while any
enabled array had an effective stride that was not
a multiple of 4 bytes if GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI
is true.
3. Does anything special need to be said aout how
this extension interacts with interleaved arrays?
RESOLUTION: No.
The same restrictions apply to interleaved arrays
and all array rendering for that matter. Regardless of how
the vertx array state variables are set, the constraints of
this extension still apply.
4. Is the GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI state stored
per vertex array object (as defined in
GL_APPLE_vertex_array_object), or per-context?
RESOLUTION: unresolved
The intent of this specification is that the
GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI is stored
per vertex array object.
However, the GL_APPLE_vertex_array_object extension
doesn't actually define the VertexArrayParameteriAPPLE
routine. That routine is defined in the
GL_APPLE_vertex_array_range specification which makes
no mention of objects at all. This would imply
the vertex array range storage hints which are
defined in the GL_APPLE_vertex_array_range are to
be stored per context, but I don't think that was
intended. Furthermore, the GL_APPLE_vertex_array_object
does not include the storage hints set by
VertexArrayParameteriAPPLE in it's list of state encapsulated
by GL_APPLE_vertex_array_object, which is further evidence
that the vertex array parameter state is not included
per-object. Again, however, I don't think that was the
intent.
In any event, assuming that the state set by
VertexArrayParameteriAPPLE is per-object, then this new
state GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI is also per object.
Whether you can get this state by a state query is a
separate issue (see issue #5 below)
5. Should the GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI parameter
state be get'able?
RESOLUTION: unresolved
Ideally yes, however the GL_APPLE_vertex_array_range
extension which adds the VertexArrayParameteriAPPLE
entry point for some reason does not also add a
corresonding GetVertexArrayParameterivAPPLE entry point.
If it did, we'd use that.
Since it doesn't, should we add the Get entry point
for this extension alone?
Or should we modify that one to allow the Getting
of the vertex array range storage hint
6. ATI_array_rev_comps_in_4_bytes is an ATI extension that
depends on, but does not require the GL_APPLE_vertex_array_range
extension because it uses the VertexArrayParameteriAPPLE entry
point. If the GL_APPLE_vertex_array_range is not supported,
then this extension defines it just as it is defined in
that extension. So the question is: is that weird?
Should there be a VertexArrayParameteriATI entry point instead
if GL_APPLE_vertex_array_range is not supported?
RESOLUTION: unresolved
Agreed, this is weird, but since the
only platform implementing this extension right now
is MacOSX where GL_APPLE_vertex_array_range is supported
this is a non-issue.
However, if this extension gets implemented on any
on any other non-Apple platforms, that happen to not support
GL_APPLE_vertex_array_range, then this will become an issue.
The recommended resolution in that case would be to get
Apple's permission to just use this one routine for this
extension.
If that fails, we will have to create
VertexArrayParameteriATI.
New Procedures and Functions
If GL_APPLE_vertex_array_range is supported, then no
new procedures and functions are required by this extension.
If GL_APPLE_vertex_array_range is not supported, then
this extension adds the following single procedure:
void VertexArrayParameteriAPPLE(enum pname, int param);
New Tokens
Accepted by the parameters of VertexArrayParameteriAPPLE
GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI 0x897C
Additions to Chapter 2 of the OpenGL 1.2.1 Specification (OpenGL Operation)
Modify Section 2.8, Vertex Arrays, p.24, second paragraph as
follows:
"The one, two, three, or four values in an array that correspond
to a single vertex comprise an array element. The values within
each array element are stored sequentially in memory, unless
GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI is set to TRUE.
GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI can be set to TRUE by using
the routine:
void VertexArrayParameteriAPPLE(enum pname, int param)
with set to GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI and
set to TRUE. The default value of
GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI is FALSE.
If GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI is set to true, and the
or "effective stride" (see table 2.6) for that array is
a multiple of 4 bytes, then the GL is expecting that the
components of an element of the array have been re-arranged as
follows:
For 1 four-byte component per 4 bytes, then
the GL is not expecting any data re-arranging.
For 2 two-byte components per 4 bytes, then
the order of the components are reversed within each
pair of components per array element,
For 4 single-byte components per 4 bytes, then
the order of the components are reversed within
each group of 4 components per array element
To be explicit and complete, the following table (2.5) describes
the possible combinations of type, element size, and
component ordering:
Bytes per Number of Original order Rearranged order
component components within 4 byte within 4 byte
per array per array groups groups
element element
------------ ---------- -------------- --------------
1 1 [A],[?],[?],[?] [?],[?],[?],[A]
................................................................
1 2 [A],[B],[?],[?] [?],[?],[B],[A]
................................................................
1 4 [A],[B],[C],[D] [D],[C],[B],[A]
................................................................
2 1 [A,B],[?,?] [?,?],[A,B]
................................................................
2 2 [A,B],[C,D] [C,D],[A,B]
................................................................
2 4 [A,B],[C,D], [C,D],[A,B],
[E,F],[G,H] [G,H],[E,F]
................................................................
4 1 [A,B,C,D] [A,B,C,D]
................................................................
4 2 [A,B,C,D], [A,B,C,D],
[E,F,G,H] [E,F,G,H]
................................................................
4 4 [A,B,C,D], [A,B,C,D],
[E,F,G,H] [E,F,G,H]
[I,J,K,L] [I,J,K,L]
[M,N,O,P] [M,N,O,P]
................................................................
- The effective element stride is assumed to be a multiple
of 4 for all cases in this table.
- An item enclosed in brackets "[]" represents a single
component of an array element
- A question mark "?" character represents a "don't care"
component or padding caused by a stride
which is wider than the native array element size.
- The letters, A,B,C,D, E,F,G,H, I,J,K,L, M,N,O,P
represent individual bytes of data which are
originally stored sequentially
- Note that all the elements for the cases where
there are 4 bytes per component remain unchanged
Table 2.5 - Expected byte and vertex array element component
ordering when using GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI
If GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI is set to true, and the
for that array is not a multiple of 4 bytes, then
the results of rendering with that array are undefined."
**** TODO: SHOULD THIS GENERATE AN INVALID_OPERATION ERROR INSTEAD??? ****
Modify Section 2.8, Vertex Arrays, p.24, second paragraph,
starting with the third sentence as follows:
"If stride is specified as zero, then array elements are stored
sequentially as well, unless GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI
is set to true.
If GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI is set to true, and
is set to zero, then the GL will consider the
"effective stride" (see table 2.6 below) between elements.
The "effective stride" is nothing more than the stride
of tightly packed data from one array element to the
next. If the "effective stride" is a multiple of 4 bytes, then
the GL still expects the array elements to be formatted as
described above in table 2.5. If GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI
is set to true, and is zero, and if the "effective stride"
is not a multiple of 4 bytes, then the results of rendering with
that array are undefined.
**** TODO: AGAIN: SHOULD THIS GENERATE AN INVALID_OPERATION ERROR INSTEAD??? ****
"Effective Stride"
when is 0
---- ------ ----------------
UNSIGNED_BYTE, BYTE 1 1*
UNSIGNED_BYTE, BYTE 2 2*
UNSIGNED_BYTE, BYTE 3 3*
UNSIGNED_BYTE, BYTE 4 4
UNSIGNED_SHORT, SHORT 1 2*
UNSIGNED_SHORT, SHORT 2 4
UNSIGNED_SHORT, SHORT 3 6*
UNSIGNED_SHORT, SHORT 4 8
UNSIGNED_INT, INT, FLOAT 1 4
UNSIGNED_INT, INT, FLOAT 2 8
UNSIGNED_INT, INT, FLOAT 3 12
UNSIGNED_INT, INT, FLOAT 4 16
DOUBLE 1 8
DOUBLE 2 16
DOUBLE 3 24
DOUBLE 4 32
Table 2.6 - Definition of effective stride when
is set to zero.
, , and parameters represent
those given to any of the gl*ArrayPointer calls.
Rendering with arrays for the cases
marked with "*" will cause undefined
results because the "effective stride"
is not a multiple of 4.
The error INVALID VALUE is generated if stride is negative.
Otherwise pointers to the ith and (i + 1)st
elements of an array differ by stride basic machine units
(typically unsigned bytes), the pointer to the (i + 1)st element
being greater. For each command, pointer specifies the location
in memory of the first value of the first element of the array
being specified...."
Additions to Chapter 3 of the OpenGL 1.2.1 Specification (Rasterization)
None.
Additions to Chapter 4 of the OpenGL 1.2.1 Specification (Per-Fragment
Operations and the Frame Buffer)
None.
Additions to Chapter 5 of the OpenGL 1.2.1 Specification (Special Functions)
**** TODO: is VertexArrayParameteriAPPLE or
GetVertexArrayParameter listable?
Additions to Chapter 6 of the OpenGL 1.2.1 Specification (State and
State Requests)
**** TODO: should VertexArrayParameteriAPPLE or
GetVertexArrayParameter go here?
Additions to Appendix A of the OpenGL 1.2.1 Specification (Invariance)
None.
Additions to the AGL/GLX/WGL Specifications
None
Dependencies on GL_APPLE_vertex_array_object
If GL_APPLE_vertex_array_object is supported, then the
array object also encapsulates the state defined by this
extension. That is, there is a unique value of
GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI per vertex array object.
Dependencies on GL_APPLE_vertex_array_range
If GL_APPLE_vertex_array_range is supported, then this extension
defines no new entry points and simply uses the
VertexArrayParameteriAPPLE entry point from that specification.
If GL_APPLE_vertex_array_range is not supported, then
this extension adds the VertexArrayParameteriAPPLE
entry point.
Dependencies on GL_APPLE_element_array
If GL_APPLE_element_array is supported, then the reformatting
requirements of this extension apply to the array
of vertex indices as well. That is, byte or short sized
index data must be re-ordered within a 4 byte group if
GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI is set to TRUE.
Errors
**** TODO: should INVALID OPERATION be set if
GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI is set to true and
all of the arrays in the array object/current array state
do not have an effective stride of a multiple of 4 bytes per array?
New State
(table 6.N, p. ###)
Initial
Get Value Type Get Command Value Description Sec. Attribute
--------- ---- ----------- ------- ----------- ---- ---------
GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI B none FALSE request special 2.8 vertex-array
interpretation
of vertex array
data
New Implementation Dependent State
None.
Example usage
- pseudo-code:
============
#if GL_ATI_array_rev_comps_in_4_bytes
if (isExtensionSupported("GL_ATI_array_rev_comps_in_4_bytes")
{
// This example uses byte-per-component color and
// short-per-component tex coords.
// Therefore,
// color arrays (8888) need special formatting
// tex coords (16_16_16_16) need special formatting
// everything else is (default) 4 byte per component format
VertexArrayParameteriAPPLE(
GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI,
GL_TRUE);
// color values will be rearranged by app into ABGR order,
// 1 byte per component, such that after component
// re-ordering within each 4 byte group, this will
// generate RGBA data per vtx
ReformatColorDataInto_ABGR_ubytes(myTexCoordPtr);
// tex coords will be rearranged by app into TSQR order,
// 1 short per component, such that after component
// re-ordering within each 4 byte group, this will
// generate STRQ data per vtx
ReformatTexCoordDataInto_TSQR_shorts(myTexCoordPtr);
// vtx position data will already be arranged by app
// into XYZW order,
// 1 float (4 bytes) per component, as expected.
// This means the data for vertices remains unchanged
// by this unpack parameter. Since it's only one component
// for every 4 bytes, no component reordering occurs,
// therefore no special reformatting is necessary for
// position data.
}
#endif
// call arrays just like before
ColorPointer ( 4, GL_UNSIGNED_BYTE, 4, myColorPtr ) ;
TexCoordPointer ( 4, GL_SHORT, 8, myTexCoordPtr) ;
VertexPointer ( 4, GL_FLOAT, 0, myVtxPointer );
// now render
glDrawArrays(...)
============
Revision History
Version 0.05 - December 5, 2003 (js)
- fixed typo in contributor info
Version 0.04 - December 5, 2003 (js)
- fixed typo in table 2.6
- fixed typo which refered to wrong extension name
Version 0.03 - December 5, 2003 (js)
- added dependency on GL_APPLE_element_array
- simplified overview section
- clarified and reformatted several items in issues list
- added issue #6 about re-using VertexArrayParameteriAPPLE
entry point
- added more explicit language about using
VertexArrayParameteriAPPLE to set value of
GL_ARRAY_REV_COMPS_IN_4_BYTES_ATI state variable
- simplified Table 2.5 based on component size instead
of component type to avoid duplicating
unsigned and signed types, all that matters is their
size anyway
- simplified Table 2.6, effective stride table
- cleaned up pseudo code example
Version 0.02 - November 26, 2003 (js)
- fleshed out, added tables for clarity
- added sample code example
- added more issues
- added state table
Version 0.01 - November 26, 2003 (js)
- initial revision
- very rough draft
|
