The SGADE Documentation

The Socrates Gameboy Advance Development Engine

The SGADE is a development library for the Nintendo Gameboy Advance. It's free for all uses and is distributed without guarantees. For more information visit the SGADE page.

Main Page Modules Data Structures File List Data Fields Globals Related Pages

SoCamera.c File Reference

#include "SoCamera.h"
#include "SoSystem.h"
#include "SoMode4PolygonRasterizer.h"
#include "SoMode4Renderer.h"
#include "SoDebug.h"


Defines
#define	SO_CAMERA_FRUSTUM_NEAR_PLANE
	Constant to uniquely identify the frustum near plane.
#define	SO_CAMERA_FRUSTUM_FAR_PLANE
	Constant to uniquely identify the frustum far plane.
#define	SO_CAMERA_FRUSTUM_LEFT_PLANE
	Constant to uniquely identify the frustum left plane.
#define	SO_CAMERA_FRUSTUM_RIGHT_PLANE
	Constant to uniquely identify the frustum right plane.
#define	SO_CAMERA_FRUSTUM_TOP_PLANE
	Constant to uniquely identify the frustum top plane.
#define	SO_CAMERA_FRUSTUM_BOTTOM_PLANE
	Constant to uniquely identify the frustum bottom plane.
Functions
void	SoCameraTransformMesh (SoCamera a_This, SoMesh a_Mesh)
	Transforms the given mesh filling the camera- and screenspace vertex buffers.
void	SoCameraSafeProject (SoCamera a_This, SoVector3 a_CameraSpaceCoordinate, SoVector2 *a_ScreenSpaceCoordinate)
	Cameraspace vertex projector that can handle vertices outside the frustum.
void	SoCameraProject (SoCamera a_This, SoVector3 a_CameraSpaceCoordinate, SoVector2 *a_ScreenSpaceCoordinate)
	Projects a vertex from cameraspace to screenspace.
void	SoCameraClipPolygon (SoCamera a_This, SoPolygon a_Polygon)
	Clips the given polygon against the camera's frustum.
void	SoCameraClipTexturedPolygonAgainstFrustumPlane (SoCamera *a_This, s32 a_WhichFrustumPlane)
	Clips a textured s_CurrentPolygon* against a single specific frustum plane.*
void	SoCameraClipSolidPolygonAgainstFrustumPlane (SoCamera *a_This, s32 a_WhichFrustumPlane)
	Clips a solid s_CurrentPolygon* against a single specific frustum plane.*
void	SoCameraProjectUnProjectedVertices (SoCamera *a_This)
	Projects the vertices that weren't projected before (i.e. vertices introduced during clipping).
sofixedpoint	SoCameraDistanceToFrustumPlane (SoCamera a_This, SoVector3 a_CameraSpaceVertex, s32 a_WhichFrustumPlane)
	Returns the fixed point distance from a cameraspace vertex to a frustum plane.
bool	SoCameraClockwise (SoVector2 *a_AtLeastThreeVertices)
	Tests whether the polygon's vertices are clockwise ordered.
void	SoCameraInitialize (SoCamera *a_This)
	Initializes a camera.
void	SoCameraSetPitch (SoCamera *a_This, s32 a_Angle)
	Sets the pitch of the camera. A full circle is 256 degrees.
void	SoCameraSetYaw (SoCamera *a_This, s32 a_Angle)
	Sets the yaw of the camera. A full circle is 256 degrees.
void	SoCameraSetRoll (SoCamera *a_This, s32 a_Angle)
	Sets the roll of the camera. A full circle is 256 degrees.
void	SoCameraSetTranslation (SoCamera *a_This, sofixedpoint a_X, sofixedpoint a_Y, sofixedpoint a_Z)
	Sets the translate of the camera.
void	SoCameraSetFarAndNearPlaneClippingEnable (SoCamera *a_This, bool a_Enable)
	Enables or disables clipping of polygons against the far and near planes.
void	SoCameraSetFrustumSidePlanesClippingEnable (SoCamera *a_This, bool a_Enable)
void	SoCameraPitch (SoCamera *a_This, s32 a_Angle)
	Pitches the camera.
