NAME

SG_Camera — Agar-SG camera node

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.