diguyViewCamera

Generated from diguyViewCamera.h

DI-Guy API Version 12.5.1

This file was automatically generated from diguyViewCamera.h. Do not edit this file directly; the changes will be lost.

Includes: diguy_constants.h | diguy_typedefs.h | declspec_diguy.h

Contents:

Alphabetical Index

class diguyViewCamera

class BDI_DECLSPEC_diguy diguyViewCamera
{
public:
    const char* get_name();
    const char* get_type_name();
    void set_near_plane(float near_plane);
    float get_near_plane();
    void set_far_plane(float far_plane);
    float get_far_plane();
    void set_fov(float fov);
    void set_max_fov(float fov);
    void set_min_fov(float fov);
    float get_fov();
    float get_min_fov();
    float get_max_fov();
    void set_aspect(float aspect);
    float get_aspect();
    void set_position(float x, float y, float z);
    float get_position_x();
    float get_position_y();
    float get_position_z();
    void set_desired_position(float x, float y, float z, bool preserve_fix = false);
    void set_orientation(float yaw, float roll, float pitch);
    void set_orientation_roll(float roll);
    float get_orientation_yaw();
    float get_orientation_roll();
    float get_orientation_pitch();
    void set_pitch_lower_limit(float limit);
    float get_pitch_lower_limit();
    void set_pitch_upper_limit(float limit);
    float get_pitch_upper_limit();
    int get_pitch_has_limits();
    void set_distance(float distance);
    void set_max_track_distance(float distance);
    void set_min_track_distance(float distance);
    float get_distance();
    float get_min_track_distance();
    float get_max_track_distance();
    void set_fix(float x, float y, float z);
    float get_fix_x();
    float get_fix_y();
    float get_fix_z();
    void set_desired_fix(float x, float y, float z);
    int set_move_mode(diguyViewCameraMoveMode move_mode);
    diguyViewCameraMoveMode get_move_mode();
    int set_speed(float speed);
    float get_speed();
    int increase_speed();
    int decrease_speed();
    int set_projection_mode(diguyViewCameraProjectionMode projection_mode);
    diguyViewCameraProjectionMode get_projection_mode();
    int load_settings(const char* settings_name);
    int load_settings(diguyViewCameraSettings* settings);
    void apply_settings();
    void set_position_double(double x, double y, double z);
    void get_position_double(double* x, double* y, double* z);
    void get_segment_origin(float* x, float* y, float* z);
    void get_position_segment_offset(float* x, float* y, float* z);
    void get_fix_segment_offset(float* x, float* y, float* z);
    void set_fix_double(double x, double y, double z);
    void set_track_name(const char* track_name);
    const char* get_track_name();
    void set_track_group_name(const char* track_name);
    const char* get_track_group_name();
    void set_track_link_name(const char* track_link_name);
    const char* get_track_link_name();
    void set_track_offset(float x, float y, float z);
    float get_track_offset_x();
    float get_track_offset_y();
    float get_track_offset_z();
    void set_track_offset_is_in_world_coordinates(int value);
    int get_track_offset_is_in_world_coordinates();
    void set_dolly_name(const char* dolly_name);
    const char* get_dolly_name();
    void set_dolly_offset(float x, float y, float z);
    float get_dolly_offset_x();
    float get_dolly_offset_y();
    float get_dolly_offset_z();
    void set_dolly_link_name(const char* dolly_link_name);
    const char* get_dolly_link_name();
    void set_dolly_offset_is_in_world_coordinates(int value);
    int get_dolly_offset_is_in_world_coordinates();
    int get_symbolic_view();
    enum {
        CALLBACK_ID_SETTINGS_CHANGED = 1
    };
#ifdef CPLUSPLUS_ONLY
    int add_callback(int callback_id,
        diguyViewCameraCallback* callback,
        void* callback_params = 0,
        void* callback_user_data = 0);
    int remove_callback(int callback_id,
        diguyViewCameraCallback* callback);
    int remove_callback_with_user_data(int callback_id,
        void* callback_user_data);
#endif
    int add_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int remove_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    void set_speed_fov_degrees_per_wheel_click(float fov_change);
    float get_speed_fov_degrees_per_wheel_click();
    void set_speed_meters_per_second(float speed);
    float get_speed_meters_per_second();
    void set_require_smooth_servo(int require);
    int get_require_smooth_servo();
    void set_servo_time_modifier( float modifier );
    float get_servo_time_modifier();
    void set_track_camera_avoids_obstacles(int avoid);
    int get_track_camera_avoids_obstacles();
    void set_ignore_mouse_drags(int ignore);
    int get_ignore_mouse_drags();
#ifdef CPLUSPLUS_ONLY
    void update_frustum(float* proj_matrix, float* model_matrix);
#endif

General Functions

All functions in this section are callable from:

C++
Script

function diguyViewCamera::get_name

Prototype:
const char* get_name();
Description:

Returns the name of the object. This pointer will never be NULL.
Returns:

name of the object

function diguyViewCamera::get_type_name

Prototype:
const char* get_type_name();
Description:

Returns the type name of the object. This pointer will never be NULL.
Returns:

type name of the object

function diguyViewCamera::set_near_plane

Prototype:
void set_near_plane(float near_plane);
Description:

This sets the distance from the camera to the near plane.
Arguments:

near_plane distance to near plane, in meters

function diguyViewCamera::get_near_plane

Prototype:
float get_near_plane();
Returns:

distance from the camera to the near plane, in meters

function diguyViewCamera::set_far_plane

Prototype:
void set_far_plane(float far_plane);
Description:

This sets the distance from the camera to the far plane.
Arguments:

far_plane distance to far plane, in meters

function diguyViewCamera::get_far_plane

Prototype:
float get_far_plane();
Returns:

distance from the camera to the far plane, in meters

function diguyViewCamera::set_fov

Prototype:
void set_fov(float fov);
Description:

This sets the field-of-view of the current camera.
Arguments:

fov field-of-view, in degrees

function diguyViewCamera::set_max_fov

Prototype:
void set_max_fov(float fov);
Description:

This sets the maximum field-of-view of the current camera. This affects the FOV that can be set via set_fov.
Arguments:

fov max field-of-view, in degrees

function diguyViewCamera::set_min_fov

Prototype:
void set_min_fov(float fov);
Description:

This sets the minimum field-of-view of the current camera. This affects the FOV that can be set via set_fov.
Arguments:

fov min field-of-view, in degrees

function diguyViewCamera::get_fov

Prototype:
float get_fov();
Returns:

field-of-view of the camera, in degrees

function diguyViewCamera::get_min_fov

Prototype:
float get_min_fov();
Returns:

min field-of-view of the camera, in degrees

function diguyViewCamera::get_max_fov

Prototype:
float get_max_fov();
Returns:

max field-of-view of the camera, in degrees

function diguyViewCamera::set_aspect

Prototype:
void set_aspect(float aspect);
Description:

This function sets the aspect ratio of the camera.
Arguments:

aspect aspect ratio; 1.3333 (4/3) is the default

function diguyViewCamera::get_aspect

Prototype:
float get_aspect();
Returns:

aspect ratio of the camera

function diguyViewCamera::set_position

Prototype:
void set_position(float x, float y, float z);
Description:

This function sets the position of the camera.
Arguments:

x, y, z position in meters from the origin

function diguyViewCamera::get_position_x

Prototype:
float get_position_x();
Returns:

x position, in meters from the origin

function diguyViewCamera::get_position_y

Prototype:
float get_position_y();
Returns:

y position, in meters from the origin

function diguyViewCamera::get_position_z

Prototype:
float get_position_z();
Returns:

z position, in meters from the origin

function diguyViewCamera::set_desired_position

Prototype:
void set_desired_position(float x, float y, float z, bool preserve_fix = false);
Description:

This function sets the desired position of the camera. The camera will interpolate over time to this position.
Arguments:

x, y, z position in meters from the origin

function diguyViewCamera::set_orientation

Prototype:
void set_orientation(float yaw, float roll, float pitch);
Description:

This function sets the orientation of the camera. Note that this affects the fix.

NOTE: Pitch angles are positive for looking down, not up!
Arguments:

yaw rotation about z axis, in degrees
roll rotation about x axis, in degrees
pitch rotation about y axis, in degrees

function diguyViewCamera::set_orientation_roll

Prototype:
void set_orientation_roll(float roll);
Description:

This function sets the roll of the camera.
Arguments:

roll rotation about x axis, in radians

function diguyViewCamera::get_orientation_yaw

Prototype:
float get_orientation_yaw();
Returns:

rotation about z axis, in degrees

function diguyViewCamera::get_orientation_roll

Prototype:
float get_orientation_roll();
Returns:

rotation about x axis, in degrees

function diguyViewCamera::get_orientation_pitch

Prototype:
float get_orientation_pitch();
Returns:

rotation about y axis, in degrees

function diguyViewCamera::set_pitch_lower_limit

Prototype:
void set_pitch_lower_limit(float limit);
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!
Arguments:

limit rotation about y axis, in degrees

function diguyViewCamera::get_pitch_lower_limit

Prototype:
float get_pitch_lower_limit();
Returns:

lower limit of the camera pitch (up/down)

function diguyViewCamera::set_pitch_upper_limit

Prototype:
void set_pitch_upper_limit(float limit);
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!
Arguments:

limit rotation about y axis, in degrees

function diguyViewCamera::get_pitch_upper_limit

Prototype:
float get_pitch_upper_limit();
Returns:

upper limit of the camera pitch (up/down)

function diguyViewCamera::get_pitch_has_limits

Prototype:
int get_pitch_has_limits();
Returns:

1 if pitch has limits, 0 if not

function diguyViewCamera::set_distance

Prototype:
void set_distance(float distance);
Description:

This function sets the distance from the position to the fix point. Note that this affects the fix values.
Arguments:

distance distance in meters

function diguyViewCamera::set_max_track_distance

Prototype:
void set_max_track_distance(float distance);
Description:

This function sets the maximum allowed distance from the position to the fix point.
Arguments:

distance distance in meters; set to -1 if no max to be used

function diguyViewCamera::set_min_track_distance

Prototype:
void set_min_track_distance(float distance);
Description:

This function sets the minimum allowed distance from the position to the fix point.
Arguments:

distance distance in meters; set to -1 if no min to be used

function diguyViewCamera::get_distance

Prototype:
float get_distance();
Returns:

distance from position to fix point, in meters

function diguyViewCamera::get_min_track_distance

Prototype:
float get_min_track_distance();
Returns:

minimum allowed tracking distance, in meters; will be less than zero if not applicable

function diguyViewCamera::get_max_track_distance

Prototype:
float get_max_track_distance();
Returns:

maximum allowed tracking distance, in meters; will be less than zero if not applicable

function diguyViewCamera::set_fix

Prototype:
void set_fix(float x, float y, float z);
Description:

This function sets the fix point of the camera. Note that this affects the orientation.
Arguments:

x, y, z position in meters from the origin

function diguyViewCamera::get_fix_x

Prototype:
float get_fix_x();
Returns:

fix point in x, in meters

function diguyViewCamera::get_fix_y

Prototype:
float get_fix_y();
Returns:

fix point in y, in meters

function diguyViewCamera::get_fix_z

Prototype:
float get_fix_z();
Returns:

fix point in z, in meters

function diguyViewCamera::set_desired_fix

Prototype:
void set_desired_fix(float x, float y, float z);
Description:

This function sets the desired fix point of the camera. The camera will interpolate to there from its current fix over time.
Arguments:

x, y, z position in meters from the origin

function diguyViewCamera::set_move_mode

Prototype:
int set_move_mode(diguyViewCameraMoveMode move_mode);
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.
Arguments:

move_mode new movement mode of the camera; enumeration of type diguyViewCameraMoveMode
DIGUY_CAMERA_MOVE_FORWARD left mouse press moves camera forward, right mouse press moves camera back
DIGUY_CAMERA_MOVE_SIDEWAYS left mouse press moves camera left, right mouse press moves camera right
DIGUY_CAMERA_MOVE_VERTICAL left mouse press moves camera up, right mouse press moves camera down
Returns:

0 on success, -1 on failure

function diguyViewCamera::get_move_mode

Prototype:
diguyViewCameraMoveMode get_move_mode();
Returns:

the most recent setting made by set_move_mode()

function diguyViewCamera::set_speed

Prototype:
int set_speed(float speed);
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.
Arguments:

speed speed of camera movement is meters per second
Returns:

0 on success, -1 on failure

function diguyViewCamera::get_speed

Prototype:
float get_speed();
Returns:

the most recent setting made by set_speed()

function diguyViewCamera::increase_speed

Prototype:
int increase_speed();
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.
Returns:

0 on success, -1 on failure

function diguyViewCamera::decrease_speed

Prototype:
int decrease_speed();
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.
Returns:

0 on success, -1 on failure

function diguyViewCamera::set_projection_mode

Prototype:
int set_projection_mode(diguyViewCameraProjectionMode projection_mode);
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.
Arguments:

projection_mode new projection mode of the camera; enumeration of type diguyViewCameraProjectionMode
DIGUY_CAMERA_PROJECTION_PERSPECTIVE standard perspective camera, can move and rotate freely
DIGUY_CAMERA_PROJECTION_PLANVIEW_XY always views in negative Z direction
DIGUY_CAMERA_PROJECTION_PLANVIEW_XZ always views in negative Y direction
DIGUY_CAMERA_PROJECTION_PLANVIEW_YZ always views in negative X direction

function diguyViewCamera::get_projection_mode

Prototype:
diguyViewCameraProjectionMode get_projection_mode();
Returns:

the most recent setting made by set_projection_mode()

Load and Apply Functions

All functions in this section are callable from:

C++
Script

function diguyViewCamera::load_settings

Prototype:
int load_settings(const char* settings_name);
Description:

Loads the specified settings into this camera.
Returns:

0 on success, -1 on failure

function diguyViewCamera::load_settings

Prototype:
int load_settings(diguyViewCameraSettings* settings);
Description:

Loads the specified settings into this camera.
Returns:

0 on success, -1 on failure

function diguyViewCamera::apply_settings

Prototype:
void apply_settings();
Description:

This function applies this camera's settings.
OpenGL Version:

This function sets the current viewpoint in these environments based on information in this camera.
Direct3D Version:

This function has no effect. The viewpoint in these environments must be set manually.

Far Position Camera Functions

The following functions are for working with a "far position", or high precision, cameras.

One approach for dealing with high-magnitude floating point numbers is to simply use doubles instead of floats. However, many rendering pipelines use single-precision floats internally, making the use of doubles to store transformations only a partial solution.

Another approach for rendering objects that are extremely far from the origin without having floating point precision problems is to move the camera and all objects it is observing closer to the origin. This avoids placing large magnitude numbers in transformation matrices, which with most graphics environments causes precision loss. This is the approach DI-Guy uses.

DI-Guy internally stores high precision positions as a "far position": a segment (integer x and y coordinates), a segment size (a floating point number), and a floating point offset into the segment (float x, y, and z coordinates). This effectively compartmentalizes x and y coordinates into a grid where each cell, or segment, of the grid is of size (segment size x segment size) meters. (Currently z coordinates are stored "as is", in single precision floats.)

The world coordinate position of a far position can be computed using the following formula:

world position = (segment * segment_size) + segment_offset

If done using doubles, the above formula provides a very accurate position, even at very high magnitudes. This is the calculation the get_position_double() function uses.

Assuming the camera and an object are in the same segment, the local (camera-relative) position of the object is simply its offset.

If a diguyViewCamera is being used to control the graphics environment viewpoint, the viewpoint matrix can be calculated from the position segment offset and the fix segment offset.

Example:

float pos_x, pos_y, pos_z;
scenario_camera->get_position_segment_offset(&pos_x, &pos_y, &pos_z);

float fix_x, fix_y, fix_z;
scenario_camera->get_fix_segment_offset(&fix_x, &fix_y, &fix_z);

glMatrixMode(GL_MODELVIEW);
glLoadIdentity();
gluLookAt(pos_x, pos_y, pos_z,
    fix_x, fix_y, fix_z,
    0.0, 0.0, 1.0);

To render non-DI-Guy objects correctly, the segment origin translation must be subtracted from the position of the objects. This is done automatically for DI-Guy characters in the OpenGL version of DI-Guy if the diguy_ogl_set_use_far_positions(1) call is made.

Example:

Far position cameras are used in the diguy_oglview_far_settingsview_far_settings.cpp example.
All functions in this section are callable from:

C++
Script

function diguyViewCamera::set_position_double

Prototype:
void set_position_double(double x, double y, double z);
Description:

This function sets the position of this camera using double precision floating point numbers. The numbers will be converted internally into a DI-Guy far position.
Arguments:

x x position, in meters
y y position, in meters
z z position, in meters

function diguyViewCamera::get_position_double

Prototype:
void get_position_double(double* x, double* y, double* z);
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.
Arguments:

x x position, in meters
y y position, in meters
z z position, in meters

function diguyViewCamera::get_segment_origin

Prototype:
void get_segment_origin(float* x, float* y, float* z);
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.
Arguments:

x x component of origin, in meters
y y component of origin, in meters
z z component of origin, in meters

function diguyViewCamera::get_position_segment_offset

Prototype:
void get_position_segment_offset(float* x, float* y, float* z);
Description:

This function returns the far position segment offset part of the camera's position. The results are placed into the passed pointers.
Arguments:

x x component of segment offset, in meters
y y component of segment offset, in meters
z z component of segment offset, in meters

function diguyViewCamera::get_fix_segment_offset

Prototype:
void get_fix_segment_offset(float* x, float* y, float* z);
Description:

This function returns the far position offset portion of the camera's fix point. The results are placed into the passed pointers.
Arguments:

x x component of fix segment offset, in meters
y y component of fix segment offset, in meters
z z component of fix segment offset, in meters

function diguyViewCamera::set_fix_double

Prototype:
void set_fix_double(double x, double y, double z);
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.
Arguments:

x x position, in meters
y y position, in meters
z z position, in meters

Look At and Look From Functions

All functions in this section are callable from:

C++
Script

function diguyViewCamera::set_track_name

Prototype:
void set_track_name(const char* track_name);
Description:

This function sets the name of the character the camera should look at, if such an 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().
Arguments:

track_name name of character to look at, or NULL if no character is to be tracked
C++ Example

The following example shows how to use some of the pose functions.
//
//  Get a pointer to the primary view's camera, and
//  to the first character.
//
diguyViewCamera* camera = scenario->get_scenario_camera();
diguyCharacter* character = scenario->get_character_at_index(0);

//
//  Look just a little bit above the character's head.
//
camera->set_track_name(character->get_name());
camera->set_track_link_name("cervical");
camera->set_track_offset(0.0f, 0.0f, 0.1f);

function diguyViewCamera::get_track_name

Prototype:
const char* get_track_name();
Returns:

name of character to be looked at; see set_track_name()

function diguyViewCamera::set_track_group_name

Prototype:
void set_track_group_name(const char* track_name);
Description:

This function sets the name of the group the camera will track.
Arguments:

track_name name of group to look at; pass NULL to un-set track group

function diguyViewCamera::get_track_group_name

Prototype:
const char* get_track_group_name();
Returns:

name of group to be looked at; see set_track_group_name()

function diguyViewCamera::set_track_link_name

Prototype:
void set_track_link_name(const char* track_link_name);
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.
Arguments:

track_link_name name of link to look at, or NULL if the base link is to be tracked

function diguyViewCamera::get_track_link_name

Prototype:
const char* get_track_link_name();
Returns:

name of link to be looked at; see set_track_link_name()

function diguyViewCamera::set_track_offset

Prototype:
void set_track_offset(float x, float y, float z);
Description:

This function sets the offset of the track position on the character specified by set_track_name(). See set_track_name() for more information.

Whether the offset is in world coordinates or character-local coordinates is controlled by a call to set_track_offset_is_in_world_coordinates().
Arguments:

x, y, z offset, in meters, of track point

function diguyViewCamera::get_track_offset_x

Prototype:
float get_track_offset_x();
Returns:

x component of track offset; see set_track_offset()

function diguyViewCamera::get_track_offset_y

Prototype:
float get_track_offset_y();
Returns:

y component of track offset; see set_track_offset()

function diguyViewCamera::get_track_offset_z

Prototype:
float get_track_offset_z();
Returns:

z component of track offset; see set_track_offset()

function diguyViewCamera::set_track_offset_is_in_world_coordinates

Prototype:
void set_track_offset_is_in_world_coordinates(int value);
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.
Arguments:

value pass 0 for character-relative, 0 for world coordinates

function diguyViewCamera::get_track_offset_is_in_world_coordinates

Prototype:
int get_track_offset_is_in_world_coordinates();
Returns:

the most recent setting made by set_track_offset_is_in_world_coordinates().

function diguyViewCamera::set_dolly_name

Prototype:
void set_dolly_name(const char* dolly_name);
Description:

This function sets the name of the entity this camera should look from, if such an entity can be found. This will cause position values to change over time.
Arguments:

dolly_name name of entity to look from, or NULL if no entity is to influence camera position

function diguyViewCamera::get_dolly_name

Prototype:
const char* get_dolly_name();
Description:

This function sets the name of the character the camera should look from, if such an character can be found. This will cause position values to change over time.
Arguments:

dolly_name name of character to look from, or NULL if no character is to influence camera position

function diguyViewCamera::set_dolly_offset

Prototype:
void set_dolly_offset(float x, float y, float z);
Description:

This function sets the offset of the dolly position on the character specified by set_dolly_name(). See set_dolly_name() for more information.

Whether the offset is in world coordinates or character-local coordinates is controlled by a call to set_dolly_offset_is_in_world_coordinates().
Arguments:

x, y, z offset, in meters, of dolly point

function diguyViewCamera::get_dolly_offset_x

Prototype:
float get_dolly_offset_x();
Returns:

x component of track offset; see set_dolly_offset()

function diguyViewCamera::get_dolly_offset_y

Prototype:
float get_dolly_offset_y();
Returns:

y component of track offset; see set_dolly_offset()

function diguyViewCamera::get_dolly_offset_z

Prototype:
float get_dolly_offset_z();
Returns:

z component of track offset; see set_dolly_offset()

function diguyViewCamera::set_dolly_link_name

Prototype:
void set_dolly_link_name(const char* dolly_link_name);
Description:

This function sets the name of the link to be dollied on the character specified by set_dolly_name().
Arguments:

dolly_link_name name of link to look from, or NULL if the position link is to influence camera position

function diguyViewCamera::get_dolly_link_name

Prototype:
const char* get_dolly_link_name();
Returns:

name of link to be looked from; see set_dolly_link_name()

function diguyViewCamera::set_dolly_offset_is_in_world_coordinates

Prototype:
void set_dolly_offset_is_in_world_coordinates(int value);
Description:

This function sets whether the offset of the dolly position is character-relative (pass 0) or in world coordinates (pass 1).

Default value is 0.
Arguments:

value pass 0 for character-relative, 0 for world coordinates

function diguyViewCamera::get_dolly_offset_is_in_world_coordinates

Prototype:
int get_dolly_offset_is_in_world_coordinates();
Returns:

the most recent setting made by set_dolly_offset_is_in_world_coordinates().

function diguyViewCamera::get_symbolic_view

Prototype:
int get_symbolic_view();
Returns:

if DI-Guy Scenario is rendering simplified 2D representations of characters.

C++ Callback Functions

enumeration

