diguyCharacterGesture.h

Go to the documentation of this file.

/****************************************************************************
 * Copyright (c) 2023 MAK Technologies, Inc.
 * All rights reserved.
 ****************************************************************************/

/*********************************************************************
 **
 *t  diguyCharacterGesture
 **
 */

#pragma once

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

#ifdef CPLUSPLUS_ONLY

class bdiGestureInit;
class bdiGestureInstance;
class bdiScenarioCharacter;
class diguyCharacterGesture;

#include <diguyCharacterGestureType.h>
#include <diguyMotionPosture.h>
#include <diguyMotionVariant.h>

#include <diguy_constants.h>
#include <diguy_typedefs.h>

#endif

#include <declspec_diguy.h>

class BDI_DECLSPEC_diguy diguyCharacterGesture
{
public:

/*****************************************************************************/
        /*l
         *b  Returns:
         **
         **    name of the gesture
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        const char* get_name();

        /*l
         *b  Returns:
         **
         **    type of the gesture
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        diguyCharacterGestureType get_gesture_type();

        /*l
         *b  Description:
         **
         **    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.
         **
         *i  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().
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int begin_now();

        /*l
         *b  Description:
         **
         **    This function returns the time at which the gesture began.
         **
         *b  Returns:
         **
         **    time in seconds when scenario began
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        float get_tin();

        /*l
         *b  Returns:
         **
         **    1 if the gesture has begun; 0 if not
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int get_has_begun_flag();

        /*l
         *b  Description:
         **
         **    This function notifies the gesture that it should complete
         **    as soon as possible.  To end a gesture immediately, call
         **    abort_now().
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int end_gesture();

        /*l
         *b  Returns:
         **
         **    1 if the gesture has completed; 0 if not
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int get_has_completed_flag();

        /*l
         *b  Description:
         **
         **    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().
         **
         *b  Arguments:
         **
         *a    max_rampdown_interval - max amount of time spent trying to
         *a                            smooth over any motion seams; pass
         *a                            0.5 for a smooth transition, pass
         *a                            0 for an immediate abort
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int abort_now(float max_rampdown_interval);

        /*l
         *b  Description:
         **
         **    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.
         **
         *a    automatic_destroy_flag - pass 1 to enable automatic
         *a                             deletion
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int set_automatic_destroy_flag(int automatic_destroy_flag);

        /*l
         *b  Description:
         **
         **    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.
         **
         *b  Arguments:
         **
         *a    flag - pass 1 to turn on interpolation, pass 0 to turn
         *a           off interpolation
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int set_interpolation_flag(int flag);

        /*l
         *b  Returns:
         **
         **    the most recent setting of set_interpolation_flag()
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int get_interpolation_flag();

        /*l
         *b  Returns:
         **
         **    how many channels are in the gesture
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int get_num_channels();

        /*l
         *b  Description:
         **
         **    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.
         **
         *b  Arguments:
         **
         *a    channel        - which channel to affect; pass a single upper
         *a                     case character (e.g., 'A')
         *a    channel_weight - value between 0 and 1; 1 means gesture is
         *a                     entirely driven by specified channel, 0 means
         *a                     specified channel has no effect on gesture
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int set_channel_weight(char channel, float channel_weight);

        /*l
         *b  Returns:
         **
         **    the current weight of the specified channel; see set_channel_weight()
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        float get_channel_weight(char channel);

        /*l
         *b  Description:
         **
         **    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().
         **
         *b  Arguments:
         **
         *a    channel               - which channel to affect; pass a single upper
         *a                            case character (e.g., 'A')
         *a    channel_weight_target - target channel weight; a value between
         *a                            0 and 1
         *a    blend_tin             - when, relative to the start of the gesture,
         *a                            the channel weight should begin moving
         *a                            toward channel_weight_target
         *a    blend_tout            - when, relative to the start of the gesture,
         *a                            the channel weight should arrive at
         *a                            channel_weight_target
         *a    blend_function_name   - name of the curve to use to move between
         *a                            current channel weight and target channel
         *a                            weight
         **
         **    The possible blend function names are:
         **
         *a    "HalfSine" - half of a sine curve going from 0 to 1;
         *a                 good blend function for smooth entry and exit
         *a    "Linear"   - linear line from 0 to 1
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int set_channel_weight_target(char channel,
                float channel_weight_target,
                float blend_tin,
                float blend_tout,
                const char* blend_function_name = 0);

        /*l
         *b  Description:
         **
         **    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.
         **
         *b  Arguments:
         **
         *a    channel               - which channel to affect; pass a single upper
         *a                            case character (e.g., 'A')
         *a    channel_weight_target - target channel weight; a value between
         *a                            0 and 1
         *a    blend_tin             - when, relative to the start of the gesture,
         *a                            the channel weight should begin moving
         *a                            toward channel_weight_target
         *a    blend_tout            - when, relative to the start of the gesture,
         *a                            the channel weight should arrive at
         *a                            channel_weight_target
         *a    blend_function_name   - name of the curve to use to move between
         *a                            current channel weight and target channel
         *a                            weight
         **
         *b  Lua Example:
         **
         *e             --  Create a gesture.
         *e             local gesture1 = character:create_gesture("example_gesture");
         *e
         *e             --  Set the starting channel weight of channel 'A' to 0.2.
         *e             gesture1:set_channel_weight('A', 0.2);
         *e
         *e             --
         *e             --  Set a channel weight target.  This call essentially does this:
         *e             --
         *e             --  Smoothly change the channel A weight of the gesture from its
         *e             --  current value (0.2) to 0, starting at 1.5 seconds into the
         *e             --  gesture, finishing 3.5 seconds into the gesture.
         *e             --
         *e             gesture1:set_channel_weight_target(
         *e                 'A',                -- channel to change
         *e                 0.0,                -- target weight
         *e                 1.5,                -- when to start changing
         *e                 3.5,                -- when to stop changing
         *e                 "HalfSine");        -- curve to use for blend
         *e
         *e             --
         *e             --  Add another channel weight target.  This call essentially does this:
         *e             --
         *e             --  Smoothly change the channel A weight of the gesture from its
         *e             --  last set channel weight (0) to 0.8, starting at 3.5 seconds into
         *e             --  the gesture, finishing 5.5 seconds into the gesture.
         *e             --
         *e             gesture1:add_channel_weight_target(
         *e                 'A',
         *e                 0.8,
         *e                 3.5,
         *e                 5.5,
         *e                 "HalfSine");
         *e
         *e             --
         *e             --  We're done tweaking the gesture.  Set its automatic destroy flag
         *e             --  so that it will be deleted when the gesture has completed.
         *e             --
         *e             gesture1:set_automatic_destroy_flag(1);
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int add_channel_weight_target(char channel,
                float channel_weight_target,
                float blend_tin,
                float blend_tout,
                const char* blend_function_name = 0);

        /*l
         *b  Description:
         **
         **    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.
         **
         *b  Arguments:
         **
         *a    duration - rampup duration, in seconds
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int set_rampup_duration(float duration);

        /*l
         *b  Returns:
         **
         **    the rampup duration as set by set_rampup_duration()
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        float get_rampup_duration();

        /*l
         *b  Description:
         **
         **    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".
         **
         *b  Arguments:
         **
         *a    blend_function_name - new rampup blend function
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int set_rampup_blend_function_name(const char* blend_function_name);

        /*l
         *b  Returns:
         **
         **    the rampup blend function as set by
         **    set_rampup_blend_function_name()
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        const char* get_rampup_blend_function_name();

        /*l
         *b  Description:
         **
         **    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.
         **
         *b  Arguments:
         **
         *a    duration - rampdown duration, in seconds
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int set_rampdown_duration(float duration);

        /*l
         *b  Returns:
         **
         **    the rampdown duration as set by set_rampdown_duration()
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        float get_rampdown_duration();

        /*l
         *b  Description:
         **
         **    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".
         **
         *b  Arguments:
         **
         *a    blend_function_name - new rampdown blend function
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        int set_rampdown_blend_function_name(const char* blend_function_name);

        /*l
         *b  Returns:
         **
         **    the rampdown blend function as set by
         **    set_rampdown_blend_function_name()
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        const char* get_rampdown_blend_function_name();

        /*l
         *b  Description:
         **
         **    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.
         **
         *b  Returns:
         **
         **    default blend duration, in seconds
         **
         *b  Callable For Gesture Types:
         **
         *-    - all
         */
        float get_default_blend_duration();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    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.
         **
         *i  Table Gestures:
         **
         **    Table gestures do not yet make use of the overall duration.
         **    The derive_duration_flag should be given a value of 0.
         **
         *b  Arguments:
         **
         *a    max_reps             - number of times gesture will be repeated
         *a    derive_duration_flag - pass 1 to derive optimal overall duration
         *a                           from passed max_reps
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - progression
         */
        int set_max_reps(int max_reps,
                int derive_duration_flag = 1);

