diguyCharacterPath

Generated from diguyCharacterPath.h

DI-Guy API Version 12.5.1

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

Includes: diguy_constants.h | declspec_diguy.h

Contents:

Alphabetical Index

Link against: libdiguy

class diguyCharacterPath

class BDI_DECLSPEC_diguy diguyCharacterPath
{
public:
    const char* get_name();
    int set_name(const char* name);
    long get_uid();
    diguyCharacter* get_character();
    int update();
    float get_length();
    float get_duration();
    int get_point_at_distance(float distance_into_path,
        float* x, float* y, float* z,
        float* rz, float* rx, float* ry);
    diguyPathShape* get_path_shape();
    int get_num_waypoints();
    diguyWaypoint* get_waypoint_at_index(int index);
    diguyWaypoint* find_waypoint(const char* name);
    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);
    int add_waypoint(diguyWaypoint* waypoint);
    int get_num_action_beads();
    diguyCharacterPathActionBead* get_action_bead_at_index(int index);
    diguyCharacterPathActionBead* find_action_bead(const char* name);
    diguyCharacterPathActionBead* get_final_action_bead();
    diguyCharacterPathActionBead* create_action_bead(const char* action,
        int index = -1);
    int destroy_action_bead(diguyCharacterPathActionBead* action_bead);
    int get_num_script_beads();
    diguyCharacterPathScriptBead* get_script_bead_at_index(int index);
    diguyCharacterPathScriptBead* find_script_bead(const char* name);
    diguyCharacterPathScriptBead* create_script_bead(const char* script,
        int index = -1,
        const char* script_type = "lua");
    int destroy_script_bead(diguyCharacterPathScriptBead* script_bead);
    int get_num_decision_beads();
    diguyCharacterPathDecisionBead* get_decision_bead_at_index(int index);
    diguyCharacterPathDecisionBead* find_decision_bead(const char* name);
    int get_num_gaze_beads();
    diguyCharacterPathGazeBead* get_gaze_bead_at_index(int index);
    diguyCharacterPathGazeBead* find_gaze_bead(const char* name);
    int get_num_aim_beads();
    diguyCharacterPathAimBead* get_aim_bead_at_index(int index);
    diguyCharacterPathAimBead* find_aim_bead(const char* name);
#ifdef CPLUSPLUS_ONLY
    enum {
        CALLBACK_ID_TIME_LEFT_DEPRECATED = 1,
        CALLBACK_ID_TIME_INTO_DEPRECATED
    };
    int add_callback(int callback_id,
        diguyCharacterPathCallback* callback,
        void* callback_params = 0,
        void* callback_user_data = 0);
    int remove_callback(int callback_id,
        diguyCharacterPathCallback* callback);
    int remove_callback_with_user_data(int callback_id,
        void* callback_user_data);
    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);

function diguyCharacterPath::get_name

Prototype:
const char* get_name();
Description:

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

name of the path
Callable From:

C++
Script

function diguyCharacterPath::set_name

Prototype:
int set_name(const char* name);
Description:

This function sets the name of this object.
Returns:

0 on success, -1 on failure
Callable From:

C++
Script

function diguyCharacterPath::get_uid

Prototype:
long get_uid();
Description:

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

function diguyCharacterPath::get_character

Prototype:
diguyCharacter* get_character();
Returns:

character that owns this path
Callable From:

C++
Script

function diguyCharacterPath::update

Prototype:
int update();
Description:

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

function diguyCharacterPath::get_length

Prototype:
float get_length();
Description:

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

length of path in meters
Callable From:

C++
Script

function diguyCharacterPath::get_duration

Prototype:
float get_duration();
Description:

This function returns how long this path is
Returns:

duration of this path, in seconds
Callable From:

C++
Script

function diguyCharacterPath::get_point_at_distance

Prototype:
int get_point_at_distance(float distance_into_path,
    float* x, float* y, float* z,
    float* rz, float* rx, float* ry);
Description:

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

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

function diguyCharacterPath::get_path_shape

Prototype:
diguyPathShape* get_path_shape();
Description:

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

Waypoint Functions

function diguyCharacterPath::get_num_waypoints

Prototype:
int get_num_waypoints();
Returns:

the number of waypoints belonging to this path
Callable From:

C++
Script

function diguyCharacterPath::get_waypoint_at_index

Prototype:
diguyWaypoint* get_waypoint_at_index(int index);
Description:

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

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

function diguyCharacterPath::find_waypoint

Prototype:
diguyWaypoint* find_waypoint(const char* name);
Description:

This function returns a pointer to the specified waypoint.
Arguments:

name name of waypoint to be found
Returns:

pointer of type diguyWaypoint; NULL if not found
Callable From:

C++
Script

function diguyCharacterPath::create_waypoint

Prototype:
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);
Description:

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

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

function diguyCharacterPath::add_waypoint

Prototype:
int add_waypoint(diguyWaypoint* waypoint);
Description:

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

waypoint waypoint to be appended to end of path
Returns:

0 on success, -1 on failure
Callable From:

C++
Script

Action Bead Functions

function diguyCharacterPath::get_num_action_beads

Prototype:
int get_num_action_beads();
Returns:

the number of action beads belonging to this path
Callable From:

C++
Script

function diguyCharacterPath::get_action_bead_at_index

Prototype:
diguyCharacterPathActionBead* get_action_bead_at_index(int index);
Description:

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
Arguments:

index index of the action bead; indices start at 0
Callable From:

C++
Script

function diguyCharacterPath::find_action_bead

Prototype:
diguyCharacterPathActionBead* find_action_bead(const char* name);
Description:

This function returns a pointer to the specified bead.
Arguments:

name name of bead to be found
Returns:

pointer of type diguyCharacterPathActionBead; NULL if not found
Callable From:

C++
Script

function diguyCharacterPath::get_final_action_bead

Prototype:
diguyCharacterPathActionBead* get_final_action_bead();
Description:

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

function diguyCharacterPath::create_action_bead

Prototype:
diguyCharacterPathActionBead* create_action_bead(const char* action,
    int index = -1);
Description:

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
Arguments:

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

function diguyCharacterPath::destroy_action_bead

Prototype:
int destroy_action_bead(diguyCharacterPathActionBead* action_bead);
Description:

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
Arguments:

action_bead object to destroy; must be part of this path
Callable From:

C++
Script

Script Bead Functions

function diguyCharacterPath::get_num_script_beads

Prototype:
int get_num_script_beads();
Returns:

the number of script beads belonging to this path
Callable From:

C++
Script

function diguyCharacterPath::get_script_bead_at_index

Prototype:
diguyCharacterPathScriptBead* get_script_bead_at_index(int index);
Description:

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
Arguments:

index index of the script bead; indices start at 0
Callable From:

C++
Script

function diguyCharacterPath::find_script_bead

Prototype:
diguyCharacterPathScriptBead* find_script_bead(const char* name);
Description:

This function returns a pointer to the specified bead.
Arguments:

name name of bead to be found
Returns:

pointer of type diguyCharacterPathScriptBead; NULL if not found
Callable From:

C++
Script

function diguyCharacterPath::create_script_bead

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

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
Arguments:

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

function diguyCharacterPath::destroy_script_bead

Prototype:
int destroy_script_bead(diguyCharacterPathScriptBead* script_bead);
Description:

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
Arguments:

script_bead object to destroy; must be part of this path
Callable From:

C++
Script

Decision Bead Functions

function diguyCharacterPath::get_num_decision_beads

Prototype:
int get_num_decision_beads();
Returns:

the number of decision beads belonging to this path
Callable From:

C++
Script

function diguyCharacterPath::get_decision_bead_at_index

Prototype:
diguyCharacterPathDecisionBead* get_decision_bead_at_index(int index);
Description:

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
Arguments:

index index of the decision bead; indices start at 0
Callable From:

C++
Script

function diguyCharacterPath::find_decision_bead

Prototype:
diguyCharacterPathDecisionBead* find_decision_bead(const char* name);
Description:

This function returns a pointer to the specified bead.
Arguments:

name name of bead to be found
Returns:

pointer of type diguyCharacterPathDecisionBead; NULL if not found
Callable From:

C++
Script

Gaze Bead Functions

function diguyCharacterPath::get_num_gaze_beads

Prototype:
int get_num_gaze_beads();
Returns:

the number of gaze beads belonging to this path
Callable From:

C++
Script

function diguyCharacterPath::get_gaze_bead_at_index

Prototype:
diguyCharacterPathGazeBead* get_gaze_bead_at_index(int index);
Description:

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
Arguments:

index index of the gaze bead; indices start at 0
Callable From:

C++
Script

function diguyCharacterPath::find_gaze_bead

Prototype:
diguyCharacterPathGazeBead* find_gaze_bead(const char* name);
Description:

This function returns a pointer to the specified bead.
Arguments:

name name of bead to be found
Returns:

pointer of type diguyCharacterPathGazeBead; NULL if not found
Callable From:

C++
Script

Aim Bead Functions

function diguyCharacterPath::get_num_aim_beads

Prototype:
int get_num_aim_beads();
Returns:

the number of aim beads belonging to this path
Callable From:

C++
Script

function diguyCharacterPath::get_aim_bead_at_index

Prototype:
diguyCharacterPathAimBead* get_aim_bead_at_index(int index);
Description:

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
Arguments:

index index of the aim bead; indices start at 0
Callable From:

C++
Script

function diguyCharacterPath::find_aim_bead

Prototype:
diguyCharacterPathAimBead* find_aim_bead(const char* name);
Description:

This function returns a pointer to the specified bead.
Arguments:

name name of bead to be found
Returns:

pointer of type diguyCharacterPathAimBead; NULL if not found
Callable From:

C++
Script

Callback Functions

enumeration

	enum {
		CALLBACK_ID_TIME_LEFT_DEPRECATED = 1,
		CALLBACK_ID_TIME_INTO_DEPRECATED
	};
Description:

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

C++
Script

function diguyCharacterPath::add_callback

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

This function adds a user callback.
Arguments:

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

function diguyCharacterPath::remove_callback

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

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

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

0 on success, -1 on failure
Callable From:

C++

function diguyCharacterPath::remove_callback_with_user_data

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

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

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

0 on success, -1 on failure
Callable From:

C++

Experimental Functions

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

function diguyCharacterPath::translate

Prototype:

int translate(float tx, float ty, float tz);

function diguyCharacterPath::rotate_about_point

Prototype:

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

function diguyCharacterPath::set_ground_clamp_when_on_path

Prototype:

int set_ground_clamp_when_on_path(int ground_clamp_when_on_path);

function diguyCharacterPath::get_ground_clamp_when_on_path

Prototype:

int get_ground_clamp_when_on_path();

function diguyCharacterPath::get_position_at_distance

Prototype:

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

function diguyCharacterPath::get_position_at_distance_double

Prototype:

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

function diguyCharacterPath::get_position_at_t

Prototype:

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

function diguyCharacterPath::get_position_at_t_double

Prototype:

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

Alphabetical Index

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

RESTRICTED RIGHTS LEGEND

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

Contractor/Manufacturer is:

Boston Dynamics/78 Fourth Avenue/Waltham MA 02451.

`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

`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

`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

`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"

`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