void	SoCameraYaw (SoCamera *a_This, s32 a_Angle)
	Yaws the camera.
void	SoCameraRoll (SoCamera *a_This, s32 a_Angle)
	Rolls the camera.
void	SoCameraForward (SoCamera *a_This, sofixedpoint a_Amount)
	Forwards the camera by the given fixed point amount.
void	SoCameraRight (SoCamera *a_This, sofixedpoint a_Amount)
	Moves the camera to the right by the given fixed point amount.
void	SoCameraUp (SoCamera *a_This, sofixedpoint a_Amount)
	Moves the camera up by the given fixed point amount.
void	SoCameraDrawMesh (SoCamera a_This, SoMesh a_Mesh)
	Draws the given mesh into the current buffer.
Variables
SoVector3	s_CameraSpaceVertexBuffer [SO_MESH_MAX_NUM_VERTICES]
SoVector2	s_ScreenSpaceVertexBuffer [SO_MESH_MAX_NUM_VERTICES]
struct {
bool m_HasTexture
u32 m_NumVertices
SoVector2 * m_ScreenSpaceVertices
SoVector3 * m_CameraSpaceVertices
SoVector2 * m_TextureCoordinates
u32 m_ClippedNumVertices
SoVector2 * m_ClippedScreenSpaceVertices
SoVector3 * m_ClippedCameraSpaceVertices
SoVector2 * m_ClippedTextureCoordinates
SoVector2 m_ScreenSpaceArray0 [SO_POLYGON_MAX_NUM_VERTICES]
SoVector3 m_CameraSpaceArray0 [SO_POLYGON_MAX_NUM_VERTICES]
SoVector2 m_TextureCrdsArray0 [SO_POLYGON_MAX_NUM_VERTICES]
SoVector2 m_ScreenSpaceArray1 [SO_POLYGON_MAX_NUM_VERTICES]
SoVector3 m_CameraSpaceArray1 [SO_POLYGON_MAX_NUM_VERTICES]
SoVector2 m_TextureCrdsArray1 [SO_POLYGON_MAX_NUM_VERTICES]
}	s_CurrentPolygon
	Describes the current polygon that is about to be drawn.

Detailed Description

Author:: Jaap Suter

Date:: Jun 26 2001

Implementation of SoCamera.h

Define Documentation

#define SO_CAMERA_FRUSTUM_BOTTOM_PLANE

Constant to uniquely identify the frustum bottom plane.

For internal use only.

#define SO_CAMERA_FRUSTUM_FAR_PLANE

Constant to uniquely identify the frustum far plane.

For internal use only.

#define SO_CAMERA_FRUSTUM_LEFT_PLANE

Constant to uniquely identify the frustum left plane.

For internal use only.

#define SO_CAMERA_FRUSTUM_NEAR_PLANE

Constant to uniquely identify the frustum near plane.

For internal use only.

#define SO_CAMERA_FRUSTUM_RIGHT_PLANE

Constant to uniquely identify the frustum right plane.

For internal use only.

#define SO_CAMERA_FRUSTUM_TOP_PLANE

Constant to uniquely identify the frustum top plane.

For internal use only.

Function Documentation

void SoCameraClipPolygon ( SoCamera * a_This,

SoPolygon * a_Polygon

)

Clips the given polygon against the camera's frustum.

For internal use only.
Only called from within SoCameraDrawMesh.

Precondition:
This method expects that the camera's has correctly filled screen- and cameraspace vertex buffers. This means that SoTransformMesh has been called previously for the mesh containing this polygon.
Postcondition:
The s_CurrentPolygon contains the polygon correctly clipped against the frustum.
Parameters:

a_This This pointer

a_Polygon Polygon to be clipped

Note that this function only clips the polygon if near- and farplane clipping and frustum sideplane clipping are enabled. If these are both disabled all this function does is copy the polygon from the given SoPolygon object into the s_CurrentPolygon object.

void SoCameraClipSolidPolygonAgainstFrustumPlane ( SoCamera * a_This,

s32 a_WhichFrustumPlane

)

