diguyViewCamera.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2016 VT MAK
 ** All rights reserved. 
 *********************************************************************/

/*********************************************************************
 **
 *t  diguyViewCamera
 **
 */

#ifndef __diguyViewCamera_H
#define __diguyViewCamera_H

#ifdef SWIG
%module diguyViewCamera
#else
#define CPLUSPLUS_ONLY
#endif

#ifdef CPLUSPLUS_ONLY
class bdiCamera;
class diguyViewCamera;
class diguyViewCameraSettings;

#include <stdio.h> // for NULL definition
#include <diguy_constants.h>
#include <diguy_typedefs.h>


#endif


#include <declspec_diguy.h>

class BDI_DECLSPEC_diguy diguyViewCamera
{

public:

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Returns the name of the object.  This pointer will never be NULL.
         **
         *b  Returns:
         **
         **    name of the object
         */
        const char* get_name();

        /*l
         *b  Description:
         **
         **    Returns the type name of the object.  This pointer will never be
         **    NULL.
         **
         *b  Returns:
         **
         **    type name of the object
         */
        const char* get_type_name();

        /*l
         *b  Description:
         **
         **    This sets the distance from the camera to the near plane.
         **
         *b  Arguments:
         **
         *a    near_plane - distance to near plane, in meters
         */
        void set_near_plane(float near_plane);

        /*l
         *b  Returns:
         **
         **    distance from the camera to the near plane, in meters
         */
        float get_near_plane();

        /*l
         *b  Description:
         **
         **    This sets the distance from the camera to the far plane.
         **
         *b  Arguments:
         **
         *a    far_plane - distance to far plane, in meters
         */
        void set_far_plane(float far_plane);

        /*l
         *b  Returns:
         **
         **    distance from the camera to the far plane, in meters
         */
        float get_far_plane();

        /*l
         *b  Description:
         **
         **    This sets the field-of-view of the current camera.
         **
         *b  Arguments:
         **
         *a    fov - field-of-view, in degrees
         */
        void set_fov(float fov);

        /*l
         *b  Description:
         **
         **    This sets the maximum field-of-view of the current camera. This
         **    affects the FOV that can be set via set_fov.
         **
         *b  Arguments:
         **
         *a    fov - max field-of-view, in degrees
         */
        void set_max_fov(float fov);

        /*l
         *b  Description:
         **
         **    This sets the minimum field-of-view of the current camera. This
         **    affects the FOV that can be set via set_fov.
         **
         *b  Arguments:
         **
         *a    fov - min field-of-view, in degrees
         */
        void set_min_fov(float fov);

        /*l
         *b  Returns:
         **
         **    field-of-view of the camera, in degrees
         */
        float get_fov();

        /*l
         *b  Returns:
         **
         **    min field-of-view of the camera, in degrees
         */
        float get_min_fov();

        /*l
         *b  Returns:
         **
         **    max field-of-view of the camera, in degrees
         */
        float get_max_fov();

        /*l
         *b  Description:
         **
         **    This function sets the aspect ratio of the camera.
         **
         *b  Arguments:
         **
         *a    aspect - aspect ratio; 1.3333 (4/3) is the default
         */
        void set_aspect(float aspect);

        /*l
         *b  Returns:
         **
         **    aspect ratio of the camera
         */
        float get_aspect();

        /*l
         *b  Description:
         **
         **    Sets whether or not the orientation and position offsets have any effect.
         **    See the class-level comments for explanations of these.
         */
        void set_offsets_active(int value);

        /*l
         *b  Description:
         **
         **    Returns whether or not the orientation and position offsets have any effect.
         */
        int get_offsets_active();
        
        /*l
         *b  Description:
         **
         **    This function sets the base position of the camera. Will not work if a dolly
         **    character has been set.
         **
         *b  Arguments:
         **
         *a    x, y, z - position in meters from the origin
         */
        void set_base_position(float x, float y, float z);

        /*l
         *b  Description:
         **
         **    This function sets the base position of the camera, and disables the offsets. 
         **    Will not work if a dolly character has been set.
         */
        void set_position(float x, float y, float z);

        /*l
         *b  Description:
         **
         **    Gets the base position of the camera.
         **
         *b  Returns:
         **
         **    x, y, and z, in meters
         */     
        void get_base_position(float *x, float *y, float *z);

        /*l
         *b  Returns:
         **
         **    x position, in meters from the origin. Not necessarily the base position of the system, but the actual 
         **    position of the camera itself.
         */
        float get_position_x();

        /*l
         *b  Returns:
         **
         **    y position, in meters from the origin. Not necessarily the base position of the system, but the actual 
         **    position of the camera itself.
         */
        float get_position_y();

        /*l
         *b  Returns:
         **
         **    z position, in meters from the origin. Not the base position of the system, but the actual 
         **    position of the camera itself.
         */
        float get_position_z();

        /*l
         *b  Description:
         **
         **    This function sets the desired base position of the camera. The camera will
         **    interpolate over time to this position.
         **
         *b  Arguments:
         **
         *a    x, y, z - position in meters from the origin
         */
        void set_desired_base_position(float x, float y, float z);

        /*l
         *b  Description:
         **
         **    Sets the desired base position and disables any offsets.
         **
         *b  Arguments:
         **
         *a    x, y, z - position in meters from the origin
         *a    preserve_fix - obsolete, but kept for backwards compatibility
         */
        void set_desired_position(float x, float y, float z, bool preserve_fix = false);

        /*l
         *b  Description:
         **
         **    This function sets the position offset of the camera. See the
         **    class-level documentation for an explanation. Note that calls to
         **    set_position_offset_is_in_world_coordinates() might change the effect of
         **    this function.
         **
         *b  Arguments:
         **
         *a    x, y, z - position in meters from the origin
         */
        void set_position_offset(float x, float y, float z);

        /*l
         *b  Description:
         **
         **    This function sets the desired position offset of the camera. The camera will
         **    interpolate over time to this position.
         **
         *b  Arguments:
         **
         *a    x, y, z - position in meters from the origin
         */
        void set_desired_position_offset(float x, float y, float z);

        /*l
         *b  Description:
         **
         **    Gets the position offset of the camera. Note that it might be
         **    relative to the base position *and* the base orientation, or just to
         **    the base position
         **
         *b  Returns:
         **
         **    x, y, and z, in meters
         */     
        void get_position_offset(float *x, float *y, float *z);

        /*l
         *b  Description:
         **
         **    Sets whether or not the position offset is relative to both base
         **    position and orientation, or just the position.
         */
        void set_position_offset_is_in_world_coordinates(int value);
        
        /*l
         *b  Returns:
         **
         **    Setting of position_offset_is_in_world_coordinates
         */     
        int get_position_offset_is_in_world_coordinates();

        /*l
         *b  Description:
         **
         **    This function sets the base orientation of the camera.  Note that this
         **    causes a new fix point to be derived.
         **
         **    *NOTE*:  Pitch angles are positive for looking down, not up!
         **
         *b  Arguments:
         **
         *a    yaw   - rotation about z axis, in degrees
         *a    roll  - rotation about x axis, in degrees
         *a    pitch - rotation about y axis, in degrees
         */
        void set_base_orientation(float yaw, float roll, float pitch);

        /*l
         *b  Description:
         **
         **    This function sets the base orientation of the camera. It will disable
         **    the offsets.
         */
        void set_orientation(float yaw, float roll, float pitch);

        /*l
         *b  Description:
         **
         **    This function sets the roll value of the camera's base orientation.
         **
         *b  Arguments:
         **
         *a    roll - rotation about x axis, in radians
         */
        void set_orientation_roll(float roll);

        /*l
         *b  Returns:
         **
         **    yaw. roll, pitch. The actual orientation, with base orientation and offset
         *     orientation both applied.
         */
        void get_orientation(float *yaw, float *roll, float *pitch);

        /*l
         *b  Returns:
         **
         **    rotation about z axis, in degrees.
         */
        float get_orientation_yaw();

        /*l
         *b  Returns:
         **
         **    rotation about x axis, in degrees
         */
        float get_orientation_roll();

        /*l
         *b  Returns:
         **
         **    rotation about y axis, in degrees
         */
        float get_orientation_pitch();

        /*l
         *b  Description:
         **
         **    This function sets the desired base orientation of the camera, which
         **    will be interpolated to over time.
         **
         **    *NOTE*: Pitch angles are positive for looking down, not up!
         **
         *b  Arguments:
         **
         *a    yaw   - rotation about z axis, in degrees
         *a    roll  - rotation about x axis, in degrees
         *a    pitch - rotation about y axis, in degrees
         */
        void set_desired_base_orientation(float yaw, float roll, float pitch);

        /*l
         *b  Description:
         **
         **    Sets the lower limit of the camera pitch *up*.  Default is
         **    very close to -90 degrees.
         **
         **    *NOTE*:  Pitch angles are positive for looking down, not up!
         **
         *b  Arguments:
         **
         *a    limit - rotation about y axis, in degrees
         */
        void set_pitch_lower_limit(float limit);

        /*l
         *b  Returns:
         **
         **    lower limit of the camera pitch (up/down)
         */
        float get_pitch_lower_limit();

        /*l
         *b  Description:
         **
         **    Sets the upper limit of the camera pitch *down*.  Default is
         **    very close to 90 degrees.
         **
         **    *NOTE*:  Pitch angles are positive for looking down, not up!
         **
         *b  Arguments:
         **
         *a    limit - rotation about y axis, in degrees
         */
        void set_pitch_upper_limit(float limit);

        /*l
         *b  Returns:
         **
         **    upper limit of the camera pitch (up/down)
         */
        float get_pitch_upper_limit();

        /*l
         *b  Returns:
         **
         **    1 if pitch has limits, 0 if not
         */
        int get_pitch_has_limits();

        /*l
         *b  Description:
         **
         **    The degimbalize angle is intended to compensate for a situation
         **   that occurs when a camera passes directly over or under the thing
         **   it is fixed on. Normally, this leads to the yaw suddenly flipping
         **   180 degrees. When the degimbalize angle is set, the camera is
         **   blocked from coming within that many degrees of the vertical.
         **   Instead, it will move along a circle around the pole.
         **
         **   Normally, this value is set to zero. The units are degrees.
         */
        void set_degimbalize_angle(float angle);

        /*l
         *b  Returns:
         **
         **    Current degimbalize angle, in degrees.
         */
        float get_degimbalize_angle();

        /*l
         *b  Description:
         **
         **    This function sets the orientation offset of the camera. See the
         **    class-level documentation for an explanation. Note that calls to
         **    set_orientation_offset_is_relative() might change the effect of
         **    this function.
         **
         *b  Arguments:
         **
         *a    yaw   - rotation about z axis, in degrees
         *a    roll  - rotation about x axis, in degrees
         *a    pitch - rotation about y axis, in degrees
         */
        void set_orientation_offset(float yaw, float roll, float pitch);

        /*l
         *b  Description:
         **
         **    Gets the orientation offset of the camera. Note that it might be
         **    relative to the base orientation, or relative to world axes.
         **
         *b  Returns:
         **
         **    yaw, pitch, roll, in degrees
         */     
        void get_orientation_offset(float *yaw, float *roll, float *pitch);

        /*l
         *b  Description:
         **
         **    This function sets the desired orientation offset of the camera, which
         **    will be interpolated to over time.
         **
         **    *NOTE*: Pitch angles are positive for looking down, not up!
         **
         *b  Arguments:
         **
         *a    yaw   - rotation about z axis, in degrees
         *a    roll  - rotation about x axis, in degrees
         *a    pitch - rotation about y axis, in degrees
         */
        void set_desired_orientation_offset(float yaw, float roll, float pitch);

        /*l
         *b  Description:
         **
         **    This function sets the distance from the position to the fix
         **    point.  This may move the fix point or the position of the camera,
         **    depending on locking.
         **
         *b  Arguments:
         **
         *a    distance - distance in meters
         */
        void set_distance(float distance);

        /*l
         *b  Description:
         **
         **    This function sets the maximum allowed distance from the position
         **    to the fix point.
         **
         *b  Arguments:
         **
         *a    distance - distance in meters; set to -1 if no max to be used
         */
        void set_max_track_distance(float distance);

        /*l
         *b  Description:
         **
         **    This function sets the minimum allowed distance from the position
         **    to the fix point.
         **
         *b  Arguments:
         **
         *a    distance - distance in meters; set to -1 if no min to be used
         */
        void set_min_track_distance(float distance);

        /*l
         *b  Returns:
         **
         **    distance from position to fix point, in meters
         */
        float get_distance();

        /*l
         *b  Returns:
         **
         **    minimum allowed tracking distance, in meters; will be less than
         **    zero if not applicable
         */
        float get_min_track_distance();

        /*l
         *b  Returns:
         **
         **    maximum allowed tracking distance, in meters; will be less than
         **    zero if not applicable
         */
        float get_max_track_distance();

        /*l
         *b  Description:
         **
         **    This function sets the fix point of the camera. Note that this
         **    affects the orientation. It may also move the camera, depending
         **    on orientation locking.
         **
         *b  Arguments:
         **
         *a    x, y, z - position in meters from the origin
         */
        void set_fix(float x, float y, float z);

        /*l
         *b  Description:
         **
         **    Causes the camera to lose whatever fix point it was pointed at. 
         **    The camera will simply maintain its current orientation until
         **    a new orientation is assigned. Only has a visible effect if the 
         **    camera is in motion.
         **
         */
        void release_fix();

        /*l
         *b  Returns:
         **
         **    fix point in x, in meters. If camera is tracking, the fix point will still
         **    be in absolute world coordinates.
         */
        float get_fix_x();

        /*l
         *b  Returns:
         **
         **    fix point in y, in meters. If camera is tracking, the fix point will still
         **    be in absolute world coordinates.
         */
        float get_fix_y();

        /*l
         *b  Returns:
         **
         **    fix point in z, in meters. If camera is tracking, the fix point will still
         **    be in absolute world coordinates.
         */
        float get_fix_z();

        /*l
         *b  Description:
         **
         **    This function sets the desired fix point of the camera. The camera
         **    will interpolate to there from its current fix over time.
         **
         *b  Arguments:
         **
         *a    x, y, z - position in meters from the origin
         */
        void set_desired_fix(float x, float y, float z);

