Detailed Description

Rendering of 3D objects.

#include <srl_scene3d.hpp>

Draw functions
static void	DrawSmoothMesh (Types::SmoothMesh &mesh, Types::Vector3D &light)
	Draw SRL::Types::SmoothMesh.

static bool	DrawMesh (Types::Mesh &mesh, const bool slaveOnly=false)
	Draw SRL::Types::Mesh.

static bool	DrawOrthographicMesh (Types::Mesh &mesh, uint16_t attribute)
	Draw SRL::Types::Mesh with orthographic projection.

Light handling functions
static void	SetDirectionalLight (const Types::Vector3D &direction)
	Set directional light source.

static void	LightInitGouraudTable (uint32_t gouraudRamOffset, uint8_t vertexCalculationBuffer, Types::HighColor tableStorage, uint32_t maxPolygons)
	Initialize gouraud table for light calculation with SRL::Scene3D::DrawSmoothMesh.

static void	LightSetGouraudTable (Types::HighColor table[32])
	Set custom light gouraud table.

static void	LightSetGouraudColor (const SRL::Types::HighColor color)
	Set gouraud color of light source.

static void	LightSetColor (const SRL::Types::HighColor color)
	Set color of the flat light source (UseLight option)

static void	LightCopyGouraudTable ()
	Copies gouraud table calculated by the library to VRAM.

Camera functions
static bool	IsOnScreen (const SRL::Types::Vector3D &point, const SRL::Types::Fxp size)
	Check if point/circle area is on screen.

static void	LookAt (const SRL::Types::Vector3D &camera, const SRL::Types::Vector3D &target, const SRL::Types::Angle roll)
	Make camera look at certain point in the 3D scene.

static SRL::Types::Fxp	ProjectToScreen (const SRL::Types::Vector3D &position, SRL::Types::Vector2D *result)
	Projects 3D point onto a screen from current transformation matrix.

static void	SetDepthDisplayLevel (const uint16_t level)
	Set value indicating how far in front of the projection surface to actually project.

static void	SetPerspective (Types::Angle angle)
	Set angle of the perspective projection.

static bool	SetWindow (Types::Vector2D &topLeft, Types::Vector2D &bottomRight, Types::Vector2D &center, Types::Fxp &depthLimit)
	Set window limiting the display of sprites and polygons.

Transformation matrix operations
static void	PushMatrix ()
	Push current matrix onto the matrix stack.

static void	PushIdentityMatrix ()
	Push current matrix onto the matrix stack and set identity matrix as current.

static void	PopMatrix ()
	Pop matrix from top of the stack and set it as current.

static void	LoadIdentity ()
	Replaces current matrix with identity matrix.

static void	IdentityTranslationMatrix ()
	Sets identity translation matrix.

static void	IdentityRotationMatrix ()
	Sets identity rotation matrix.

static void	SetMatrix (SRL::Types::Matrix &matrix)
	Set current matrix.

static void	GetMatrix (SRL::Types::Matrix *result)
	Get current matrix.

static void	InvertMatrix ()
	Inverts current matrix.

static void	TransposeMatrix ()
	Transpose current matrix (zero movement in parallel direction)

static void	MultiplyMatrix (SRL::Types::Matrix &matrix)
	Multiply current matrix by specified matrix.

static void	Rotate (const SRL::Types::Vector3D &axis, SRL::Types::Angle angle)
	Rotate current matrix around arbitrary axis by specific angle.

static void	RotateX (SRL::Types::Angle angle)
	Rotate current matrix around X axis by specific angle.

static void	RotateX (SRL::Types::Fxp sin, SRL::Types::Fxp cos)
	Rotate current matrix around X axis by specific sinus and cosine values.

static void	RotateY (SRL::Types::Angle angle)
	Rotate current matrix around Y axis by specific angle.

static void	RotateY (SRL::Types::Fxp sin, SRL::Types::Fxp cos)
	Rotate current matrix around Y axis by specific sinus and cosine values.

static void	RotateZ (SRL::Types::Angle angle)
	Rotate current matrix around Z axis by specific angle.

static void	RotateZ (SRL::Types::Fxp sin, SRL::Types::Fxp cos)
	Rotate current matrix around X axis by specific sinus and cosine values.

static void	Scale (SRL::Types::Fxp x, SRL::Types::Fxp y, SRL::Types::Fxp z)
	Scale current transformation matrix.

static void	Scale (const SRL::Types::Vector3D &scale)
	Scale current transformation matrix.

static void	Scale (SRL::Types::Fxp scale)
	Scale current transformation matrix.

static void	Translate (SRL::Types::Fxp x, SRL::Types::Fxp y, SRL::Types::Fxp z)
	Translate current transformation matrix.

static void	Translate (const SRL::Types::Vector3D &delta)
	Translate current transformation matrix.

static SRL::Types::Vector3D	TransformPoint (const SRL::Types::Vector3D &point)
	Transforms point by current transformation matrix.

static SRL::Types::Vector3D	TransformVector (const SRL::Types::Vector3D &point)
	Transforms direction vector by current transformation matrix.

Member Function Documentation

◆ DrawMesh()

static bool SRL::Scene3D::DrawMesh	(	Types::Mesh &	mesh,
		const bool	slaveOnly = false )

inlinestatic

Draw SRL::Types::Mesh.

Parameters

mesh	SRL::Types::Mesh to draw
slaveOnly	Value indicates whether processing of the SRL::Types::Mesh should be handled only on the slave CPU

Returns: True on success

◆ DrawOrthographicMesh()

static bool SRL::Scene3D::DrawOrthographicMesh	(	Types::Mesh &	mesh,
		uint16_t	attribute )

inlinestatic

Draw SRL::Types::Mesh with orthographic projection.

Note: Light source calculations and clipping cannot be performed with this function.

Parameters

mesh	SRL::Types::Mesh to draw
attribute	Indicates an attribute in the SRL::Types::Mesh that will be shared by all polygons. If set to 0, each polygon is displayed using the data at the beginning of the attribute table, otherwise specified attribute data will be displayed.

Returns: True On success

◆ DrawSmoothMesh()

static void SRL::Scene3D::DrawSmoothMesh	(	Types::SmoothMesh &	mesh,
		Types::Vector3D &	light )

inlinestatic

Draw SRL::Types::SmoothMesh.

Parameters

mesh	SRL::Types::SmoothMesh to draw
light	Light direction unit vector (This is independent of the SRL::Scene3D::SetDirectionalLight)

◆ GetMatrix()

static void SRL::Scene3D::GetMatrix ( SRL::Types::Matrix * result )

inlinestatic

Get current matrix.

Note: This will copy current matrix to specified address

Parameters

result Transformation matrix

◆ IsOnScreen()

static bool SRL::Scene3D::IsOnScreen	(	const SRL::Types::Vector3D &	point,
		const SRL::Types::Fxp	size )

inlinestatic

Check if point/circle area is on screen.

Parameters

point	Point to test
size	Size of the point

Returns: true if point is on screen

◆ LightCopyGouraudTable()

static void SRL::Scene3D::LightCopyGouraudTable ( )

inlinestatic

Copies gouraud table calculated by the library to VRAM.

// Attach the function to VBlank

SRL::Core::OnVblank += SRL::Scene3D::LightCopyGouraudTable;

SRL::Core::OnVblank

static SRL::Types::Event OnVblank

Event triggered every v-blank.

Definition srl_core.hpp:26

SRL::Scene3D::LightCopyGouraudTable

static void LightCopyGouraudTable()

Copies gouraud table calculated by the library to VRAM.

Definition srl_scene3d.hpp:132

Note: This function must be always called in vblank when using SRL::Scene3D::DrawSmoothMesh()

◆ LightInitGouraudTable()

static void SRL::Scene3D::LightInitGouraudTable	(	uint32_t	gouraudRamOffset,
		uint8_t *	vertexCalculationBuffer,
		Types::HighColor *	tableStorage,
		uint32_t	maxPolygons )

inlinestatic

Initialize gouraud table for light calculation with SRL::Scene3D::DrawSmoothMesh.

// When the total number of polygons is 500 and the maximum number of vertices per model is 100.
#define MAX_POLYGON 500
#define MAX_MODEL_VERT 100
SRL::Types::HighColor workTable[MAX_POLYGON << 2];
uint8 vertWork[MAX_MODEL_VERT];
 
SRL::Scene3D::LightInitGouraudTable(0, vertWork, workTable, MAX_POLYGON);

Parameters

gouraudRamOffset	Relative address to the first entry from which to write light gouraud data in SRL::VDP1::GetGouraudTable(). Using 0 here would mean first entry, 2 is second entry in the table, where each entry is 4 color long.
vertexCalculationBuffer	Vertex arithmetic work buffer
tableStorage	Work gouraud table with size of maxPolygons
maxPolygons	Maximum number of polygons that can be processed by the light calculation

◆ LightSetColor()

static void SRL::Scene3D::LightSetColor ( const SRL::Types::HighColor color )

inlinestatic

Set color of the flat light source (UseLight option)

Parameters

color Light source color

◆ LightSetGouraudColor()

static void SRL::Scene3D::LightSetGouraudColor ( const SRL::Types::HighColor color )

inlinestatic

Set gouraud color of light source.

Note: This option will override SRL::Types::LightSetGouraudTable()

Parameters

color Light source color

◆ LightSetGouraudTable()

static void SRL::Scene3D::LightSetGouraudTable ( Types::HighColor table[32] )

inlinestatic

Set custom light gouraud table.

Table must contain 32 color entries from the darkest color to the brightest.

Parameters

table custom light table

◆ LookAt()

static void SRL::Scene3D::LookAt	(	const SRL::Types::Vector3D &	camera,
		const SRL::Types::Vector3D &	target,
		const SRL::Types::Angle	roll )

inlinestatic

Make camera look at certain point in the 3D scene.

Parameters

camera	Camera location
target	Target point
roll	Rotation around the line of sight vector

◆ MultiplyMatrix()

static void SRL::Scene3D::MultiplyMatrix ( SRL::Types::Matrix & matrix )

inlinestatic

Multiply current matrix by specified matrix.

Parameters

matrix Matrix to multiply current matrix with

◆ ProjectToScreen()

static SRL::Types::Fxp SRL::Scene3D::ProjectToScreen	(	const SRL::Types::Vector3D &	position,
		SRL::Types::Vector2D *	result )

inlinestatic

Projects 3D point onto a screen from current transformation matrix.

Parameters

position	Position in world space
result	Position on screen

Returns: Fxp Distance from world space to screen space

◆ Rotate()

static void SRL::Scene3D::Rotate	(	const SRL::Types::Vector3D &	axis,
		SRL::Types::Angle	angle )

inlinestatic

Rotate current matrix around arbitrary axis by specific angle.

Parameters

axis	Rotation axis
angle	Rotation angle

◆ RotateX() [1/2]

static void SRL::Scene3D::RotateX ( SRL::Types::Angle angle )

inlinestatic

Rotate current matrix around X axis by specific angle.

Parameters

angle Rotation angle

◆ RotateX() [2/2]

static void SRL::Scene3D::RotateX	(	SRL::Types::Fxp	sin,
		SRL::Types::Fxp	cos )

inlinestatic

Rotate current matrix around X axis by specific sinus and cosine values.

Parameters

sin	Sinus value
cos	Cosine value

◆ RotateY() [1/2]

static void SRL::Scene3D::RotateY ( SRL::Types::Angle angle )

inlinestatic

Rotate current matrix around Y axis by specific angle.

Parameters

angle Rotation angle

◆ RotateY() [2/2]

static void SRL::Scene3D::RotateY	(	SRL::Types::Fxp	sin,
		SRL::Types::Fxp	cos )

inlinestatic

Rotate current matrix around Y axis by specific sinus and cosine values.

Parameters

sin	Sinus value
cos	Cosine value

◆ RotateZ() [1/2]

static void SRL::Scene3D::RotateZ ( SRL::Types::Angle angle )

inlinestatic

Rotate current matrix around Z axis by specific angle.

Parameters

angle Rotation angle

◆ RotateZ() [2/2]

static void SRL::Scene3D::RotateZ	(	SRL::Types::Fxp	sin,
		SRL::Types::Fxp	cos )

inlinestatic

Rotate current matrix around X axis by specific sinus and cosine values.

Parameters

sin	Sinus value
cos	Cosine value

◆ Scale() [1/3]

static void SRL::Scene3D::Scale ( const SRL::Types::Vector3D & scale )

inlinestatic

Scale current transformation matrix.

Parameters

scale Scale factor

◆ Scale() [2/3]

static void SRL::Scene3D::Scale ( SRL::Types::Fxp scale )

inlinestatic

Scale current transformation matrix.

Parameters

scale Scale factor

◆ Scale() [3/3]

static void SRL::Scene3D::Scale	(	SRL::Types::Fxp	x,
		SRL::Types::Fxp	y,
		SRL::Types::Fxp	z )

inlinestatic

Scale current transformation matrix.

Parameters

x	Scale factor on X axis
y	Scale factor on Y axis
z	Scale factor on Z axis

◆ SetDepthDisplayLevel()

