#include <diguySensorRegion.h>

Public Member Functions
General Functions
Unless otherwise specified, callable from: C++ Script
const char *	get_name ()
	Returns the name of the object. More...

int	set_name (const char *name)
	This function sets the name of this object. More...

const char *	get_type_name ()
	Returns the type name of the object. More...

int	contains_point (float tx, float ty, float tz)
	This function is checks whether the passed x, y, z position is in the sensor region. More...

int	contains_character (const char *character_name)
	This function checks to see whether the passed character is within this sensor region. More...

int	contains_character_by_type (const char *character_type)
	This function checks to see whether a character with the specified type is within this sensor region. More...

int	contains_character_by_type_and_appearance (const char character_type, const char appearance)
	This function checks to see whether a character with the specified type and appearance is within this sensor region. More...

int	contains_character_from_group (const char *group_name)
	This function checks to see whether a character from the specified group is within this sensor region. More...

int	contains_character_link (const char character_name, const char link_name, float offset_tx, float offset_ty, float offset_tz)
	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. More...

int	add_characters_in_region_to_group (diguyCharacterGroup *group)
	This function checks all characters in the scenario for whether they are in this sensor region. More...

int	add_candidate_characters_in_region_to_group (diguyCharacterGroup candidates_group, diguyCharacterGroup group)
	This function checks all characters in the candidates_group for whether they are in this sensor region. More...

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. Unless otherwise specified, callable from: C++ Script
int	set_autosense_candidates_group (diguyCharacterGroup *autosense_candidates_group)
	This function sets the group that will be used as autosense candidates. More...

diguyCharacterGroup *	get_autosense_candidates_group ()
	Returns: the most recent setting of set_autosense_candidates_group() More...

int	set_autosense_members_group (diguyCharacterGroup *autosense_members_group)
	This function sets the group that will be used to hold autosense candidate characters that are in this sensor region. More...

diguyCharacterGroup *	get_autosense_members_group ()
	Returns: the most recent setting of set_autosense_members_group() More...

diguyCharacter *	get_autosense_callback_candidate_entered ()
	This function returns the character of the autosense candidates group that has entered the sensor region, triggering a CALLBACK_ID_AUTOSENSE_CHARACTER_ENTERED callback. More...

diguyCharacter *	get_autosense_callback_candidate_left ()
	This function returns the character of the autosense candidates group that has left the sensor region, triggering a CALLBACK_ID_AUTOSENSE_CHARACTER_LEFT callback. More...

int	get_min (float *\note, float y, float *z)

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

int	get_max (float *\note, float y, float *z)

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

Event Handler Functions
Unless otherwise specified, callable from: C++ Script
int	map_event_handler_to_callback_id (int callback_id, const char *handler_name)
	This function maps the event handler with the given name to a callback id. More...

int	unmap_event_handler_from_callback_id (int callback_id, const char *handler_name, int unmap_all_matches=0)
	This function unmaps the event handler with the given name from a callback id. More...

Callback Functions
enum	{ CALLBACK_ID_CREATE = 1, CALLBACK_ID_DESTROY, CALLBACK_ID_DETONATION, CALLBACK_ID_AUTOSENSE_CHARACTER_ENTERED, CALLBACK_ID_AUTOSENSE_CHARACTER_LEFT }
	This is an enumeration of the different callbacks that can be registered with add_callback() and add_callback_script(). More...

int	add_callback (int callback_id, diguySensorRegionCallback callback, void callback_params=0, void *callback_user_data=0)
	This function adds a user callback. More...

int	remove_callback (int callback_id, diguySensorRegionCallback *callback)
	This function removes a user callback. More...

int	remove_callback_with_user_data (int callback_id, void *callback_user_data)
	This function removes a user callback. More...

int	add_callback_script (int callback_id, const char callback_script, const char callback_script_type=NULL)
	This function adds a user callback script. More...

int	remove_callback_script (int callback_id, const char callback_script, const char callback_script_type=NULL)
	This function removes a user callback script previously added with add_callback_script(). More...

Private Functions
The functions and variables past this point are for internal use only. No external access to them is expected or necessary.
bdiScenarioSensorRegion *	m_sensor_region
	A pointer to internal data. More...

class	bdiScenarioSensorRegion

	diguySensorRegion (bdiScenarioSensorRegion *sensor_region)
	A private constructor. More...

Detailed Description

Describes a 3D axis aligned volume that can be used to trigger events when they are entered and exited

Member Enumeration Documentation

anonymous enum

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

Usable From:

C++
Script

Enumerator
CALLBACK_ID_CREATE
CALLBACK_ID_DESTROY
CALLBACK_ID_DETONATION
CALLBACK_ID_AUTOSENSE_CHARACTER_ENTERED
CALLBACK_ID_AUTOSENSE_CHARACTER_LEFT

Constructor & Destructor Documentation

diguySensorRegion::diguySensorRegion ( bdiScenarioSensorRegion * sensor_region )