        /*l
         *b  Description:
         **
         **    This function sets the movement mode of the camera.
         **
         **    In DI-Guy Scenario in Camera Input Mode, the movement mode of the
         **    camera determines what will happen when mouse buttons are pressed
         **    in the view window.
         **
         *b  Arguments:
         **
         *a    move_mode - new movement mode of the camera; enumeration
         *a                of type diguyViewCameraMoveMode
         **
         *a    DIGUY_CAMERA_MOVE_DRAG  -        mouse input drags and rotates
         *a                                                                     the landscape (from user's perspective)
         *a                                                                     in a manner similar to an RTS game
         *a    DIGUY_CAMERA_MOVE_ORBIT  -       mouse input causes the camera to
         *a                                                                     circle around a fix point or a
         *a                                                                     tracked character
         *a    DIGUY_CAMERA_MOVE_FORWARD  - left mouse press moves camera
         *a                                 forward, right mouse press moves
         *a                                 camera back
         *a    DIGUY_CAMERA_MOVE_SIDEWAYS - left mouse press moves camera
         *a                                 left, right mouse press moves
         *a                                 camera right
         *a    DIGUY_CAMERA_MOVE_VERTICAL - left mouse press moves camera
         *a                                 up, right mouse press moves
         *a                                 camera down
         **
         **    Note: entering forward, sideways, or vertical mode will cause the
         **    camera to stop tracking any entity currently being tracked. It's
         **    impossible to fly the camera around the world and keep it fixed to
         **    a target at the same time.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_move_mode(diguyViewCameraMoveMode move_mode);

        /*l
         *b  Returns:
         **
         **    the most recent setting made by set_move_mode()
         */
        diguyViewCameraMoveMode get_move_mode();

        /*l
         *b  Description:
         **
         **    This function sets the movement speed of the camera when the
         **    camera is translating due to user input.
         **
         **    In DI-Guy Scenario in Camera Input Mode, the movement speed of the
         **    camera determines how fast the camera will move when mouse buttons
         **    are pressed in the view window.
         **
         *b  Arguments:
         **
         *a    speed - speed of camera movement is meters per second
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_speed(float speed);

        /*l
         *b  Returns:
         **
         **    the most recent setting made by set_speed()
         */
        float get_speed();

        /*l
         *b  Description:
         **
         **    This function increases the movement speed of the camera
         **    when the camera is translating due to user input.  The
         **    increase is typically by a factor of 2.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int increase_speed();

        /*l
         *b  Description:
         **
         **    This function decreases the movement speed of the camera
         **    when the camera is translating due to user input.  The
         **    decrease is typically by a factor of 2.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int decrease_speed();

        /*l
         *b  Description:
         **
         **    This function sets the projection mode of the camera.
         **
         **    In DI-Guy Scenario in Camera Input Mode, the movement
         **    mode of the camera determines what will happen when
         **    mouse buttons are pressed in the view window.
         **
         *b  Arguments:
         **
         *a    projection_mode - new projection mode of the camera;
         *a                      enumeration of type
         *a                      diguyViewCameraProjectionMode
         **
         *a    DIGUY_CAMERA_PROJECTION_PERSPECTIVE - standard perspective
         *a                                          camera, can move and
         *a                                          rotate freely
         *a    DIGUY_CAMERA_PROJECTION_PLANVIEW_XY - always views in negative
         *a                                          Z direction
         *a    DIGUY_CAMERA_PROJECTION_PLANVIEW_XZ - always views in negative
         *a                                          Y direction
         *a    DIGUY_CAMERA_PROJECTION_PLANVIEW_YZ - always views in negative
         *a                                          X direction
         **
         *b  Notes:
         **
         **    In projection modes, only the fix point and the distance from it
         **  can be changed. Dollying and tracking are each possible, and
         **  effectively the same, but can't be done at once.
         **
         */
        int set_projection_mode(diguyViewCameraProjectionMode projection_mode);

        /*l
         *b  Returns:
         **
         **    the most recent setting made by set_projection_mode()
         */
        diguyViewCameraProjectionMode get_projection_mode();

        void set_height_above_terrain(float height);

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Loads the specified settings into this camera.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int load_settings(const char* settings_name);

        /*l
         *b  Description:
         **
         **    Loads the specified settings into this camera.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int load_settings(diguyViewCameraSettings* settings);

        /*l
         *b  Description:
         **
         **    This function applies this camera's settings and internal
         **    state to the actual view frustrum. It should be called as
         **    often as the camera needs to be updated. Note that code that
         **    controls the camera's motions (e.g. when the camera is
         **    tracking a character) gets called via 
         **    diguyScenario::update().
         **
         *i  OpenGL Version:
         **
         **    This function sets the current viewpoint in these
         **    environments based on information in this camera.
         **
         *i  Direct3D Version:
         **
         **    This function has no effect.  The viewpoint in
         **    these environments must be set manually.
         */
        void apply_settings();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets the base position of this camera using
         **    double precision floating point numbers.  The numbers
         **    will be converted internally into a DI-Guy far position.
         **
         *b  Arguments:
         **
         *a    x - x position, in meters
         *a    y - y position, in meters
         *a    z - z position, in meters
         */
        void set_base_position_double(double x, double y, double z);

        /*l
         *b  Description:
         **
         **  Equivalent to set_base_position_double(), but disables offsets.
         */
        void set_position_double(double x, double y, double z);

        /*l
         *b  Description:
         **
         **    Gets the base position of the camera.
         **
         *b  Returns:
         **
         **    x, y, and z, in meters
         */     
        void get_base_position_double(double *x, double *y, double *z);

        /*l
         *b  Description:
         **
         **    This function returns the world-space position of this
         **    camera.  These values are computed from the DI-Guy
         **    far position of the camera.  The results are placed into
         **    the passed pointers. If camera is dollied, the position will 
         **    still indicate its absolute world coordinates.
         **
         *b  Arguments:
         **
         *a    x - x position, in meters
         *a    y - y position, in meters
         *a    z - z position, in meters
         */
        void get_position_double(double* x, double* y, double* z);

        /*l
         *b  Description:
         **
         **    This function returns the world-space origin of the far
         **    position segment the camera is in.  This segment origin
         **    plus the position segment offset returned by
         **    get_position_segment_offset() yields the final world-space
         **    position of the camera.
         **
         **    The results are placed into the passed pointers.
         **
         *b  Arguments:
         **
         *a    x - x component of origin, in meters
         *a    y - y component of origin, in meters
         *a    z - z component of origin, in meters
         */
        void get_segment_origin(float* x, float* y, float* z);

        /*l
         *b  Description:
         **
         **    This function returns the far position segment offset
         **    part of the camera's base position.  The results are placed
         **    into the passed pointers.
         **
         *b  Arguments:
         **
         *a    x - x component of segment offset, in meters
         *a    y - y component of segment offset, in meters
         *a    z - z component of segment offset, in meters
         */
        void get_position_segment_offset(float* x, float* y, float* z);

        /*l
         *b  Description:
         **
         **    This function returns the far position offset portion of
         **    the camera's fix point.  The results are placed into the
         **    passed pointers.
         **
         *b  Arguments:
         **
         *a    x - x component of fix segment offset, in meters
         *a    y - y component of fix segment offset, in meters
         *a    z - z component of fix segment offset, in meters
         */
        void get_fix_segment_offset(float* x, float* y, float* z);

        /*l
         *b  Description:
         **
         **    This function sets the fix point of the camera using
         **    double precision floating point numbers.  The numbers
         **    will be converted internally into a DI-Guy far position. Note
         **    that this affects the orientation.
         **
         *b  Arguments:
         **
         *a    x - x position, in meters
         *a    y - y position, in meters
         *a    z - z position, in meters
         */
        void set_fix_double(double x, double y, double z);

        void convert_to_local_camera(double * x, double * y, double * z);

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets the name of the character the camera should
         **    look at, if such a character can be found.  This will cause
         **    fix values to change over time.
         **
         **    By default the camera will look at the idealized position of
         **    the character (a spot on the ground typically under the center
         **    of gravity for human characters).  To look at a particular part
         **    of a character, call set_track_link_name().
         **
         **    The spot looked at on a link can be offset by calling
         **    set_track_offset().  Whether the offset is in world coordinates
         **    or character-local coordinates is controlled by a call to
         **    set_track_offset_is_in_world_coordinates().
         **
         **    Note that tracking and dollying can be combined. For example, 
         **    picture a camera affixed to a pedestrian walking along. The
         **    camera might track a car going by in a different direction. The 
         **    dolly entity and the tracked entity can even be the same.
         **
         **        Setting a track entity will change the movement mode of the camera
         **    to stationary or orbit. This is because the camera can't be flown
         **    around the world if it is fixed on something.
         **
         *b  Arguments:
         **
         *a    track_name - name of character to look at, or NULL if no character
         *a                 is to be tracked
         **
         **
         *b  C++ Example
         **
         **   The following example shows how to use some of the pose
         **   functions.
         **
         *e     //
         *e     //  Get a pointer to the primary view's camera, and
         *e     //  to the first character.
         *e     //
         *e     diguyViewCamera* camera = scenario->get_scenario_camera();
         *e     diguyCharacter* character = scenario->get_character_at_index(0);
         *e
         *e     //
         *e     //  Look just a little bit above the character's head.
         *e     //
         *e     camera->set_track_name(character->get_name());
         *e     camera->set_track_link_name("cervical");
         *e     camera->set_track_offset(0.0f, 0.0f, 0.1f);
         */
        void set_track_name(const char* track_name);

        /*l
         *b  Returns:
         **
         **    name of character to be looked at; see set_track_name()
         */
        const char* get_track_name();

        /*l
         *b  Description:
         **
         **    This function sets the name of the group the camera will track.
         **
         *b  Arguments:
         **
         *a    track_name - name of group to look at; pass NULL to un-set track
         *a                 group
         */
        void set_track_group_name(const char* track_name);

        /*l
         *b  Returns:
         **
         **    name of group to be looked at; see set_track_group_name()
         */
        const char* get_track_group_name();

        /*l
         *b  Description:
         **
         **    This function sets the name of the link to be tracked on
         **    the character specified by set_track_name().  See
         **    set_track_name() for more information.
         **
         *b  Arguments:
         **
         *a    track_link_name - name of link to look at, or NULL if the base
         *a                      link is to be tracked
         */
        void set_track_link_name(const char* track_link_name);

        /*l
         *b  Returns:
         **
         **    name of link to be looked at; see set_track_link_name()
         */
        const char* get_track_link_name();

        /*l
         *b  Description:
         **
         **    This function sets the position of the look-at point relative
         **    to the tracked entity. Note that this overrides any position
         **    given to set_fix().
         **
         **    Whether the offset is in world coordinates or character-local
         **    coordinates is controlled by a call to
         **    set_track_offset_is_in_world_coordinates().
         **
         *b  Arguments:
         **
         *a    x, y, z - offset, in meters, of track point
         */
        void set_track_offset(float x, float y, float z);

        /*l
         *b  Returns:
         **
         **    x component of track offset; see set_track_offset()
         */
        float get_track_offset_x();

        /*l
         *b  Returns:
         **
         **    y component of track offset; see set_track_offset()
         */
        float get_track_offset_y();

        /*l
         *b  Returns:
         **
         **    z component of track offset; see set_track_offset()
         */
        float get_track_offset_z();

        /*l
         *b  Description:
         **
         **    This function sets whether the offset of the track
         **    position is character-relative (pass 0) or in
         **    world coordinates (pass 1).
         **
         **    Default value is 0.
         **
         *b  Arguments:
         **
         *a    value - pass 0 for character-relative, 0 for world coordinates
         */
        void set_track_offset_is_in_world_coordinates(int value);

        /*l
         *b  Returns:
         **
         **    the most recent setting made by set_track_offset_is_in_world_coordinates().
         */
        int get_track_offset_is_in_world_coordinates();

        /*l
         *b  Description:
         **
         **    Sets the dolly entity. The "dolly" is the character that the camera 
         **    "rides" on, though at an offset. Picture the camera cart commonly 
         **    used in film-making, with the camera viewing the subject from the 
         **    end of a crane that extends out from the cart. The cart would be the
         **    dolly character.
         **
         **    Once you set a dolly character, you lose the ability to set the base
         **    position and orientation of the camera. However, you can still set the
         **    position offset and the orientation offset.
         **
         **    Note that tracking and dollying can be combined. For example, 
         **    picture a camera affixed to a pedestrian walking along. The
         **    camera might track a car going by in a different direction. The 
         **    dolly entity and the tracked entity can even be the same.
         **
         **    Setting a dolly entity may switch the camera's movement mode to orbit,
         **    if the character is already tracking something. The tracked entity will
         **    be orbited, but if the dolly character moves, the camera will still maintain
         **    its position relative to that character.
         **
         *b  Arguments:
         **
         *a    dolly_name - name of entity to look from, or NULL if none
         */
        void set_dolly_name(const char* dolly_name);

        /*l
         *b  Description:
         **
         **    This function gets the name of the dolly entity.
         **
         *b  Arguments:
         **
         *a    dolly_name - name of character to look from, or NULL
         */
        const char* get_dolly_name();

        /*l
         *b  Description:
         **
         **    Sets the position at which the camera will be relative to the 
         **    dolly entity. This function does the same thing as set_position_offset(),
         **        but remains here for backwards compatibility.
         **
         **    Whether the offset is in world coordinates or character-local
         **    coordinates is controlled by a call to
         **    set_dolly_offset_is_in_world_coordinates().
         **
         *b  Arguments:
         **
         *a    x, y, z - offset, in meters, of dolly point
         */
        void set_dolly_offset(float x, float y, float z);

        /*l
         *b  Returns:
         **
         **    x component of position offset; see set_dolly_offset()
         */
        float get_dolly_offset_x();

        /*l
         *b  Returns:
         **
         **    y component of position offset; see set_dolly_offset()
         */
        float get_dolly_offset_y();

        /*l
         *b  Returns:
         **
         **    z component of position offset; see set_dolly_offset()
         */
        float get_dolly_offset_z();

        /*l
         *b  Description:
         **
         **    This function sets the name of the link to be dollied on
         **    the character specified by set_dolly_name().
         **
         *b  Arguments:
         **
         *a    dolly_link_name - name of link to look from, or NULL if the
         *a                      position link is to influence camera position
         */
        void set_dolly_link_name(const char* dolly_link_name);

        /*l
         *b  Returns:
         **
         **    name of link to be looked from; see set_dolly_link_name()
         */
        const char* get_dolly_link_name();

        /*l
         *b  Description:
         **
         **    This function sets whether the position offset is character-relative 
         **    (pass 0) or in world coordinates (pass 1).
         **
         **    Default value is 0.
         **
         *b  Arguments:
         **
         *a    value - pass 0 for character-relative, 1 for world coordinates
         */
        void set_dolly_offset_is_in_world_coordinates(int value);

        /*l
         *b  Returns:
         **
         **    the most recent setting made by
         **    set_dolly_offset_is_in_world_coordinates().
         */
        int get_dolly_offset_is_in_world_coordinates();

        /*l
         *b  Description:
         **
         **    Sets whether the camera's orientation offset is relative or not. If it's
         **    relative, it will be in the coordinate system established by the base
         **    orientation (or the orientation of the dolly character). If not relative,
         **    it will be in the world's coordinate system.
         **
         **    For example, setting an orientation of (-90, 0, 0) when the dolly entity
         **    is rolled 45 degrees to the left will cause the camera to look towards
         **    the area to the dolly entity's right, which will be up towards to the
         **    sky. If the dolly entity rolls 90 degrees to the right (from where it
         **    is) the camera will now be facing the ground.
         **
         **    When the camera is tracking something, however, the orientation offset's
         **    yaw and pitch components will be derived.
         **
         **    Default value is 0.
         **
         *b  Arguments:
         **
         *a    value - pass 1 to match orientation, 0 to not match
         */
        void set_orientation_offset_is_relative(int value);

        /*l
         *b  Returns:
         **
         **    the most recent setting made by set_orientation_offset_is_relative().
         */
        int get_orientation_offset_is_relative();

        /*l
         *b  Description:
         **
         **  This function has been deprecated, but remains for backwards compatibility.
         **  It is replaced by set_orientation_offset_is_relative()
         */
        void set_match_dolly_orientation(int value);

        /*l
         *b  Description:
         **
         **  This function has been deprecated, but remains for backwards compatibility.
         **  It is replaced by get_orientation_offset_is_relative()
         */
        int get_match_dolly_orientation();

        /*l
         *b  Description:
         **
         **  If activated, the camera will behave differently when both dollying and tracking.
         **  The base orientation will swivel towards the target. Move the position offset
         **  back a bit, and the dolly character will remain between the camera and target.
         */
        void set_use_special_track_mode(int value);

        /*l
         *b  Returns:
         **
         **    1, if special track mode is being used.
         */
        int get_use_special_track_mode();

        /*l
         *b  Returns:
         **
         **    if DI-Guy Scenario is rendering simplified 2D representations of
         **    characters.
         */
        int get_symbolic_view();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This is an enumeration of the different callbacks
         **    that can be registered with add_callback() and
         **    add_callback_script().
         **
         *b  Usable From:
         **
         *-    - C++
         *-    - Script
         */
        enum {
                CALLBACK_ID_SETTINGS_CHANGED = 1
        };

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function adds a user callback.
         **
         *b  Arguments:
         **
         *a    callback        - pointer to function with prototype
         *a                      diguyViewCameraCallback (typedefed above)
         *a    callback_id     - integer id of when this callback is to be called
         *a    callback_params - struct containing additional parameters
         *a                      needed by some callbacks; actual type depends
         *a                      on callback_id
         *a    callback_user_data - pointer for user's own use; DI-Guy will
         *a                         do nothing to the contents of this pointer
         *a                         beyond passing it back when the callback is
         *a                         invoked
         **
         **    callback_id should be one of the following values:
         **
         *i    CALLBACK_ID_SETTINGS_CHANGED
         **
         **      This callback will be called if the current settings of this
         **      camera change
         **
         **    Callbacks return a value of type diguyCallbackReturn,
         **    which will be DIGUY_CALLBACK_STOP or DIGUY_CALLBACK_CONTINUE.
         **    If the callback returns DIGUY_CALLBACK_STOP, the default handler
         **    of the function will not be called; the callback is asserting
         **    that it has done everything necessary for the function call.
         **    If the callback returns DIGUY_CALLBACK_CONTINUE, the default
         **    handler for the function will be called after the callback.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int add_callback(int callback_id,
                diguyViewCameraCallback* callback,
                void* callback_params = 0,
                void* callback_user_data = 0);

        /*l
         *b  Description:
         **
         **    This function removes a user callback.  All callbacks matching
         **    the specified callback_id and callback function will be removed.
         **
         *b  Arguments:
         **
         *a    callback_id     - integer id of when this callback is to be called
         *a    callback        - pointer to function with prototype
         *a                      diguyViewCameraCallback (typedefed above)
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_callback(int callback_id,
                diguyViewCameraCallback* callback);

        /*l
         *b  Description:
         **
         **    This function removes a user callback.  All callbacks matching
         **    the specified callback_id and callback_user_data pointer will
         **    be removed.
         **
         *b  Arguments:
         **
         *a    callback_id        - integer id of when this callback is to be called
         *a    callback_user_data - pointer for user's own use
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_callback_with_user_data(int callback_id,
                void* callback_user_data);

#endif

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function adds a user callback script.  Callback scripts can
         **    be removed with remove_callback_script().
         **
         *b  Arguments:
         **
         *a    callback_id          - integer id of the callback
         *a    callback_script      - script text of callback to be added
         *a    callback_script_type - the type of script contained in
         *a                           callback_script
         **
         **    If NULL is passed for callback_script_type, a default script type
         **    will be derived based on the default script interpreter of the
         **    scenario.
         **
         *i  lua specific:
         **
         **    When the script is called, the object for which it is being called
         **    will be in the callback_object local.
         **
         **    To pass NULL when calling from a lua script, use nil.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int add_callback_script(int callback_id,
                const char* callback_script,
                const char* callback_script_type = NULL);

        /*l
         *b  Description:
         **
         **    This function removes a user callback script previously added with
         **    add_callback_script().
         **
         *b  Arguments:
         **
         *a    callback_id          - integer id of the callback
         *a    callback_script      - script text of callback previously added
         *a    callback_script_type - the type of script contained in
         *a                           callback_script
         **
         **    If NULL is passed for callback_script, all callback
         **    scripts whose ids match callback_id and whose types match
         **    callback_script_type will be removed.
         **
         **    If NULL is passed for callback_script_type, a default script type
         **    will be derived based on the default script interpreter of the
         **    scenario.
         **
         *i  lua specific:
         **
         **    To pass NULL when calling from a lua script, use nil.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_callback_script(int callback_id,
                const char* callback_script,
                const char* callback_script_type = NULL);


/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

        /*l
        **    Prints information about the camera's current state to the log.
        */
        void print_debug_info(const char *tag);
        
