diguySensorRegion

Generated from diguySensorRegion.h

DI-Guy API Version 12.5.1

This file was automatically generated from diguySensorRegion.h. Do not edit this file directly; the changes will be lost.

Includes: diguy_constants.h | diguy_typedefs.h | declspec_diguy.h

Contents:

Alphabetical Index

Link against: libdiguy

class diguySensorRegion

class BDI_DECLSPEC_diguy diguySensorRegion
{
public:
    const char* get_name();
    int set_name(const char* name);
    const char* get_type_name();
    int contains_point(float tx, float ty, float tz);
    int contains_character(const char* character_name);
    int contains_character_by_type(const char* character_type);
    int contains_character_by_type_and_appearance(const char* character_type,
        const char* appearance);
    int contains_character_from_group(const char* group_name);
    int contains_character_link(const char* character_name,
        const char* link_name,
        float offset_tx, float offset_ty, float offset_tz);
    int add_characters_in_region_to_group(diguyCharacterGroup* group);
    int add_candidate_characters_in_region_to_group(diguyCharacterGroup* candidates_group,
        diguyCharacterGroup* group);
    int set_autosense_candidates_group(diguyCharacterGroup* autosense_candidates_group);
    diguyCharacterGroup* get_autosense_candidates_group();
    int set_autosense_members_group(diguyCharacterGroup* autosense_members_group);
    diguyCharacterGroup* get_autosense_members_group();
    diguyCharacter* get_autosense_callback_candidate_entered();
    diguyCharacter* get_autosense_callback_candidate_left();
    enum {
        CALLBACK_ID_CREATE = 1,
        CALLBACK_ID_DESTROY,
        CALLBACK_ID_DETONATION,
        CALLBACK_ID_AUTOSENSE_CHARACTER_ENTERED,
        CALLBACK_ID_AUTOSENSE_CHARACTER_LEFT
    };
#ifdef CPLUSPLUS_ONLY
    int add_callback(int callback_id,
        diguySensorRegionCallback* callback,
        void* callback_params = 0,
        void* callback_user_data = 0);
    int remove_callback(int callback_id,
        diguySensorRegionCallback* callback);
    int remove_callback_with_user_data(int callback_id,
        void* callback_user_data);
#endif
    int add_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int remove_callback_script(int callback_id,
        const char* callback_script,
        const char* callback_script_type = NULL);
    int map_event_handler_to_callback_id(int callback_id,
        const char* handler_name);
    int unmap_event_handler_from_callback_id(int callback_id,
        const char* handler_name,
        int unmap_all_matches = 0);

function diguySensorRegion::get_name

Prototype:
const char* get_name();
Description:

Returns the name of the object. This pointer will never be NULL.
Returns:

name of the object
Callable From:

C++
Script

function diguySensorRegion::set_name

Prototype:
int set_name(const char* name);
Description:

This function sets the name of this object.
Returns:

0 on success, -1 on failure
Callable From:

C++
Script

function diguySensorRegion::get_type_name

Prototype:
const char* get_type_name();
Description:

Returns the type name of the object. This pointer will never be NULL.
Returns:

type name of the object
Callable From:

C++
Script

function diguySensorRegion::contains_point

Prototype:
int contains_point(float tx, float ty, float tz);
Description:

This function is checks whether the passed x, y, z position is in the sensor region.
Arguments:

tx, ty, tz point to check
Returns:

1 if the passed point is in the sensor region; 0 otherwise.

function diguySensorRegion::contains_character

Prototype:
int contains_character(const char* character_name);
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.
Arguments:

character character to check
Returns:

1 if the passed character is in the sensor region; 0 otherwise.
Callable From:

C++
Script
Decision Bead

function diguySensorRegion::contains_character_by_type

Prototype:
int contains_character_by_type(const char* character_type);
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.
Arguments:

character_type character type to check
Returns:

1 if a character with the passed type is in the sensor region; 0 otherwise.
Callable From:

C++
Script
Decision Bead

function diguySensorRegion::contains_character_by_type_and_appearance

Prototype:
int contains_character_by_type_and_appearance(const char* character_type,
    const char* appearance);
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.
Arguments:

character_type character type to check
appearance appearance to check
Returns:

1 if a character with the passed type is in the sensor region; 0 otherwise.
Callable From:

C++
Script
Decision Bead

function diguySensorRegion::contains_character_from_group

Prototype:
int contains_character_from_group(const char* group_name);
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.
Arguments:

group_name group of characters to check
Returns:

1 if a character from the group is in the sensor region; 0 otherwise.
Callable From:

C++
Script
Decision Bead

function diguySensorRegion::contains_character_link

Prototype:
int contains_character_link(const char* character_name,
    const char* link_name,
    float offset_tx, float offset_ty, float offset_tz);
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.
Arguments:

character_name name of the character
link_name name of the link
offset_tx, offset_ty, offset_tz offset in link
Returns:

1 if the passed character link is in the sensor region; 0 otherwise.

function diguySensorRegion::add_characters_in_region_to_group

Prototype:
int add_characters_in_region_to_group(diguyCharacterGroup* group);
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().
Arguments:

group group to which characters in sensor region should be added
Returns:

0 on success, -1 on failure
Callable From:

C++
Script

function diguySensorRegion::add_candidate_characters_in_region_to_group

Prototype:
int add_candidate_characters_in_region_to_group(diguyCharacterGroup* candidates_group,
    diguyCharacterGroup* group);
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.
Arguments:

candidates_group group whose members should be checked
group group to which characters in sensor region should be added
Returns:

0 on success, -1 on failure
Callable From:

C++
Script

Autosense Functions

The autosense functions make it easy to add callbacks and event logic for when specific characters enter or leave a sensor region.

In each scenario update, the characters in the sensor region's autosense candidates group are checked for whether they are inside the sensor region. Candidate characters that are inside the sensor region are put into the autosense members group. Candidates that are not in the sensor region are removed from the members group.

The members group is always a subset of the candidates group. Characters should not be manually added or removed from the members group.

When a candidate character enters the sensor region for the first time, callbacks and events with id CALLBACK_ID_AUTOSENSE_CHARACTER_ENTERED are called.

When a candidate character leaves the sensor region, callbacks and events with id CALLBACK_ID_AUTOSENSE_CHARACTER_LEFT are called.

function diguySensorRegion::set_autosense_candidates_group

Prototype:
int set_autosense_candidates_group(diguyCharacterGroup* autosense_candidates_group);
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().
Arguments:

autosense_candidates_group group of characters to use as candidates
Returns:

0 on success, -1 on failure
Callable From:

C++
Script

function diguySensorRegion::get_autosense_candidates_group

Prototype:
diguyCharacterGroup* get_autosense_candidates_group();
Returns:

the most recent setting of set_autosense_candidates_group()
Callable From:

C++
Script

function diguySensorRegion::set_autosense_members_group

Prototype:
int set_autosense_members_group(diguyCharacterGroup* autosense_members_group);
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.
Arguments:

autosense_members_group group that holds which candidate characters are in this sensor region
Returns:

0 on success, -1 on failure
Callable From:

C++
Script

function diguySensorRegion::get_autosense_members_group

Prototype:
diguyCharacterGroup* get_autosense_members_group();
Returns:

the most recent setting of set_autosense_members_group()
Callable From:

C++
Script

function diguySensorRegion::get_autosense_callback_candidate_entered

Prototype:
diguyCharacter* get_autosense_callback_candidate_entered();
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.
Returns:

autosense candidate that has entered this region; NULL if not in a CALLBACK_ID_AUTOSENSE_CHARACTER_ENTERED callback
Callable From:

C++
Script

function diguySensorRegion::get_autosense_callback_candidate_left

Prototype:
diguyCharacter* get_autosense_callback_candidate_left();
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.
Returns:

autosense candidate that has left this region; NULL if not in a CALLBACK_ID_AUTOSENSE_CHARACTER_LEFT callback
Callable From:

C++
Script

Callback Functions

enumeration

