diguySensorRegion.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2014 VT MAK
 ** All rights reserved. 
 *********************************************************************/

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

#ifndef __diguySensorRegion_H
#define __diguySensorRegion_H

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

#ifdef CPLUSPLUS_ONLY

#include <stdio.h> // for NULL definition
#include <diguy_constants.h>
#include <diguy_typedefs.h>

class bdiScenarioSensorRegion;
class diguySensorRegion;
class diguyCharacter;
class diguyCharacterGroup;

#endif


#include <declspec_diguy.h>

/****************************************************************************/
class BDI_DECLSPEC_diguy diguySensorRegion
{

public:

        /*l
         *b  Description:
         **
         **    Returns the name of the object.  This pointer will
         **    never be NULL.
         **
         *b  Returns:
         **
         **    name of the object
         **
         *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:
         **
         **    Returns the type name of the object.  This pointer will
         **    never be NULL.
         **
         *b  Returns:
         **
         **    type name of the object
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        const char* get_type_name();

        /*l
         *b  Description:
         **
         **    This function is checks whether the passed x, y, z position
         **    is in the sensor region.
         **
         *b  Arguments:
         **
         *a    tx, ty, tz - point to check
         **
         *b  Returns:
         **
         **    1 if the passed point is in the sensor region;
         **    0 otherwise.
         */
        int contains_point(float tx, float ty, float tz);

        /*l
         *b  Description:
         **
         **    This function checks to see whether the passed character is
         **    within this sensor region.  The actual point that is checked
         **    is the point returned by diguyCharacter::get_position().
         **
         **    Note that this point is typically by the character's feet, so
         **    it is possible for the upper half of a character to pass
         **    through a sensor region without this function detecting this.
         **
         **    To check the upper portion of a character, use
         **    contains_character_link() instead, and specify "cervical"
         **    or "back" as the link.
         **
         *b  Arguments:
         **
         *a    character - character to check
         **
         *b  Returns:
         **
         **    1 if the passed character is in the sensor region;
         **    0 otherwise.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        int contains_character(const char* character_name);

        /*l
         *b  Description:
         **
         **    This function checks to see whether a character with the specified
         **    type is within this sensor region.  The actual point that is
         **    checked is the point returned by diguyCharacter::get_position().
         **
         **    Note that this point is typically by the character's feet, so it
         **    is possible for the upper half of a character to pass through a
         **    sensor region without this function detecting this.
         **
         *b  Arguments:
         **
         *a    character_type - character type to check
         **
         *b  Returns:
         **
         **    1 if a character with the passed type is in the sensor region;
         **    0 otherwise.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        int contains_character_by_type(const char* character_type);

        /*l
         *b  Description:
         **
         **    This function checks to see whether a character with the specified
         **    type and appearance is within this sensor region.  The actual point
         **    that is checked is the point returned by
         **    diguyCharacter::get_position().
         **
         **    Note that this point is typically by the character's feet, so
         **    it is possible for the upper half of a character to pass
         **    through a sensor region without this function detecting this.
         **
         *b  Arguments:
         **
         *a    character_type - character type to check
         *a    appearance     - appearance to check
         **
         *b  Returns:
         **
         **    1 if a character with the passed type is in the sensor region;
         **    0 otherwise.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        int contains_character_by_type_and_appearance(const char* character_type,
                const char* appearance);

        /*l
         *b  Description:
         **
         **    This function checks to see whether a character from the specified
         **    group is within this sensor region.  The actual point that is
         **    checked is the point returned by diguyCharacter::get_position().
         **
         **    Note that this point is typically by the character's feet, so it
         **    is possible for the upper half of a character to pass through a
         **    sensor region without this function detecting this.
         **
         *b  Arguments:
         **
         *a    group_name - group of characters to check
         **
         *b  Returns:
         **
         **    1 if a character from the group is in the sensor region;
         **    0 otherwise.
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         *-    - Decision Bead
         */
        int contains_character_from_group(const char* group_name);

        /*l
         *b  Description:
         **
         **    This function is similar to contains_character(), but
         **    rather than checking whether the character's ideal position
         **    is in the sensor region, this function checks whether the
         **    specified link is in the sensor region.
         **
         *b  Arguments:
         **
         *a    character_name - name of the character
         *a    link_name      -  name of the link
         *a    offset_tx, offset_ty, offset_tz - offset in link
         **
         *b  Returns:
         **
         **    1 if the passed character link is in the sensor region;
         **    0 otherwise.
         */
        int contains_character_link(const char* character_name,
                const char* link_name,
                float offset_tx, float offset_ty, float offset_tz);

        /*l
         *b  Description:
         **
         **    This function checks all characters in the scenario for whether
         **    they are in this sensor region.  Each character that is in the
         **    sensor region is put into the passed character group.  Note that
         **    the group is first cleared of all members.
         **
         **    A subset of characters can be checked by calling
         **    add_candidate_characters_in_region_to_group().
         **
         *b  Arguments:
         **
         *a    group - group to which characters in sensor region should
         *a            be added
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int add_characters_in_region_to_group(diguyCharacterGroup* group);

        /*l
         *b  Description:
         **
         **    This function checks all characters in the candidates_group
         **    for whether they are in this sensor region.  Each character that
         **    is in the sensor region is put into the passed character group.
         **    Note that the group is first cleared of all members.
         **
         *b  Arguments:
         **
         *a    candidates_group - group whose members should be checked
         *a    group            - group to which characters in sensor region
         *a                       should be added
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int add_candidate_characters_in_region_to_group(diguyCharacterGroup* candidates_group,
                diguyCharacterGroup* group);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets the group that will be used as
         **    autosense candidates.
         **
         **    The passed group must be created by the DI-Guy Scenario UI
         **    or via a call to diguyScenario::create_group().
         **
         **    The members of the candidates group should be set using
         **    the DI-Guy Scenario UI or via calls to
         **    diguyCharacterGroup::add_member().
         **
         *b  Arguments:
         **
         *a    autosense_candidates_group - group of characters to
         *a                                 use as candidates
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_autosense_candidates_group(diguyCharacterGroup* autosense_candidates_group);

        /*l
         *b  Returns:
         **
         **    the most recent setting of set_autosense_candidates_group()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyCharacterGroup* get_autosense_candidates_group();

        /*l
         *b  Description:
         **
         **    This function sets the group that will be used to hold
         **    autosense candidate characters that are in this sensor
         **    region.
         **
         **    The passed group must be created by the DI-Guy Scenario UI
         **    or via a call to diguyScenario::create_group().
         **
         **    The members group is always a subset of the candidates group.
         **    Characters should not be manually added or removed from the
         **    members group.
         **
         *b  Arguments:
         **
         *a    autosense_members_group - group that holds which candidate
         *a                              characters are in this sensor region
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_autosense_members_group(diguyCharacterGroup* autosense_members_group);

        /*l
         *b  Returns:
         **
         **    the most recent setting of set_autosense_members_group()
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyCharacterGroup* get_autosense_members_group();

        /*l
         *b  Description:
         **
         **    This function returns the character of the autosense
         **    candidates group that has entered the sensor
         **    region, triggering a CALLBACK_ID_AUTOSENSE_CHARACTER_ENTERED
         **    callback.  This function will return NULL when not in the
         **    above callback.
         **
         *b  Returns:
         **
         **    autosense candidate that has entered this region; NULL if
         **    not in a CALLBACK_ID_AUTOSENSE_CHARACTER_ENTERED callback
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyCharacter* get_autosense_callback_candidate_entered();

        /*l
         *b  Description:
         **
         **    This function returns the character of the autosense
         **    candidates group that has left the sensor
         **    region, triggering a CALLBACK_ID_AUTOSENSE_CHARACTER_LEFT
         **    callback.  This function will return NULL when not in the
         **    above callback.
         **
         *b  Returns:
         **
         **    autosense candidate that has left this region; NULL if
         **    not in a CALLBACK_ID_AUTOSENSE_CHARACTER_LEFT callback
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyCharacter* get_autosense_callback_candidate_left();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This is an enumeration of the different callbacks
         **    that can be registered with add_callback() and
         **    add_callback_script().
         **
         *b  Usable From:
         **
         *-    - C++
         *-    - Script
         */
        enum {
                CALLBACK_ID_CREATE = 1,
                CALLBACK_ID_DESTROY,
                CALLBACK_ID_DETONATION,
                CALLBACK_ID_AUTOSENSE_CHARACTER_ENTERED,
                CALLBACK_ID_AUTOSENSE_CHARACTER_LEFT
        };


#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function adds a user callback.  Callbacks can be removed
         **    with remove_callback() or remove_callback_with_user_data().
         **
         *b  Arguments:
         **
         *a    callback        - pointer to function with prototype
         *a                      diguySensorRegionCallback (typedefed above)
         *a    callback_id     - integer id of when this callback is to be called
         *a    callback_params - not currently used; pass NULL
         *a    callback_user_data - pointer for user's own use; DI-Guy will
         *a                         do nothing to the contents of this pointer
         *a                         beyond passing it back when the callback is
         *a                         invoked
         **
         **    callback_id should be one of the following values:
         **
         *i    CALLBACK_ID_CREATE
         **
         **      This callback will be called when a new sensor region is created.
         **
         **      Note that this callback can only be added by calling
         **      diguyScenario::add_default_sensor_region_callback(); adding it
         **      with diguySensorRegion::add_callback() will have no effect, as
         **      by that time the sensor region has already been created.
         **
         *i    CALLBACK_ID_DESTROY
         **
         **      This callback will be called when a sensor region is
         **      destroyed.
         **
         *i    CALLBACK_ID_DETONATION
         **
         **      This callback will be called when a detonation occurs within
         **      the sensor region.
         **
         *i    CALLBACK_ID_AUTOSENSE_CHARACTER_ENTERED
         **
         **      This callback will be called when an autosense candidate
         **      character first enters the sensor region.
         **
         *i    CALLBACK_ID_AUTOSENSE_CHARACTER_LEFT
         **
         **      This callback will be called when an autosense candidate
         **      character first leaves the sensor region.
         **
         **    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.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int add_callback(int callback_id,
                diguySensorRegionCallback* callback,
                void* callback_params = 0,
                void* callback_user_data = 0);

        /*l
         *b  Description:
         **
         **    This function removes a user callback.  All callbacks matching
         **    the specified callback_id and callback function will be removed.
         **
         *b  Arguments:
         **
         *a    callback_id     - integer id of when this callback is to be called
         *a    callback        - pointer to function with prototype
         *a                      diguySensorRegionCallback (typedefed above)
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_callback(int callback_id,
                diguySensorRegionCallback* callback);

        /*l
         *b  Description:
         **
         **    This function removes a user callback.  All callbacks matching
         **    the specified callback_id and callback_user_data pointer will
         **    be removed.
         **
         *b  Arguments:
         **
         *a    callback_id        - integer id of when this callback is to be called
         *a    callback_user_data - pointer for user's own use
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int remove_callback_with_user_data(int callback_id,
                void* callback_user_data);

#endif

        /*l
         *b  Description:
         **
         **    This function adds a user callback script.  Callback scripts can
         **    be removed with remove_callback_script().
         **
         **    See diguyCharacter::add_callback_script() for an example
         **    of use.
         **
         *b  Arguments:
         **
         *a    callback_id          - integer id of the callback
         *a    callback_script      - script text of callback to be added
         *a    callback_script_type - the type of script contained in
         *a                           callback_script
         **
         **    If NULL is passed for callback_script_type, a default script type
         **    will be derived based on the default script interpreter of the
         **    scenario.
         **
         *i  lua specific:
         **
         **    When the script is called, the object for which it is being called
         **    will be in the callback_object global.
         **
         **    To pass NULL when calling from a lua script, use nil.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int add_callback_script(int callback_id,
                const char* callback_script,
                const char* callback_script_type = NULL);

        /*l
         *b  Description:
         **
         **    This function removes a user callback script previously added with
         **    add_callback_script().
         **
         **    See diguyCharacter::remove_callback_script() for an example
         **    of use.
         **
         *b  Arguments:
         **
         *a    callback_id          - integer id of the callback
         *a    callback_script      - script text of callback previously added
         *a    callback_script_type - the type of script contained in
         *a                           callback_script
         **
         **    If NULL is passed for callback_script, all callback
         **    scripts whose ids match callback_id and whose types match
         **    callback_script_type will be removed.
         **
         **    If NULL is passed for callback_script_type, a default script type
         **    will be derived based on the default script interpreter of the
         **    scenario.
         **
         *i  Lua specific:
         **
         **    To pass NULL when calling from a lua script, use nil.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int remove_callback_script(int callback_id,
                const char* callback_script,
                const char* callback_script_type = NULL);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function maps the event handler with the given name
         **    to a callback id.  This mapping will be saved in the .dss
         **    file and restored when the .dss file is loaded.
         **
         **    Mappings can also be made via the DI-Guy Scenario UI.
         **
         **    The event handler is one of the following:
         **
         *-      - a scene object callback function registered by
         *-        diguyScenario::register_sensor_region_event_handler() or
         *-        diguyScenario::register_sensor_region_event_handler_from_library()
         *-      - a script registered by
         *-        diguyScenario::register_sensor_region_event_handler_script()
         *-      - a Script, Decision, or Library Function in the scenario
         *-        whose "Event Type" is "Sensor Region"
         **
         *b  Arguments:
         **
         *a    callback_id        - integer id of callback
         *a    handler_name       - name of the event handler to map
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int map_event_handler_to_callback_id(int callback_id,
                const char* handler_name);

        /*l
         *b  Description:
         **
         **    This function unmaps the event handler with the given name
         **    from a callback id.
         **
         *b  Arguments:
         **
         *a    callback_id        - integer id of callback
         *a    handler_name       - name of the event handler to map
         *a    unmap_all_matches  - pass 0 to unmap only the first match,
         *a                         pass 1 to unmap all matches
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int unmap_event_handler_from_callback_id(int callback_id,
                const char* handler_name,
                int unmap_all_matches = 0);


#ifdef CPLUSPLUS_ONLY

private:

        /*l
         **    A private constructor.
         */
        diguySensorRegion(bdiScenarioSensorRegion* sensor_region);

        /*l
         **    A pointer to internal data.
         */
        bdiScenarioSensorRegion* m_sensor_region;

        friend class bdiScenarioSensorRegion;

#endif

};

#endif /* __diguySensorRegion_H */