diguyPathShape.h

Go to the documentation of this file.

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

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

#ifndef __diguyPathShape_H
#define __diguyPathShape_H

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

#ifdef CPLUSPLUS_ONLY
class bdiScenarioPathShape;
class diguyWaypoint;
#endif


#include <declspec_diguy.h>

/****************************************************************************/
class BDI_DECLSPEC_diguy diguyPathShape
{

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

        /*l
         *b  Description:
         **
         **    Returns the name of the path shape.  This pointer will
         **    never be NULL.
         **
         *b  Returns:
         **
         **    name of the path shape
         */
        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 path shapes are assigned a unique identifier, or uid.  This
         **    function returns this path shape's uid.
         **
         **    *Note*: unique identifiers will change between DI-Guy runs!
         **
         *b  Returns:
         **
         **    unique identifier of object
         */
        long get_uid();

        /*l
         *b  Description:
         **
         **    This function determines what happens to objects following this
         **    path when they reach the end.
         **
         **    If 1, the object is restricted to stay at the end of the path.
         **
         **    If 0, the object will wrap to the beginning of the path.
         **
         *b  Arguments:
         **
         *a    value - 1 to clamp, 0 to wrap
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_clamp_at_end_flag(int value);

        /*l
         *b  Returns:
         **
         **    most recent setting of set_clamp_at_end_flag().
         */
        int get_clamp_at_end_flag();

        /*l
         *b  Description:
         **
         **    This function should be called after all modifications have
         **    been made to the path shape and its waypoints and it is time
         **    to re-derive the overall path shape.
         **
         **    This update is deferred for reasons of performance; if there
         **    are a lot of modifications to be made to the path shape 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.
         **    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
         **    shape, in meters.
         **
         *b  Returns:
         **
         **    length of path shape in meters
         */
        float get_length();

        /*l
         *b  Description:
         **
         **    This function returns, via the passed variable pointers,
         **    the position and orientation of the point on the path shape
         **    at the specified distance.
         **
         *b  Arguments:
         **
         *a    distance_into_path_shape - distance in meters into path shape
         *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_shape,
                float* x, float* y, float* z,
                float* rz, float* rx, float* ry);


/*****************************************************************************/
        /*l
         *b  Returns:
         *
         **     the number of waypoints belonging to this path shape
         */
        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 shape.
         **
         *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
         */
        diguyWaypoint* get_waypoint_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function creates a new waypoint that is added to the
         **    path shape.  Do not call diguyScenario::destroy_waypoint() on
         **    the returned waypoint; it will be destroyed automatically
         **    with the path shape.
         **
         *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 shape; indices start at 0; pass -1 to
         *a                 add to end of path shape
         **
         *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 shape.
         **
         **    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  Description:
         **
         **    This function tells the Navmesh regions to use this path as a
         **    connection between two regions. The Navmesh should automatically
         **    choose the regions closest to the start and end points of the
         **    path.  By default this functionality is off, but once activated
         **    it's assumed to be a two way connection.
         **
         *b  Arguments:
         **
         *a    use_as_portal - 1 to use as a connection, 0 to not
         */
        void set_use_as_navmesh_portal(int use_as_portal);

        /*l
         *b  Description:
         **
         **    This function returns if the path is being used as a connection
         **    between two regions.
         **
         *b  Returns:
         **
         *a    1 if is a connection, 0 if not
         */
        int get_use_as_navmesh_portal();

        /*l
         *b  Description:
         **
         **    This function tells the Navmesh regions to use this path as a one
         **    way connection between two regions.  Defaults to 0 (two way
         **    connection)
         **
         *b  Arguments:
         **
         *a    one_way - 1 to set as one way connection, 0 to set as
         *a              bidirectional
         */
        void set_one_way_portal(int one_way);

        /*l
         *b  Description:
         **
         **    This function returns if the path is being used as a one way
         **    connection between two regions.
         **
         *b  Returns:
         **
         *a    1 if is one way connection, 0 if two way
         */
        int get_one_way_portal();


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

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

#ifdef CPLUSPLUS_ONLY

        bdiScenarioPathShape* get_scripted_object() {return m_path_shape;}

private:

        /*l
         **    A private constructor.
         */
        diguyPathShape(bdiScenarioPathShape* path_shape);

        /*l
         **    A pointer to internal data.
         */
        bdiScenarioPathShape* m_path_shape;

        friend class bdiScenarioPathShape;
        friend class diguyScenario;

#endif

};

#endif /* __diguyPathShape_H */