DI-Guy SDK Documentation  13.1
List of all members
diguyViewCamera Class Reference
DI-Guy Scenario Application APIs

The class that represents a camera in the world. More...

#include <diguyViewCamera.h>

Public Member Functions

General Functions

All functions in this section are callable from:

  • C++
  • Script
const char * get_name ()
 Returns the name of the object. More...
 
const char * get_type_name ()
 Returns the type name of the object. More...
 
void set_near_plane (float near_plane)
 This sets the distance from the camera to the near plane. More...
 
float get_near_plane ()
 Returns: distance from the camera to the near plane, in meters. More...
 
void set_far_plane (float far_plane)
 This sets the distance from the camera to the far plane. More...
 
float get_far_plane ()
 Returns: distance from the camera to the far plane, in meters. More...
 
void set_fov (float fov)
 This sets the field-of-view of the current camera. More...
 
void set_max_fov (float fov)
 This sets the maximum field-of-view of the current camera. More...
 
void set_min_fov (float fov)
 This sets the minimum field-of-view of the current camera. More...
 
float get_fov ()
 Returns: field-of-view of the camera, in degrees. More...
 
float get_min_fov ()
 Returns: min field-of-view of the camera, in degrees. More...
 
float get_max_fov ()
 Returns: max field-of-view of the camera, in degrees. More...
 
void set_aspect (float aspect)
 This function sets the aspect ratio of the camera. More...
 
float get_aspect ()
 Returns: aspect ratio of the camera. More...
 
void set_offsets_active (int value)
 Sets whether or not the orientation and position offsets have any effect. More...
 
int get_offsets_active ()
 Returns whether or not the orientation and position offsets have any effect. More...
 
void set_base_position (float x, float y, float z)
 This function sets the base position of the camera. More...
 
void set_position (float x, float y, float z)
 This function sets the base position of the camera, and disables the offsets. More...
 
void get_base_position (float **\note, float *y, float *z)
 Gets the base position of the camera. More...
 
float get_position_x ()
 Returns: x position, in meters from the origin. More...
 
float get_position_y ()
 Returns: y position, in meters from the origin. More...
 
float get_position_z ()
 Returns: z position, in meters from the origin. More...
 
void set_desired_base_position (float x, float y, float z)
 This function sets the desired base position of the camera. More...
 
void set_desired_position (float x, float y, float z, bool preserve_fix=false)
 Sets the desired base position and disables any offsets. More...
 
void set_position_offset (float x, float y, float z)
 This function sets the position offset of the camera. More...
 
void set_desired_position_offset (float x, float y, float z)
 This function sets the desired position offset of the camera. More...
 
void get_position_offset (float **\note, float *y, float *z)
 Gets the position offset of the camera. More...
 
void set_position_offset_is_in_world_coordinates (int value)
 Sets whether or not the position offset is relative to both base position and orientation, or just the position. More...
 
int get_position_offset_is_in_world_coordinates ()
 Returns: Setting of position_offset_is_in_world_coordinates. More...
 
void set_base_orientation (float yaw, float roll, float pitch)
 This function sets the base orientation of the camera. More...
 
void set_orientation (float yaw, float roll, float pitch)
 This function sets the base orientation of the camera. More...
 
void set_orientation_roll (float roll)
 This function sets the roll value of the camera's base orientation. More...
 
void get_orientation (float *yaw, float **\returnoll, float *pitch)
 Returns: yaw. More...
 
float get_orientation_yaw ()
 Returns: rotation about z axis, in degrees. More...
 
float get_orientation_roll ()
 Returns: rotation about x axis, in degrees. More...
 
float get_orientation_pitch ()
 Returns: rotation about y axis, in degrees. More...
 
void set_desired_base_orientation (float yaw, float roll, float pitch)
 This function sets the desired base orientation of the camera, which will be interpolated to over time. More...
 
void set_pitch_lower_limit (float limit)
 Sets the lower limit of the camera pitch up. More...
 
float get_pitch_lower_limit ()
 Returns: lower limit of the camera pitch (up/down) More...
 
void set_pitch_upper_limit (float limit)
 Sets the upper limit of the camera pitch down. More...
 
float get_pitch_upper_limit ()
 Returns: upper limit of the camera pitch (up/down) More...
 
int get_pitch_has_limits ()
 Returns: 1 if pitch has limits, 0 if not. More...
 
void set_degimbalize_angle (float angle)
 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. More...
 
float get_degimbalize_angle ()
 Returns: Current degimbalize angle, in degrees. More...
 
void set_orientation_offset (float yaw, float roll, float pitch)
 This function sets the orientation offset of the camera. More...
 
