diguyCharacterGroup.h

Go to the documentation of this file.

/*
 *  Copyright (C) 1992-2013 Boston Dynamics
 *  ALL RIGHTS RESERVED.
 *
 *  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 Software 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.
 */


/*********************************************************************
 **
 *t  diguyCharacterGroup
 **
 */

#ifndef __diguyCharacterGroup_H
#define __diguyCharacterGroup_H


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

#ifdef CPLUSPLUS_ONLY
#include <stdio.h>
class bdiScenarioCharacterGroup;
class diguyCharacter;
class diguyVariable;
class diguyViewLabel;
class diguyFormation;
#endif


#include <declspec_diguy.h>

/****************************************************************************/
class BDI_DECLSPEC_diguy diguyCharacterGroup
{

public:

        /*l
         *b  Returns:
         **
         **    name of the group; this value will never be NULL
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_name();

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

        /*l
         *b  Description:
         **
         **    Adds the passed character to the group if not already in it.
         **
         *b  Returns:
         **
         **    0 if the character is now a part of the group, -1 if not
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int add_member(diguyCharacter* character);

        /*l
         *b  Description:
         **
         **    Adds all characters of the scenario as members of the group.
         **
         *b  Returns:
         **
         **    Always return 0.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int add_all_characters_as_members();

        /*l
         *b  Description:
         **
         **    Removes the passed character from the group if it
         **    is a member.
         **
         *b  Returns:
         **
         **    0 if the character was part of the group and removed;
         **    -1 if not
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int remove_member(diguyCharacter* character);

        /*l
         *b  Description:
         **
         **    Removes all members of the group.
         **
         *b  Returns:
         **
         **    Always return 0.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int remove_all_members();

        /*l
         *b  Description:
         **
         **    The function can be used to check if a specific character is in
         **    this group.
         **
         **    Also see diguyCharacter::is_group_member().
         **
         *b  Returns:
         **
         **    1 if the passed character is a member of the group;
         **    0 if not
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int is_member(diguyCharacter* character);

        /*l
         *b  Returns:
         **
         **    number of member characters in group
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_num_members();

        /*l
         *b  Returns:
         **
         **    group member at specified index; NULL if no character
         **    at specified index
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyCharacter* get_member_at_index(int index);

        /*l
         *b  Returns:
         **
         **    index of member, or -1 if not found
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_index_of_member(diguyCharacter* character);

        /*l
         *b  Description:
         **
         **    See diguyFormation for a description of subgroups.
         **
         *b  Returns:
         **
         **    subgroup number within formation of character at index,
         **    or -1
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_subgroup_number(diguyFormation* formation, int index);

        /*l
         *b  Description:
         **
         **    See diguyFormation for a description of subgroups.
         **
         *b  Returns:
         **
         **    index within subgroup, or 0
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_index_in_subgroup(diguyFormation* formation, int index);


        /*l
         *b  Description:
         **
         **    Sets whether all characters in group are enabled.  Equivalent to
         **    calling diguyCharacter::set_enabled() for group members.
         **
         *b  Returns:
         **
         **    Always return 0.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_all_members_enabled(int enabled);

        /*l
         *b  Description:
         **
         **    Updates all characters in the group.  Equivalent to calling
         **    diguyCharacter::update() for all group members.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int update_all_members(float t);

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function draws all members of the group.
         **    See diguyCharacter::draw().
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int draw_all_members();

        /*l
         *b  Description:
         **
         **    This function draws pass 1 of all members of the group.
         **    See diguyCharacter::draw_pass1().
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int draw_pass1_all_members();

        /*l
         *b  Description:
         **
         **    This function draws pass 2 all members of the group.
         **    See diguyCharacter::draw_pass2().
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int draw_pass2_all_members();

#endif

        /*l
         *b  Description:
         **
         **    This function sets the current tin time of all characters
         **    in the group.  See diguyCharacter::set_current_tin().
         **
         *b  Arguments:
         **
         *a    tin - new value of current tin in seconds
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_all_members_current_tin(float tin);

        /*l
         *b  Description:
         **
         **    This function sets the current tout time of all characters
         **    in the group.  See diguyCharacter::set_current_tout().
         **
         *b  Arguments:
         **
         *a    tout - new value of current tout in seconds
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_all_members_current_tout(float tout);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function returns a pointer to the label object of
         **    the group.
         **
         **    Currently group labels are only enabled in DI-Guy Scenario.
         **
         *b  Returns:
         **
         **    pointer to the group's label
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyViewLabel* get_label();

        /*l
         *b  Description:
         **
         **    This function sets how high the label of the group will float
         **    above the group's centroid.
         **
         *b  Arguments:
         **
         *a    offset - offset, in meters, of label above group
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_label_offset_above_centroid(float offset);

        /*l
         *b  Returns:
         **
         **    how high the label of the group will float above the group centroid
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        float get_label_offset_above_centroid();


/*****************************************************************************/
        /*l
         *b  Returns:
         **
         **    number of variables the group has
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int     get_num_variables();

        /*l
         *b  Returns:
         **
         **    pointer of type diguyVariable; NULL if no
         **    variable at the specified index
         **
         *b  Arguments:
         **
         *a    index - index of the variable; indices start at 0
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyVariable* get_variable_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function returns a pointer to the specified variable.
         **
         *b  Arguments:
         **
         *a    name - name of variable to be found
         **
         *b  Returns:
         **
         **    pointer of type diguyVariable; NULL if not found
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyVariable* find_variable(const char* name);

        /*l
         *b  Description:
         **
         **    This function finds the variable with the given name or
         **    creates it if it doesn't exist.
         **
         *b  Arguments:
         **
         *a    name - name of the variable to find or create
         **
         *b  Returns:
         **
         **    pointer of type diguyVariable; should never be NULL
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyVariable* find_or_create_variable(const char* name);

        /*l
         *b  Description:
         **
         **    This function destroys the passed variable.
         **
         *b  Arguments:
         **
         *a    variable - pointer to a diguyVariable
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int destroy_variable(diguyVariable* variable);


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

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

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

        int rotate_all_paths_about_current_waypoint(float rz, float rx, float ry);

        /*l
         *b  Description:
         **
         **    Get the character closest to the specified point.
         **
         *b  Arguments:
         **
         *a    x, y, z - position in meters from the origin
         **
         *b  Returns:
         **
         **    pointer to diguyCharacter, or NULL in none found
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyCharacter* get_nearest_character_to_point(float x, float y, float z);

        /*l
         *b  Description:
         **
         **    Get the character furthest from the specified point.
         **
         *b  Arguments:
         **
         *a    x, y, z - position in meters from the origin
         **
         *b  Returns:
         **
         **    pointer to diguyCharacter, or NULL if none found
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyCharacter* get_farthest_character_to_point(float x, float y, float z);

        /*l
         *b  Description:
         **
         **    Get centroid of group (average of character positions).
         **
         *b  Arguments:
         **
         *a    x, y, z - position in meters from the origin
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_group_centroid(float* x, float* y, float* z);

        /*l
         *b  Description:
         **
         **    Get minimum enclosing circle of group. Note that this is slower
         **    than getting the centroid.
         **
         *b  Arguments:
         **
         *a    x, y, z - center of circle of group in meters from the origin
         *a    radius  - radius of circle
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_group_min_circle(float* x, float* y, float* z, float* radius);

        /*l
         *b  Description:
         **
         **    Send a message to all characters in group. See
         **    diguyCharacter::agent_accept_message().
         **
         *b  Arguments:
         **
         *a    sender         - who is sending the message
         *a    message_type   - what type of message is being sent
         *a    message        - the message string
         *a    message_params - optional parameter string
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int send_message_to_all_members(const char* sender,
                const char* message_type,
                const char* message,
                const char* message_params = NULL);

        /*l
         *b  Description:
         **
         **    Puts the group into the specified formation, applying
         **    agent_pursue_character_with_offset() to each character except the
         **    leader.
         **
         *b  Arguments:
         **
         *a    leader         - leader; can be NULL
         *a    formation      - name of formation
         *a    dir_x      - x component of the formation's heading
         *a    dir_y      - y component of the formation's heading
         *a    desired_radius - if not given (-1.0), get radius from formation
         *a    require_sort   - if 1, group must be resorted; if 0, it may still
         *a                     be
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int apply_formation_to_group_with_dir(diguyCharacter* leader,
                diguyFormation* formation,
                float dir_x,
                float dir_y,
                float desired_radius = -1.0f,
                int require_sort = 1);

        /*l
         *b  Description:
         **
         **    Puts the group into the specified formation, applying
         **    agent_pursue_character_with_offset() to each character except the
         **    leader.
         **
         *b  Arguments:
         **
         *a    leader         - leader; can be NULL
         *a    formation      - name of formation
         *a    goal_x      - x component of the formation's goal point
         *a    goal_y      - y component of the formation's goal point
         *a    desired_radius - if not given (-1.0), get radius from formation
         *a    require_sort   - if 1, group must be resorted; if 0, it may still
         *a                     be
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int apply_formation_to_group_with_goal(diguyCharacter* leader,
                diguyFormation* formation,
                float goal_x,
                float goal_y,
                float desired_radius = -1.0f,
                int require_sort = 1);

        /*l
         *b  Description:
         **
         **    Puts the group into the specified formation, applying
         **    agent_pursue_character_with_offset() to each character except the
         **    leader.
         **
         *b  Arguments:
         **
         *a    leader         - leader; can be NULL
         *a    formation      - name of formation
         *a    desired_radius - if not given (-1.0), get radius from formation
         *a    require_sort   - if 1, group must be resorted; if 0, it may still
         *a                     be
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int apply_formation_to_group(diguyCharacter* leader,
                diguyFormation* formation,
                float desired_radius = -1.0f,
                int require_sort = 1);

        /*l
         *b  Description:
         **
         **    Returns the last-set formation
         **
         *b  Returns:
         **
         **    The formation or NULL
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyFormation* get_current_formation();

        /*l
         *b  Description:
         **
         **    Sorts group relative to the point given. The point should be on
         **    the left or in the front, depending on what order the formation is
         **    in.  This updates an internal list of sorted group members.
         **
         *b  Arguments:
         **
         *a    x         - x component of point
         *a    y         - y component of point
         *a    z         - z component of point
         *a    formation - the formation; pass NULL for no formation
         *a    leader    - the leader; pass NULL for no formation leader
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int sort_group_based_on_pos(float x,
                float y,
                float z,
                diguyFormation* formation = NULL,
                diguyCharacter* leader = NULL);

        /*l
         *b  Returns:
         **
         **    member of formation-sorted group; NULL if no character at index
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyCharacter* get_sorted_member_at_index(int index);

        /*l
         *b  Returns:
         **
         **    number of active members
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_num_active_members();

#ifdef CPLUSPLUS_ONLY

        bdiScenarioCharacterGroup* get_scripted_object() {return m_scripted_object;}

private:

        /*l
         **    A private constructor.
         */
        diguyCharacterGroup(bdiScenarioCharacterGroup* scripted_object);

        /*l
         **    A private destructor.
         */
        virtual ~diguyCharacterGroup();

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

        friend class bdiScenarioCharacterGroup;

#endif

};


#endif /* __diguyCharacterGroup_H */


/*
 *  Copyright (C) 1992-2013 Boston Dynamics
 *  ALL RIGHTS RESERVED.
 *
 *  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 Software 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.
 */