	enum {
		CALLBACK_ID_SETTINGS_CHANGED = 1
	};
Description:

This is an enumeration of the different callbacks that can be registered with add_callback() and add_callback_script().
Usable From:

C++
Script

function diguyViewCamera::add_callback

Prototype:
int add_callback(int callback_id,
    diguyViewCameraCallback* callback,
    void* callback_params = 0,
    void* callback_user_data = 0);
Description:

This function adds a user callback.
Arguments:

callback pointer to function with prototype diguyViewCameraCallback (typedefed above)
callback_id integer id of when this callback is to be called
callback_params struct containing additional parameters needed by some callbacks; actual type depends on callback_id
callback_user_data pointer for user's own use; DI-Guy will do nothing to the contents of this pointer beyond passing it back when the callback is invoked

callback_id should be one of the following values:
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.
Returns:

0 on success, -1 on failure

function diguyViewCamera::remove_callback

Prototype:
int remove_callback(int callback_id,
    diguyViewCameraCallback* callback);
Description:

This function removes a user callback. All callbacks matching the specified callback_id and callback function will be removed.
Arguments:

callback_id integer id of when this callback is to be called
callback pointer to function with prototype diguyViewCameraCallback (typedefed above)
Returns:

0 on success, -1 on failure

function diguyViewCamera::remove_callback_with_user_data

Prototype:
int remove_callback_with_user_data(int callback_id,
    void* callback_user_data);
Description:

This function removes a user callback. All callbacks matching the specified callback_id and callback_user_data pointer will be removed.
Arguments:

callback_id integer id of when this callback is to be called
callback_user_data pointer for user's own use
Returns:

0 on success, -1 on failure

C++/Script Callback Functions

function diguyViewCamera::add_callback_script

Prototype:
int add_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL);
Description:

This function adds a user callback script. Callback scripts can be removed with remove_callback_script().
Arguments:

callback_id integer id of the callback
callback_script script text of callback to be added
callback_script_type the type of script contained in 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.
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.
Returns:

0 on success, -1 on failure

function diguyViewCamera::remove_callback_script

Prototype:
int remove_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL);
Description:

This function removes a user callback script previously added with add_callback_script().
Arguments:

callback_id integer id of the callback
callback_script script text of callback previously added
callback_script_type the type of script contained in 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.
lua specific:

To pass NULL when calling from a lua script, use nil.
Returns:

0 on success, -1 on failure

Experimental Functions

The following functions are experimental and may change or disappear with no warning.
Unless otherwise noted all are callable from:

C++
Script

function diguyViewCamera::set_speed_fov_degrees_per_wheel_click

Prototype:
void set_speed_fov_degrees_per_wheel_click(float fov_change);
Description:

Sets number of degrees by which the camera FOV should change whenever the user moves the mouse wheel.
Arguments:

fov_change change to FOV in degrees

function diguyViewCamera::get_speed_fov_degrees_per_wheel_click

Prototype:
float get_speed_fov_degrees_per_wheel_click();
Description:

Gets the number of degrees by which the camera FOV should change whenever the user moves the mouse wheel.
Returns:

