| | '''OpenGL extension APPLE.vertex_array_range |
| | |
| | This module customises the behaviour of the |
| | OpenGL.raw.GL.APPLE.vertex_array_range to provide a more |
| | Python-friendly API |
| | |
| | Overview (from the spec) |
| | |
| | This extension is designed to allow very high vertex processing rates which |
| | are facilitated both by relieving the CPU of as much processing burden as |
| | possible and by allowing graphics hardware to directly access vertex data. |
| | Because this extension is implemented as an addition to the vertex array |
| | specification provided by OpenGL 1.1, applications can continue to use |
| | existing vertex submission logic while taking advantage of vertex array |
| | ranges to more efficiently process those arrays. |
| | |
| | The vertex array coherency model provided by OpenGL 1.1 requires that |
| | vertex data specified in vertex arrays be transferred from system memory |
| | each time Begin, DrawArrays, or DrawElements is called. Further, OpenGL |
| | 1.1 requires that the transfer of data be completed by the time End, |
| | DrawArrays, or DrawElements returns. Both of these requirements are |
| | relaxed by the vertex array range extension. Vertex data may be cached |
| | by the GL so there is no guarantee that changes to the vertex data will |
| | be reflected in following drawing commands unless it is flushed with |
| | FlushVertexArrayRangeAPPLE. The reading of vertex data may be deferred |
| | by the GL so there is no guarantee that the GL will be finished reading |
| | the data until completion is forced by the use of Finish or the APPLE_fence |
| | extension. |
| | |
| | Vertex array range can be enabled in two ways. EnableClientState can be |
| | used with the VERTEX_ARRAY_RANGE_APPLE param to enable vertex array range |
| | for the client context. One can also simply set the vertex array storage |
| | hint to either STORAGE_CACHED_APPLE or STORAGE_SHARED_APPLE (as discussed |
| | below) to enable a particular vertex array range. Once this is done, use of |
| | vertex array range requires the definition of a specific memory range for |
| | vertex data through VertexArrayRangeAPPLE. It is recommended this data be |
| | page aligned (4096 byte boundaries) and a multiple of page size in length |
| | for maximum efficiency in data handling and internal flushing, but this is |
| | not a requirement and any location and length of data can be defined as a |
| | vertex array. This extension provides no memory allocators as any |
| | convenient memory allocator can be used. |
| | |
| | Once a data set is established, using VertexArrayRangeAPPLE, it can be can |
| | be drawn using standard OpenGL vertex array commands, as one would do |
| | without this extension. Note, if any the data for any enabled array for a |
| | given array element index falls outside of the vertex array range, an |
| | undefined vertex is generated. One should also understand removing or |
| | replacing all calls to vertex array range functions with no-ops or disabling |
| | the vertex array range by disabling the VERTEX_ARRAY_RANGE_APPLE client |
| | state should not change the results of an application's OpenGL drawing. |
| | |
| | For static data no additional coherency nor synchronization must be done and |
| | the client is free to draw with the specified draw as it sees fit. |
| | |
| | If data is dynamic, thus to be modified, FlushVertexArrayRangeAPPLE should |
| | be used. The command is issued when data has been modified since the last |
| | call to VertexArrayRangeAPPLE or FlushVertexArrayRangeAPPLE and prior to |
| | drawing with such data. FlushVertexArrayRangeAPPLE only provides memory |
| | coherency prior to drawing (such as ensuring CPU caches are flushed or VRAM |
| | cached copies are updated) and does not provide any synchronization with |
| | previously issued drawing commands. The range flushed can be the specific |
| | range modified and does not have to be the entire vertex array range. |
| | Additionally, data maybe read immediately after a flush without need for |
| | further synchronization, thus overlapping areas of data maybe read, modified |
| | and written between two successive flushes and the data will be |
| | consistent. |
| | |
| | To synchronize data modification after drawing two methods can be used. A |
| | Finish command can be issued which will not return until all previously |
| | issued commands are complete, forcing completely synchronous operation. |
| | While this guarantees all drawing is complete it may not be the optimal |
| | solution for clients which just need to ensure drawing with the vertex array |
| | range or a specific range with the array is compete. The APPLE_fence |
| | extension can be used when dynamic data modifications need to be |
| | synchronized with drawing commands. Specifically, if data is to be modified, |
| | a fence can be set immediately after drawing with the data. Once it comes |
| | time to modify the data, the application must test (or finish) this fence to |
| | ensure the drawing command has completed. Failure to do this could result in |
| | new data being used by the previously issued drawing commands. It should be |
| | noted that providing the maximum time between the drawing set fence and the |
| | modification test/finish fence allows the most asynchronous behavior and |
| | will result in the least stalling waiting for drawing completion. Techniques |
| | such as double buffering vertex data can be used to help further prevent |
| | stalls based on fence completion but are beyond the scope of this extension. |
| | |
| | Once an application is finished with a specific vertex array range or at |
| | latest prior to exit, and prior to freeing the memory associated with this |
| | vertex array, the client should call VertexArrayRangeAPPLE with a data |
| | location and length of 0 to allow the internal memory managers to complete |
| | any commitments for the array range. In this case once |
| | VertexArrayRangeAPPLE returns it is safe to de-allocate the memory. |
| | |
| | Three types of storage hints are available for vertex array ranges; client, |
| | shared, and cached. These hints are set by passing the |
| | STORAGE_CLIENT_APPLE, STORAGE_SHARED_APPLE, or STORAGE_CACHED_APPLE param to |
| | VertexArrayParameteriAPPLE with VERTEX_ARRAY_STORAGE_HINT_APPLE pname. |
| | Client storage, the default OpenGL behavior, occurs when |
| | VERTEX_ARRAY_RANGE_APPLE is disabled AND the STORAGE_CLIENT_APPLE hint is |
| | set. Note, STORAGE_CLIENT_APPLE is also the default hint setting. Shared |
| | memory usage is normally used for dynamic data that is expected to be |
| | modified and is likely mapped to AGP memory space for access by both the |
| | graphics hardware and client. It is set when either |
| | VERTEX_ARRAY_RANGE_APPLE is enabled, without the STORAGE_CACHED_APPLE hint |
| | being set, or in all cases when the STORAGE_SHARED_APPLE hint is set. |
| | Finally, the cached storage is designed to support static data and data which |
| | could be cached in VRAM. This provides maximum access bandwidth for the |
| | vertex array and occurs when the STORAGE_CACHED_APPLE hint is set. |
| | |
| | The following pseudo-code represents the treatment of a vertex array range |
| | memory depending on the hint setting and whether vertex array range is |
| | enabled for the client context: |
| | |
| | if (VERTEX_ARRAY_STORAGE_HINT_APPLE == STORAGE_CACHED_APPLE) |
| | vertex array is treated as cached |
| | else if (VERTEX_ARRAY_STORAGE_HINT_APPLE == STORAGE_SHARED_APPLE) |
| | vertex array is treated as shared |
| | else if (VERTEX_ARRAY_RANGE_APPLE enabled) |
| | vertex array is treated as shared |
| | else |
| | vertex array is treated as client |
| | |
| | Note, these hints can affect how array flushes are handled and the overhead |
| | associated with flushing the array, it is recommended that data be handled |
| | as shared unless it really is static and there are no plans to modify it. |
| | |
| | To summarize the vertex array range extension provides relaxed |
| | synchronization rules for handling vertex array data allowing high bandwidth |
| | asynchronous data transfer from client memory to graphics hardware. |
| | Different flushing and synchronization rules are required to ensure data |
| | coherency when modifying data. Lastly, memory handling hints are provided |
| | to allow the tunning of memory storage and access for maximum efficiency. |
| | |
| | The official definition of this extension is available here: |
| | http://www.opengl.org/registry/specs/APPLE/vertex_array_range.txt |
| | ''' |
| | from OpenGL import platform, constant, arrays |
| | from OpenGL import extensions, wrapper |
| | import ctypes |
| | from OpenGL.raw.GL import _types, _glgets |
| | from OpenGL.raw.GL.APPLE.vertex_array_range import * |
| | from OpenGL.raw.GL.APPLE.vertex_array_range import _EXTENSION_NAME |
| |
|
| | def glInitVertexArrayRangeAPPLE(): |
| | '''Return boolean indicating whether this extension is available''' |
| | from OpenGL import extensions |
| | return extensions.hasGLExtension( _EXTENSION_NAME ) |
| |
|
| | glVertexArrayRangeAPPLE=wrapper.wrapper(glVertexArrayRangeAPPLE).setOutput( |
| | 'pointer',size=lambda x:(x,),pnameArg='length',orPassIn=True |
| | ) |
| | glFlushVertexArrayRangeAPPLE=wrapper.wrapper(glFlushVertexArrayRangeAPPLE).setOutput( |
| | 'pointer',size=lambda x:(x,),pnameArg='length',orPassIn=True |
| | ) |
| | |