        /*l
         *b  Description:
         **
         **    Sets number of degrees by which the camera FOV should change
         **    whenever the user moves the mouse wheel.
         **
         *b  Arguments:
         **
         *a    fov_change - change to FOV in degrees
         **
         */
        void set_speed_fov_degrees_per_wheel_click(float fov_change);

        /*l
         *b  Description:
         **
         **    Gets the number of degrees by which the camera FOV should change
         **    whenever the user moves the mouse wheel.
         **
         *b  Returns:
         **
         **    change to FOV, in degrees
         */
        float get_speed_fov_degrees_per_wheel_click();

        /*l
         *b  Description:
         **
         **    Sets how fast the camera should move in various flyaround modes.
         **
         *b  Arguments:
         **
         *a    speed - flying speed in meters per second
         */
        void set_speed_meters_per_second(float speed);

        /*l
         *b  Description:
         **
         **    Gets how fast the camera should move in various flyaround modes.
         **
         *b  Returns:
         **
         **    speed in meters per second
         */
        float get_speed_meters_per_second();

        /*l
         *b  Description:
         **
         **    Sets whether the camera should smoothly servo to its new desired
         **    position/heading (as opposed to instantly popping there).
         **
         *b  Arguments:
         **
         *a    target (position, orientation, or fix)
         *a    require - 0 for smooth servoing
         */
        void set_require_smooth_servo(diguyViewCameraServoTarget target, int require);

        /*l
         *b  Description:
         **
         **    Similar to main set_require_smooth_servo(), but sets value for all 
         **    targets. Here for backwards compatibility.
         */
        void set_require_smooth_servo(int require);

        /*l
         *b  Description:
         **
         **    Gets whether the camera should smoothly servo to its new desired
         **    position/heading (as opposed to instantly popping there).
         **
         *b  Returns:
         **
         **    1 if smooth servoing is required; 0 if not
         */
        int get_require_smooth_servo(diguyViewCameraServoTarget target);

        /*l
         *b  Description:
         **
         **    Sets a factor that determines how smoothly the camera should servo.
         **    If a high number (e.g. 10.0), the camera will servo quickly. If 
         **    a low number (e.g. 1.0), it will servo more slowly.
         **
         *b  Arguments:
         **
         *a    target (position, orientation, or fix)
         *a    modifier
         */
        void set_servo_time_modifier( diguyViewCameraServoTarget target, float modifier );

        /*l
         *b  Description:
         **
         **    Similar to main set_servo_time_modifier(). Sets value for all targets.
         */
        void set_servo_time_modifier( float modifier );

        /*l
         *b  Returns:
         **
         **    The servo modifier time that determines how smoothly the camera
         **    should servo.
         */
        float get_servo_time_modifier(diguyViewCameraServoTarget target);

        /*l
         *b  Description:
         **
         **    Sets if the camera mover should make an effort to avoid obstacles
         **    that block visibility while a character or group is being tracked.
         **
         *b  Arguments:
         **
         *a    avoids    - true for avoidance
         */
        void set_track_camera_avoids_obstacles(int avoid);

        /*l
         *b  Description:
         **
         **    Gets whether the camera mover should make an effort to avoid
         **    obstacles that block visibility while a character or group is
         **    being tracked.
         **
         *b  Returns:
         **
         **    1 if obstacle avoidance should be attempted
         */
        int get_track_camera_avoids_obstacles();

        /*l
         *b  Description:
         **
         **    Sets if the camera should not respond to mouse input from DI-Guy Scenario.  
         **    In Scenario, responding is the default. In API Mode, not responding is the default.
         **
         *b  Arguments:
         **
         *a    avoids - 1 to ignore mouse drags; 0 if not
         */
        void set_ignore_mouse_drags(int ignore);

        /*l
         *b  Description:
         **
         **    Gets whether the camera should ignore mouse input from DI-Guy Scenario.
         **
         *b  Returns:
         **
         **    1 if mouse drags are to be ignored; 0 if not
         */
        int get_ignore_mouse_drags();

#ifdef CPLUSPLUS_ONLY
        /*l
         *b  Description:
         **
         **    Allows the diguy camera to build an internal frustum needed for
         **    doing character and scene object culling.  projection_matrix and
         **    model_matrix should be pointers to 16 floats in OpenGL style matrix
         **    format.
         ** 
         *b  This function is not callable from lua. 
         */
        void update_frustum(float* proj_matrix, float* model_matrix);

#endif

#ifdef CPLUSPLUS_ONLY

        bdiCamera* get_scripted_object() {return m_camera;}

private:

        /*l
         **  A private constructor.
         */
        diguyViewCamera(bdiCamera* camera);

        /*l
         **  A pointer to internal data.
         */
        bdiCamera* m_camera;

        friend class bdiCamera;

        static bool s_warn_if_position_set_ignored;

#endif

};

#endif /* __diguyViewCamera_H */