void get_orientation_offset (float *yaw, float **\returnoll, float *pitch)
 Gets the orientation offset of the camera. More...
 
void set_desired_orientation_offset (float yaw, float roll, float pitch)
 This function sets the desired orientation offset of the camera, which will be interpolated to over time. More...
 
void set_distance (float distance)
 This function sets the distance from the position to the fix point. More...
 
void set_max_track_distance (float distance)
 This function sets the maximum allowed distance from the position to the fix point. More...
 
void set_min_track_distance (float distance)
 This function sets the minimum allowed distance from the position to the fix point. More...
 
float get_distance ()
 Returns: distance from position to fix point, in meters. More...
 
float get_min_track_distance ()
 Returns: minimum allowed tracking distance, in meters; will be less than zero if not applicable. More...
 
float get_max_track_distance ()
 Returns: maximum allowed tracking distance, in meters; will be less than zero if not applicable. More...
 
void set_fix (float x, float y, float z)
 This function sets the fix point of the camera. More...
 
void release_fix ()
 Causes the camera to lose whatever fix point it was pointed at. More...
 
float get_fix_x ()
 Returns: fix point in x, in meters. More...
 
float get_fix_y ()
 Returns: fix point in y, in meters. More...
 
float get_fix_z ()
 Returns: fix point in z, in meters. More...
 
void set_desired_fix (float x, float y, float z)
 This function sets the desired fix point of the camera. More...
 
int set_move_mode (diguyViewCameraMoveMode move_mode)
 This function sets the movement mode of the camera. More...
 
diguyViewCameraMoveMode get_move_mode ()
 Returns: the most recent setting made by set_move_mode() More...
 
int set_speed (float speed)
 This function sets the movement speed of the camera when the camera is translating due to user input. More...
 
float get_speed ()
 Returns: the most recent setting made by set_speed() More...
 
int increase_speed ()
 This function increases the movement speed of the camera when the camera is translating due to user input. More...
 
int decrease_speed ()
 This function decreases the movement speed of the camera when the camera is translating due to user input. More...
 
int set_projection_mode (diguyViewCameraProjectionMode projection_mode)
 This function sets the projection mode of the camera. More...
 
diguyViewCameraProjectionMode get_projection_mode ()
 Returns: the most recent setting made by set_projection_mode() More...
 
Load and Apply Functions
   The idea is that a scenario can contain multiple "settings" camera.

These cameras are set with values that can be copied into the main scenario camera, whenever the user decides to load a new camera setting. The user can also modify the scenario camera and copy its values back into a settings camera.

All functions in this section are callable from:

  • C++
  • Script
int load_settings (const char *settings_name)
 Loads the specified settings into this camera. More...
 
int load_settings (diguyViewCameraSettings *settings)
 Loads the specified settings into this camera. More...
 
void apply_settings ()
 This function applies this camera's settings and internal state to the actual view frustrum. More...
 
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_ogl/view_far_settings/view_far_settings.cpp example.

All functions in this section are callable from:

  • C++
  • Script
void set_base_position_double (double x, double y, double z)
 This function sets the base position of this camera using double precision floating point numbers. More...
 
void set_position_double (double x, double y, double z)
 Equivalent to set_base_position_double(), but disables offsets. More...
 
void get_base_position_double (double **\note, double *y, double *z)
 Gets the base position of the camera. More...
 
void get_position_double (double *x, double *y, double *z)
 This function returns the world-space position of this camera. More...
 
void get_segment_origin (float *x, float *y, float *z)
 This function returns the world-space origin of the far position segment the camera is in. More...
 
void get_position_segment_offset (float *x, float *y, float *z)
 This function returns the far position segment offset part of the camera's base position. More...
 
void get_fix_segment_offset (float *x, float *y, float *z)
 This function returns the far position offset portion of the camera's fix point. More...
 
void set_fix_double (double x, double y, double z)
 This function sets the fix point of the camera using double precision floating point numbers. More...
 
Look At and Look From Functions

All functions in this section are callable from:

  • C++
  • Script
void set_track_name (const char *track_name)
 This function sets the name of the character the camera should look at, if such a character can be found. More...
 
const char * get_track_name ()
 Returns: name of character to be looked at; see set_track_name() More...
 
void set_track_group_name (const char *track_name)
 This function sets the name of the group the camera will track. More...
 
const char * get_track_group_name ()
 Returns: name of group to be looked at; see set_track_group_name() More...
 
void set_track_link_name (const char *track_link_name)
 This function sets the name of the link to be tracked on the character specified by set_track_name(). More...
 
const char * get_track_link_name ()
 Returns: name of link to be looked at; see set_track_link_name() More...
 
void set_track_offset (float x, float y, float z)
 This function sets the position of the look-at point relative to the tracked entity. More...
 
float get_track_offset_x ()
 Returns: x component of track offset; see set_track_offset() More...
 
float get_track_offset_y ()
 Returns: y component of track offset; see set_track_offset() More...
 
float get_track_offset_z ()
 Returns: z component of track offset; see set_track_offset() More...
 
void set_track_offset_is_in_world_coordinates (int value)
 This function sets whether the offset of the track position is character-relative (pass 0) or in world coordinates (pass 1). More...
 
int get_track_offset_is_in_world_coordinates ()
 Returns: the most recent setting made by set_track_offset_is_in_world_coordinates(). More...
 
void set_dolly_name (const char *dolly_name)
 Sets the dolly entity. More...
 
const char * get_dolly_name ()
 This function gets the name of the dolly entity. More...
 
void set_dolly_offset (float x, float y, float z)
 Sets the position at which the camera will be relative to the dolly entity. More...
 
float get_dolly_offset_x ()
 Returns: x component of position offset; see set_dolly_offset() More...
 
float get_dolly_offset_y ()
 Returns: y component of position offset; see set_dolly_offset() More...
 
float get_dolly_offset_z ()
 Returns: z component of position offset; see set_dolly_offset() More...
 
void set_dolly_link_name (const char *dolly_link_name)
 This function sets the name of the link to be dollied on the character specified by set_dolly_name(). More...
 
const char * get_dolly_link_name ()
 Returns: name of link to be looked from; see set_dolly_link_name() More...
 
void set_dolly_offset_is_in_world_coordinates (int value)
 This function sets whether the position offset is character-relative (pass 0) or in world coordinates (pass 1). More...
 
int get_dolly_offset_is_in_world_coordinates ()
 Returns: the most recent setting made by set_dolly_offset_is_in_world_coordinates(). More...
 
void set_orientation_offset_is_relative (int value)
 Sets whether the camera's orientation offset is relative or not. More...
 
int get_orientation_offset_is_relative ()
 Returns: the most recent setting made by set_orientation_offset_is_relative(). More...
 
void set_match_dolly_orientation (int value)
 This function has been deprecated, but remains for backwards compatibility. More...
 
int get_match_dolly_orientation ()
 This function has been deprecated, but remains for backwards compatibility. More...
 
void set_use_special_track_mode (int value)
 If activated, the camera will behave differently when both dollying and tracking. More...
 
int get_use_special_track_mode ()
 Returns: 1, if special track mode is being used. More...
 
int get_symbolic_view ()
 Returns: if DI-Guy Scenario is rendering simplified 2D representations of characters. More...
 
C++/Script Callback Functions
int add_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL)
 This function adds a user callback script. More...
 
int remove_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=NULL)
 This function removes a user callback script previously added with add_callback_script(). More...
 
Experimental Functions

The following functions are experimental and may change or disappear with no warning.

Unless otherwise noted all are callable from:

  • C++
  • Script
void set_speed_fov_degrees_per_wheel_click (float fov_change)
 Sets number of degrees by which the camera FOV should change whenever the user moves the mouse wheel. More...
 
float get_speed_fov_degrees_per_wheel_click ()
 Gets the number of degrees by which the camera FOV should change whenever the user moves the mouse wheel. More...
 
void set_speed_meters_per_second (float speed)
 Sets how fast the camera should move in various flyaround modes. More...
 
float get_speed_meters_per_second ()
 Gets how fast the camera should move in various flyaround modes. More...
 
void set_require_smooth_servo (int require)
 Sets whether the camera should smoothly servo to its new desired position/heading (as opposed to instantly popping there). More...
 
int get_require_smooth_servo ()
 Gets whether the camera should smoothly servo to its new desired position/heading (as opposed to instantly popping there). More...
 
void set_servo_time_modifier (float modifier)
 Sets a factor that determines how smoothly the camera should servo. More...
 
float get_servo_time_modifier ()
 Returns: The servo modifier time that determines how smoothly the camera should servo. More...
 
void set_track_camera_avoids_obstacles (int avoid)
 Sets if the camera mover should make an effort to avoid obstacles that block visibility while a character or group is being tracked. More...
 
int get_track_camera_avoids_obstacles ()
 Gets whether the camera mover should make an effort to avoid obstacles that block visibility while a character or group is being tracked. More...
 
void set_ignore_mouse_drags (int ignore)
 Sets if the camera should not respond to mouse input from DI-Guy Scenario. More...
 
int get_ignore_mouse_drags ()
 Gets whether the camera should ignore mouse input from DI-Guy Scenario. More...
 
void update_frustum (float *proj_matrix, float *model_matrix)
 Allows the diguy camera to build an internal frustum needed for doing character and scene object culling. More...
 

