diguyCharacterPath Class Reference

A interface for manipulating a characters spline path typically authored in DI-Guy Scenario. More...

#include <diguyCharacterPath.h>

Public Member Functions
const char *	get_name ()
	Returns the name of the path. More...
int	set_name (const char *name)
	This function sets the name of this object. More...
long	get_uid ()
	All character paths are assigned a unique identifier, or uid. More...
diguyCharacter *	get_character ()
	Returns: character that owns this path. More...
int	update ()
	This function should be called after all modifications have been made to the path and it is time to re-derive the overall path shape and when actions happen. More...
float	get_length ()
	This function returns the total length of the path, in meters. More...
float	get_duration ()
	This function returns how long this path is. More...
int	get_point_at_distance (float distance_into_path, float *x, float *y, float *z, float *rz, float *rx, float *ry)
	This function returns, via the passed variable pointers, the position and orientation of the point on the path at the specified distance. More...
diguyPathShape *	get_path_shape ()
	This function returns the underlying path shape of the path. More...
Waypoint Functions
int	get_num_waypoints ()
	Returns: More...
diguyWaypoint *	get_waypoint_at_index (int index)
	This function gets the waypoint at the specified index and returns a pointer to it. More...
diguyWaypoint *	find_waypoint (const char *name)
	This function returns a pointer to the specified waypoint. More...
diguyWaypoint *	create_waypoint (float x=0.0f, float y=0.0f, float z=0.0f, float yaw=0.0f, float roll=0.0f, float pitch=0.0f, float weight=1.0f, int index=-1)
	This function creates a new waypoint that is added to the path. More...
int	add_waypoint (diguyWaypoint *waypoint)
	This function adds a waypoint to the path. More...
Action Bead Functions
int	get_num_action_beads ()
	Returns: More...
diguyCharacterPathActionBead *	get_action_bead_at_index (int index)
	This function gets the action bead at the specified index and returns a pointer to it. More...
diguyCharacterPathActionBead *	find_action_bead (const char *name)
	This function returns a pointer to the specified bead. More...
diguyCharacterPathActionBead *	get_final_action_bead ()
	This function returns a pointer to the last action bead of the path. More...
diguyCharacterPathActionBead *	create_action_bead (const char *action, int index=-1)
	This function inserts a new action bead at the specified index and returns a pointer to it. More...
int	destroy_action_bead (diguyCharacterPathActionBead *action_bead)
	This function removes the passed action bead from the path and destroys it. More...
Script Bead Functions
int	get_num_script_beads ()
	Returns: More...
diguyCharacterPathScriptBead *	get_script_bead_at_index (int index)
	This function gets the script bead at the specified index and returns a pointer to it. More...
diguyCharacterPathScriptBead *	find_script_bead (const char *name)
	This function returns a pointer to the specified bead. More...
diguyCharacterPathScriptBead *	create_script_bead (const char *script, int index=-1, const char *script_type="lua")
	This function inserts a new script bead at the specified index and returns a pointer to it. More...
int	destroy_script_bead (diguyCharacterPathScriptBead *script_bead)
	This function removes the passed script bead from the path and destroys it. More...
Decision Bead Functions
int	get_num_decision_beads ()
	Returns: More...
diguyCharacterPathDecisionBead *	get_decision_bead_at_index (int index)
	This function gets the decision bead at the specified index and returns a pointer to it. More...
diguyCharacterPathDecisionBead *	find_decision_bead (const char *name)
	This function returns a pointer to the specified bead. More...
Gaze Bead Functions
int	get_num_gaze_beads ()
	Returns: More...
diguyCharacterPathGazeBead *	get_gaze_bead_at_index (int index)
	This function gets the gaze bead at the specified index and returns a pointer to it. More...
diguyCharacterPathGazeBead *	find_gaze_bead (const char *name)
	This function returns a pointer to the specified bead. More...
Aim Bead Functions
int	get_num_aim_beads ()
	Returns: More...
diguyCharacterPathAimBead *	get_aim_bead_at_index (int index)
	This function gets the aim bead at the specified index and returns a pointer to it. More...
diguyCharacterPathAimBead *	find_aim_bead (const char *name)
	This function returns a pointer to the specified bead. More...