private

A private constructor.

Member Function Documentation

const char* diguySensorRegion::get_name ( )

Returns the name of the object.

This pointer will never be NULL.

Returns:

name of the object

int diguySensorRegion::set_name ( const char * name )

This function sets the name of this object.

Returns:

0 on success, -1 on failure

const char* diguySensorRegion::get_type_name ( )

Returns the type name of the object.

This pointer will never be NULL.

Returns:

type name of the object

int diguySensorRegion::contains_point	(	float	tx,
		float	ty,
		float	tz
	)

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

Parameters

tx,ty,tz point to check

Returns:

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

int diguySensorRegion::contains_character ( const char * character_name )

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.

Parameters

character character to check

Returns:

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

Callable From:

C++
Script
Decision Bead

int diguySensorRegion::contains_character_by_type ( const char * character_type )

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.

Parameters

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

int diguySensorRegion::contains_character_by_type_and_appearance	(	const char *	character_type,
		const char *	appearance
	)

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.

Parameters

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

int diguySensorRegion::contains_character_from_group ( const char * group_name )

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.

Parameters

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

int diguySensorRegion::contains_character_link	(	const char *	character_name,
		const char *	link_name,
		float	offset_tx,
		float	offset_ty,
		float	offset_tz
	)

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.

Parameters

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.

int diguySensorRegion::add_characters_in_region_to_group ( diguyCharacterGroup * group )

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

Parameters

group group to which characters in sensor region should be added

Returns:

0 on success, -1 on failure

int diguySensorRegion::add_candidate_characters_in_region_to_group	(	diguyCharacterGroup *	candidates_group,
		diguyCharacterGroup *	group
	)

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.

Parameters

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

int diguySensorRegion::set_autosense_candidates_group ( diguyCharacterGroup * autosense_candidates_group )

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

Parameters

autosense_candidates_group group of characters to use as candidates

Returns:

0 on success, -1 on failure

diguyCharacterGroup* diguySensorRegion::get_autosense_candidates_group ( )

Returns: the most recent setting of set_autosense_candidates_group()

int diguySensorRegion::set_autosense_members_group ( diguyCharacterGroup * autosense_members_group )

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.

Parameters

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

Returns:

0 on success, -1 on failure

diguyCharacterGroup* diguySensorRegion::get_autosense_members_group ( )

Returns: the most recent setting of set_autosense_members_group()

diguyCharacter* diguySensorRegion::get_autosense_callback_candidate_entered ( )

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

diguyCharacter* diguySensorRegion::get_autosense_callback_candidate_left ( )

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

int diguySensorRegion::get_min	(	float **\	note,
		float *	y,
		float *	z
	)

int diguySensorRegion::set_min	(	float	x,
		float	y,
		float	z,
		int	validate = `1`
	)

int diguySensorRegion::get_max	(	float **\	note,
		float *	y,
		float *	z
	)

int diguySensorRegion::set_max	(	float	x,
		float	y,
		float	z,
		int	validate = `1`
	)

int diguySensorRegion::add_callback	(	int	callback_id,
		diguySensorRegionCallback *	callback,
		void *	callback_params = `0`,
		void *	callback_user_data = `0`
	)

This function adds a user callback.

Callbacks can be removed with remove_callback() or remove_callback_with_user_data().

Parameters

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++

int diguySensorRegion::remove_callback	(	int	callback_id,
		diguySensorRegionCallback *	callback
	)

This function removes a user callback.

All callbacks matching the specified callback_id and callback function will be removed.

Parameters

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

Callable From:

C++

int diguySensorRegion::remove_callback_with_user_data	(	int	callback_id,
		void *	callback_user_data
	)

This function removes a user callback.

All callbacks matching the specified callback_id and callback_user_data pointer will be removed.

Parameters

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

int diguySensorRegion::add_callback_script	(	int	callback_id,
		const char *	callback_script,
		const char *	callback_script_type = `NULL`
	)

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.

Parameters

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

int diguySensorRegion::remove_callback_script	(	int	callback_id,
		const char *	callback_script,
		const char *	callback_script_type = `NULL`
	)

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

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

Parameters

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

int diguySensorRegion::map_event_handler_to_callback_id	(	int	callback_id,
		const char *	handler_name
	)

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"

Parameters

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

Returns:

0 on success, -1 on failure

int diguySensorRegion::unmap_event_handler_from_callback_id	(	int	callback_id,
		const char *	handler_name,
		int	unmap_all_matches = `0`
	)

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

Parameters

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

Friends And Related Function Documentation

friend class bdiScenarioSensorRegion

friend

Member Data Documentation

bdiScenarioSensorRegion* diguySensorRegion::m_sensor_region

private

A pointer to internal data.

The documentation for this class was generated from the following file:

E:/nightly/2751/include/diguySensorRegion.h

Public Member Functions

Callback Functions

Private Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation