1XXX - Not complete yet!!!
2Name
3
4    SGIX_vertex_array_object
5
6Name Strings
7
8    GL_SGIX_vertex_array_object
9
10Version
11
12    $Date: 1997/02/21 17:33:22 $ $Revision: 1.3 $
13
14Number
15
16    XXX
17
18Dependencies
19
20    Requires either OpenGL 1.1 or EXT_vertex_array to be present.
21    EXT_compiled_vertex_array affects the definition of this extension.
22
23Overview
24
25    This extension introduces named vertex array objects.  This extension is 
26    primarily useful when coupled with the EXT_compiled_vertex_array extension,
27    although that extension is not strictly required.  
28
29    A significant problem with compiled vertex arrays is that they allow only
30    one set of arrays to be locked at one time.  This means that
31    implementations of compiled vertex array cannot cache copies of vertex
32    array data effectively when more than one vertex array is used to compose
33    each rendered frame.  After the first vertex array data is locked, and
34    perhaps cached by the implementation, the locking of subsequent vertex
35    arrays forces the cached copy of the first vertex array to be lost.  It
36    cannot be reused next time the original vertex array is re-locked.  The
37    only way around this situation is for the application program to put all
38    vertex array data into one humungous array and lock it all at once, but
39    this is an unreasonable application burden.
40
41    The vertex array object extension addresses this issue by allowing
42    multiple sets of vertex arrays to be locked, and thus cached in the
43    graphics hardware, at one time.
44
45Issues
46
47    * It's not clear how useful this is without EXT_compiled_vertex_array.
48
49    A: It could allow the implementation to leave DMA-able arrays locked in
50    host memory, even while they are not bound.  This can speed subsequent
51    downloads.  Does this really matter?
52
53    * Why can't you just use display lists for this?
54
55    Matt: On some low-end systems, GL hardware state cannot be read back from
56    the hardware, so the state is stored either on the CPU or early in the gfx
57    pipeline.  If the storage location from which display lists are injected
58    into the gfx pipe is downstream from this GL state shadow unit, then
59    executing display lists cannot modify GL state.  In summary, low-end
60    graphics hardware cannot accelerate display lists since they can modify GL
61    state.  Note that even "easy" display lists with only vertex and color
62    data modify state.  Vertex array objects are vastly superior to display
63    lists in that they are not required to update the GL state that they
64    modify.
65
66    Phil: Vertex arrays, unlike display lists, leave behind no "side-effect"
67    state, so they don't need to influence the shadow state. In general,
68    vertex array objects are much more "hardware-friendly" than display lists.
69
70    * Rather than add an entirely new mechanism, which applies to only one
71    case of the many that display lists cover, could you add an extension that
72    relaxes the state-modification behavior of dlists?
73
74    Matt: Perhaps it could be done, but i don't think anyone would like that.
75    It pretty much breaks the display list model.  In order for display lists
76    to really be acceleratable on Odyssey, all glEnd commands would have to
77    lose current state.
78
79    Dave Gorgen: A context switch could happen even in the midst of a DL, so
80    the idea of relaxing the state-modifying behavior of display lists seems
81    quite messy to specify.  State could be lost at essentially any glEnd
82    function.
83
84    * What about just accelerating vertex arrays in display lists?  The idea
85    is to build a display list which contains only DrawElements commands.
86    Such a display list would have the desired property of not modifying any
87    GL state.
88
89    Matt: We want to cache the vertex array data.  And we want to be able to
90    have multiple arrays of data cached at the same time.  Caching drawarrays
91    in display lists doesn't really buy you anything.  What we're looking for
92    is a way to cache the data in a persistent way, even while other vertex
93    arrays are in use.  Also, multiple uses of the same vertex array data in
94    different display lists could not be shared by such a mechanism.
95
96    * Should we add a general object mechanism?
97    
98    Yes
99
100Reasoning
101
102    * Note that PrioritizeVertexArraysSGIX and AreVertexArraysResidentSGIX do
103    take zero as a valid argument, which differs with the EXT_texture_object.
104
105    * Regarding display lists on Odyssey:  
106
107New Procedures and Functions
108
109    void GenVertexArraysSGIX(sizei n,
110			     uint* arrays);
111
112    void DeleteVertexArraysSGIX(sizei n,
113			        const uint* arrays);
114
115    void BindVertexArraySGIX(uint array);
116
117    void PrioritizeVertexArraysSGIX(sizei n,
118			       	    const uint* arrays,
119			       	    const clampf* priorities);
120
121    boolean AreVertexArraysResidentSGIX(sizei n,
122				 	const uint* arrays,
123					boolean* residences);
124
125    boolean IsVertexArraySGIX(uint array);
126
127New Tokens
128
129    Accepted by the <value> parameters of GetBooleanv, GetDoublev, GetFloatv,
130    GetIntegerv: 
131
132	VERTEX_ARRAY_PRIORITY_SGIX	0x????
133
134    Accepted by the <value> parameters of GetBooleanv, GetDoublev, GetFloatv,
135    GetIntegerv:
136
137	VERTEX_ARRAY_RESIDENT_SGIX	0x????
138
139    Accepted by the <value> parameters of GetBooleanv, GetDoublev, GetFloatv,
140    GetIntegerv:
141
142	VERTEX_ARRAY_BINDING_SGIX	0x????
143
144Additions to Chapter 2 of the 1.0 Specification (OpenGL Operation)
145
146  Add a new section, 2.8.1: Vertex Array Objects.
147
148    It is possible to create named vertex array objects.  The name space for
149    vertex array objects is the unsigned integers, with zero reserved by the
150    GL.
151
152    A vertex array object is created by binding an unused name.  This binding
153    is accomplished by calling BindVertexArraySGIX with <array> set to the
154    name of the new vertex array object.  When a vertex array object is bound,
155    the association with the previously bound vertex array is automatically
156    broken.  When a new vertex array object is first created, it is a clean
157    copy of the default GL state for all vertex array state fields, as
158    described in the additions to Section 6.
159
160    While a vertex array object is bound, GL operations affect the bound
161    vertex array object, and queries return state from the bound vertex array
162    object.  If DrawElements, ArrayElement, or DrawArrays are invoked, the
163    bound vertex array object is used.
164
165    In order that access to the default vertex array not be lost, this
166    extension treats them as though their names were all zero.  Thus the
167    default vertex array is operated on, queried, and applied while zero is
168    bound.
169
170    Vertex Array objects are deleted by calling DeleteVertexArraysSGIX with
171    <arrays> pointing to a list of <n> names of vertex array object to be
172    deleted.  After a vertex array object is deleted, it has no contents and
173    its name is freed.  If a vertex array object that is currently bound is
174    deleted, the binding reverts to zero.  DeleteVertexArraysSGIX ignores
175    names that do not correspond to vertex arrays objects, including zero.
176
177    GenVertexArraysSGIX returns <n> vertex array object names in <arrays>.
178    These names are chosen in an unspecified manner, the only condition being
179    that only names that were not in use immediately prior to the call to
180    GenVertexArraysSGIX are considered.  Names returned by GenVertexArraysSGIX
181    are marked as used (so that they are not returned by subsequent calls to
182    GenVertexArraysSGIX), but they are associated with a vertex array object
183    only after they are first bound (just as if the name were unused).
184
185    An implementation may choose to establish a working set of vertex array
186    objects on which binding operations are performed with higher performance.
187    A vertex array object that is currently being treated as a part of the
188    working set is said to be resident.  AreVertexArraysResidentSGIX returns
189    TRUE if all of the <n> vertex array objects (or default vertex arrays)
190    named in <arrays> are resident, FALSE otherwise.  Note that the default
191    vertex array may be listed in the <arrays> parameter.  If FALSE is
192    returned, the residence of each vertex array object (and possibly that of
193    the default vertex array) is returned in <residences>.  Otherwise the
194    contents of the <residences> array are not changed.  If any of the names
195    in <arrays> is not the name of a vertex array object or zero, FALSE is
196    returned, the error INVALID_VALUE is generated, and the contents of
197    <residences> are indeterminate.  The resident status of a single bound
198    vertex array object can also be queried by calling GetIntegerv,
199    GetBooleanv, GetDoublev, or GetFloatv with <value> set to
200    VERTEX_ARRAY_RESIDENT_SGIX.  Note that the residence status of vertex
201    array zero may be determined by calling any of
202    AreVertexArraysResidentSGIX, GetFloatv, GetDoublev, GetIntegerv, or
203    GetBooleanv.
204
205    Applications guide the OpenGL implementation in determining which vertex
206    array objects should be resident by specifying a priority for each vertex
207    array object.  PrioritizeVertexArraysSGIX sets the priorities of the <n>
208    vertex array objects in <arrays> to the values in <priorities>.  Each
209    priority value is clamped to the range [0.0, 1.0] before it is assigned.
210    Zero indicates the lowest priority, and hence the least likelihood of
211    being resident.  One indicates the highest priority, and hence the
212    greatest likelihood of being resident.  PrioritizeVertexArraysSGIX does
213    accept priorities for and vertex array zero, the default vertex array
214    object.
215
216  Add a new section, 2.8.2: Compiled Vertex Array Objects.
217
218    LockArraysEXT and UnlockArraysEXT cause vertex array objects (or the
219    default vertex array) which is currently bound to be considered locked.
220    Locking allows pre-compilation or copying of the array contents.  The
221    implementation is free to copy array elements when they become locked, and
222    use those cached copies until such time as the vertex array becomes
223    unlocked.
224
225    When a vertex array object (or the default vertex array) which was bound
226    becomes unbound (due to a rebinding to another object or default texture),
227    the current lock state is retained in the vertex array object.  When a new
228    vertex array object is bound, the lock state of the new current array
229    object is restored from the last time it was bound.
230
231    If vertex array data is locked when an object becomes unbound, the memory
232    in the client-side array should not be modified until after that vertex
233    array object is both rebound and unlocked.  In other words, locking
234    persists even when the vertex object is currently unbound.  The client
235    array is still considered locked, and its contents should not be changed
236    or undefined results may occur.
237
238    This behavior allows applications using multiple vertex array objects to
239    retain cached copies of those vertex arrays in the graphics hardware,
240    whenever possible.
241
242Additions to Chapter 3 of the 1.0 Specification (Rasterization)
243
244    None
245
246Additions to Chapter 4 of the 1.0 Specification (Per-Fragment Operations
247and the Frame Buffer)
248
249    None
250
251Additions to Chapter 5 of the 1.0 Specification (Special Functions)
252
253    None of these commands are included in display lists.
254
255Additions to Chapter 6 of the 1.0 Specification (State and State Requests)
256
257    IsVertexArraySGIX returns TRUE if <array> is the name of a valid vertex
258    array object.  If <array> is zero, or is a non-zero value that is not
259    the name of a vertex array object, or if an error condition occurs,
260    IsVertexArraySGIX returns FALSE.
261
262    The name of the vertex array object currently bound is returned in
263    <params> when GetIntegerv is called with <value> set to
264    VERTEX_ARRAY_BINDING_SGIX.  If no vertex array object is currently bound,
265    zero is returned.  
266
267    A vertex array object comprises the vertex array priority, element size,
268    type, stride, and client array pointters that are associated with that
269    object.  More explicitly, the state list
270
271	VERTEX_ARRAY_PRIORITY_SGIX,
272	VERTEX_ARRAY_SIZE,
273	VERTEX_ARRAY_TYPE,
274	VERTEX_ARRAY_STRIDE,
275	VERTEX_ARRAY_POINTER,
276	NORMAL_ARRAY_TYPE,
277	NORMAL_ARRAY_STRIDE,
278	NORMAL_ARRAY_POINTER,
279	COLOR_ARRAY_SIZE,
280	COLOR_ARRAY_TYPE,
281	COLOR_ARRAY_STRIDE,
282	COLOR_ARRAY_POINTER,
283	INDEX_ARRAY_TYPE,
284	INDEX_ARRAY_STRIDE,
285	INDEX_ARRAY_POINTER,
286	TEXTURE_COORD_ARRAY_SIZE,
287	TEXTURE_COORD_ARRAY_TYPE,
288	TEXTURE_COORD_ARRAY_STRIDE,
289	TEXTURE_COORD_ARRAY_POINTER,
290	EDGE_FLAG_ARRAY_STRIDE,
291	EDGE_FLAG_ARRAY_POINTER,
292	ARRAY_ELEMENT_LOCK_FIRST_EXT,
293	ARRAY_ELEMENT_LOCK_COUNT_EXT
294
295    composes a single vertex array object.
296
297Additions to the GLX Specification
298
299    Vertex array objects are shared between GLX rendering contexts if and only
300    if the rendering contexts share display lists.  No change is made to
301    the GLX API.
302
303GLX Protocol
304
305    XXX - Not figured out yet.
306
307Dependencies on OpenGL 1.1
308Dependencies on EXT_vertex_array
309
310    Requires either OpenGL 1.1 or EXT_vertex_array to be present.
311
312Dependencies on EXT_compiled_vertex_array
313
314    If EXT_compiled_vertex_array is not supported, section 2.8.2 should
315    be omited, and the ARRAY_ELEMENT_XXX constants in the Chapter 6 addition
316    should be omitted. 
317
318Errors
319
320    INVALID_VALUE is generated if GenVertexArraysSGIX parameter <n> is
321    negative.
322
323    INVALID_VALUE is generated if DeleteVertexArraysSGIX parameter <n> is
324    negative.
325
326    INVALID_VALUE is generated if PrioritizeVertexArraysSGIX parameter <n>
327    negative.
328
329    INVALID_VALUE is generated if AreVertexArraysResidentSGIX parameter <n> is
330    negative.
331
332    INVALID_VALUE is generated by AreVertexArraysResidentSGIX if any of the
333    names in <arrays> is not the name of a vertex array object or zero.
334
335    INVALID_OPERATION is generated if any of the commands defined in this
336    extension is executed between the execution of Begin and the corresponding
337    execution of End.
338
339New State
340
341  Append to table 6.6: Vertex Array Data:
342
343    Get Value				Get Command		Type			Initial Value		Attribute
344    ---------				-----------		----			-------------		---------
345    VERTEX_ARRAY_BINDING_SGIX		GetIntegerv		Z+			0			client
346    VERTEX_ARRAY_PRIORITY_SGIX		GetFloatv		R[0,1]			1			client
347
348New Implementation Dependent State
349
350    None
351