C++ Callback Functions

enum  { CALLBACK_ID_SETTINGS_CHANGED = 1 }
 This is an enumeration of the different callbacks that can be registered with add_callback() and add_callback_script(). More...
 
int add_callback (int callback_id, diguyViewCameraCallback *callback, void *callback_params=0, void *callback_user_data=0)
 This function adds a user callback. More...
 
int remove_callback (int callback_id, diguyViewCameraCallback *callback)
 This function removes a user callback. More...
 
int remove_callback_with_user_data (int callback_id, void *callback_user_data)
 This function removes a user callback. More...
 

Private Functions

The functions and variables past this point are for internal use only.

No external access to them is expected or necessary.

bdiCamera * m_camera
 A pointer to internal data. More...
 
class bdiCamera
 
static bool s_warn_if_position_set_ignored
 
bdiCamera * get_scripted_object ()
 
 diguyViewCamera (bdiCamera *camera)
 A private constructor. More...
 

Detailed Description

The class that represents a camera in the world.

Description

The scenery, objects, and characters shown in the window of a diguyView represent those seen from an imaginary camera floating in space. A diguyViewCamera can be thought of as a system consisting of a camera, a base position and orientation, a position offset, and an orientation offset.

Imagine a camera mounted on the end of a pole, with the pole's other end being attached to a base. The base moves and swivels according to its position and orientation settings, and the pole moves along with the base. The position offset describes where the camera end of the pole is located relative to the base position. The orientation offset describes the orientation of the camera itself (on the end of the pole). The orientation offset can be relative to the base's orientation (imagine someone riding an airplane who points a camera out the airplane's right window, so that the right wing always remains in view, even as the plane turns, rolls, and dives). Or, the orientation offset can be relative to the world axes (imagine someone riding in a airplane who keeps the camera constantly pointed east, even as the plane yaws, banks, and pitches).

A camera may also be assigned a fix point, which represents a point in space that the camera will stay focused on even as it moves around. If the user assigns a fix point, however, the base orientation and the orientation offset will be automatically derived.

This is a very flexible system that can be used in a variety of ways. The user may disable the position and orientation offsets and have a simple camera that floats in space, rotating as desired. Or, the user can create a camera that swings around corners as it moves, in the manner of a crane-mounted film camera seen on a movie set. Or, the user can attach a camera to a character and have it "follow along" behind the character to provide a "third-person" view often seen in videogames. This is called dollying.

Base position, base orientation, position offset, orientation offset, and fix point are all values that can be set instantly, or the camera can be programmed to smoothly servo to any of these values over time. Sometimes, the servoing is desirable, such as in cases where the user wants the camera to slide gracefully across a stretch of ground, or to turn in a natural-looking way from one direction to a another. Other times, the servoing is best turned off, such as in cases where the camera's state is being set on every frame. Servoing can also be selectively enabled or disabled for different attributes. For example, the user might want to attach the camera to a vehicle (which sends regular position updates), but retain smooth swiveling.

DIGuy Scenario provides several "camera mover" classes, which translate mouse input into movement of the main view camera. As a convenience, a diguyViewCamera can be assigned a dolly entity, a tracking entity, or both. If there is a dolly entity, the camera movers will attempt to keep the camera attached to it, offset by the position and orientation offsets. If there is a tracking entity, the camera movers will attempt to keep the camera's fix point upon that entity.

Member Enumeration Documentation

anonymous enum

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

Usable From:

  • C++
  • Script
Enumerator
CALLBACK_ID_SETTINGS_CHANGED 

Constructor & Destructor Documentation

diguyViewCamera::diguyViewCamera ( bdiCamera *  camera)
private

A private constructor.

Member Function Documentation

const char* diguyViewCamera::get_name ( )

Returns the name of the object.

This pointer will never be NULL.

Returns:

name of the object

const char* diguyViewCamera::get_type_name ( )

Returns the type name of the object.

This pointer will never be NULL.

Returns:

type name of the object

void diguyViewCamera::set_near_plane ( float  near_plane)

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

Parameters
near_planedistance to near plane, in meters
float diguyViewCamera::get_near_plane ( )

Returns: distance from the camera to the near plane, in meters.

void diguyViewCamera::set_far_plane ( float  far_plane)

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

Parameters
far_planedistance to far plane, in meters
float diguyViewCamera::get_far_plane ( )

Returns: distance from the camera to the far plane, in meters.

void diguyViewCamera::set_fov ( float  fov)

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

Parameters
fovfield-of-view, in degrees
void diguyViewCamera::set_max_fov ( float  fov)

This sets the maximum field-of-view of the current camera.

This affects the FOV that can be set via set_fov.

Parameters
fovmax field-of-view, in degrees
void diguyViewCamera::set_min_fov ( float  fov)

This sets the minimum field-of-view of the current camera.

This affects the FOV that can be set via set_fov.

Parameters
fovmin field-of-view, in degrees
float diguyViewCamera::get_fov ( )

Returns: field-of-view of the camera, in degrees.

float diguyViewCamera::get_min_fov ( )

Returns: min field-of-view of the camera, in degrees.

float diguyViewCamera::get_max_fov ( )

Returns: max field-of-view of the camera, in degrees.

void diguyViewCamera::set_aspect ( float  aspect)

This function sets the aspect ratio of the camera.

Parameters
aspectaspect ratio; 1.3333 (4/3) is the default
float diguyViewCamera::get_aspect ( )

Returns: aspect ratio of the camera.

void diguyViewCamera::set_offsets_active ( int  value)

Sets whether or not the orientation and position offsets have any effect.

See the class-level comments for explanations of these.

int diguyViewCamera::get_offsets_active ( )

Returns whether or not the orientation and position offsets have any effect.

void diguyViewCamera::set_base_position ( float  x,
float  y,
float  z 
)

This function sets the base position of the camera.

Will not work if a dolly character has been set.

Parameters
x,y,zposition in meters from the origin
void diguyViewCamera::set_position ( float  x,
float  y,
float  z 
)

This function sets the base position of the camera, and disables the offsets.

Will not work if a dolly character has been set.

void diguyViewCamera::get_base_position ( float **\  note,
float *  y,
float *  z 
)

Gets the base position of the camera.

Returns:

x, y, and z, in meters

float diguyViewCamera::get_position_x ( )

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 diguyViewCamera::get_position_y ( )

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 diguyViewCamera::get_position_z ( )

Returns: z position, in meters from the origin.

Not the base position of the system, but the actual position of the camera itself.

void diguyViewCamera::set_desired_base_position ( float  x,
float  y,
float  z 
)

This function sets the desired base position of the camera.

The camera will interpolate over time to this position.

Parameters
x,y,zposition in meters from the origin
void diguyViewCamera::set_desired_position ( float  x,
float  y,
float  z,
bool  preserve_fix = false 
)

Sets the desired base position and disables any offsets.

Parameters
x,y,zposition in meters from the origin
preserve_fixobsolete, but kept for backwards compatibility
void diguyViewCamera::set_position_offset ( float  x,
float  y,
float  z 
)

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.

Parameters
x,y,zposition in meters from the origin
void diguyViewCamera::set_desired_position_offset ( float  x,
float  y,
float  z 
)

This function sets the desired position offset of the camera.

The camera will interpolate over time to this position.

Parameters
x,y,zposition in meters from the origin
void diguyViewCamera::get_position_offset ( float **\  note,
float *  y,
float *  z 
)

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

Returns:

x, y, and z, in meters

void diguyViewCamera::set_position_offset_is_in_world_coordinates ( int  value)

Sets whether or not the position offset is relative to both base position and orientation, or just the position.

int diguyViewCamera::get_position_offset_is_in_world_coordinates ( )

Returns: Setting of position_offset_is_in_world_coordinates.

void diguyViewCamera::set_base_orientation ( float  yaw,
float  roll,
float  pitch 
)

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!

Parameters
yawrotation about z axis, in degrees
rollrotation about x axis, in degrees
pitchrotation about y axis, in degrees
void diguyViewCamera::set_orientation ( float  yaw,
float  roll,
float  pitch 
)

This function sets the base orientation of the camera.

It will disable the offsets.

void diguyViewCamera::set_orientation_roll ( float  roll)

This function sets the roll value of the camera's base orientation.

Parameters
rollrotation about x axis, in radians
void diguyViewCamera::get_orientation ( float *  yaw,
float **\  returnoll,
float *  pitch 
)

Returns: yaw.

roll, pitch. The actual orientation, with base orientation and offset orientation both applied.

float diguyViewCamera::get_orientation_yaw ( )

Returns: rotation about z axis, in degrees.

float diguyViewCamera::get_orientation_roll ( )

Returns: rotation about x axis, in degrees.

float diguyViewCamera::get_orientation_pitch ( )

Returns: rotation about y axis, in degrees.

void diguyViewCamera::set_desired_base_orientation ( float  yaw,
float  roll,
float  pitch 
)

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!

Parameters
yawrotation about z axis, in degrees
rollrotation about x axis, in degrees
pitchrotation about y axis, in degrees
void diguyViewCamera::set_pitch_lower_limit ( float  limit)

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!

Parameters
limitrotation about y axis, in degrees
float diguyViewCamera::get_pitch_lower_limit ( )

Returns: lower limit of the camera pitch (up/down)

void diguyViewCamera::set_pitch_upper_limit ( float  limit)

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!

Parameters
limitrotation about y axis, in degrees
float diguyViewCamera::get_pitch_upper_limit ( )

Returns: upper limit of the camera pitch (up/down)

int diguyViewCamera::get_pitch_has_limits ( )

Returns: 1 if pitch has limits, 0 if not.

void diguyViewCamera::set_degimbalize_angle ( float  angle)

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.

float diguyViewCamera::get_degimbalize_angle ( )

Returns: Current degimbalize angle, in degrees.

void diguyViewCamera::set_orientation_offset ( float  yaw,
float  roll,
float  pitch 
)

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.

Parameters
yawrotation about z axis, in degrees
rollrotation about x axis, in degrees
pitchrotation about y axis, in degrees
void diguyViewCamera::get_orientation_offset ( float *  yaw,
float **\  returnoll,
float *  pitch 
)

Gets the orientation offset of the camera.

Note that it might be relative to the base orientation, or relative to world axes.

Returns:

yaw, pitch, roll, in degrees

void diguyViewCamera::set_desired_orientation_offset ( float  yaw,
float  roll,
float  pitch 
)

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!

Parameters
yawrotation about z axis, in degrees
rollrotation about x axis, in degrees
pitchrotation about y axis, in degrees
void diguyViewCamera::set_distance ( float  distance)

This function sets the distance from the position to the fix point.

Note that this affects the fix values.

Parameters
distancedistance in meters
void diguyViewCamera::set_max_track_distance ( float  distance)

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

Parameters
distancedistance in meters; set to -1 if no max to be used
void diguyViewCamera::set_min_track_distance ( float  distance)

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

Parameters
distancedistance in meters; set to -1 if no min to be used
float diguyViewCamera::get_distance ( )

Returns: distance from position to fix point, in meters.

float diguyViewCamera::get_min_track_distance ( )

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

float diguyViewCamera::get_max_track_distance ( )

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

void diguyViewCamera::set_fix ( float  x,
float  y,
float  z 
)

This function sets the fix point of the camera.

Note that this affects the orientation.

Parameters
x,y,zposition in meters from the origin
void diguyViewCamera::release_fix ( )

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.

float diguyViewCamera::get_fix_x ( )

Returns: fix point in x, in meters.

If camera is tracking, the fix point will still be in absolute world coordinates.

float diguyViewCamera::get_fix_y ( )

Returns: fix point in y, in meters.

If camera is tracking, the fix point will still be in absolute world coordinates.

float diguyViewCamera::get_fix_z ( )

Returns: fix point in z, in meters.

If camera is tracking, the fix point will still be in absolute world coordinates.

void diguyViewCamera::set_desired_fix ( float  x,
float  y,
float  z 
)

This function sets the desired fix point of the camera.

The camera will interpolate to there from its current fix over time.

Parameters
x,y,zposition in meters from the origin
int diguyViewCamera::set_move_mode ( diguyViewCameraMoveMode  move_mode)

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.

Parameters
move_modenew movement mode of the camera; enumeration of type diguyViewCameraMoveMode
DIGUY_CAMERA_MOVE_FORWARDleft mouse press moves camera forward, right mouse press moves camera back
DIGUY_CAMERA_MOVE_SIDEWAYSleft mouse press moves camera left, right mouse press moves camera right
DIGUY_CAMERA_MOVE_VERTICALleft mouse press moves camera up, right mouse press moves camera down

Returns:

0 on success, -1 on failure

diguyViewCameraMoveMode diguyViewCamera::get_move_mode ( )

Returns: the most recent setting made by set_move_mode()

int diguyViewCamera::set_speed ( float  speed)

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.

Parameters
speedspeed of camera movement is meters per second

Returns:

0 on success, -1 on failure

float diguyViewCamera::get_speed ( )

Returns: the most recent setting made by set_speed()

int diguyViewCamera::increase_speed ( )

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

int diguyViewCamera::decrease_speed ( )

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

int diguyViewCamera::set_projection_mode ( diguyViewCameraProjectionMode  projection_mode)

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.

Parameters
projection_modenew projection mode of the camera; enumeration of type diguyViewCameraProjectionMode
DIGUY_CAMERA_PROJECTION_PERSPECTIVEstandard perspective camera, can move and rotate freely
DIGUY_CAMERA_PROJECTION_PLANVIEW_XYalways views in negative Z direction
DIGUY_CAMERA_PROJECTION_PLANVIEW_XZalways views in negative Y direction
DIGUY_CAMERA_PROJECTION_PLANVIEW_YZalways views in negative X direction

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.

diguyViewCameraProjectionMode diguyViewCamera::get_projection_mode ( )

Returns: the most recent setting made by set_projection_mode()

int diguyViewCamera::load_settings ( const char *  settings_name)

Loads the specified settings into this camera.

Returns:

0 on success, -1 on failure

int diguyViewCamera::load_settings ( diguyViewCameraSettings *  settings)

Loads the specified settings into this camera.

Returns:

0 on success, -1 on failure

void diguyViewCamera::apply_settings ( )

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().

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.

void diguyViewCamera::set_base_position_double ( double  x,
double  y,
double  z 
)

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.

Parameters
xx position, in meters
yy position, in meters
zz position, in meters
void diguyViewCamera::set_position_double ( double  x,
double  y,
double  z 
)

Equivalent to set_base_position_double(), but disables offsets.

void diguyViewCamera::get_base_position_double ( double **\  note,
double *  y,
double *  z 
)

Gets the base position of the camera.

Returns:

x, y, and z, in meters

void diguyViewCamera::get_position_double ( double *  x,
double *  y,
double *  z 
)

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.

Parameters
xx position, in meters
yy position, in meters
zz position, in meters
void diguyViewCamera::get_segment_origin ( float *  x,
float *  y,
float *  z 
)

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.

Parameters
xx component of origin, in meters
yy component of origin, in meters
zz component of origin, in meters
void diguyViewCamera::get_position_segment_offset ( float *  x,
float *  y,
float *  z 
)

This function returns the far position segment offset part of the camera's base position.

The results are placed into the passed pointers.

Parameters
xx component of segment offset, in meters
yy component of segment offset, in meters
zz component of segment offset, in meters
void diguyViewCamera::get_fix_segment_offset ( float *  x,
float *  y,
float *  z 
)

This function returns the far position offset portion of the camera's fix point.

The results are placed into the passed pointers.

Parameters
xx component of fix segment offset, in meters
yy component of fix segment offset, in meters
zz component of fix segment offset, in meters
void diguyViewCamera::set_fix_double ( double  x,
double  y,
double  z 
)

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.

Parameters
xx position, in meters
yy position, in meters
zz position, in meters
void diguyViewCamera::set_track_name ( const char *  track_name)

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.

Parameters
track_namename 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);
const char* diguyViewCamera::get_track_name ( )

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

void diguyViewCamera::set_track_group_name ( const char *  track_name)

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

Parameters
track_namename of group to look at; pass NULL to un-set track group
const char* diguyViewCamera::get_track_group_name ( )

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

void diguyViewCamera::set_track_link_name ( const char *  track_link_name)

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.

Parameters
track_link_namename of link to look at, or NULL if the base link is to be tracked
const char* diguyViewCamera::get_track_link_name ( )

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

void diguyViewCamera::set_track_offset ( float  x,
float  y,
float  z 
)

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().

Parameters
x,y,zoffset, in meters, of track point
float diguyViewCamera::get_track_offset_x ( )

Returns: x component of track offset; see set_track_offset()

float diguyViewCamera::get_track_offset_y ( )

Returns: y component of track offset; see set_track_offset()

float diguyViewCamera::get_track_offset_z ( )

Returns: z component of track offset; see set_track_offset()

void diguyViewCamera::set_track_offset_is_in_world_coordinates ( int  value)

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.

Parameters
valuepass 0 for character-relative, 0 for world coordinates
int diguyViewCamera::get_track_offset_is_in_world_coordinates ( )

Returns: the most recent setting made by set_track_offset_is_in_world_coordinates().

void diguyViewCamera::set_dolly_name ( const char *  dolly_name)

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.

Parameters
dolly_namename of entity to look from, or NULL if none
const char* diguyViewCamera::get_dolly_name ( )

This function gets the name of the dolly entity.

Parameters
dolly_namename of character to look from, or NULL
void diguyViewCamera::set_dolly_offset ( float  x,
float  y,
float  z 
)

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().

Parameters
x,y,zoffset, in meters, of dolly point
float diguyViewCamera::get_dolly_offset_x ( )

Returns: x component of position offset; see set_dolly_offset()

float diguyViewCamera::get_dolly_offset_y ( )

Returns: y component of position offset; see set_dolly_offset()

float diguyViewCamera::get_dolly_offset_z ( )

Returns: z component of position offset; see set_dolly_offset()

void diguyViewCamera::set_dolly_link_name ( const char *  dolly_link_name)

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

Parameters
dolly_link_namename of link to look from, or NULL if the position link is to influence camera position
const char* diguyViewCamera::get_dolly_link_name ( )

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

void diguyViewCamera::set_dolly_offset_is_in_world_coordinates ( int  value)

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

Default value is 0.

Parameters
valuepass 0 for character-relative, 1 for world coordinates
int diguyViewCamera::get_dolly_offset_is_in_world_coordinates ( )

Returns: the most recent setting made by set_dolly_offset_is_in_world_coordinates().

