diguyCharacterPath.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2022 MAK Technologies, Inc.
 ** All rights reserved. 
 *********************************************************************/

/*********************************************************************
 **
 *t  diguyCharacterPath
 **
 *b    Link against: libdiguy
 */

#ifndef __diguyCharacterPath_H
#define __diguyCharacterPath_H

#ifdef SWIG
%module diguyCharacterPath
#else
#define CPLUSPLUS_ONLY
#endif

#ifdef CPLUSPLUS_ONLY

class bdiScenarioPath;
class diguyCharacter;
class diguyCharacterPath;
class diguyCharacterPathActionBead;
class diguyCharacterPathScriptBead;
class diguyCharacterPathDecisionBead;
class diguyCharacterPathGazeBead;
class diguyCharacterPathAimBead;
class diguyPathShape;
class diguyWaypoint;

#include <diguy_constants.h>
#include <stdlib.h>

#endif /* CPLUSPLUS_ONLY */



#include <declspec_diguy.h>

class BDI_DECLSPEC_diguy diguyCharacterPath
{

/*****************************************************************************/
public:

        /*l
         *b  Description:
         **
         **    Returns the name of the path.  This pointer will
         **    never be NULL.
         **
         *b  Returns:
         **
         **    name of the path
         */
        const char* get_name();

        /*l
         *b  Description:
         **
         **    This function sets the name of this object.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_name(const char* name);

        /*l
         *b  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!
         **
         *b  Returns:
         **
         **    unique identifier of object
         */
        long get_uid();

        /*l
         *b  Returns:
         **
         **    character that owns this path
         */
        diguyCharacter* get_character();

        /*l
         *b  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.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int update();

        /*l
         *b  Description:
         **
         **    This function returns the total length of the path,
         **    in meters.
         **
         *b  Returns:
         **
         **    length of path in meters
         */
        float get_length();

        /*l
         *b  Description:
         **
         **    This function returns how long this path is
         **
         *b  Returns:
         **
         **    duration of this path, in seconds
         */
        float get_duration();

        /*l
         *b  Description:
         **
         **    This function returns, via the passed variable pointers,
         **    the position and orientation of the point on the path
         **    at the specified distance.
         **
         *b  Arguments:
         **
         *a    distance_into_path - distance in meters into path
         *a                         of the desired point
         *a    x, y, z    - position of point in meters from the origin
         *a    rz, rx, ry - orientation of point in degrees counter-clockwise
         *a                 from the positive X axis
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int get_point_at_distance(float distance_into_path,
                float* x, float* y, float* z,
                float* rz, float* rx, float* ry);

        /*l
         *b  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!
         **
         *b  Returns:
         **
         **    pointer to object of type diguyPathShape
         */
        diguyPathShape* get_path_shape();


/*****************************************************************************/
        /*l
         *b  Returns:
         *
         **     the number of waypoints belonging to this path
         */
        int get_num_waypoints();

        /*l
         *b  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.
         **
         *b  Arguments:
         **
         *a    index - index of the waypoint; indices start at 0
         **
         *b  Returns:
         **
         **    pointer of type diguyWaypoint; NULL if no
         **    waypoint at the specified index
         **
         *b  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.
         **
         *e     local character = this_scenario:get_character_at_index(0);
         *e     local path0 = character:get_path_at_index(0);
         *e
         *e     local wp0 = path0:get_waypoint_at_index(0);
         *e     local wp0_x = wp0:get_x();
         *e     wp0:set_x(wp0_x + 1.0);
         *e
         *e     path0:update();
         */
        diguyWaypoint* get_waypoint_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the specified waypoint.
         **
         *b  Arguments:
         **
         *a    name    - name of waypoint to be found
         **
         *b  Returns:
         **
         **    pointer of type diguyWaypoint; NULL if not found
         */
        diguyWaypoint* find_waypoint(const char* name);

        /*l
         *b  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.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - position in meters from the origin
         *a    rz, rx, ry - orientations in degrees counter-clockwise
         *a                 from the positive X axis
         *a    weight     - how much influence this waypoint exerts
         *a                 over the path curve
         *a    index      - where the waypoint should be inserted in
         *a                 the path; indices start at 0; pass -1 to
         *a                 add to end of path
         **
         *b  Returns:
         **
         **    pointer to type diguyWaypoint
         */
        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);

        /*l
         *b  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.
         **
         *b  Arguments:
         **
         *a    waypoint - waypoint to be appended to end of path
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int add_waypoint(diguyWaypoint* waypoint);

        /*l
         *b  Description:
         **
         **    This function destroys a waypoint on the path.
         **
         *b  Arguments:
         **
         *a    waypoint - waypoint to be deleted
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int destroy_waypoint(diguyWaypoint* waypoint);

/*****************************************************************************/
        /*l
         *b  Returns:
         *
         **     the number of action beads belonging to this path
         */
        int get_num_action_beads();

        /*l
         *b  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.
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPathActionBead; NULL if no
         **    action bead at the specified index
         **
         *b  Arguments:
         **
         *a    index - index of the action bead; indices start at 0
         */
        diguyCharacterPathActionBead* get_action_bead_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the specified bead.
         **
         *b  Arguments:
         **
         *a    name    - name of bead to be found
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPathActionBead; NULL if not found
         */
        diguyCharacterPathActionBead* find_action_bead(const char* name);

        /*l
         *b  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:
         **
         *e     int num_action_beads = path->get_num_action_beads();
         *e     diguyCharacterPathActionBead* ab;
         *e     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.
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPathActionBead; this pointer
         **    should never be NULL
         */
        diguyCharacterPathActionBead* get_final_action_bead();

        /*l
         *b  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.
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPathActionBead; NULL if
         **    insertion failed
         **
         *b  Arguments:
         **
         *a    action - action new bead should perform
         *a    index  - index of the action bead; indices start at 0;
         *a             pass -1 to append the action bead to the end
         *a             of the path
         */
        diguyCharacterPathActionBead* create_action_bead(const char* action,
                int index = -1);

        /*l
         *b  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.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Arguments:
         **
         *a    action_bead - object to destroy; must be part of this path
         */
        int destroy_action_bead(diguyCharacterPathActionBead* action_bead);


/*****************************************************************************/
        /*l
         *b  Returns:
         *
         **     the number of script beads belonging to this path
         */
        int get_num_script_beads();

        /*l
         *b  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.
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPathScriptBead; NULL if no
         **    script bead at the specified index
         **
         *b  Arguments:
         **
         *a    index - index of the script bead; indices start at 0
         */
        diguyCharacterPathScriptBead* get_script_bead_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the specified bead.
         **
         *b  Arguments:
         **
         *a    name    - name of bead to be found
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPathScriptBead; NULL if not found
         */
        diguyCharacterPathScriptBead* find_script_bead(const char* name);

        /*l
         *b  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.
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPathScriptBead; NULL if
         **    insertion failed
         **
         *b  Arguments:
         **
         *a    script - script new bead should perform
         *a    index  - index of the script bead; indices start at 0;
         *a             pass -1 to create the bead at the last index
         *a    script_type - defaults to "lua"
         */
        diguyCharacterPathScriptBead* create_script_bead(const char* script,
                int index = -1,
                const char* script_type = "lua");

        /*l
         *b  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.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Arguments:
         **
         *a    script_bead - object to destroy; must be part of this path
         */
        int destroy_script_bead(diguyCharacterPathScriptBead* script_bead);


/*****************************************************************************/
        /*l
         *b  Returns:
         *
         **     the number of decision beads belonging to this path
         */
        int get_num_decision_beads();

        /*l
         *b  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.
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPathDecisionBead; NULL if no
         **    script bead at the specified index
         **
         *b  Arguments:
         **
         *a    index - index of the decision bead; indices start at 0
         */
        diguyCharacterPathDecisionBead* get_decision_bead_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the specified bead.
         **
         *b  Arguments:
         **
         *a    name    - name of bead to be found
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPathDecisionBead; NULL if not found
         */
        diguyCharacterPathDecisionBead* find_decision_bead(const char* name);


/*****************************************************************************/
        /*l
         *b  Returns:
         *
         **     the number of gaze beads belonging to this path
         */
        int get_num_gaze_beads();

        /*l
         *b  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.
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPathDecisionBead; NULL if no
         **    script bead at the specified index
         **
         *b  Arguments:
         **
         *a    index - index of the gaze bead; indices start at 0
         */
        diguyCharacterPathGazeBead* get_gaze_bead_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the specified bead.
         **
         *b  Arguments:
         **
         *a    name    - name of bead to be found
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPathGazeBead; NULL if not found
         */
        diguyCharacterPathGazeBead* find_gaze_bead(const char* name);


/*****************************************************************************/
        /*l
         *b  Returns:
         *
         **     the number of aim beads belonging to this path
         */
        int get_num_aim_beads();

        /*l
         *b  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.
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPathDecisionBead; NULL if no
         **    script bead at the specified index
         **
         *b  Arguments:
         **
         *a    index - index of the aim bead; indices start at 0
         */
        diguyCharacterPathAimBead* get_aim_bead_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the specified bead.
         **
         *b  Arguments:
         **
         *a    name    - name of bead to be found
         **
         *b  Returns:
         **
         **    pointer of type diguyCharacterPathAimBead; NULL if not found
         */
        diguyCharacterPathAimBead* find_aim_bead(const char* name);



/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/
/****************************************************************************/

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


#ifdef CPLUSPLUS_ONLY

        bdiScenarioPath* get_scripted_object() {return m_scripted_object;}

private:

        /*l
         **    A private constructor.
         */
        diguyCharacterPath(bdiScenarioPath* path);

        /*l
         **    A private destructor.
         */
        ~diguyCharacterPath();

        /*l
         **    A pointer to internal data.
         */
        bdiScenarioPath* m_scripted_object;

        friend class bdiScenarioPath;
        friend class diguyCharacter;

#endif /* CPLUSPLUS_ONLY */

};

#endif /* __diguyCharacterPath_H */