Clips a solid s_CurrentPolygon against a single specific frustum plane.

For internal use only.
Only called from within SoCameraClipPolygon

Precondition:
s_CurrentPolygon correctly filled.
Postcondition:
The s_CurrentPolygon but now clipped against the given plane.
Parameters:

a_This This pointer

a_WhichFrustumPlane Identifies the frustum to which you want to know clip. This is one of the SO_CAMERA_FRUSTUM_ * _PLANE constants.

This function only clips the vertices (no texture coordinates). It uses the m_Clipped prefixed members of the s_CurrentPolygon structure as an intermediate result to store the clipped polygon, and swaps the arrays at the end so it becomes normal again.
It that didn't make sense then tell me.

void SoCameraClipTexturedPolygonAgainstFrustumPlane ( SoCamera * a_This,

s32 a_WhichFrustumPlane

)

Clips a textured s_CurrentPolygon against a single specific frustum plane.

For internal use only.
Only called from within SoCameraClipPolygon

Precondition:
s_CurrentPolygon correctly filled.
Postcondition:
The s_CurrentPolygon but now clipped against the given plane.
Parameters:

a_This This pointer

a_WhichFrustumPlane Identifies the frustum to which you want to know clip. This is one of the SO_CAMERA_FRUSTUM_ * _PLANE constants.

This function clips the texture coordinates as well as the vertices. It uses the m_Clipped prefixed members of the s_CurrentPolygon structure as an intermediate result to store the clipped polygon, and swaps the arrays at the end so it becomes normal again.
It that didn't make sense then tell me.

bool SoCameraClockwise ( SoVector2 * a_AtLeastThreeVertices )

Tests whether the polygon's vertices are clockwise ordered.

For internal use only.

Parameters:

a_AtLeastThreeVertices An array of at least three 2D vertices

Todo:
Move backface culling from 2D to 3D.

Tests whether the given triangle (first three vertices of a polygon) are lying in a clockwise order. This can be used for backface culling.

sofixedpoint SoCameraDistanceToFrustumPlane ( SoCamera * a_This,

SoVector3 * a_CameraSpaceVertex,

s32 a_WhichFrustumPlane

)

Returns the fixed point distance from a cameraspace vertex to a frustum plane.

For internal use only.

Parameters:

a_This This pointer

a_CameraSpaceVertex Vertex in camera space

a_WhichFrustumPlane Identifies the frustum to which you want to know the distance. This is one of the SO_CAMERA_FRUSTUM_ * _PLANE constants.

void SoCameraPitch ( SoCamera * a_This,

s32 a_Angle

)

Pitches the camera.

Parameters:

a_This This pointer

a_Angle Angle, a full circle is 256 degrees

The difference between this function and the SoCameraSetPitch function is that this function adds the given pitch to the existing pitch.

void SoCameraProject ( SoCamera * a_This,

SoVector3 * a_CameraSpaceCoordinate,

SoVector2 * a_ScreenSpaceCoordinate

)

Projects a vertex from cameraspace to screenspace.

For internal use only.

Parameters:

a_This This pointer

a_CameraSpaceCoordinate Vertex in camera space

Return values:

a_ScreenSpaceCoordinate Transformed vertex

Todo:
Optimize

Warning:
This function does no frustum checks, so if you're not carefull you can get some weird results. You might even get a divide by zero. Use it only for vertices that are guaranteed to be inbetween the near and far clipping planes.

void SoCameraProjectUnProjectedVertices ( SoCamera * a_This )

Projects the vertices that weren't projected before (i.e. vertices introduced during clipping).

For internal use only.

Parameters:

a_This This pointer

Projects all unprojected vertices in the s_CurrentPolygon structure. These are the vertices introduced during clipping.

void SoCameraRoll ( SoCamera * a_This,

s32 a_Angle

)

Rolls the camera.

Parameters:

a_This This pointer

a_Angle Angle, a full circle is 256 degrees

The difference between this function and the SoCameraSetRoll function is that this function adds the given roll to the existing roll.

