Display list system.
[C API]

Detailed Description

display list system

A display list is a list that contains commands to be executed every frame. Commands in a list are execurted sequentially in the order of insertion. Internally each display list contains a heap which may change when the list enlarges that why display list commands MUST NOT use pointers to something inside the command data (in the heap). Display lists are thread safe.

The display list execution occurs in two passes :

Opaque rendering pass.
Transparent rendering pass.

There is two types of display list :

Main display list (main-list).
Sub display list (sub-list).

The display list system will only executes main-lists. As the order display list execution order is indetermined, the graphic context should be set at the beginning of each main-list. Anyway it is resetted to default values before each main-list execution.

Sub-lists could be executed via the sub-list command from either a main-list or another sub-list.

Author:: vincent penne
benjamin gerard

Files

file display_list.h

thread safe display list support for dcplaya

Data Structures

struct dl_context_t

Display list render context. More...

struct dl_runcontext_t

Display list run context. More...

struct dl_command_t

Display list command header structure. More...

struct dl_list

Display list structure. More...

struct dl_heap_transfert_t

Heap transfert struct. More...

Display list flags.

#define DL_INHERIT_PARENT   0

effective = parent

#define DL_INHERIT_LOCAL   1

effective = local

#define DL_INHERIT_ADD   2

effective = parent+local

#define DL_INHERIT_MUL   3

effective = parent*local

Display list system initialization.

int dl_init (void)

Initialize the display list system.

int dl_shutdown (void)

Shutdown the display list system.

Display list management.

dl_list_t * dl_create (int heapsize, int active, int sub, const char *name)

Create a new display list.

void dl_destroy (dl_list_t *dl)

Destroy the given display list (Does not ckeck the reference count.

void dl_reference (dl_list_t *dl)

Reference a display list.

int dl_dereference (dl_list_t *dl)

Dereference a display list and destroy it if there is no more reference on it.

Display list control.

int dl_get_active (dl_list_t *dl)

Query active state of given display list.

int dl_set_active (dl_list_t *dl, int active)

Change active state of a display list.

int dl_set_active2 (dl_list_t *l1, dl_list_t *l2, int active)

Change active state of two display list.

Display list command functions.

Set of function of creating and removing display list commands.
How to add a command to a display list :

Allocate requested number of byte for the command in the display list heap with the dl_alloc() function. After this function the display list will be locked.
Fill command data in the returned memory area.
Insert the command to the display list with the dl_insert() function. This will unlock the display list.

void * dl_alloc (dl_list_t *dl, size_t size)

Allocate requested number of byte in the display list heap and keep display list locked until dl_insert() function call.

dl_comid_t dl_insert (dl_list_t *dl, void *pcom, dl_command_func_t o_render, dl_command_func_t t_render)

Insert the given command into the display list.

void dl_clear (dl_list_t *dl)

Clear the display list (i.e.

dl_comid_t dl_nop_command (dl_list_t *dl)

Insert an NO-OPERATION command to display list.

dl_comid_t dl_sublist_command (dl_list_t *dl, dl_list_t *sublist, const dl_runcontext_t *rc)

Insert an SUB-LIST command to display list.

Display list rendering functions.

These functions must be call by the rendering thread to perform display list rendering process in a given mode.

void dl_render_opaque (void)

Render all active display list in opaque mode.

void dl_render_transparent (void)

Render all active display list in transparent mode.

Display list context access.

void dl_set_trans (dl_list_t *dl, const matrix_t mat)

Set display list global transformation.

float * dl_get_trans (dl_list_t *dl)

Get display list global transformation.

void dl_set_color (dl_list_t *dl, const dl_color_t *col)

Set display list global color.

dl_color_t * dl_get_color (dl_list_t *dl)

Get display list global color.

Defines

#define DL_COMID_ERROR   -1

Constant for errorneous dl_comid_t.

Typedefs

typedef draw_color_t dl_color_t

Display list color type.

typedef draw_clipbox_t dl_clipbox_t

Display list clipping box type.

typedef dl_code_e(* dl_command_func_t )(void *, dl_context_t *)

Function type to render in opaque list or transparent list ; its argument is the pointer on the command that contained it.

typedef int dl_comid_t

Display list command identifier.

typedef dl_list dl_list_t

Display list structure.

Enumerations

enum dl_code_e { DL_COMMAND_OK = 0, DL_COMMAND_BREAK = 1, DL_COMMAND_SKIP = 2, DL_COMMAND_ERROR = -1 }

Display list command error codes enumeration. More...

Functions

typedef LIST_HEAD (dl_lists, dl_list) dl_lists_t

Enumeration Type Documentation

enum dl_code_e

Display list command error codes enumeration.

Enumeration values:

DL_COMMAND_OK Command success.

DL_COMMAND_BREAK Command asks to break display list execution.

DL_COMMAND_SKIP Command asks to skip next display list command.

DL_COMMAND_ERROR Command failed.

Function Documentation

dl_list_t* dl_create ( int heapsize,

int active,

int sub,

const char * name

)

Create a new display list.

Parameters:

heapsize Size of the command heap (0 to get a default size of 1Kb)

active Initial active state

sub 0:main-list, <>0:sub-list

name name of display list (debug purpose !)

Returns:
pointer to the created display list.

Return values:

0 error.

void dl_destroy ( dl_list_t * dl )

Destroy the given display list (Does not ckeck the reference count.

See also:
dl_dereference().

void dl_reference ( dl_list_t * dl )

Reference a display list.

See also:
dl_dereference().

int dl_dereference ( dl_list_t * dl )

Dereference a display list and destroy it if there is no more reference on it.

Returns:
Number of remaining reference.

See also:
dl_reference().
dl_destroy_list().

int dl_get_active ( dl_list_t * dl )

Query active state of given display list.

Parameters:

dl Display list

Returns:
Display list active state.

Return values:

0 Display list is inactive.

1 Display list is active.

int dl_set_active ( dl_list_t * dl,

int active

)

Change active state of a display list.

Parameters:

dl Display list

active new active state

Returns:
Display list preivious active state.

Return values:

0 Display list was inactive.

1 Display list was active.

int dl_set_active2 ( dl_list_t * l1,

dl_list_t * l2,

int active

)

Change active state of two display list.
The dl_set_active2() is an atomic function for changing the active state of two diaply list. It is very useful to perform a double-buffering emulation.

Parameters:

l1 First display list.

l2 Second display list.

active Bit 0 is first list new active state. Bit 1 is second list new active state.

Returns:
Display lists preivious active state. Bit 0 is first list previous active state. Bit 1 is second list previous active state.

void* dl_alloc ( dl_list_t * dl,

size_t size

)

Allocate requested number of byte in the display list heap and keep display list locked until dl_insert() function call.

Parameters:

dl Display list

size Requested number of by to allocate.

Returns:
Pointer into the display list memory heap allocated buffer.

Return values:

0 Failure.

Warning:
The display list is locked by the thread when the function returns successfully. You MUST to call dl_insert() function to unlock it.

dl_comid_t dl_insert ( dl_list_t * dl,

void * pcom,

dl_command_func_t o_render,

dl_command_func_t t_render

)

Insert the given command into the display list.

Parameters:

dl Display list locked by dl_alloc() function.

pcom Display list command allocated by dl_alloc() function.

o_render Opaque render callback.

t_render Transparent render callback.

Returns:
Command identifier

Return values:

DL_COMMID_ERROR failure

void dl_clear ( dl_list_t * dl )

Clear the display list (i.e.
reset the command list)
Parameters:

dl Display list locked by dl_alloc() function.

dl_comid_t dl_nop_command ( dl_list_t * dl )

Insert an NO-OPERATION command to display list.

Parameters:

dl Display list

Returns:
Command identifier

Return values:

DL_COMMID_ERROR failure

dl_comid_t dl_sublist_command ( dl_list_t * dl,

dl_list_t * sublist,

const dl_runcontext_t * rc

)

Insert an SUB-LIST command to display list.

Parameters:

dl Display list

sublist Sub display list to run (must be a sublist).

rc run context

Returns:
Command identifier

Return values:

DL_COMMID_ERROR failure

See also:
dl_create()

void dl_set_trans ( dl_list_t * dl,

const matrix_t mat

)

Set display list global transformation.

Parameters:

dl Display list

mat New matrix

float* dl_get_trans ( dl_list_t * dl )

Get display list global transformation.

Parameters:

dl Display list

void dl_set_color ( dl_list_t * dl,

const dl_color_t * col

)

Set display list global color.

Parameters:

dl Display list

col New color

dl_color_t* dl_get_color ( dl_list_t * dl )

Get display list global color.

Parameters:

dl Display list

dcplaya documentation version 1.2

Generated on January 2004 by doxygen 1.3.5


Files
file	display_list.h
	thread safe display list support for dcplaya
Data Structures
struct	dl_context_t
	Display list render context. More...
struct	dl_runcontext_t
	Display list run context. More...
struct	dl_command_t
	Display list command header structure. More...
struct	dl_list
	Display list structure. More...
struct	dl_heap_transfert_t
	Heap transfert struct. More...
Display list flags.
#define	DL_INHERIT_PARENT 0
	effective = parent
#define	DL_INHERIT_LOCAL 1
	effective = local
#define	DL_INHERIT_ADD 2
	effective = parent+local
#define	DL_INHERIT_MUL 3
	effective = parent*local
Display list system initialization.
int	dl_init (void)
	Initialize the display list system.
int	dl_shutdown (void)
	Shutdown the display list system.
Display list management.
dl_list_t *	dl_create (int heapsize, int active, int sub, const char *name)
	Create a new display list.
void	dl_destroy (dl_list_t *dl)
	Destroy the given display list (Does not ckeck the reference count.
void	dl_reference (dl_list_t *dl)
	Reference a display list.
int	dl_dereference (dl_list_t *dl)
	Dereference a display list and destroy it if there is no more reference on it.
Display list control.
int	dl_get_active (dl_list_t *dl)
	Query active state of given display list.
int	dl_set_active (dl_list_t *dl, int active)
	Change active state of a display list.
int	dl_set_active2 (dl_list_t l1, dl_list_t l2, int active)
	Change active state of two display list.
Display list command functions.
Set of function of creating and removing display list commands. How to add a command to a display list : Allocate requested number of byte for the command in the display list heap with the dl_alloc() function. After this function the display list will be locked. Fill command data in the returned memory area. Insert the command to the display list with the dl_insert() function. This will unlock the display list.
void *	dl_alloc (dl_list_t *dl, size_t size)
	Allocate requested number of byte in the display list heap and keep display list locked until dl_insert() function call.
dl_comid_t	dl_insert (dl_list_t dl, void pcom, dl_command_func_t o_render, dl_command_func_t t_render)
	Insert the given command into the display list.
void	dl_clear (dl_list_t *dl)
	Clear the display list (i.e.
dl_comid_t	dl_nop_command (dl_list_t *dl)
	Insert an NO-OPERATION command to display list.
dl_comid_t	dl_sublist_command (dl_list_t dl, dl_list_t sublist, const dl_runcontext_t *rc)
	Insert an SUB-LIST command to display list.
Display list rendering functions.
These functions must be call by the rendering thread to perform display list rendering process in a given mode.
void	dl_render_opaque (void)
	Render all active display list in opaque mode.
void	dl_render_transparent (void)
	Render all active display list in transparent mode.
Display list context access.
void	dl_set_trans (dl_list_t *dl, const matrix_t mat)
	Set display list global transformation.
float *	dl_get_trans (dl_list_t *dl)
	Get display list global transformation.
void	dl_set_color (dl_list_t dl, const dl_color_t col)
	Set display list global color.
dl_color_t *	dl_get_color (dl_list_t *dl)
	Get display list global color.
Defines
#define	DL_COMID_ERROR -1
	Constant for errorneous dl_comid_t.
Typedefs
typedef draw_color_t	dl_color_t
	Display list color type.
typedef draw_clipbox_t	dl_clipbox_t
	Display list clipping box type.
typedef dl_code_e(*	dl_command_func_t )(void , dl_context_t )
	Function type to render in opaque list or transparent list ; its argument is the pointer on the command that contained it.
typedef int	dl_comid_t
	Display list command identifier.
typedef dl_list	dl_list_t
	Display list structure.
Enumerations
enum	dl_code_e { DL_COMMAND_OK = 0, DL_COMMAND_BREAK = 1, DL_COMMAND_SKIP = 2, DL_COMMAND_ERROR = -1 }
	Display list command error codes enumeration. More...
Functions
typedef	LIST_HEAD (dl_lists, dl_list) dl_lists_t

Display list system. [C API]

Detailed Description

Files

Data Structures

Display list flags.

Display list system initialization.

Display list management.

Display list control.

Display list command functions.

Display list rendering functions.

Display list context access.

Defines

Typedefs

Enumerations

Functions

Enumeration Type Documentation

Function Documentation

Display list system.
[C API]