diguySensorRegion.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2022 MAK Technologies, Inc.
 ** 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
    */
   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:
    **
    **    Returns the type name of the object.  This pointer will
    **    never be NULL.
    **
    *b  Returns:
    **
    **    type name of the object
    */
   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
    */
   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
    */
   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
    */
   int set_autosense_candidates_group(diguyCharacterGroup* autosense_candidates_group);

   /*l
    *b  Returns:
    **
    **    the most recent setting of set_autosense_candidates_group()
    */
   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
    */
   int set_autosense_members_group(diguyCharacterGroup* autosense_members_group);

   /*l
    *b  Returns:
    **
    **    the most recent setting of set_autosense_members_group()
    */
   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
    */
   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
    */
   diguyCharacter* get_autosense_callback_candidate_left();

   int get_min(float *x, float *y, float *z);
   int set_min(float x, float y, float z, int validate = 1);

   int get_max(float *x, float *y, float *z);
   int set_max(float x, float y, float z, int validate = 1);

/*****************************************************************************/
   /*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
    **
    *b  Callable From:
    **
    *-    - C++
    */
   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
    */
   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
    */
   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 */