Experimental Functions
The following functions are experimental and may change or disappear with no warning.
int	translate (float tx, float ty, float tz)
int	rotate_about_point (float rz, float rx, float ry, float rotation_pt_x, float rotation_pt_y, float rotation_pt_z)
int	set_ground_clamp_when_on_path (int ground_clamp_when_on_path)
int	get_ground_clamp_when_on_path ()
int	get_position_at_distance (float distance, float *tx, float *ty, float *tz, float *rz=NULL, float *rx=NULL, float *ry=NULL)
int	get_position_at_distance_double (float distance, double *tx, double *ty, double *tz, float *rz=NULL, float *rx=NULL, float *ry=NULL)
int	get_position_at_t (float t, float *tx, float *ty, float *tz, float *rz=NULL, float *rx=NULL, float *ry=NULL)
int	get_position_at_t_double (float t, double *tx, double *ty, double *tz, float *rz=NULL, float *rx=NULL, float *ry=NULL)

Callback Functions
enum	{ CALLBACK_ID_TIME_LEFT_DEPRECATED = 1, CALLBACK_ID_TIME_INTO_DEPRECATED }
	This is an enumeration of the different callbacks that can be registered with add_callback(). More...
int	add_callback (int callback_id, diguyCharacterPathCallback *callback, void *callback_params=0, void *callback_user_data=0)
	This function adds a user callback. More...
int	remove_callback (int callback_id, diguyCharacterPathCallback *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.
bdiScenarioPath *	m_scripted_object
	A pointer to internal data. More...
class	bdiScenarioPath
class	diguyCharacter
bdiScenarioPath *	get_scripted_object ()
	diguyCharacterPath (bdiScenarioPath *path)
	A private constructor. More...
	~diguyCharacterPath ()
	A private destructor. More...

Detailed Description

A interface for manipulating a characters spline path typically authored in DI-Guy Scenario.

Member Enumeration Documentation

anonymous enum

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

Usable From:

• C++
• Script

Enumerator
CALLBACK_ID_TIME_LEFT_DEPRECATED
CALLBACK_ID_TIME_INTO_DEPRECATED

Constructor & Destructor Documentation

diguyCharacterPath::diguyCharacterPath ( bdiScenarioPath *  path )

private

A private constructor.

diguyCharacterPath::~diguyCharacterPath ( )

private

A private destructor.

Member Function Documentation

const char* diguyCharacterPath::get_name

(

)

Returns the name of the path.

This pointer will never be NULL.

Returns:

name of the path

Callable From:

• C++
• Script

int diguyCharacterPath::set_name

(

const char *

name

)

This function sets the name of this object.

Returns:

0 on success, -1 on failure

Callable From:

• C++
• Script

long diguyCharacterPath::get_uid

(

)

All character paths are assigned a unique identifier, or uid.

This function returns this path's uid.

Note: unique identifiers will change between DI-Guy runs!

Returns:

unique identifier of object

Callable From:

• C++
• Script

diguyCharacter* diguyCharacterPath::get_character

(

)

Returns: character that owns this path.

Callable From:

• C++
• Script

int diguyCharacterPath::update

(

)

This function should be called after all modifications have been made to the path and it is time to re-derive the overall path shape and when actions happen.

This update is deferred for reasons of performance; if there are a lot of modifications to be made to the path they can all be done in a group with only a single final update.

A call to update() is typically required after certain calls are made on objects owned by the path, such as a diguyWaypoint or a diguyCharacterPathActionBead. The documentation for function calls of these objects will state whether a subsequent update() call is necessary.

Returns:

0 on success, -1 on failure

Callable From:

• C++
• Script

float diguyCharacterPath::get_length

(

)

This function returns the total length of the path, in meters.

Returns:

length of path in meters

Callable From:

• C++
• Script

float diguyCharacterPath::get_duration

(

)

This function returns how long this path is.

Returns:

duration of this path, in seconds

Callable From:

• C++
• Script

int diguyCharacterPath::get_point_at_distance	(	float	distance_into_path,
		float *	x,
		float *	y,
		float *	z,
		float *	rz,
		float *	rx,
		float *	ry
	)

This function returns, via the passed variable pointers, the position and orientation of the point on the path at the specified distance.

Parameters

distance_into_path	distance in meters into path of the desired point
x,y,z	position of point in meters from the origin
rz,rx,ry	orientation of point in degrees counter-clockwise from the positive X axis

Returns:

0 on success, -1 on failure

Callable From:

• C++
• Script

diguyPathShape* diguyCharacterPath::get_path_shape

(

)

This function returns the underlying path shape of the path.

The path shape defines only the waypoints and associated spline shape of the path; it doesn't not contain any beads or other information.

The returned path shape should be considered READ ONLY. DO NOT edit the path shape using diguyPathShape member functions!

Returns:

pointer to object of type diguyPathShape

Callable From:

• C++
• Script

int diguyCharacterPath::get_num_waypoints

(

)

Returns:

the number of waypoints belonging to this path

Callable From:

• C++
• Script

diguyWaypoint* diguyCharacterPath::get_waypoint_at_index

(

int

index

)

This function gets the waypoint at the specified index and returns a pointer to it.

The returned waypoint can then be queried for information or modified.

Note that if the waypoint is modified, the update() function must be called to update the path's shape and other information.

Parameters

index

index of the waypoint; indices start at 0

Returns:

pointer of type diguyWaypoint; NULL if no waypoint at the specified index

Callable From:

• C++
• Script

Lua Example:

This example gets the first waypoint of the first character's first path. It then changes the x coordinate of the waypoint and updates the path to reflect the change.

local character = this_scenario:get_character_at_index(0);
local path0 = character:get_path_at_index(0);

local wp0 = path0:get_waypoint_at_index(0);
local wp0_x = wp0:get_x();
wp0:set_x(wp0_x + 1.0);

path0:update();

diguyWaypoint* diguyCharacterPath::find_waypoint

(

const char *

name

)

This function returns a pointer to the specified waypoint.

Parameters

name	name of waypoint to be found

Returns:

pointer of type diguyWaypoint; NULL if not found

Callable From:

• C++
• Script

diguyWaypoint* diguyCharacterPath::create_waypoint	(	float	x = 0.0f,
		float	y = 0.0f,
		float	z = 0.0f,
		float	yaw = 0.0f,
		float	roll = 0.0f,
		float	pitch = 0.0f,
		float	weight = 1.0f,
		int	index = -1
	)

This function creates a new waypoint that is added to the path.

Do not call diguyScenario::destroy_waypoint() on the returned waypoint; it will be destroyed automatically with the path.

Parameters

tx,ty,tz	position in meters from the origin
rz,rx,ry	orientations in degrees counter-clockwise from the positive X axis
weight	how much influence this waypoint exerts over the path curve
index	where the waypoint should be inserted in
the	path; indices start at 0; pass 1 to add to end of path

Returns:

pointer to type diguyWaypoint

Callable From:

• C++
• Script

int diguyCharacterPath::add_waypoint

(

diguyWaypoint *

waypoint

)

This function adds a waypoint to the path.

The waypoint should be created using the function diguyScenario::create_waypoint(), and destroyed using the function diguyScenario::destroy_waypoint().

An internal copy of the waypoint is made, so it can be destroyed right after this function call or used for other path shapes.

Parameters

waypoint

waypoint to be appended to end of path

Returns:

0 on success, -1 on failure

Callable From:

• C++
• Script

int diguyCharacterPath::get_num_action_beads

(

)

Returns:

the number of action beads belonging to this path

Callable From:

• C++
• Script

diguyCharacterPathActionBead* diguyCharacterPath::get_action_bead_at_index

(

int

index

)

This function gets the action bead at the specified index and returns a pointer to it.

The returned action bead can then be queried for information or modified.

Note that if the action bead is modified, the update() function must be called to update the path's information.

Returns:

pointer of type diguyCharacterPathActionBead; NULL if no action bead at the specified index

Parameters

index

index of the action bead; indices start at 0

Callable From:

• C++
• Script

diguyCharacterPathActionBead* diguyCharacterPath::find_action_bead

(

const char *

name

)

This function returns a pointer to the specified bead.

Parameters

name	name of bead to be found

Returns:

pointer of type diguyCharacterPathActionBead; NULL if not found

Callable From:

• C++
• Script

diguyCharacterPathActionBead* diguyCharacterPath::get_final_action_bead

(

)

This function returns a pointer to the last action bead of the path.

The last action bead is slightly different than the rest. It has no inherent duration or length; instead, it effectively specifies what the character should do once this path has completed.

Calling this function is the same as the following:

int num_action_beads = path->get_num_action_beads();
diguyCharacterPathActionBead* ab;
ab = path->get_action_bead_at_index(num_action_beads-1);

Do not call delete or destroy_action_bead() on the returned pointer. All paths must have a final action bead.

Returns:

pointer of type diguyCharacterPathActionBead; this pointer should never be NULL

Callable From:

• C++
• Script

diguyCharacterPathActionBead* diguyCharacterPath::create_action_bead	(	const char *	action,
		int	index = -1
	)

This function inserts a new action bead at the specified index and returns a pointer to it.

The returned action bead can then be queried for information or modified.

Note that the update() function must be called after this function.

Do not call delete on the returned pointer. Use destroy_action_bead() instead.

Returns:

pointer of type diguyCharacterPathActionBead; NULL if insertion failed

Parameters

action	action new bead should perform
index	index of the action bead; indices start at 0;
pass	1 to append the action bead to the end of the path

Callable From:

• C++
• Script

int diguyCharacterPath::destroy_action_bead

(

diguyCharacterPathActionBead *

action_bead

)

This function removes the passed action bead from the path and destroys it.

Note that the update() function must be called after this function.

Returns:

0 on success, -1 on failure

Parameters

action_bead

object to destroy; must be part of this path

Callable From:

• C++
• Script

int diguyCharacterPath::get_num_script_beads

(

)

Returns:

the number of script beads belonging to this path

Callable From:

• C++
• Script

diguyCharacterPathScriptBead* diguyCharacterPath::get_script_bead_at_index

(

int

index

)

This function gets the script bead at the specified index and returns a pointer to it.

The returned script bead can then be queried for information or modified.

Note that if the script bead is modified, the update() function must be called to update the path's information.

Returns:

pointer of type diguyCharacterPathScriptBead; NULL if no script bead at the specified index

Parameters

index

index of the script bead; indices start at 0

Callable From:

• C++
• Script

diguyCharacterPathScriptBead* diguyCharacterPath::find_script_bead

(

const char *

name

)

This function returns a pointer to the specified bead.

Parameters

name	name of bead to be found

Returns:

pointer of type diguyCharacterPathScriptBead; NULL if not found

Callable From:

• C++
• Script

diguyCharacterPathScriptBead* diguyCharacterPath::create_script_bead	(	const char *	script,
		int	index = -1,
		const char *	script_type = "lua"
	)

This function inserts a new script bead at the specified index and returns a pointer to it.

The returned script bead can then be queried for information or modified.

Note that the update() function must be called after this function.

Do not call delete on the returned pointer. Use destroy_script_bead() instead.

Returns:

pointer of type diguyCharacterPathScriptBead; NULL if insertion failed

Parameters

script	script new bead should perform
index	index of the script bead; indices start at 0;
pass	1 to create the bead at the last index
script_type	defaults to "lua"

Callable From:

• C++
• Script

int diguyCharacterPath::destroy_script_bead

(

diguyCharacterPathScriptBead *

script_bead

)

This function removes the passed script bead from the path and destroys it.

Note that the update() function must be called after this function.

Returns:

0 on success, -1 on failure

Parameters

script_bead

object to destroy; must be part of this path

Callable From:

• C++
• Script

int diguyCharacterPath::get_num_decision_beads

(

)

Returns:

the number of decision beads belonging to this path

Callable From:

• C++
• Script

diguyCharacterPathDecisionBead* diguyCharacterPath::get_decision_bead_at_index

(

int

index

)

This function gets the decision bead at the specified index and returns a pointer to it.

The returned decision bead can then be queried for information.

Note that if the decision bead is modified, the update() function must be called to update the path's information.

Returns:

pointer of type diguyCharacterPathDecisionBead; NULL if no script bead at the specified index

Parameters

index

index of the decision bead; indices start at 0

Callable From:

• C++
• Script

diguyCharacterPathDecisionBead* diguyCharacterPath::find_decision_bead

(

const char *

name

)

This function returns a pointer to the specified bead.

Parameters

name	name of bead to be found

Returns:

pointer of type diguyCharacterPathDecisionBead; NULL if not found

Callable From:

• C++
• Script

int diguyCharacterPath::get_num_gaze_beads

(

)

Returns:

the number of gaze beads belonging to this path

Callable From:

• C++
• Script

diguyCharacterPathGazeBead* diguyCharacterPath::get_gaze_bead_at_index

(

int

index

)

This function gets the gaze bead at the specified index and returns a pointer to it.

The returned gaze bead can then be queried for information.

Note that if the gaze bead is modified, the update() function must be called to update the path's information.

Returns:

pointer of type diguyCharacterPathDecisionBead; NULL if no script bead at the specified index

Parameters

index

index of the gaze bead; indices start at 0

Callable From:

• C++
• Script

diguyCharacterPathGazeBead* diguyCharacterPath::find_gaze_bead

(

const char *

name

)

This function returns a pointer to the specified bead.

Parameters

name	name of bead to be found

Returns:

pointer of type diguyCharacterPathGazeBead; NULL if not found

Callable From:

• C++
• Script

int diguyCharacterPath::get_num_aim_beads

(

)

Returns:

the number of aim beads belonging to this path

Callable From:

• C++
• Script

diguyCharacterPathAimBead* diguyCharacterPath::get_aim_bead_at_index

(

int

index

)

This function gets the aim bead at the specified index and returns a pointer to it.

The returned aim bead can then be queried for information.

Note that if the aim bead is modified, the update() function must be called to update the path's information.

Returns:

pointer of type diguyCharacterPathDecisionBead; NULL if no script bead at the specified index

Parameters

index

index of the aim bead; indices start at 0

Callable From:

• C++
• Script

diguyCharacterPathAimBead* diguyCharacterPath::find_aim_bead

(

const char *

name

)

This function returns a pointer to the specified bead.

Parameters

name	name of bead to be found

Returns:

pointer of type diguyCharacterPathAimBead; NULL if not found

Callable From:

• C++
• Script

int diguyCharacterPath::add_callback	(	int	callback_id,
		diguyCharacterPathCallback *	callback,
		void *	callback_params = 0,
		void *	callback_user_data = 0
	)

This function adds a user callback.

Parameters

callback	pointer to function with prototype diguyCharacterPathCallback (typedefed above)
callback_id	integer id of when this callback is to be called
callback_params	not currently used; pass NULL
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_TIME_LEFT_DEPRECATED

 This callback id was formerly CALLBACK_ID_TIME_LEFT, which
 has been deprecated.  Use a decision bead or script bead
 located near the end of the path for new development.

CALLBACK_ID_TIME_INTO_DEPRECATED

 This callback id was formerly CALLBACK_ID_TIME_INTO, which
 has been deprecated.  Use a decision bead or script bead
 located near the beginning of the path for new development.

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

Callable From:

• C++

int diguyCharacterPath::remove_callback	(	int	callback_id,
		diguyCharacterPathCallback *	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 diguyCharacterCallback (typedefed above)

Returns:

0 on success, -1 on failure

Callable From:

• C++

int diguyCharacterPath::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

Callable From:

• C++

int diguyCharacterPath::translate	(	float	tx,
		float	ty,
		float	tz
	)

int diguyCharacterPath::rotate_about_point	(	float	rz,
		float	rx,
		float	ry,
		float	rotation_pt_x,
		float	rotation_pt_y,
		float	rotation_pt_z
	)

int diguyCharacterPath::set_ground_clamp_when_on_path

(

int

ground_clamp_when_on_path

)

int diguyCharacterPath::get_ground_clamp_when_on_path

(

)

int diguyCharacterPath::get_position_at_distance	(	float	distance,
		float *	tx,
		float *	ty,
		float *	tz,
		float *	rz = NULL,
		float *	rx = NULL,
		float *	ry = NULL
	)

int diguyCharacterPath::get_position_at_distance_double	(	float	distance,
		double *	tx,
		double *	ty,
		double *	tz,
		float *	rz = NULL,
		float *	rx = NULL,
		float *	ry = NULL
	)

int diguyCharacterPath::get_position_at_t	(	float	t,
		float *	tx,
		float *	ty,
		float *	tz,
		float *	rz = NULL,
		float *	rx = NULL,
		float *	ry = NULL
	)

int diguyCharacterPath::get_position_at_t_double	(	float	t,
		double *	tx,
		double *	ty,
		double *	tz,
		float *	rz = NULL,
		float *	rx = NULL,
		float *	ry = NULL
	)

bdiScenarioPath* diguyCharacterPath::get_scripted_object ( )

inline

Friends And Related Function Documentation

friend class bdiScenarioPath

friend

friend class diguyCharacter

friend

Member Data Documentation

bdiScenarioPath* diguyCharacterPath::m_scripted_object

private

A pointer to internal data.

---

The documentation for this class was generated from the following file:

• c:/diguy125/include/diguyCharacterPath.h