	enum {
		CALLBACK_ID_CREATE = 1,
		CALLBACK_ID_DESTROY,
		CALLBACK_ID_DETONATION,
		CALLBACK_ID_AUTOSENSE_CHARACTER_ENTERED,
		CALLBACK_ID_AUTOSENSE_CHARACTER_LEFT
	};
Description:

This is an enumeration of the different callbacks that can be registered with add_callback() and add_callback_script().
Usable From:

C++
Script

function diguySensorRegion::add_callback

Prototype:
int add_callback(int callback_id,
    diguySensorRegionCallback* callback,
    void* callback_params = 0,
    void* callback_user_data = 0);
Description:

This function adds a user callback. Callbacks can be removed with remove_callback() or remove_callback_with_user_data().
Arguments:

callback pointer to function with prototype diguySensorRegionCallback (typedefed above)
callback_id integer id of when this callback is to be called
callback_params not currently used; pass NULL
callback_user_data pointer for user's own use; DI-Guy will do nothing to the contents of this pointer beyond passing it back when the callback is invoked

callback_id should be one of the following values:
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.
CALLBACK_ID_DESTROY

This callback will be called when a sensor region is destroyed.
CALLBACK_ID_DETONATION

This callback will be called when a detonation occurs within the sensor region.
CALLBACK_ID_AUTOSENSE_CHARACTER_ENTERED

This callback will be called when an autosense candidate character first enters the sensor region.
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.
Returns:

0 on success, -1 on failure
Callable From:

C++

function diguySensorRegion::remove_callback

Prototype:
int remove_callback(int callback_id,
    diguySensorRegionCallback* callback);
Description:

This function removes a user callback. All callbacks matching the specified callback_id and callback function will be removed.
Arguments:

callback_id integer id of when this callback is to be called
callback pointer to function with prototype diguySensorRegionCallback (typedefed above)
Returns:

0 on success, -1 on failure

function diguySensorRegion::remove_callback_with_user_data

Prototype:
int remove_callback_with_user_data(int callback_id,
    void* callback_user_data);
Description:

This function removes a user callback. All callbacks matching the specified callback_id and callback_user_data pointer will be removed.
Arguments:

callback_id integer id of when this callback is to be called
callback_user_data pointer for user's own use
Returns:

0 on success, -1 on failure

function diguySensorRegion::add_callback_script

Prototype:
int add_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL);
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.
Arguments:

callback_id integer id of the callback
callback_script script text of callback to be added
callback_script_type the type of script contained in 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.
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.
Returns:

0 on success, -1 on failure
Callable From:

C++
Script

function diguySensorRegion::remove_callback_script

Prototype:
int remove_callback_script(int callback_id,
    const char* callback_script,
    const char* callback_script_type = NULL);
Description:

This function removes a user callback script previously added with add_callback_script().

See diguyCharacter::remove_callback_script() for an example of use.
Arguments:

callback_id integer id of the callback
callback_script script text of callback previously added
callback_script_type the type of script contained in 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.
Lua specific:

To pass NULL when calling from a lua script, use nil.
Returns:

0 on success, -1 on failure
Callable From:

C++
Script

Event Handler Functions

function diguySensorRegion::map_event_handler_to_callback_id

Prototype:
int map_event_handler_to_callback_id(int callback_id,
    const char* handler_name);
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"
Arguments:

callback_id integer id of callback
handler_name name of the event handler to map
Returns:

0 on success, -1 on failure
Callable From:

C++
Script

function diguySensorRegion::unmap_event_handler_from_callback_id

Prototype:
int unmap_event_handler_from_callback_id(int callback_id,
    const char* handler_name,
    int unmap_all_matches = 0);
Description:

This function unmaps the event handler with the given name from a callback id.
Arguments:

callback_id integer id of callback
handler_name name of the event handler to map
unmap_all_matches pass 0 to unmap only the first match, pass 1 to unmap all matches
Returns:

0 on success, -1 on failure
Callable From:

C++
Script

Alphabetical Index

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 Sofware 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.

`character_type`	character type to check
`appearance`	appearance to check

`character_name`	name of the character
`link_name`	name of the link
`offset_tx, offset_ty, offset_tz`	offset in link

`candidates_group`	group whose members should be checked
`group`	group to which characters in sensor region should be added

`callback`	pointer to function with prototype diguySensorRegionCallback (typedefed above)
`callback_id`	integer id of when this callback is to be called
`callback_params`	not currently used; pass NULL
`callback_user_data`	pointer for user's own use; DI-Guy will do nothing to the contents of this pointer beyond passing it back when the callback is invoked

`callback_id`	integer id of the callback
`callback_script`	script text of callback to be added
`callback_script_type`	the type of script contained in callback_script

`callback_id`	integer id of callback
`handler_name`	name of the event handler to map