void SoCameraSafeProject ( SoCamera * a_This,

SoVector3 * a_CameraSpaceCoordinate,

SoVector2 * a_ScreenSpaceCoordinate

)

Cameraspace vertex projector that can handle vertices outside the frustum.

For internal use only.

Parameters:

a_This This pointer

a_CameraSpaceCoordinate Vertex in camera space

Return values:

a_ScreenSpaceCoordinate Transformed vertex

If the vertex cannot be projected because it is outside of the frustum a negative value is loaded in the X component. Since a negative X means it's offscreen we can use this to tell that this vertex couldn't be projected on screen.
We use the SO_CAMERA_FRUSTUM_ * _PLANE constants for this so we can identify which plane it was clipped by first. That's why these constants have to be negative.

void SoCameraTransformMesh ( SoCamera * a_This,

SoMesh * a_Mesh

)

Transforms the given mesh filling the camera- and screenspace vertex buffers.

For internal use only.
Used by SoCameraDrawMesh only.
Parameters:

a_This This pointer

a_Mesh Mesh to be transformed

This method calculates the objectspace to cameraspace (via worldspace) matrix and transforms the mesh by that matrix, filling the cameraspace vertex buffer. It then uses a safe project method to project the vertices to screenspace. This safeproject marks any vertex that couldn't be projected because it was outside of the frustum.

void SoCameraYaw ( SoCamera * a_This,

s32 a_Angle

)

Yaws the camera.

Parameters:

a_This This pointer

a_Angle Angle, a full circle is 256 degrees

The difference between this function and the SoCameraSetYaw function is that this function adds the given yaw to the existing yaw.

Variable Documentation

SoVector3 m_CameraSpaceArray0[ SO_POLYGON_MAX_NUM_VERTICES ]

For internal use only.

SoVector3 m_CameraSpaceArray1[ SO_POLYGON_MAX_NUM_VERTICES ]

For internal use only.

SoVector3* m_CameraSpaceVertices

Camera space coordinates of the polygon.

SoVector3* m_ClippedCameraSpaceVertices

For internal use only.

u32 m_ClippedNumVertices

For internal use only.

SoVector2* m_ClippedScreenSpaceVertices

For internal use only.

SoVector2* m_ClippedTextureCoordinates

For internal use only.

bool m_HasTexture

Whether or not the polygon has a texture.

u32 m_NumVertices

Number of vertices in the polygon.

SoVector2 m_ScreenSpaceArray0[ SO_POLYGON_MAX_NUM_VERTICES ]

For internal use only.

SoVector2 m_ScreenSpaceArray1[ SO_POLYGON_MAX_NUM_VERTICES ]

For internal use only.

SoVector2* m_ScreenSpaceVertices

Screenspace coordinates of the polygon.

SoVector2* m_TextureCoordinates

Texture coordinates of the polygon.

SoVector2 m_TextureCrdsArray0[ SO_POLYGON_MAX_NUM_VERTICES ]

For internal use only.

SoVector2 m_TextureCrdsArray1[ SO_POLYGON_MAX_NUM_VERTICES ]

For internal use only.

SoVector3 s_CameraSpaceVertexBuffer[ SO_MESH_MAX_NUM_VERTICES ] [static]

For internal use only.
Buffer that is able to contain all of a mesh's vertices transformed from object to camera space.

struct { ... } s_CurrentPolygon [static]

Describes the current polygon that is about to be drawn.

For internal use only.

This struct is used to describe the polygon that is about to be rendered. It contains all the information to clip and render it.
We are actually able to store two polygons in this struct. An original one, and a clipped one. But after each clipping phase (against one frustumplane) we swap the data members so that the ones without the Clipped prefix are always the result. So the members with the Clipped prefix are actually only used as intermediates.

SoVector2 s_ScreenSpaceVertexBuffer[ SO_MESH_MAX_NUM_VERTICES ] [static]

For internal use only.
Buffer that is able to contain all of a mesh's vertices transformed from camera space to screen space.

SoCamera.c File Reference

Defines

Functions

Variables

Detailed Description

Define Documentation

Function Documentation

Variable Documentation