defining custom renderers, primitive types, and state

Collaboration diagram for defining custom renderers, primitive types, and state:

Functions
void	pglRegisterCustomPrimType (GLenum primType, pglU64_t requirements, pglU64_t rendererReqMask, int mergeContiguous)
void	pglEnableCustom (pglU64_t flag)
void	pglDisableCustom (pglU64_t flag)
void	pglUserRenderContextChanged ()
void	pglBeginRendererDefs ()
void	pglRegisterRenderer (void *renderer)
void	pglEndRendererDefs ()
const char *	pglGetCurRendererName ()

Detailed Description

API to define custom primitive types, state chagnes, renderers, or override the default renderers.

The ps2gl code that runs on the ee core is just a large, ugly state machine – all of the "real" work is done in the renderers. There are currently a dozen or so internal renderers which handle different types of geometry, lighting, texturing, etc. Most of the internal renderers implement some case that none of the others can do, but a few are specializations of more general renderers that implement a commonly encountered case more efficiently that the general renderer can. Using the functions described below, an application can define custom renderers or override existing ones.

But first, an explanation of how ps2gl chooses renderers is necessary. ps2gl keeps a bitfield of capabilities that a renderer must provide to be chosen to render. This bitfield is called the "renderer requirements" and describes things like lighting, texturing, prim type, shading type, etc. Each renderer also keeps a corresponding bitfield describing the capabilities that it provides, called its "capabilities." Each bit means that the corresponding capability is required (or provided, in the case of a renderer). Consider the "lighting" bit. This bit is set when glEnable( GL_LIGHTING ) is called and changes the renderer requirements, causing ps2gl to look for a new renderer the next time geometry is rendered. Each renderer's capabilities will be compared to the current renderer requirements, and the first renderer that meets all the requirements is chosen. In this example, only a renderer that can do lit geometry will be selected.

Renderers are searched in the order they were registered, application-defined renderers first. This means that specialized renderers should be registered before general ones. It also means that to override a default renderer, an application need only register a renderer that provides the same capabilites (or a subset).

Implementing a custom renderer whose purpose is not to override a built-in renderer implies defining custom prim types and/or properties, for which the upper 32 bits of the renderer capabilities/requirements are reserved. See the function documentation below for more details.

For more information on implementing a renderer, see the file "renderer.h" which defines the CRenderer interface. (Sorry, but the renderer needs to be a cpp class.) The best examples are the default renderers, so take a look at linear_renderer.* and base_renderer.*.

Function Documentation

pglRegisterCustomPrimType()

void pglRegisterCustomPrimType	(	GLenum	primType,
		pglU64_t	requirements,
		pglU64_t	rendererReqMask,
		int	mergeContiguous
	)

#include <src/gmanager.cpp>

Register a new primitive. After registering a primitive with this call it can be used anywhere a normal primitive can be used (glBegin, glDrawArrays, etc.). Defining a new primitive usually implies writing a renderer to go along with it.

Parameters

primType	bit 31 must be set (this indicates a user prim to ps2gl). The lower 31 bits should be a number from 0 to PGL_MAX_CUSTOM_PRIM_TYPES.
requirements	gives the bit flags to be set in the renderer requirements bitfield (see the documentation for custom renderers). Usually this will be one bit indicating the prim type used to select a renderer.
rendererReqMask	a mask to be applied to the renderer requirements bitfield before testing against renderer capabilities. This could be used, for example, to mask off the default lower 32 bits if they are irrelevent to this custom primitive type.
mergeContiguous	rather calling a renderer with every block of geometry that is specified (with glBegin/End, DrawArrays, etc.), ps2gl tries to combine multiple blocks into a single call to the renderer. This flag tells ps2gl whether it can treat blocks of geometry that were specified independently but are contiguous in memory as a single block. (State changes will of course force them to be treated separately.) This is done, for example, with points, lines, triangles, and quads, but not with strips, since merging would lose the strip boundaries.

Definition at line 477 of file gmanager.cpp.

pglEnableCustom()

void pglEnableCustom

(

pglU64_t

flag

)

#include <src/gmanager.cpp>

Enable a custom attribute/state change. Call this to enable the corresponding bit(s) in the renderer requirements bitfield (see above). The lower 32 bits should be zero.

Parameters

flag	the bit(s) to enable (lower 32 should be zero)

Definition at line 490 of file gmanager.cpp.

pglDisableCustom()

void pglDisableCustom

(

pglU64_t

flag

)

#include <src/gmanager.cpp>

Disable a custom attribute/state change. Call this to disable the corresponding bit(s) in the renderer requirements bitfield. The lower 32 bits should be zero.

Parameters

flag	the bit(s) to disable (lower 32 should be zero). This is the same constant passed to pglEnableCustom.

Definition at line 502 of file gmanager.cpp.

pglUserRenderContextChanged()

void pglUserRenderContextChanged

(

)

#include <src/gmanager.cpp>

Definition at line 508 of file gmanager.cpp.

pglBeginRendererDefs()

void pglBeginRendererDefs

(

)

#include <src/renderermanager.cpp>

Call this before registering any renderers.

Definition at line 692 of file renderermanager.cpp.

pglRegisterRenderer()

void pglRegisterRenderer

(

void *

renderer

)

#include <src/renderermanager.cpp>

Register a custom renderer. The maximum number of custom renderers is indicated by PGL_MAX_CUSTOM_RENDERERS.

Parameters

renderer

should point to a CRenderer object (passed as a void* for compatibility with C code)

Definition at line 704 of file renderermanager.cpp.

pglEndRendererDefs()

void pglEndRendererDefs

(

)

#include <src/renderermanager.cpp>

Call this after registering custom renderers.

Definition at line 713 of file renderermanager.cpp.

pglGetCurRendererName()

const char * pglGetCurRendererName

(

)

#include <src/renderermanager.cpp>

Returns the name (string) of the current renderer. You'll need to call glFlush() to be sure that the renderer is in in sync. Probably doesn't make much sense to call this inside of a glBegin/glEnd pair.

Returns

pointer to the renderer's name

Definition at line 725 of file renderermanager.cpp.

References CRenderer::GetName().