Scene Submission

PowerVR API for submitting scene geometry More...

Topics
	Direct Rendering
	API for using direct rendering with the PVR
	Polygon Lists
	PVR API for managing list submission
	Vertex DMA
	Use the DMA to transfer inactive lists to the PVR

Functions
void	pvr_set_presort_mode (int presort)
	Set the translucent polygon sort mode for the next frame.
void	pvr_scene_begin (void)
	Begin collecting data for a frame of 3D output to the off-screen frame buffer.
void	pvr_scene_begin_txr (pvr_ptr_t txr, uint32_t *rx, uint32_t *ry)
	Begin collecting data for a frame of 3D output to the specified texture.
int	pvr_scene_finish (void)
	Call this after you have finished submitting all data for a frame.
int	pvr_wait_ready (void)
	Block the caller until the PVR system is ready for another frame to be submitted.
int	pvr_check_ready (void)
	Check if the PVR system is ready for another frame to be submitted.

Detailed Description

PowerVR API for submitting scene geometry

This API is used to submit triangle strips to the PVR via the TA interface in the chip.

An important side note about the PVR is that all primitive types must be submitted grouped together. If you have 10 polygons for each list type, then the PVR must receive them via the TA by list type, with a list delimiter in between.

So there are two modes you can use here. The first mode allows you to submit data directly to the TA. Your data will be forwarded to the chip for processing as it is fed to the PVR module. If your data is easily sorted into the primitive types, then this is the fastest mode for submitting data.

The second mode allows you to submit data via main-RAM vertex buffers, which will be queued until the proper primitive type is active. In this case, each piece of data is copied into the vertex buffer while the wrong list is activated, and when the proper list becomes activated, the data is all sent at once. Ideally this would be via DMA, right now it is by store queues. This has the advantage of allowing you to send data in any order and have the PVR functions resolve how it should get sent to the hardware, but it is slower.

The nice thing is that any combination of these modes can be used. You can assign a vertex buffer for any list, and it will be used to hold the incoming vertex data until the proper list has come up. Or if the proper list is already up, the data will be submitted directly. So if most of your polygons are opaque, and you only have a couple of translucents, you can set a small buffer to gather translucent data and then it will get sent when you do a pvr_end_scene().

Thanks to Mikael Kalms for the idea for this API.

Note

Another somewhat subtle point that bears mentioning is that in the normal case (interrupts enabled) an interrupt handler will automatically take care of starting a frame rendering (after scene_finish()) and also flipping pages when appropriate.

Function Documentation

pvr_check_ready()

int pvr_check_ready

(

void

)

Check if the PVR system is ready for another frame to be submitted.

Return values

0	If the PVR is ready for a new scene. You must call pvr_wait_ready() afterwards, before starting a new scene.
-1	If the PVR is not ready for a new scene yet.

pvr_scene_begin()

void pvr_scene_begin

(

void

)

Begin collecting data for a frame of 3D output to the off-screen frame buffer.

You must call this function (or pvr_scene_begin_txr()) for ever frame of output.

pvr_scene_begin_txr()

void pvr_scene_begin_txr	(	pvr_ptr_t	txr,
		uint32_t *	rx,
		uint32_t *	ry )

Begin collecting data for a frame of 3D output to the specified texture.

This function currently only supports outputting at the same size as the actual screen. Thus, make sure rx and ry are at least large enough for that. For a 640x480 output, rx will generally be 1024 on input and ry 512, as these are the smallest values that are powers of two and will hold the full screen sized output.

Parameters

txr	The texture to render to.
rx	Width of the texture buffer (in pixels).
ry	Height of the texture buffer (in pixels).

pvr_scene_finish()

int pvr_scene_finish

(

void

)

Call this after you have finished submitting all data for a frame.

Once this has been called, you can not submit any more data until one of the pvr_scene_begin() or pvr_scene_begin_txr() functions is called again.

Return values

0	On success.
-1	On error (no scene started).

pvr_set_presort_mode()

void pvr_set_presort_mode

(

int

presort

)

Set the translucent polygon sort mode for the next frame.

This function sets the translucent polygon sort mode for the next frame of output, potentially switching between autosort and presort mode.

For most programs, you'll probably want to set this at initialization time (with the autosort_disabled field in the pvr_init_params_t structure) and not mess with it per-frame. It is recommended that if you do use this function to change the mode that you should set it each frame to ensure that the mode is set properly.

Parameters

presort

Set to 1 to set the presort mode for translucent polygons, set to 0 to use autosort mode.

pvr_wait_ready()

int pvr_wait_ready

(

void

)

Block the caller until the PVR system is ready for another frame to be submitted.

The PVR system allocates enough space for two frames: one in data collection mode, and another in rendering mode. If a frame is currently rendering, and another frame has already been closed, then the caller cannot do anything else until the rendering frame completes. Note also that the new frame cannot be activated except during a vertical blanking period, so this essentially waits until a rendered frame is complete and a vertical blank happens.

Return values

0	On success. A new scene can be started now.
-1	On error. Something is probably very wrong...