SG_VIEW(3)

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.