x3drender::RenderState Class Reference

Create a render state and then render it. More...

#include <render.h>

Inheritance diagram for x3drender::RenderState:

[legend]Collaboration diagram for x3drender::RenderState:

[legend]List of all members.


Public Member Functions
void	ApplyTransform (const x3d::SFNode *node, fast_math::Matrix4x4 &matrix)
	Apply the transformation defined in a node to a matrix.
bool	Execute (RenderShape::execute_function_t func)
	Execute a function on all the render shapes of this state.
const x3d::SFString &	GetViewpointDescription () const
	Get the current viewpoint description if any.
const fast_math::Matrix4x4 &	GetViewpointInversePerspectiveMatrix ()
	Get the current viewpoint inverse perspective matrix.
const fast_math::Matrix4x4 &	GetViewpointPerspectiveMatrix ()
	Get the current viewpoint perspective matrix.
const fast_math::Matrix4x4 &	GetViewpointPositionMatrix ()
	Get the current viewpoint position matrix.
bool	Initialize (x3d::SFNodePtr root)
	Initialize the render state with a tree of nodes.
	RenderState (RenderProcessor *render_processor)
	Initialize a render state.
void	SetScreenSizes (unsigned int width, unsigned int height)
	Defines the width and height of the output screen.
void	SetViewpointName (const char *name)
	Set the name of the viewpoint to start with.
bool	Update ()
	Update all the render shape which needs to be updated.
virtual	~RenderState ()
	Get rid of all the resources used by the RenderState object.
Private Member Functions
void	SetCurrentViewpoint (x3d::Viewpoint *viewpoint)
	Change the current viewpoint properly.
bool	SetupShape (x3d::SFNodePtr node, x3d::MFNode parents, fast_math::Matrix4x4 &matrix)
	Finalize the RenderShape setup.
bool	WalkTree (x3d::SFNodePtr node, x3d::MFNode parents, fast_math::Matrix4x4 &matrix)
	This function walks a tree of node to find shapes.
Private Attributes
x3d::ViewpointPtr	f_current_viewpoint
unsigned int	f_height
RenderProcessorPtr	f_render_processor
RenderShapeVector	f_render_shapes
x3d::SFNodePtr	f_root
x3d::SFString	f_start_viewpoint_name
fast_math::Matrix4x4	f_viewpoint_inverse_perspective_matrix
bool	f_viewpoint_inverse_perspective_matrix_defined
fast_math::Matrix4x4	f_viewpoint_perspective_matrix
bool	f_viewpoint_perspective_matrix_defined
fast_math::Matrix4x4	f_viewpoint_position_matrix
bool	f_viewpoint_position_matrix_defined
x3d::MFNode	f_viewpoint_stack
fast_math::Matrix4x4	f_viewpoint_transform
unsigned int	f_width

Detailed Description

Create a render state and then render it.

Constructor & Destructor Documentation

x3drender::RenderState::RenderState ( RenderProcessor * render_processor )

Initialize a render state.

Parameters:

[in] render_processor The render processor used to draw the shapes. This parameter is mandatory.

This function will initialize a render state object with a corresponding render processor.
The render processor will know how to create the render shapes (it may have some extra fields in its render shapes than in the system render shapes.)
The processor is also capable of rendering the shapes on screen or in a buffer.

See also:
RenderState::~RenderState

x3drender::RenderState::~RenderState ( ) [virtual]

Get rid of all the resources used by the RenderState object.
Note that the need for this function is mostly in case we get some virtual functions.

See also:
RenderState::RenderState

Member Function Documentation

void x3drender::RenderState::ApplyTransform ( const x3d::SFNode * node,

fast_math::Matrix4x4 & matrix

)

Apply the transformation defined in a node to a matrix.
This function will determine the type of a node and if it is some sort of transformation node (not just a Transform node) then the transformation will be applied to the input matrix.
This is used whenever the tree of nodes is traversed to setup all the RenderShape and later whenever an individual shape's transformation changes.

See also:
Initialization

bool x3drender::RenderState::Execute ( RenderShape::execute_function_t func )

Execute a function on all the render shapes of this state.

Parameters:

[in] func The offset of the function to call in the render shape

This function is used by render processors to execute some function (such as Render()!) on all the shapes defined in their render state.
The function being called may return false in which case the loop breaks and the Execute() function returns false. This can be used to search for a specific node, for instance.
By default, your functions should always return true (success).

Returns:
true whenever all the render shapes functions have been executed

const x3d::SFString & x3drender::RenderState::GetViewpointDescription ( ) const

Get the current viewpoint description if any.
This function returns the current viewpoint description. The content of the string will change with each viewpoint.

Returns:
An SFString with the viewpoint description.

const fast_math::Matrix4x4 & x3drender::RenderState::GetViewpointInversePerspectiveMatrix ( )

Get the current viewpoint inverse perspective matrix.
The viewpoint defines a perspective matrix with a direction, an orientation and a field of view. The field of view is used to create the projection matrix for OpenGL. Also, the inverse can be used to compute the screen pixel position of your objects. This function returns that matrix.
Note that the direction and orientation are computed in the viewpoint position matrix and you will also need it to compute the screen position of your objects.

Returns:
A matrix with the inverse of the viewpoint perspective matrix

See also:
GetViewpointPerspectiveMatrix()
GetViewpointPositionMatrix()

const fast_math::Matrix4x4 & x3drender::RenderState::GetViewpointPerspectiveMatrix ( )