void diguyViewCamera::set_orientation_offset_is_relative ( int  value)

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.

Parameters
valuepass 1 to match orientation, 0 to not match
int diguyViewCamera::get_orientation_offset_is_relative ( )

Returns: the most recent setting made by set_orientation_offset_is_relative().

void diguyViewCamera::set_match_dolly_orientation ( int  value)

This function has been deprecated, but remains for backwards compatibility.

It is replaced by set_orientation_offset_is_relative()

int diguyViewCamera::get_match_dolly_orientation ( )

This function has been deprecated, but remains for backwards compatibility.

It is replaced by get_orientation_offset_is_relative()

void diguyViewCamera::set_use_special_track_mode ( int  value)

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.

int diguyViewCamera::get_use_special_track_mode ( )

Returns: 1, if special track mode is being used.

int diguyViewCamera::get_symbolic_view ( )

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

int diguyViewCamera::add_callback ( int  callback_id,
diguyViewCameraCallback *  callback,
void *  callback_params = 0,
void *  callback_user_data = 0 
)

This function adds a user callback.

Parameters
callbackpointer to function with prototype diguyViewCameraCallback (typedefed above)
callback_idinteger id of when this callback is to be called
callback_paramsstruct containing additional parameters needed by some callbacks; actual type depends on callback_id
callback_user_datapointer 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

int diguyViewCamera::remove_callback ( int  callback_id,
diguyViewCameraCallback *  callback 
)

This function removes a user callback.

All callbacks matching the specified callback_id and callback function will be removed.

Parameters
callback_idinteger id of when this callback is to be called
callbackpointer to function with prototype diguyViewCameraCallback (typedefed above)

Returns:

0 on success, -1 on failure

int diguyViewCamera::remove_callback_with_user_data ( int  callback_id,
void *  callback_user_data 
)

This function removes a user callback.

All callbacks matching the specified callback_id and callback_user_data pointer will be removed.

Parameters
callback_idinteger id of when this callback is to be called
callback_user_datapointer for user's own use

Returns:

0 on success, -1 on failure

int diguyViewCamera::add_callback_script ( int  callback_id,
const char *  callback_script,
const char *  callback_script_type = NULL 
)

This function adds a user callback script.

Callback scripts can be removed with remove_callback_script().

Parameters
callback_idinteger id of the callback
callback_scriptscript text of callback to be added
callback_script_typethe 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

int diguyViewCamera::remove_callback_script ( int  callback_id,
const char *  callback_script,
const char *  callback_script_type = NULL 
)

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

Parameters
callback_idinteger id of the callback
callback_scriptscript text of callback previously added
callback_script_typethe 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

void diguyViewCamera::set_speed_fov_degrees_per_wheel_click ( float  fov_change)

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

Parameters
fov_changechange to FOV in degrees
float diguyViewCamera::get_speed_fov_degrees_per_wheel_click ( )

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

void diguyViewCamera::set_speed_meters_per_second ( float  speed)

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

Parameters
speedflying speed in meters per second
float diguyViewCamera::get_speed_meters_per_second ( )

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

Returns:

speed in meters per second

void diguyViewCamera::set_require_smooth_servo ( int  require)

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

Parameters
require0 for smooth servoing
int diguyViewCamera::get_require_smooth_servo ( )

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

void diguyViewCamera::set_servo_time_modifier ( float  modifier)

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

float diguyViewCamera::get_servo_time_modifier ( )

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

void diguyViewCamera::set_track_camera_avoids_obstacles ( int  avoid)

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

Parameters
avoidstrue for avoidance
int diguyViewCamera::get_track_camera_avoids_obstacles ( )

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

void diguyViewCamera::set_ignore_mouse_drags ( int  ignore)

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.

Parameters
avoids1 to ignore mouse drags; 0 if not
int diguyViewCamera::get_ignore_mouse_drags ( )

Gets whether the camera should ignore mouse input from DI-Guy Scenario.

Returns:

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

void diguyViewCamera::update_frustum ( float *  proj_matrix,
float *  model_matrix 
)

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.

bdiCamera* diguyViewCamera::get_scripted_object ( )
inline

Friends And Related Function Documentation

friend class bdiCamera
friend

Member Data Documentation

bdiCamera* diguyViewCamera::m_camera
private

A pointer to internal data.

bool diguyViewCamera::s_warn_if_position_set_ignored
staticprivate
The documentation for this class was generated from the following file: