Vertex arrays

Relinquish has a simple way of creating intelived vertex arrays containing attribute data for the array. When a array is allocated the application defines the format of the array and once acctivated the array all vertex pointers are set up correctly behind the scene. Binding and unbinding vertex array data is expencive and often applications want to draw many objects using the same vertex formats. Relinquish therfor lets you allocate a "pool" of vertex data and then sub allocate "sections" of that pool. By drawing different sections from the same pool the rendering engine does not have to rebind vertex objects or reset vertex pointers making it substantialy faster. Sections can also be returned to the pool so thet the memory can be reused. Thgis will cause the memory pool to be come fragmented, and in order to solve that the and in order to solve that the user can call r_array_defrag to defragment the pool. If the application wants to use array without the need to first allocate a pool and then a segment, they can set any segment to NULL to use the entire pool as a single segment.

r_array_vertex_size

uint r_array_vertex_size(SUIFormats *vertex_format_types, uint *vertex_format_size, uint vertex_format_count);

Description: Computes in bytes the size of a specific vertex format.

Types:

Enum:

SUIFormats

SUI_INT8

SUI_UINT8

SUI_INT16

SUI_UINT16

SUI_INT32

SUI_UINT32

SUI_FLOAT

SUI_DOUBLE

r_array_allocate

void *r_array_allocate(uint vertex_count, SUIFormats *vertex_format_types, uint *vertex_format_size, uint vertex_format_count);

Description: Allocates a pool of vertex data containing vertex_count number of vertiuces. vertex_format_count describes the number of attributes the vertexcx format, vertex_format_types describes the types of each attribute, and vertex_format_size describes how many components each attribute has (1-4). The function returns a opaque void pointer to the pool.

Types:

Enum:

SUIFormats

SUI_INT8

SUI_UINT8

SUI_INT16

SUI_UINT16

SUI_INT32

SUI_UINT32

SUI_FLOAT

SUI_DOUBLE

r_array_free

void r_array_free(void *pool);

Description: Frees a pool from memory. All sections of this pool is also automaticaly freed.

r_array_defrag

boolean r_array_defrag(void *pool);

Description: Activates the defragmentation funtion of the Reliquish array system. The cuntion will only move a single section per call. The function returns TRUE if the buffer is entierly defragmented. To compleatly defrag a pool a loop is needed. Example: while(!r_array_defrag(pool));

r_array_section_allocate

void *r_array_section_allocate(void *pool, uint size);

Description: Allocates a section containing "size" number of vertices.

r_array_section_free

void r_array_section_free(void *pool, void *section);

Description: Returns a secton of a pool.

r_array_deactivate

void r_array_deactivate();

Description: Deactivates any bound vertex arrays. _Usefull if you want to mix Relinquish based code with vanilla OpenGL or anothert rendering library.

r_array_section_draw

void r_array_section_draw(void *pool, void *section, uint primitive_type, uint vertex_start, uint vertex_count);

Description: Draws vertex_count number of primitives from the pool/section beginning with vertex_start. vertex_start and vertex_count are bound checked, so a application can set vertex_start to 0 and vertex_count to -1 inorder to draw the entire pool/section.

r_array_reference_draw

void r_array_reference_draw(void *pool, void *section, uint primitive_type, uint vertex_start, uint vertex_count);

Description: Draws the array using a section as storage place for reference data. This function is only vertex_start and vertex_count are bound checked, so a application can set vertex_start to 0 and vertex_count to -1 inorder to draw the entire pool/section.

r_array_load_vertex

void r_array_load_vertex(void *pool, void *section, void *data, uint start, uint length);

Description: Loads vertex data from a pointer in to a a pool or section. "start" specifyes now many vertices oin to the pool/section the data sghould be set, and length specifies the number of vertices to be uploaded. Relinquish will automaticaly bounds check, if the application tries to upload more vertex data then there is space for. The vertex data needs to be stored in the same way as it is specified in the vertex array. Each new attrtibute data needs to start on an even 32 bits, so some padding may be needed.

r_array_load_reference

void r_array_load_reference(void *pool, void *section, uint *data, uint length);

Description: Loads 32 bit unsigned ints in to a section, in order to store reference data. Note that sectons are still allocated in sizes of vertices, so applications needs to know the size of a vertex in order to allocate the right section size. Given that vertex positions chjange when r_array_defrag is called, it is inadvicable to use referenced arrays with dynamicly allocated and freed sections.

r_array_get_size

uint r_array_get_size(void *pool);

Description: Returns the size of the array counted in vertices.

r_array_get_used

uint r_array_get_used(void *pool);

Description: Returns the number of vertices in the array used by sections.

r_array_get_left

uint r_array_get_left(void *pool);

Description: Returns the number of vertices in the array not used by sections.

r_array_get_vertex_size

uint r_array_get_vertex_size(void *pool);

Description: Returns the size in bytes of a vertex in the array.

r_array_section_get_vertex_count

uint r_array_section_get_vertex_count(void *section);

Description: Returns the number of vertices in a section.

r_array_section_get_vertex_start

uint r_array_section_get_vertex_start(void *section);

Description: Returns the reference number of the first vertex in a section. This value is only valid untill r_array_defrag is called.