        /*l
         *b  Returns:
         **
         **    the number of times the gesture will be repeated
         **
         *b  Callable For Gesture Types:
         **
         *-    - progression
         */
        int get_max_reps();

        /*l
         *b  Description:
         **
         **    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()).
         **
         *i  Table Gestures:
         **
         **    Table gestures do not yet make use of the overall duration.
         **
         *b  Arguments:
         **
         *a    overall_duration     - duration of all stages of the gesture,
         *a                           in seconds
         *a    derive_max_reps_flag - pass 1 to derive optimal number of
         *a                           reps for the given duration
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - progression
         */
        int set_overall_duration(float overall_duration,
                int derive_max_reps_flag = 1);

        /*l
         *b  Returns:
         **
         **    the overall duration in seconds of the gesture
         **
         *i  Table Gestures:
         **
         **    Table gestures do not yet make use of the overall duration.
         **
         *b  Callable For Gesture Types:
         **
         *-    - progression
         */
        float get_overall_duration();

        /*l
         *b  Returns:
         **
         **    the number of stages in the gesture
         **
         *b  Callable For Gesture Types:
         **
         *-    - progression
         **
         */
        int get_num_progression_stages();

        /*l
         *b  Description:
         **
         **    This function sets the exact duration of the specified stage
         **    of the gesture.
         **
         *b  Arguments:
         **
         *a    stage    - stage; an integer between 1 and 3
         *a    duration - duration of stage, in seconds
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - progression
         */
        int set_progression_stage_duration(int stage, float duration);

        /*l
         *b  Returns:
         **
         **    the duration in seconds of specified stage of the gesture
         **
         *b  Arguments:
         **
         *a    stage    - stage; an integer between 1 and 3
         **
         *b  Callable For Gesture Types:
         **
         *-    - progression
         */
        float get_progression_stage_duration(int stage);

        /*l
         *b  Returns:
         **
         **    the optimal duration in seconds of specified stage of the gesture
         **
         *b  Arguments:
         **
         *a    stage    - stage; an integer between 1 and 3
         **
         *b  Callable For Gesture Types:
         **
         *-    - progression
         */
        float get_progression_stage_optimal_duration(int stage);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    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.
         **
         *b  Arguments:
         **
         *a    action_name - name of desired action
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - table
         */
        int set_table_action_desired(const char* action_name);

        /*l
         *b  Description:
         **
         **    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.
         **
         *b  Returns:
         **
         **    name of desired action, "error" on error
         **
         *b  Callable For Gesture Types:
         **
         *-    - table
         */
        const char* get_table_action_desired();

        /*l
         *b  Description:
         **
         **    This function returns how much time it will take to reach
         **    the desired action for table gestures.
         **
         *b  Returns:
         **
         **    time in seconds needed to reach desired action
         **
         *b  Callable For Gesture Types:
         **
         *-    - table
         */
        float get_time_required_to_reach_table_action_desired();

        /*l
         *b  Description:
         **
         **    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.
         **
         *b  Returns:
         **
         **    number of actions in table gesture
         **
         *b  Callable For Gesture Types:
         **
         *-    - table
         */
        int get_num_table_actions();

        /*l
         *b  Description:
         **
         **    This function returns the name of the table action at the
         **    specified index.
         **
         *b  Returns:
         **
         **    name of table action; NULL if no action at given index
         **
         *b  Callable For Gesture Types:
         **
         *-    - table
         */
        const char* get_table_action_at_index(int index);

        /*l
         *b  Description:
         **
         **    This function returns how long a single repetition of a
         **    table action takes.
         **
         *b  Arguments:
         **
         *a    action_name - name of action
         **
         *b  Returns:
         **
         **    duration of single rep, in seconds
         **
         *b  Callable For Gesture Types:
         **
         *-    - table
         */
        float get_table_action_rep_duration(const char* action_name);

        /*l
         *b  Description:
         **
         **    This function returns how long the transition motion(s)
         **    take between two table actions.
         **
         *b  Arguments:
         **
         *a    action_from - name of origin action
         *a    action_to - name of destination action
         **
         *b  Returns:
         **
         **    duration of transition, in seconds
         **
         *b  Callable For Gesture Types:
         **
         *-    - table
         */
        float get_table_transition_duration(const char* action_from,
                const char* action_to);

        /*l
         *b  Description:
         **
         **    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.
         **
         *b  Arguments:
         **
         *a    action_name - name of beginning action
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - table
         */
        int set_table_action_begin(const char* action_name);