change to FOV, in degrees

function diguyViewCamera::set_speed_meters_per_second

Prototype:
void set_speed_meters_per_second(float speed);
Description:

Sets how fast the camera should move in various flyaround modes.
Arguments:

speed flying speed in meters per second

function diguyViewCamera::get_speed_meters_per_second

Prototype:
float get_speed_meters_per_second();
Description:

Gets how fast the camera should move in various flyaround modes.
Returns:

speed in meters per second

function diguyViewCamera::set_require_smooth_servo

Prototype:
void set_require_smooth_servo(int require);
Description:

Sets whether the camera should smoothly servo to its new desired position/heading (as opposed to instantly popping there).
Arguments:

require 0 for smooth servoing

function diguyViewCamera::get_require_smooth_servo

Prototype:
int get_require_smooth_servo();
Description:

Gets whether the camera should smoothly servo to its new desired position/heading (as opposed to instantly popping there).
Returns:

1 if smooth servoing is required; 0 if not

function diguyViewCamera::set_servo_time_modifier

Prototype:
void set_servo_time_modifier( float modifier );
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.

modifier

function diguyViewCamera::get_servo_time_modifier

Prototype:
float get_servo_time_modifier();
Returns:

The servo modifier time that determines how smoothly the camera should servo.

function diguyViewCamera::set_track_camera_avoids_obstacles

