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

void	set_height_above_terrain (float height)
	used for calculating shadow map offset 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...

void	convert_to_local_camera (double x, double y, double *z)
	Converts the passed in values into the current local space of the diguy camera. 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	print_debug_info (const char *tag)
	Prints information about the camera's current state to the log. More...

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 (diguyViewCameraServoTarget target, int require)
	Sets whether the camera should smoothly servo to its new desired position/heading (as opposed to instantly popping there). More...

void	set_require_smooth_servo (int require)
	Similar to main set_require_smooth_servo(), but sets value for all targets. More...

int	get_require_smooth_servo (diguyViewCameraServoTarget target)
	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 (diguyViewCameraServoTarget target, float modifier)
	Sets a factor that determines how smoothly the camera should servo. More...

void	set_servo_time_modifier (float modifier)
	Similar to main set_servo_time_modifier(). More...

float	get_servo_time_modifier (diguyViewCameraServoTarget target)
	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.

Versions of this document

Text file: 8/6/2016
diguyViewCamera.h: 8/6/2016

Google doc: 8/6/2016

Overview

Cameras are an essential feature of any modern gaming or simulation engine. They represent a point in space from which the user sees the 3D environment and characters within it. Typically, cameras can be moved around and oriented to face in different directions. In some use cases, the user has controls that steer a camera around the environment, allowing him/her to visit different parts of it. In other cases, the user controls a character or vehicle to which the camera is mounted. Or, the camera's motions could be scripted, working without user direction.

The DI-Guy camera is a complex system that can be used in a variety of ways. The many features can make its behavior potentially confusing, so it's helpful start by considering the most basic use case.

A simple camera:

A simple camera can be thought of as having a position, an orientation, a fix point, and a distance. The position is where the camera is in the world. The orientation is its yaw, pitch, and roll (applied in that order). The fix point is the point being looked at, and the distance is how far from the camera it is.

As one might expect, not all these pieces of information are necessary to set up a camera. Two of the three following will do:

Position
Orientation/distance
Fix Point

Normally, setting the camera's orientation will cause a new fix point to be derived at <distance> meters from the camera. Setting a new fix point will cause the derivation of a new orientation and distance. Setting the camera's position will cause a new fix point to be derived, but maintain the current orientation. Orientation/distance and fix are always consistent with each other.

Locking

Sometimes, it's handy to make sure that the camera always maintains its fix point, even as we change its orientation/distance or its position. For this purpose, we can "lock" the fix point.

Now, if the caller alters the camera's position, it will turn automatically to keep the fix point centered. If the caller alters the camera's orientation, its position will change so that the fix point remains in view. This is handy for when we want to make the camera "orbit" around the fix point.

Alternatively, we can lock the camera's orientation/distance. In this case, if the caller alters the camera's fix point, the camera's position will change as well. This is handy for when we want to keep the camera in the same spot relative to the thing we're looking at, even if it moves.

It is possible to lock both fix and orientation. The effect of this is that we won't be able to set the camera's position directly; rather, it will be derived from the fix or orientation settings.

Servoing

The camera can be made to move smoothly over time, changing its orientation/distance, fix, or position over some number of seconds. This achieved by calling:

set_desired_position()
set_desired_orientation()/set_desired_distance()
set_desired_fix()

After one of the calls above, the camera will transition from the current value to the desired one. It can servo more than one of these settings at a time, though the "lock" flags already described determine what will happen as the changing values are applied.

For example, if we want the camera to seem to orbit around the fix point, we should lock the fix point, then servo the orientation. If we want the camera to follow the fix point, while moving independently, we should lock it and servo the position. If we want the camera to move from one place to another while spinning around 180 degrees, we should lock nothing and servo the position and orientation.

Offsets

In this section, we move beyond the simple camera to its more complex usage. Previous section of this document discussed a camera with a position, orientation/distance, and fix point. However, our camera system also provides a position offset and an orientation offset.

What this means is that the camera can be mounted on an invisible platform, whose position and orientation are the base position/orientation. An invisible rod extends from the platform to the camera itself. The end of the rod is determined by the position offset, which is relative to the platform's position, and the camera's final orientation is determined by the orientation offset, which is usually (but not always – see below) relative to the platform's orientation.

