Polygon Lists

PVR API for managing list submission More...

Functions
void *	pvr_set_vertbuf (pvr_list_t list, void *buffer, int len)
	Setup a vertex buffer for one of the list types.
int	pvr_list_begin (pvr_list_t list)
	Begin collecting data for the given list type.
int	pvr_list_finish (void)
	End collecting data for the current list type.
int	pvr_prim (void *data, int size)
	Submit a primitive of the current list type.
int	pvr_list_prim (pvr_list_t list, void *data, int size)
	Submit a primitive of the given list type.
int	pvr_list_flush (pvr_list_t list)
	Flush the buffered data of the given list type to the TA.

Detailed Description

PVR API for managing list submission

Function Documentation

pvr_list_begin()

int pvr_list_begin

(

pvr_list_t

list

)

Begin collecting data for the given list type.

Lists do not have to be submitted in any particular order, but all types of a list must be submitted at once (unless vertex DMA mode is enabled).

Note that there is no need to call this function in DMA mode unless you want to make use of pvr_prim() for compatibility. This function will automatically call pvr_list_finish() if a list is already opened before opening the new list.

Parameters

list	The list to open.

Return values

0	On success.
-1	If the specified list has already been closed.

pvr_list_finish()

int pvr_list_finish

(

void

)

End collecting data for the current list type.

Lists can never be opened again within a single frame once they have been closed. Thus submitting a primitive that belongs in a closed list is considered an error. Closing a list that is already closed is also an error.

Note that if you open a list but do not submit any primitives, a blank one will be submitted to satisfy the hardware. If vertex DMA mode is enabled, then this simply sets the current list pointer to no list, and none of the above restrictions apply.

Return values

0	On success.
-1	On error.

pvr_list_flush()

int pvr_list_flush

(

pvr_list_t

list

)

Flush the buffered data of the given list type to the TA.

This function is currently not implemented, and calling it will result in an assertion failure. It is intended to be used later in a "hybrid" mode where both direct and DMA TA submission is possible.

Parameters

list	The list to flush.

Return values

-1	On error (it is not possible to succeed).

pvr_list_prim()

int pvr_list_prim	(	pvr_list_t	list,
		void *	data,
		int	size )

Submit a primitive of the given list type.

Data will be queued in a vertex buffer, thus one must be available for the list specified (will be asserted by the code).

Parameters

list	The list to submit to.
data	The primitive to submit.
size	The size of the primitive in bytes. This must be a multiple of 32.

Return values

0	On success.
-1	On error.

pvr_prim()

int pvr_prim	(	void *	data,
		int	size )

Submit a primitive of the current list type.

Note that any values submitted in this fashion will go directly to the hardware without any sort of buffering, and submitting a primitive of the wrong type will quite likely ruin your scene. Note that this also will not work if you haven't begun any list types (i.e., all data is queued). If DMA is enabled, the primitive will be appended to the end of the currently selected list's buffer.

Warning

data must be 32-byte aligned!

Parameters

data	The primitive to submit.
size	The length of the primitive, in bytes. Must be a multiple of 32.

Return values

0	On success.
-1	On error.

pvr_set_vertbuf()

void * pvr_set_vertbuf	(	pvr_list_t	list,
		void *	buffer,
		int	len )

Setup a vertex buffer for one of the list types.

If the specified list type already has a vertex buffer, it will be replaced by the new one.

Note

Each buffer should actually be twice as long as what you will need to hold two frames worth of data).

Warning

You should generally not try to do this at any time besides before a frame is begun, or Bad Things May Happen.

Parameters

list	The primitive list to set the buffer for.
buffer	The location of the buffer in main RAM. This must be aligned to a 32-byte boundary.
len	The length of the buffer. This must be a multiple of 64, and must be at least 128 (even if you're not using the list).

Returns

The old buffer location (if any)