Prototype:
void set_track_camera_avoids_obstacles(int avoid);
Description:

Sets if the camera mover should make an effort to avoid obstacles that block visibility while a character or group is being tracked.
Arguments:

avoids true for avoidance

function diguyViewCamera::get_track_camera_avoids_obstacles

Prototype:
int get_track_camera_avoids_obstacles();
Description:

Gets whether the camera mover should make an effort to avoid obstacles that block visibility while a character or group is being tracked.
Returns:

1 if obstacle avoidance should be attempted

function diguyViewCamera::set_ignore_mouse_drags

Prototype:
void set_ignore_mouse_drags(int ignore);
Description:

Sets if the camera should not respond to mouse drags. Responding is the default.
Arguments:

avoids 1 to ignore mouse drags; 0 if not

function diguyViewCamera::get_ignore_mouse_drags

Prototype:
int get_ignore_mouse_drags();
Description:

Gets whether the camera should ignore mouse drags.
Returns:

1 if mouse drags are to be ignored; 0 if not

function diguyViewCamera::update_frustum

Prototype:
void update_frustum(float* proj_matrix, float* model_matrix);
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.

This function is not callable from lua.

Alphabetical Index

These coded instructions, statements, and computer programs contain unpublished proprietary information of Boston Dynamics and are protected by Copyright Laws of the United States. They may not be used, duplicated, or disclosed in any form, in whole or in part, without the prior written consent from Boston Dynamics.

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the government is subject to restrictions as set forth in FAR 52.227.19(c)(2) or subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Sofware clause at DFARS 252.227-7013 and/or in similar or successor clauses in the FAR, or the DOD or NASA FAR Supplement, or to subparagraphs (c)(1) and (c)(2) of the Commercial Computer Software--Restricted Rights at 48 CFR 52.227-19, as applicable. Unpublished-rights reserved under the Copyright Laws of the United States.

Contractor/Manufacturer is:

Boston Dynamics/78 Fourth Avenue/Waltham MA 02451.

`yaw`	rotation about z axis, in degrees
`roll`	rotation about x axis, in degrees
`pitch`	rotation about y axis, in degrees

`move_mode`	new movement mode of the camera; enumeration of type `diguyViewCameraMoveMode`
`DIGUY_CAMERA_MOVE_FORWARD`	left mouse press moves camera forward, right mouse press moves camera back
`DIGUY_CAMERA_MOVE_SIDEWAYS`	left mouse press moves camera left, right mouse press moves camera right
`DIGUY_CAMERA_MOVE_VERTICAL`	left mouse press moves camera up, right mouse press moves camera down

`projection_mode`	new projection mode of the camera; enumeration of type `diguyViewCameraProjectionMode`
`DIGUY_CAMERA_PROJECTION_PERSPECTIVE`	standard perspective camera, can move and rotate freely
`DIGUY_CAMERA_PROJECTION_PLANVIEW_XY`	always views in negative Z direction
`DIGUY_CAMERA_PROJECTION_PLANVIEW_XZ`	always views in negative Y direction
`DIGUY_CAMERA_PROJECTION_PLANVIEW_YZ`	always views in negative X direction

`x`	x position, in meters
`y`	y position, in meters
`z`	z position, in meters

`x`	x component of origin, in meters
`y`	y component of origin, in meters
`z`	z component of origin, in meters

`x`	x component of segment offset, in meters
`y`	y component of segment offset, in meters
`z`	z component of segment offset, in meters

`x`	x component of fix segment offset, in meters
`y`	y component of fix segment offset, in meters
`z`	z component of fix segment offset, in meters

`callback`	pointer to function with prototype diguyViewCameraCallback (typedefed above)
`callback_id`	integer id of when this callback is to be called
`callback_params`	struct containing additional parameters needed by some callbacks; actual type depends on callback_id
`callback_user_data`	pointer for user's own use; DI-Guy will do nothing to the contents of this pointer beyond passing it back when the callback is invoked

`callback_id`	integer id of the callback
`callback_script`	script text of callback to be added
`callback_script_type`	the type of script contained in callback_script