It's important to remember that the base position/orientation, position/orientation offsets, and actual position/orientation are three different things. The base and offset values describe the camera SYSTEM; the actual values tell us where the camera ITSELF is.

The complete list of positional attributes:

Base position
Base orientation
Distance (to fix point)
Fix point
Position offset
Orientation offset

Offsets only apply if set_offsets_active() is called; otherwise the camera remains the simple camera. The main use for them is in situations where we want to attach the camera to some character and have it stick with that character, but also maintain its own relative position and direction. Imagine, for example, a camera on the underbelly of a drone aircraft. The camera will stick with the drone through its maneuvers, but can be swiveled to look at points on the ground. Alternatively, it could track a fix point, as described above.

The offsets can be used in different ways.

Position offset

Relative: in the coordinate system established by the base orientation
World: in the world's coordinate system (but still an offset from base position)

Orientation offset

Relative: relative to the base orientation
World: relative to the world's axes (effectively making the base orientation irrelevant)

Offsets and locking: Note that if the orientation is locked, the camera will maintain the same ACTUAL orientation (see above). The practical outcome of this is that we can change the base orientation of the camera system the orientation offset will change to keep the direction consist. This is useful for when we want to keep a camera attached to a moving character pointed in the same direction, even as the character moves and turns.

Dollying and Tracking

These are convenience concepts that exist on top of the code framework already described.

If you set a dolly character, it will become the platform that the camera rides on, and the camera's base position/orientation will match the character's. Callers can still change the position/orientation offsets, or how they're applied. A common use for this kind of feature is a third-person "videogame" camera that follows behind a walking character, but might swivel one way or the other as the character turns around obstacles. One can even dolly to a link on a particular character – this might be handy if you want a camera mounted on the revolving turret of a tank.

If you set a track character, that character will determine the camera's fix point. There are ways to fix on a particular body link or at a point offset from the character.

Dolly and track characters can be set at the same time. An example use would be a camera dollied to the doorway of a moving bus, which turns to observe a pedestrian walking down the sidewalk. A camera can even track the same character that it's dollied to.

Under the hood, the dolly character (if used) will take over setting the camera's base position and orientation. The track character will drive the camera's fix point.

DI-Guy Scenario's Camera Page

The Look-From Section

This encompasses the camera's base position, base orientation, position offset, and orientation offset. If the camera is dollied to something, the user will lose control over its base position and base orientation, but can still control how the offsets are applied relative to these.

The look-from character is the dolly character. If no selection is made, no dollying will be used.

The Look-At Section

This defines the fix point of the camera. If the camera is tracking something, the fix point will be the tracked character, a part of the tracked character's body, or a position relative to the tracked character. The user can specifies whether the offset is in the local or world coordinate system.

The look-at entity is the entity to track. If no selection is made, no character or group will be tracked.

Move Modes

There are different ways of using the mouse to control a camera. Note that dollying and tracking might work somewhat differently in each mode, though the basic concepts are the same.

Parameters

DRAG	The user can "pull" the terrain around with the mouse.
ORBIT	Mouse drags cause the camera to circle around the entity being tracked. Unlike in FLY mode, the camera stays with a tracked entity. If there is not a tracked entity, the camera will orbit the fix point.
FLY	FORWARD Mouse button presses cause the camera to fly forward or backward. Mouse drags rotate the camera. If the camera is dollied to a character, movement will be relative to that character. Switching to this mode turns off tracking.
FLY	SIDEWAYS and FLY VERTICAL Same as FLY FORWARD, but the mouse buttons cause different directional moves.
STATIONARY	This is a hidden mode that does not appear in Scenario's UI. It's used when the camera is tracking something, but remains in one place. The mode is canceled and changed to FLY as soon as the user moves the mouse. The tracking is undone.

Projection Modes

Parameters

PERSPECTIVE	a normal 3D perspective, with closer objects being bigger than far-away objects
PLAN_XY	a perspective-less top-down view, similar to the plan view in VR-Forces
PLAN_XZ	a perspective-less view along the world's Y axis
PLAN_YZ	a perspective-less view along the world's X axis
ORTHOGRAPHIC	a perspective-less view reminiscent of the Sims. Pro tip: change the camera's orientation values (in the text boxes) for a different view.

