diguyCharacterGesture.h

Go to the documentation of this file.

/****************************************************************************
 * Copyright (c) 2024 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;

};