SYNOPSIS

#include <agar/core.h>
#include <agar/sg.h>

DESCRIPTION

A SG_Camera node defines a point of view inside a SG(3) scene-graph. When rendering a scene, the SG_View(3) widget is associated with a SG_Camera node, which defines both the projection matrix and the initial OpenGL modelview matrix.

The SG_Camera class implements perspective, orthographic and user-specified projection modes.

INHERITANCE HIERARCHY

AG_Object(3)-> SG_Node(3)-> SG_Camera.

INITIALIZATION

SG_Camera * SG_CameraNew (SG_Node *parent, const char *name)

SG_Camera * SG_CameraNewDuplicate (SG_Node *parent, const char *name, const SG_Camera *origCam)

The SG_CameraNew() function allocates, initializes, and attaches a new SG_Camera object. The SG_CameraNewDuplicate() variant initializes the new camera with the same parameters as camOrig.

PROJECTION TRANSFORMATIONS

Projection transformations are used to map object coordinates to window coordinates for two-dimensional display devices. Each SG_Camera instance is associated with a projection transformation.

void SG_CameraGetProjection (SG_Camera *cam, M_Matrix44 *P)

void SG_CameraSetOrthographic (SG_Camera *cam)

void SG_CameraSetPerspective (SG_Camera *cam, M_Real fov, M_Real aspect)

void SG_CameraSetUser (SG_Camera *cam, const M_Matrix44 *Pleft, const M_Matrix44 *Pright)

void SG_CameraSetClipPlanes (SG_Camera *cam, M_Real near, M_Real far)

void SG_CameraSetBackPolyMode (SG_Camera *cam, const SG_CameraPolyMode *polymode)

void SG_CameraSetFacePolyMode (SG_Camera *cam, const SG_CameraPolyMode *polymode)

The SG_CameraGetProjection() function returns the current projection matrix of cam into P.

The SG_CameraSetOrthographic() function sets the projection matrix of cam to an orthographic projection matrix. SG_CameraSetPerspective() selects a perspective matrix. For perspective projections, aspect defines the aspect ratio (ratio of width to height) and fov defines the field-of-view angle in degrees in the y direction.

The SG_CameraSetUser() function sets the projection matrix of cam to user-specified matrices Pleft (left eye) and Pright (right eye). Unless stereo rendering is activated, only Pleft is used.

The near and far clipping planes are defined by SG_CameraSetClipPlanes(). near and far represent the distance from the standard XY plane to the near and far clipping planes.

SG_CameraSetBackPolyMode() and SG_CameraSetFacePolyMode() configure the way back-facing or front-facing polygons are rendered by views using this camera. The structure is defined as:

typedef struct sg_camera_polymode {
	enum {
		SG_CAMERA_POINTS,		/* Render as points */
		SG_CAMERA_WIREFRAME,		/* Render in wireframe */
		SG_CAMERA_FLAT_SHADED,		/* Flat-shaded */
		SG_CAMERA_SMOOTH_SHADED		/* Smooth-shaded */
	} mode;
	int cull;				/* Cull entirely */
} SG_CameraPolyMode;

CONTROLLING CAMERA ORIENTATION

void SG_CameraRotMouse (SG_Camera *cam, SG_View *sv, int xRel, int yRel)

void SG_CameraSetRotCtrlCircular (SG_Camera *cam, SG_Node *n)

void SG_CameraSetRotCtrlElliptic (SG_Camera *cam, SG_Node *n1, SG_Node *n2)

SG_CameraRotMouse() is typically invoked by SG_View(3) (or a derived widget) to rotate the camera by mouse action. xRel and yRel are the relative mouse coordinates since the last mouse motion event.

SG_CameraSetRotCtrlCircular() configures the camera such that mouse motion will translate to a circular orbit around a specified node n. Similarly, SG_CameraSetRotCtrlElliptic() arranges for an elliptic orbit around two specified nodes n1 and n2.

INTERNAL WIDGET API

void SG_CameraProject (SG_Camera *cam)

void SG_CameraProjectLeft (SG_Camera *cam)

void SG_CameraProjectRight (SG_Camera *cam)

void SG_CameraSetup (SG_Camera *cam)

The SG_CameraProject() function multiplies the current projection matrix by the projection matrix associated with a camera cam. If quad-buffer stereo project is needed, SG_CameraProjectLeft() and SG_CameraProjectRight() may be called instead. Functions are used internally by SG_View(3), or derivatives of it. The camera object must be locked by the caller.

The SG_CameraSetup() function applies the viewing transformation associated with a camera. As opposed to SG_CameraProject() which is only called on rescale, SG_CameraSetup() is normally called from the "draw" function of SG_View(3) (or derived widget), prior to rendering the scene. The camera object must be locked by the caller.

STRUCTURE DATA

For the SG_Camera object:

enum sg_camera_pmode pmode	Effective projection mode, one of SG_CAMERA_PERSPECTIVE, SG_CAMERA_ORTHOGRAPHIC or SG_CAMERA_USER_PROJ (read-only, use SG_CameraSetPerspective(), SG_CameraSetOrthographic() or SG_CameraSetUser() to set the projection mode).
SG_CameraPolyMode polyFace	Method of rendering for front-facing polygons (read-only, use SG_CameraSetFacePolyMode() to set).
SG_CameraPolyMode polyBack	Method of rendering for back-facing polygons (read-only, use SG_CameraSetBackPolyMode() to set).
M_Real fov	Field of view (in radians).
M_Real aspect	Aspect ratio.
M_Real near	Near clipping plane.
M_Real far	Far clipping plane.
M_Matrix44 userProj	User-specified projection matrix, usually given by SG_CameraSetUser(). The matrix is in column-major format.

HISTORY

The SG_Camera node class first appeared in Agar 1.6.0.