        /*l
         *b  Returns:
         **
         **    the name of the beginning action of a table gesture,
         **    as set by set_table_action_begin()
         **
         *b  Callable For Gesture Types:
         **
         *-    - table
         */
        const char* get_table_action_begin();

        /*l
         *b  Description:
         **
         **    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.
         **
         *b  Arguments:
         **
         *a    action_name - name of ending action
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable For Gesture Types:
         **
         *-    - table
         */
        int set_table_action_end(const char* action_name);

        /*l
         *b  Returns:
         **
         **    the name of the ending action of a table gesture,
         **    as set by set_table_action_end()
         **
         *b  Callable For Gesture Types:
         **
         *-    - table
         */
        const char* get_table_action_end();

        /*l
         *b  Returns:
         **
         **    the name of the action the table gesture is currently
         **    playing
         **
         *b  Callable For Gesture Types:
         **
         *-    - table
         */
        const char* get_table_action_now();

        /*l
         *b  Returns:
         **
         **    the name of the action the table gesture will play next
         **
         *b  Callable For Gesture Types:
         **
         *-    - table
         */
        const char* get_table_action_next();

        /*l
         *b  Description:
         **
         **    This function forces the current action of the table gesture
         **    to be the action identified by action_name.
         **
         *b  Arguments:
         **
         *a    action_name            - name of the action to be performed by
         *a                             the gesture
         *a    include_transition_arc - flag for whether the transition
         *a                             motion from the current action to
         *a                             the new action is included;
         *a                             pass 1 for best chance of good looking
         *a                             transition;
         *a                             pass 0 for fastest response
         *a    max_rampdown_interval  - max amount of time spent trying to
         *a                             smooth over any motion seams; set
         *a                             to 0.5 for a smooth transition, set
         *a                             to 0 for a potentially rough transition
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int force_table_action(const char* action_name,
                int include_transition_arc = 1,
                float max_rampdown_interval = 0.5f);


/*****************************************************************************/
        /*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_ATTAINED_DESIRED_ACTION
        };

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function adds a user callback.
         **
         *b  Arguments:
         **
         *a    callback        - pointer to function with prototype
         *a                      diguyCharacterGestureCallback (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 gesture is created.
         **
         *i    CALLBACK_ID_DESTROY
         **
         **      This callback will be called when the gesture is destroyed.
         **
         *i    CALLBACK_ID_ATTAINED_DESIRED_ACTION
         **
         **      This callback will be called when a table gesture has reached
         **      its desired action as set by set_table_action_desired().
         **
         *i    Callback Return Values:
         **
         **    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,
                diguyCharacterGestureCallback* 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                      diguyCharacterGestureCallback (typedefed above)
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int remove_callback(int callback_id,
                diguyCharacterGestureCallback* 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
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int remove_callback_with_user_data(int callback_id,
                void* callback_user_data);

#endif /* CPLUSPLUS_ONLY */

        /*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 scalar.
         **
         **    To pass NULL when calling from a lua script, use nil.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int add_callback_script( int callback_id, const char* callback_script,
                const char* callback_script_type = nullptr );

        /*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
         */
        int remove_callback_script( int callback_id, const char* callback_script,
                const char* callback_script_type = nullptr );


/****************************************************************************/
/****************************************************************************/

#ifdef CPLUSPLUS_ONLY

        bdiGestureInstance* get_scripted_object() { return m_scripted_object; }

private:

        /*l
         **    A private constructor.  Call diguyCharacter::create_gesture()
         **    to create this object.
         */
        diguyCharacterGesture(bdiGestureInstance* scripted_object);

        /*l
         **    A private destructor.  Call diguyCharacter::destroy_gesture()
         **    to destroy this object.
         */
        ~diguyCharacterGesture();

        /*l
         **    A pointer to internal data.
         */
        bdiGestureInstance* m_scripted_object;

        friend class bdiScenarioCharacter;
        friend class bdiGestureInstance;
        friend class diguyCharacter;

#endif

};


class BDI_DECLSPEC_diguy diguyGestureMetadata
{
public:

        const char* get_name();
        const char* get_ui_name();
        const char* get_category();
        const char* get_description();
        float get_duration();

        diguyMotionPosture get_posture();
        diguyMotionVariant get_variant();

protected:

        friend class bdiGestureInit;

        diguyGestureMetadata( bdiGestureInit* m_internal_data );

        bdiGestureInit* m_internal_data;

};