Get the current viewpoint perspective matrix.
This function can be used to request the viewpoint perspective matrix. It will be computed only once, unless the viewpoint changes and forces the function to recompute a new frustum.
We compute the viewpoint perspective matrix ourselves (instead of using the gluPerspective() function which would do it for us) because we need it in order to sort the shapes in Z order from back to front. That is, we need the inverse matrix, but it is easier to compute the projection first and then compute its inverse.
Note since we already have this matrix available in all cases, you can get it to setup the projection matrix in OpenGL.
The matrix is defined as follow:
| f/aspect 0 0 0 | | 0 f 0 0 | | 0 0 p q | | 0 0 -1 0 |
with p = (zfar + znear) / (znear - zfar) q = 2 * zfar * znear / (znear - zfar) and f = 1 / tan(fovy / 2)
The fovy is the vertical field of view (when the Y coordinates go from the bottom of the screen to the top). far and near are computed internally. The aspect ratio is defined as:
screen width / screen height
For the aspect ratio to be computed properly, you need to setup the screen width and height with SetScreenSizes().

Note:
The viewpoint can also be positioned. This is applied to the viewpoint position matrix instead. See the GetViewpointPositionMatrix() to get that matrix. The objects in our view will have their matrix multiplied by this viewpoint position matrix so they are placed properly.
The aspect is computed as width / height. But X3D gives us a field of view which is determined using the smallest of width or height. Thus in the code, there are two cases to defined entry 0,0 and 1,1 of the matrix depending of the width and height of the output screen.

Returns:
A matrix with the viewpoint perspective matrix

See also:
GetViewpointPositionMatrix()
GetViewpointInverseMatrix()

const fast_math::Matrix4x4 & x3drender::RenderState::GetViewpointPositionMatrix ( )

Get the current viewpoint position matrix.
This function can be used to request the viewpoint position matrix. It will be computed only once, unless the viewpoint changes and forces the function to recompute a new position.
We compute the viewpoint position matrix ourselves (instead of using the glRotatef() and glTranslatef() functions which would do it for us) because we need it in order to sort the shapes in Z order from back to front. This matrix will be multiplied by each object matrix to know exactly where such and such object is in the current world.
Note since we already have this matrix available in all cases, you can get it to setup the model view matrix in OpenGL.
The matrix is defined as the product of:

The transformation matrix of the viewpoint

The orientation of the viewpoint (angle negated)

The translation of the viewpoint (negated)

The orientation angle and the translations are negated since it is the eye which is moving. This means everything else is seemingly moving in the opposite direction.

Returns:
A matrix with the viewpoint position matrix

See also:
GetViewpointPerspectiveMatrix()
GetViewpointInverseMatrix()

bool x3drender::RenderState::Initialize ( x3d::SFNodePtr root )

Initialize the render state with a tree of nodes.

Parameters:

[in] root The root of the tree to render.

Before you can render anything, you need to create a state. This is done with the Initialize() function call. This call will walk the tree and setup render shapes to be drawn by a render processor.
The root node can be of nearly any type (i.e. X3D, Scene, or even directly a Shape.) You cannot specify a node which is a child of a Shape (Appearance, Geometry node, etc.).

Warning:
You must call SetViewpointName() BEFORE calling Initialize() if you want the correct viewpoint to be selected on startup. This is usually the name defined as the anchor in a URL (i.e. url::ViewpointName).
You must call SetScreenSizes() BEFORE calling Initialize() if you want the objects to be properly ordered.

Note:
This function does not cull any shape. Instead it puts all the shapes accessible at the time of the call in a flat list which can later be used to render the shapes back to front.

Returns:
true when the initialization succeeds

See also:
WalkTree
SetupShape

void x3drender::RenderState::SetCurrentViewpoint ( x3d::Viewpoint * viewpoint ) [private]

Change the current viewpoint properly.
The render state needs to listen to the viewpoint since whenever it changes, all the shapes Z order may change and therefore we will need to recompute all the shape positions properly.
This function takes care of removing the previous listener from the previous viewpoint and setup the new viewpoint with this listener. The render state itself is the listener.

See also:
x3d::SFNode::RegisterListener

void x3drender::RenderState::SetScreenSizes ( unsigned int width,

unsigned int height

)

Defines the width and height of the output screen.

Parameters:

[in] width The width, in pixels, of the screen.

[in] height The height, in pixels, of the screen.

This function will be used to determine the width and height of the output screen.
It is expected to be set to the width and height of the output window. It is used to compute the perspective of the projection matrix.

Warning:
To make sure that the initialization works, you must setup the screen sizes.

See also:
Initialize()
SetViewpointName()

bool x3drender::RenderState::SetupShape ( x3d::SFNodePtr node,

x3d::MFNode parents,

fast_math::Matrix4x4 & matrix

) [private]

Finalize the RenderShape setup.

For internal use only.

This function finalizes the render shape setup by setting up the parent nodes and the matrix and then walk the tree under the shape object to get the geometry and the appearance of the shape.

void x3drender::RenderState::SetViewpointName ( const char * name )

Set the name of the viewpoint to start with.

Parameters:

[in] name The name of the viewpoint to select at the start.

In order to start at a specific viewpoint, you need to setup the viewpoint name before you call the Initialize() function.

See also:
Initialize()
SetScreenSizes()

bool x3drender::RenderState::Update ( )

Update all the render shape which needs to be updated.
This function will update all the shapes found in the list of shapes to be rendered in this render state.

See also:
RenderShape::Update()

bool x3drender::RenderState::WalkTree ( x3d::SFNodePtr node,

x3d::MFNode parents,

fast_math::Matrix4x4 & matrix

) [private]

This function walks a tree of node to find shapes.

For internal use only.

Parameters:

[in] node The scene node or some child of a scene node.

[in] parents The parents of the current node.

[in] matrix The current transformation matrix (start with the identity).

This function recursively walks a tree of nodes to find all the shapes and groupings.

Returns:
true whenever a shape was successfully added to the array of shapes.

See also:
Initialize