static void SRL::Scene3D::SetDepthDisplayLevel ( const uint16_t level )

inlinestatic

Set value indicating how far in front of the projection surface to actually project.

Function specifies the distance from the forward boundary surface to the rear boundary surface.

Parameters

level

Display level. See table below for valid parameter values and image above for explanation.

parameter value	real value
1	1/2
2	1/4
3	1/8
4	1/16
5	1/32
6	1/64
7	1/128

◆ SetDirectionalLight()

static void SRL::Scene3D::SetDirectionalLight ( const Types::Vector3D & direction )

inlinestatic

Set directional light source.

Note: If scaling operation is being performed on current matrix, normal vector of the polygon is also being affected,thus brightness will change accordingly.

Parameters

direction Light direction unit vector

◆ SetMatrix()

static void SRL::Scene3D::SetMatrix ( SRL::Types::Matrix & matrix )

inlinestatic

Set current matrix.

Parameters

matrix Transformation matrix

◆ SetPerspective()

static void SRL::Scene3D::SetPerspective ( Types::Angle angle )

inlinestatic

Set angle of the perspective projection.

Perspective angle determines the angle corresponding to the width of the screen. In combination with SRL::Scene3D::SetDepthDisplayLevel and SRL::Scene3D::SetWindow projection volume can be completely determined.

Note: Because this function also sets parameter for rotating scroll, also execute slRpasaIntSet() before calling this if using rotating scroll

Parameters

angle Perspective angle (Range 10-160 degrees)

◆ SetWindow()

static bool SRL::Scene3D::SetWindow	(	Types::Vector2D &	topLeft,
		Types::Vector2D &	bottomRight,
		Types::Vector2D &	center,
		Types::Fxp &	depthLimit )

inlinestatic

Set window limiting the display of sprites and polygons.

There can be two windows on screen at once, sprite clipping can be used to decide whether sprites are displayed inside the window or not.
Depth limit indicates maximal distance to the near projection plane.
Center point can be used to set projection center.

Note: Be careful! This function also affects sprites rendered with SRL::Scene2D.

Parameters

topLeft	Top left point on the screen
bottomRight	Bottom right point on the screen
center	3D projection center (vanishing point)
depthLimit	Maximal allowed distance from the near projection plane

Returns: True on success

◆ TransformPoint()

static SRL::Types::Vector3D SRL::Scene3D::TransformPoint ( const SRL::Types::Vector3D & point )

inlinestatic

Transforms point by current transformation matrix.

Parameters

point Point to transform

Returns: Transformed point

◆ TransformVector()

static SRL::Types::Vector3D SRL::Scene3D::TransformVector ( const SRL::Types::Vector3D & point )

inlinestatic

Transforms direction vector by current transformation matrix.

Parameters

point Direction vector to transform

Returns: Transformed direction vector

◆ Translate() [1/2]

static void SRL::Scene3D::Translate ( const SRL::Types::Vector3D & delta )

inlinestatic

Translate current transformation matrix.

Parameters

delta Translation delta

◆ Translate() [2/2]

static void SRL::Scene3D::Translate	(	SRL::Types::Fxp	x,
		SRL::Types::Fxp	y,
		SRL::Types::Fxp	z )

inlinestatic

Translate current transformation matrix.

Parameters

x	Translation delta on X axis
y	Translation delta on Y axis
z	Translation delta on Z axis

Detailed Description

Draw functions

Light handling functions

Camera functions

Transformation matrix operations

Member Function Documentation

◆ DrawMesh()

◆ DrawOrthographicMesh()

◆ DrawSmoothMesh()

◆ GetMatrix()

◆ IsOnScreen()

◆ LightCopyGouraudTable()

◆ LightInitGouraudTable()

◆ LightSetColor()

◆ LightSetGouraudColor()

◆ LightSetGouraudTable()

◆ LookAt()

◆ MultiplyMatrix()

◆ ProjectToScreen()

◆ Rotate()

◆ RotateX() [1/2]

◆ RotateX() [2/2]

◆ RotateY() [1/2]

◆ RotateY() [2/2]

◆ RotateZ() [1/2]

◆ RotateZ() [2/2]

◆ Scale() [1/3]

◆ Scale() [2/3]

◆ Scale() [3/3]

◆ SetDepthDisplayLevel()

◆ SetDirectionalLight()

◆ SetMatrix()

◆ SetPerspective()

◆ SetWindow()

◆ TransformPoint()

◆ TransformVector()

◆ Translate() [1/2]

◆ Translate() [2/2]