Notes: In the non-perspective modes, it's impossible to dolly to one character and track another. If both selections are made, the dolly choice will simply be ignored. DRAG and ORBIT move modes can only be used in PERSPECTIVE projection mode

Camera Movers

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_plane distance 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_plane distance 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

fov	field-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

fov	max 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

fov	min 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

aspect aspect 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,z position 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,z position 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,z	position in meters from the origin
preserve_fix	obsolete, 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,z position 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,z position 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

yaw	rotation about z axis, in degrees
roll	rotation about x axis, in degrees
pitch	rotation 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

roll	rotation 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

yaw	rotation about z axis, in degrees
roll	rotation about x axis, in degrees
pitch	rotation 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

limit rotation 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

limit rotation 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

yaw	rotation about z axis, in degrees
roll	rotation about x axis, in degrees
pitch	rotation 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

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

void diguyViewCamera::set_distance ( float distance )

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

This may move the fix point or the position of the camera, depending on locking.

Parameters

distance distance 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

distance distance 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

distance distance 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. It may also move the camera, depending on orientation locking.

Parameters

x,y,z position 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,z position 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_mode	new movement mode of the camera; enumeration of type diguyViewCameraMoveMode
DIGUY_CAMERA_MOVE_DRAG	mouse input drags and rotates the landscape (from user's perspective) in a manner similar to an RTS game
DIGUY_CAMERA_MOVE_ORBIT	mouse input causes the camera to circle around a fix point or a tracked character
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

**

Note: entering forward, sideways, or vertical mode will cause the camera to stop tracking any entity currently being tracked. It's impossible to fly the camera around the world and keep it fixed to a target at the same time.

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

speed speed 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_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

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

void diguyViewCamera::set_height_above_terrain ( float height )

used for calculating shadow map offset

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

x	x position, in meters
y	y position, in meters
z	z 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

x	x position, in meters
y	y position, in meters
z	z 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

x	x component of origin, in meters
y	y component of origin, in meters
z	z 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

x	x component of segment offset, in meters
y	y component of segment offset, in meters
z	z 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

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

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

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

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

Converts the passed in values into the current local space of the diguy camera.

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.

Setting a track entity will change the movement mode of the camera to stationary or orbit. This is because the camera can't be flown around the world if it is fixed on something.

Parameters

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);

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_name name 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_name name 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,z offset, 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

value pass 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.

Setting a dolly entity may switch the camera's movement mode to orbit, if the character is already tracking something. The tracked entity will be orbited, but if the dolly character moves, the camera will still maintain its position relative to that character.

Parameters

dolly_name name 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_name name 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,z offset, 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_name name 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

value pass 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

value pass 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

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

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_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

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_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

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_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

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_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

void diguyViewCamera::print_debug_info ( const char * tag )

Prints information about the camera's current state to the log.

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_change change 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

speed flying 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	(	diguyViewCameraServoTarget	target,
		int	require
	)

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

target (position, orientation, or fix)

Parameters

require 0 for smooth servoing

void diguyViewCamera::set_require_smooth_servo ( int require )

Similar to main set_require_smooth_servo(), but sets value for all targets.

Here for backwards compatibility.

int diguyViewCamera::get_require_smooth_servo ( diguyViewCameraServoTarget target )

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	(	diguyViewCameraServoTarget	target,
		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.

target (position, orientation, or fix) modifier

void diguyViewCamera::set_servo_time_modifier ( float modifier )

Similar to main set_servo_time_modifier().

Sets value for all targets.

float diguyViewCamera::get_servo_time_modifier ( diguyViewCameraServoTarget target )

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

avoids true 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

avoids 1 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:

diguyViewCamera.h

Public Member Functions

C++ Callback Functions

Private Functions

Detailed Description

Overview

A simple camera:

Locking

Servoing

Offsets

The complete list of positional attributes:

Position offset

Orientation offset

Dollying and Tracking

DI-Guy Scenario's Camera Page

The Look-From Section

The Look-At Section

Move Modes

Projection Modes

Camera Movers

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation