NAME

SG_View — Agar-SG scene rendering widget

SYNOPSIS

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

DESCRIPTION

The SG_View widget renders a SG(3) scene graph from the point of view of a specified SG_Camera(3) node.

INHERITANCE HIERARCHY

AG_Object(3) -> AG_Widget(3) -> SG_View.

INITIALIZATION

SG_View *
SG_ViewNew(AG_Widget *parent, SG *sg, Uint flags);

void
SG_ViewSetBgColor(SG_View *view, const AG_Color *c);

void
SG_ViewKeydownFn(SG_View *view, AG_EventFn fn, const char *fmt, ...);

void
SG_ViewKeyupFn(SG_View *view, AG_EventFn fn, const char *fmt, ...);

void
SG_ViewButtondownFn(SG_View *view, AG_EventFn fn, const char *fmt, ...);

void
SG_ViewButtonupFn(SG_View *view, AG_EventFn fn, const char *fmt, ...);

void
SG_ViewMotionFn(SG_View *view, AG_EventFn fn, const char *fmt, ...);

The SG_ViewNew() function allocates, initializes, and attaches a SG_View object. Acceptable flags options include:

SG_VIEW_HFILL

Expand horizontally in parent container.

SG_VIEW_VFILL

Expand vertically in parent container. Shorthand for SG_VIEW_HFILL | SG_VIEW_VFILL.

SG_VIEW_NO_LIGHTING

Disable lighting calculations.

SG_VIEW_NO_DEPTH_TESTS

Disable Z-buffering.

SG_VIEW_CAMERA_STATUS

Display active camera status as overlay.

SG_VIEW_EDIT

Allow edition commands.

SG_VIEW_BGFILL

Fill background with the specified color (see SG_ViewSetBgColor()).

SG_ViewNew() may fail returning NULL if there is no default camera (e.g., ‘Camera0’ node) in the scene.

SG_ViewSetBgFill() specifies a background color c (effective only if SG_VIEW_BGFILL is set).

The SG_View*Fn() functions are used to set up optional callback functions to invoke upon specific GUI events. SG_ViewKeydownFn() and SG_ViewKeyupFn() set callbacks for ‘key-down’ and ‘key-up’ events. SG_ViewButtondownFn(), SG_ViewButtonupFn() and SG_ViewMotionFn() set callbacks for ‘mouse-button-down’, ‘mouse-button-up’ and ‘mouse-motion’ events, respectively.

SCENE TRANSITIONS

int
SG_ViewTransition(SG_View *view, SG *sg, SG_Camera *cam, Uint flags);

void
SG_ViewSetFadeColor(SG_View *view, const AG_Color *c);

void
SG_ViewSetFadeDuration(SG_View *view, Uint ms);

The SG_ViewTransition() function arranges for a transition to a new scene sg and camera cam. If the cam argument is NULL, the default camera is used. By default, the transition is immediate. The following flags are accepted:

SG_VIEW_TRANSFADE

Fade-out and fade-in to the new scene. The function will return immediately (caller can poll transProgress to determine completeness; see “STRUCTURE DATA”).

SG_ViewTransition() may fail and return NULL if a camera could not be found or a transition is already in progress.

SG_ViewSetFadeColor() sets a fill color for the SG_VIEW_TRANSFADE effect.

SG_ViewSetFadeDuration() configures the duration of the fade effect in milliseconds.

CAMERAS AND PROJECTIONS

void
SG_ViewSetCamera(SG_View *view, SG_Camera *cam);

void
SG_ViewUnProject(SG_View *view, int x, int y, M_Vector3 *vOut);

The SG_ViewSetCamera() function changes the current camera of the view.

The SG_ViewUnProject() function translates the given two-dimensional view (widget) coordinates x, y to 3D world coordinates in vOut, according to the active camera's position, orientation and projection. The returned point is coincident with the camera's near plane.

STRUCTURE DATA

For the AG_SG_View object:

SG *sg

Pointer to the active SG(3) object (read-only; use SG_ViewTransition()).

SG *sgTrans

Transition in progress to this scene (read-only).

float transProgress

Progress of the scene transition (-1.0 = start, 0.0 = midway, +1.0 = done).

SG_Camera *cam

Active camera (read-only; use SG_ViewSetCamera()).

SG_Camera *camTrans

Transition in progress to this camera (read-only).

SEE ALSO

M_Matrix(3), M_Real(3), M_Vector(3), SG(3), SG_Camera(3), SG_Intro(3)

HISTORY

The SG_View widget first appeared in Agar 1.6.0.