diguyViewCamera.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2022 MAK Technologies, Inc.
 ** 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 */