SG_CAMERA(3)

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.

SEE ALSO
M_Matrix(3), M_Real(3), M_Vector(3), SG(3), SG_Intro(3), SG_Light(3), SG_Node(3), SG_View(3)

HISTORY
The SG_Camera node class first appeared in Agar 1.6.0.