diguyCharacterGesture Class Reference

A class representing a overlaid performance on a character's base animation. More...

#include <diguyCharacterGesture.h>

Public Member Functions
Common Functions
Unless otherwise specified, all functions callable from: C++ Script
const char *	get_name ()
	Returns: name of the gesture. More...
diguyCharacterGestureType	get_gesture_type ()
	Returns: type of the gesture. More...
int	begin_now ()
	This function causes the gesture to begin immediately. More...
float	get_tin ()
	This function returns the time at which the gesture began. More...
int	get_has_begun_flag ()
	Returns: 1 if the gesture has begun; 0 if not. More...
int	end_gesture ()
	This function notifies the gesture that it should complete as soon as possible. More...
int	get_has_completed_flag ()
	Returns: 1 if the gesture has completed; 0 if not. More...
int	abort_now (float max_rampdown_interval)
	This function causes this gesture to abort. More...
int	set_automatic_destroy_flag (int automatic_destroy_flag)
	This function causes the gesture object to be automatically deleted when the gesture has completed. More...
int	set_interpolation_flag (int flag)
	This function sets whether joint angles in the gesture will be interpolated. More...
int	get_interpolation_flag ()
	Returns: the most recent setting of set_interpolation_flag() More...
int	get_num_channels ()
	Returns: how many channels are in the gesture. More...
int	set_channel_weight (char channel, float channel_weight)
	This function sets the weight of the specified channel. More...
float	get_channel_weight (char channel)
	Returns: the current weight of the specified channel; see set_channel_weight() More...
int	set_channel_weight_target (char channel, float channel_weight_target, float blend_tin, float blend_tout, const char *blend_function_name=0)
	This function schedules a smooth ramp of the channel weight from its current value to the specified target value. More...
int	add_channel_weight_target (char channel, float channel_weight_target, float blend_tin, float blend_tout, const char *blend_function_name=0)
	This function is similar to set_channel_weight_target(), but adds the channel weight target to a queue of pending targets. More...
int	set_rampup_duration (float duration)
	This function sets how long the gesture will take to "rampup" control of joints from the base motion to the gesture. More...
float	get_rampup_duration ()
	Returns: the rampup duration as set by set_rampup_duration() More...
int	set_rampup_blend_function_name (const char *blend_function_name)
	This function sets which blend function will be used during rampup to transition control of joints from the base motion to the gesture. More...
const char *	get_rampup_blend_function_name ()
	Returns: the rampup blend function as set by set_rampup_blend_function_name() More...
int	set_rampdown_duration (float duration)
	This function sets how long the gesture will take to "rampdown" control of joints from the gesture to the base motion. More...
float	get_rampdown_duration ()
	Returns: the rampdown duration as set by set_rampdown_duration() More...
int	set_rampdown_blend_function_name (const char *blend_function_name)
	This function sets which blend function will be used during rampdown to transition control of joints from the gesture to the base motion. More...
const char *	get_rampdown_blend_function_name ()
	Returns: the rampdown blend function as set by set_rampdown_blend_function_name() More...
float	get_default_blend_duration ()
	This function returns the default blend duration. More...
Progression Gesture Functions
int	set_max_reps (int max_reps, int derive_duration_flag=1)
	This function sets the number of times the gesture will be repeated. More...
int	get_max_reps ()
	Returns: the number of times the gesture will be repeated. More...
int	set_overall_duration (float overall_duration, int derive_max_reps_flag=1)
	This function sets the overall duration the gesture will have. More...
float	get_overall_duration ()
	Returns: the overall duration in seconds of the gesture. More...
int	get_num_progression_stages ()
	Returns: the number of stages in the gesture. More...
int	set_progression_stage_duration (int stage, float duration)
	This function sets the exact duration of the specified stage of the gesture. More...
float	get_progression_stage_duration (int stage)
	Returns: the duration in seconds of specified stage of the gesture. More...
float	get_progression_stage_optimal_duration (int stage)
	Returns: the optimal duration in seconds of specified stage of the gesture. More...
Table Gesture Functions
int	set_table_action_desired (const char *action_name)
	This function sets the desired action for table gestures. More...
const char *	get_table_action_desired ()
	This function returns the desired action for table gestures. More...
float	get_time_required_to_reach_table_action_desired ()
	This function returns how much time it will take to reach the desired action for table gestures. More...
int	get_num_table_actions ()
	This function returns how many actions a table gesture contains. More...
const char *	get_table_action_at_index (int index)
	This function returns the name of the table action at the specified index. More...
float	get_table_action_rep_duration (const char *action_name)
	This function returns how long a single repetition of a table action takes. More...
float	get_table_transition_duration (const char *action_from, const char *action_to)
	This function returns how long the transition motion(s) take between two table actions. More...
int	set_table_action_begin (const char *action_name)
	This function sets which action a table gesture should begin at when begin_now() is called. More...
const char *	get_table_action_begin ()
	Returns: the name of the beginning action of a table gesture, as set by set_table_action_begin() More...
int	set_table_action_end (const char *action_name)
	This function sets which action a table gesture should end with when end_gesture() is called. More...
const char *	get_table_action_end ()
	Returns: the name of the ending action of a table gesture, as set by set_table_action_end() More...
const char *	get_table_action_now ()
	Returns: the name of the action the table gesture is currently playing. More...
const char *	get_table_action_next ()
	Returns: the name of the action the table gesture will play next. More...
int	force_table_action (const char *action_name, int include_transition_arc=1, float max_rampdown_interval=0.5f)
	This function forces the current action of the table gesture to be the action identified by action_name. More...

Callback Functions
enum	{ CALLBACK_ID_CREATE = 1, CALLBACK_ID_DESTROY, CALLBACK_ID_ATTAINED_DESIRED_ACTION }
	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, diguyCharacterGestureCallback *callback, void *callback_params=0, void *callback_user_data=0)
	This function adds a user callback. More...
int	remove_callback (int callback_id, diguyCharacterGestureCallback *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=nullptr)
	This function adds a user callback script. More...
int	remove_callback_script (int callback_id, const char *callback_script, const char *callback_script_type=nullptr)
	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.
bdiGestureInstance *	m_scripted_object
	A pointer to internal data. More...
class	bdiScenarioCharacter
class	bdiGestureInstance
class	diguyCharacter
bdiGestureInstance *	get_scripted_object ()
	diguyCharacterGesture (bdiGestureInstance *scripted_object)
	A private constructor. More...
	~diguyCharacterGesture ()
	A private destructor. More...

Detailed Description

A class representing a overlaid performance on a character's base animation.

Constructor & Destructor Documentation

diguyCharacterGesture::diguyCharacterGesture ( bdiGestureInstance *  scripted_object )

private

A private constructor.

Call diguyCharacter::create_gesture() to create this object.

diguyCharacterGesture::~diguyCharacterGesture ( )

private

A private destructor.

Call diguyCharacter::destroy_gesture() to destroy this object.

Member Function Documentation

const char* diguyCharacterGesture::get_name

(

)

Returns: name of the gesture.

Callable For Gesture Types:

• all

diguyCharacterGestureType diguyCharacterGesture::get_gesture_type

(

)

Returns: type of the gesture.

Callable For Gesture Types:

• all

int diguyCharacterGesture::begin_now

(

)

This function causes the gesture to begin immediately.

The gesture will continue until it has completed or is aborted.

Calling this function on a gesture that has already begun will result in a warning message and have no other effect.

Progression Gestures:

The overall duration of the gesture can be set by calling set_overall_duration(). The durations of each stage will be set proportionately over the overall duration.

Alternatively, the durations of individual stages of the gesture can be set by calling set_stage_duration().

The number of repetitions of the gesture can be set by calling set_max_reps().

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• all

float diguyCharacterGesture::get_tin

(

)

This function returns the time at which the gesture began.

Returns:

time in seconds when scenario began

Callable For Gesture Types:

• all

int diguyCharacterGesture::get_has_begun_flag

(

)

Returns: 1 if the gesture has begun; 0 if not.

Callable For Gesture Types:

• all

int diguyCharacterGesture::end_gesture

(

)

This function notifies the gesture that it should complete as soon as possible.

To end a gesture immediately, call abort_now().

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• all

int diguyCharacterGesture::get_has_completed_flag

(

)

Returns: 1 if the gesture has completed; 0 if not.

Callable For Gesture Types:

• all

int diguyCharacterGesture::abort_now

(

float

max_rampdown_interval

)

This function causes this gesture to abort.

Aborting a gesture doesn't destroy it. The gesture can be begun again if desired. To end a gesture gracefully call end_gesture().

Parameters

max_rampdown_interval

max amount of time spent trying to smooth over any motion seams; pass 0.5 for a smooth transition, pass 0 for an immediate abort

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• all

int diguyCharacterGesture::set_automatic_destroy_flag

(

int

automatic_destroy_flag

)

This function causes the gesture object to be automatically deleted when the gesture has completed.

No further calls through the diguyCharacterGesture object can or should be made, so this function should only be called once all durations, reps, etc. have been set.

Parameters

automatic_destroy_flag

pass 1 to enable automatic deletion

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• all

int diguyCharacterGesture::set_interpolation_flag

(

int

flag

)

This function sets whether joint angles in the gesture will be interpolated.

This takes more time, but results in smoother motion at high frame rates.

Parameters

flag	pass 1 to turn on interpolation, pass 0 to turn off interpolation

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• all

int diguyCharacterGesture::get_interpolation_flag

(

)

Returns: the most recent setting of set_interpolation_flag()

Callable For Gesture Types:

• all

int diguyCharacterGesture::get_num_channels

(

)

Returns: how many channels are in the gesture.

Callable For Gesture Types:

• all

int diguyCharacterGesture::set_channel_weight	(	char	channel,
		float	channel_weight
	)

This function sets the weight of the specified channel.

The other channel weights in a multi-channel gesture will be affected by this call so that all channel weight add to 1.

If the gesture does not have the channel, this function has no effect.

Parameters

channel	which channel to affect; pass a single upper case character (e.g., 'A')
channel_weight	value between 0 and 1; 1 means gesture is entirely driven by specified channel, 0 means specified channel has no effect on gesture

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• all

float diguyCharacterGesture::get_channel_weight

(

char

channel

)

Returns: the current weight of the specified channel; see set_channel_weight()

Callable For Gesture Types:

• all

int diguyCharacterGesture::set_channel_weight_target	(	char	channel,
		float	channel_weight_target,
		float	blend_tin,
		float	blend_tout,
		const char *	blend_function_name = 0
	)

This function schedules a smooth ramp of the channel weight from its current value to the specified target value.

This function is equivalent to calling set_channel_weight() many times over the course of a gesture.

Calling this function removes any pending channel weight targets added by calls to either set_channel_weight_target() or add_channel_weight_target().

Parameters

channel	which channel to affect; pass a single upper case character (e.g., 'A')
channel_weight_target	target channel weight; a value between 0 and 1
blend_tin	when, relative to the start of the gesture, the channel weight should begin moving toward channel_weight_target
blend_tout	when, relative to the start of the gesture, the channel weight should arrive at channel_weight_target
blend_function_name	name of the curve to use to move between current channel weight and target channel weight

The possible blend function names are:

Parameters

HalfSine	half of a sine curve going from 0 to 1; good blend function for smooth entry and exit
Linear	linear line from 0 to 1

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• all

int diguyCharacterGesture::add_channel_weight_target	(	char	channel,
		float	channel_weight_target,
		float	blend_tin,
		float	blend_tout,
		const char *	blend_function_name = 0
	)

This function is similar to set_channel_weight_target(), but adds the channel weight target to a queue of pending targets.

The gesture will not begin moving the current channel weight to the specified target until all pending channel weight targets from previous calls to set_channel_weight_target() and add_channel_weight_target() have been reached.

Parameters

channel	which channel to affect; pass a single upper case character (e.g., 'A')
channel_weight_target	target channel weight; a value between 0 and 1
blend_tin	when, relative to the start of the gesture, the channel weight should begin moving toward channel_weight_target
blend_tout	when, relative to the start of the gesture, the channel weight should arrive at channel_weight_target
blend_function_name	name of the curve to use to move between current channel weight and target channel weight

Lua Example:

--  Create a gesture.
local gesture1 = character:create_gesture("example_gesture");

--  Set the starting channel weight of channel 'A' to 0.2.
gesture1:set_channel_weight('A', 0.2);

--
--  Set a channel weight target.  This call essentially does this:
--
--  Smoothly change the channel A weight of the gesture from its
--  current value (0.2) to 0, starting at 1.5 seconds into the
--  gesture, finishing 3.5 seconds into the gesture.
--
gesture1:set_channel_weight_target(
    'A',                -- channel to change
    0.0,                -- target weight
    1.5,                -- when to start changing
    3.5,                -- when to stop changing
    "HalfSine");        -- curve to use for blend

--
--  Add another channel weight target.  This call essentially does this:
--
--  Smoothly change the channel A weight of the gesture from its
--  last set channel weight (0) to 0.8, starting at 3.5 seconds into
--  the gesture, finishing 5.5 seconds into the gesture.
--
gesture1:add_channel_weight_target(
    'A',
    0.8,
    3.5,
    5.5,
    "HalfSine");

--
--  We're done tweaking the gesture.  Set its automatic destroy flag
--  so that it will be deleted when the gesture has completed.
--
gesture1:set_automatic_destroy_flag(1);

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• all

int diguyCharacterGesture::set_rampup_duration

(

float

duration

)

This function sets how long the gesture will take to "rampup" control of joints from the base motion to the gesture.

A longer rampup will result in a smoother transition into the gesture.

If the rampup duration is longer than the first motion of the gesture, it will be shortened to be the same duration as the first motion. Motion motions are 0.5 seconds or shorter.

The default duration is 0.5 seconds.

Parameters

duration

rampup duration, in seconds

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• all

float diguyCharacterGesture::get_rampup_duration

(

)

Returns: the rampup duration as set by set_rampup_duration()

Callable For Gesture Types:

• all

int diguyCharacterGesture::set_rampup_blend_function_name

(

const char *

blend_function_name

)

This function sets which blend function will be used during rampup to transition control of joints from the base motion to the gesture.

The default blend function is "HalfSine".

Parameters

blend_function_name

new rampup blend function

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• all

const char* diguyCharacterGesture::get_rampup_blend_function_name

(

)

Returns: the rampup blend function as set by set_rampup_blend_function_name()

Callable For Gesture Types:

• all

int diguyCharacterGesture::set_rampdown_duration

(

float

duration

)

This function sets how long the gesture will take to "rampdown" control of joints from the gesture to the base motion.

A longer rampdown will result in a smoother transition out of the gesture.

Parameters

duration

rampdown duration, in seconds

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• all

float diguyCharacterGesture::get_rampdown_duration

(

)

Returns: the rampdown duration as set by set_rampdown_duration()

Callable For Gesture Types:

• all

int diguyCharacterGesture::set_rampdown_blend_function_name

(

const char *

blend_function_name

)

This function sets which blend function will be used during rampdown to transition control of joints from the gesture to the base motion.

The default blend function is "HalfSine".

Parameters

blend_function_name

new rampdown blend function

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• all

const char* diguyCharacterGesture::get_rampdown_blend_function_name

(

)

Returns: the rampdown blend function as set by set_rampdown_blend_function_name()

Callable For Gesture Types:

• all

float diguyCharacterGesture::get_default_blend_duration

(

)

This function returns the default blend duration.

This is the amount of time the gesture will take to blend motions together to produce more seamless motions.

Returns:

default blend duration, in seconds

Callable For Gesture Types:

• all

int diguyCharacterGesture::set_max_reps	(	int	max_reps,
		int	derive_duration_flag = 1
	)

This function sets the number of times the gesture will be repeated.

The optimal overall duration can be optionally computed based on the number of repetitions specified.

Table Gestures:

Table gestures do not yet make use of the overall duration. The derive_duration_flag should be given a value of 0.

Parameters

max_reps	number of times gesture will be repeated
derive_duration_flag	pass 1 to derive optimal overall duration from passed max_reps

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• progression

int diguyCharacterGesture::get_max_reps

(

)

Returns: the number of times the gesture will be repeated.

Callable For Gesture Types:

• progression

int diguyCharacterGesture::set_overall_duration	(	float	overall_duration,
		int	derive_max_reps_flag = 1
	)

This function sets the overall duration the gesture will have.

The optimal number of repetitions can be optionally computed based on the specified duration.

Calling this function will override any previous calls that set specific stage durations (e.g., as set by a call to set_stage_duration()).

Table Gestures:

Table gestures do not yet make use of the overall duration.

Parameters

overall_duration	duration of all stages of the gesture, in seconds
derive_max_reps_flag	pass 1 to derive optimal number of reps for the given duration

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• progression

float diguyCharacterGesture::get_overall_duration

(

)

Returns: the overall duration in seconds of the gesture.

Table Gestures:

Table gestures do not yet make use of the overall duration.

Callable For Gesture Types:

• progression

int diguyCharacterGesture::get_num_progression_stages

(

)

Returns: the number of stages in the gesture.

Callable For Gesture Types:

• progression

int diguyCharacterGesture::set_progression_stage_duration	(	int	stage,
		float	duration
	)

This function sets the exact duration of the specified stage of the gesture.

Parameters

stage	stage; an integer between 1 and 3
duration	duration of stage, in seconds

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• progression

float diguyCharacterGesture::get_progression_stage_duration

(

int

stage

)

Returns: the duration in seconds of specified stage of the gesture.

Parameters

stage

stage; an integer between 1 and 3

Callable For Gesture Types:

• progression

float diguyCharacterGesture::get_progression_stage_optimal_duration

(

int

stage

)

Returns: the optimal duration in seconds of specified stage of the gesture.

Parameters

stage

stage; an integer between 1 and 3

Callable For Gesture Types:

• progression

int diguyCharacterGesture::set_table_action_desired

(

const char *

action_name

)

This function sets the desired action for table gestures.

The gesture will begin a transition to the desired action as soon as it can.

The time required to reach the desired action can be determined by calling the get_time_required_to_reach_table_action_desired() function.

Parameters

action_name

name of desired action

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• table

const char* diguyCharacterGesture::get_table_action_desired

(

)

This function returns the desired action for table gestures.

If this gesture is not a table gesture the string "error" will be returned.

The desired action can be set using the set_table_action_desired() function.

Returns:

name of desired action, "error" on error

Callable For Gesture Types:

• table

float diguyCharacterGesture::get_time_required_to_reach_table_action_desired

(

)

This function returns how much time it will take to reach the desired action for table gestures.

Returns:

time in seconds needed to reach desired action

Callable For Gesture Types:

• table

int diguyCharacterGesture::get_num_table_actions

(

)

This function returns how many actions a table gesture contains.

The function get_table_action_at_index() can be called to get the name of the actions.

Returns:

number of actions in table gesture

Callable For Gesture Types:

• table

const char* diguyCharacterGesture::get_table_action_at_index

(

int

index

)

This function returns the name of the table action at the specified index.

Returns:

name of table action; NULL if no action at given index

Callable For Gesture Types:

• table

float diguyCharacterGesture::get_table_action_rep_duration

(

const char *

action_name

)

This function returns how long a single repetition of a table action takes.

Parameters

action_name

name of action

Returns:

duration of single rep, in seconds

Callable For Gesture Types:

• table

float diguyCharacterGesture::get_table_transition_duration	(	const char *	action_from,
		const char *	action_to
	)

This function returns how long the transition motion(s) take between two table actions.

Parameters

action_from	name of origin action
action_to	name of destination action

Returns:

duration of transition, in seconds

Callable For Gesture Types:

• table

int diguyCharacterGesture::set_table_action_begin

(

const char *

action_name

)

This function sets which action a table gesture should begin at when begin_now() is called.

The gesture's first motion will be the transition motion from the beginning action to the desired action if the actions differ, or the looping motion of the desired action if they are the same.

The default beginning action is the action at index 0.

Parameters

action_name

name of beginning action

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• table

const char* diguyCharacterGesture::get_table_action_begin

(

)

Returns: the name of the beginning action of a table gesture, as set by set_table_action_begin()

Callable For Gesture Types:

• table

int diguyCharacterGesture::set_table_action_end

(

const char *

action_name

)

This function sets which action a table gesture should end with when end_gesture() is called.

The default ending action is the action at index 0.

Parameters

action_name

name of ending action

Returns:

0 on success, -1 on failure

Callable For Gesture Types:

• table

const char* diguyCharacterGesture::get_table_action_end

(

)

Returns: the name of the ending action of a table gesture, as set by set_table_action_end()

Callable For Gesture Types:

• table

const char* diguyCharacterGesture::get_table_action_now

(

)

Returns: the name of the action the table gesture is currently playing.

Callable For Gesture Types:

• table

const char* diguyCharacterGesture::get_table_action_next

(

)

Returns: the name of the action the table gesture will play next.

Callable For Gesture Types:

• table

int diguyCharacterGesture::force_table_action	(	const char *	action_name,
		int	include_transition_arc = 1,
		float	max_rampdown_interval = 0.5f
	)

This function forces the current action of the table gesture to be the action identified by action_name.

Parameters

action_name	name of the action to be performed by the gesture
include_transition_arc	flag for whether the transition motion from the current action to the new action is included; pass 1 for best chance of good looking transition; pass 0 for fastest response
max_rampdown_interval	max amount of time spent trying to smooth over any motion seams; set to 0.5 for a smooth transition, set to 0 for a potentially rough transition

Returns:

0 on success, -1 on failure

bdiGestureInstance* diguyCharacterGesture::get_scripted_object ( )

inline

Friends And Related Function Documentation

friend class bdiScenarioCharacter

friend

friend class bdiGestureInstance

friend

friend class diguyCharacter

friend

Member Data Documentation

bdiGestureInstance* diguyCharacterGesture::m_scripted_object

private

A pointer to internal data.

---

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

• diguyCharacterGesture.h