diguyCharacterPoseOverride.h

Go to the documentation of this file.

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

 /*********************************************************************
  **
  *t  diguyCharacterPoseOverride
  **
  */

#pragma once

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

#ifdef CPLUSPLUS_ONLY
#include <stdlib.h>

class bdiPoseOverride;
class bdiScenarioCharacter;
class bdiTopology;
#endif


#include <declspec_diguy.h>

class BDI_DECLSPEC_diguy diguyCharacterPoseOverride
{
public:

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    Allocates an array of floats to hold the joint angles for
         **    each degree of freedom, or weights to specify how pose angles
         **    will affect a character.  The size of the array will be equal
         **    to the value returned by get_num_vars().
         **
         **    The allocated array should be freed by calling free_pose_array().
         **
         **    The allocated array will contain uninitialized values.
         **
         **    If the array is to hold weights, each entry in the array
         **    should be set to a valid value between 0.0 and 1.0.
         **
         **    If the array is to hold pose angles, each pose variable whose
         **    corresponding weight is going to be non-0 should be set to a
         **    valid value.
         **
         *b  Returns:
         **
         **    pointer to array of floats, NULL if the array cannot be allocated
         **
         *b  Callable From:
         **
         *-    - C++
         **
         *b  C++ Example:
         **
         **    See example for set_pose_in_radians().
         */
        float* allocate_pose_array();

        /*l
         *b  Description:
         **
         **    Frees an array allocated with allocate_pose_array().
         **
         *b  Arguments:
         **
         *a    array - array of pose angles to be freed
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int free_pose_array( float* array );

#endif

        /*l
         *b  Description:
         **
         **    This function returns the number of the variables
         **    representing joint angles.
         **
         *b  Returns:
         **
         **    an integer representing the number of joint angles
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_num_vars();

#ifdef CPLUSPLUS_ONLY

        /*l
         *b  Description:
         **
         **    This function allocates an array of pointer to char*s
         **    (i.e., C-style strings).
         **
         **    This array can then be passed to get_var_names().
         **
         **    It should be freed using the function free_var_names().
         **    The size of the array will be equal to the value returned
         **    by get_num_vars().
         **
         *b  Returns:
         **
         **    an array of pointers to char*'s (i.e. pointers to strings)
         **
         *b  Callable From:
         **
         *-    - C++
         **
         *b  C++ Example:
         **
         **    See example for get_var_names().
         */
        char** allocate_var_names();

        /*l
         *b  Description:
         **
         **    This function fills out the passed array of strings with
         **    the list of the names of the variables representing joint
         **    angles.
         **
         *b  Arguments:
         **
         *a    var_names - an array of strings as allocated by
         *a                allocate_var_names()
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         **
         *b  C++ Example:
         **
         *e    //
         *e    // Create a pose override for character.
         *e    //
         *e    pose_override = character1->create_pose_override();
         *e
         *e    //
         *e    // Allocate a list of joint angle names and fill it.
         *e    //  Print the joint angle names, then destroy the array.
         *e    //
         *e    char** varnames = pose_override->allocate_var_names();
         *e    pose_override->get_var_names(varnames);
         *e
         *e    for (i = 0; i < character1->get_pose_array_size(); i++)
         *e        bdi_log_printf(BDI_LOG_INFO, "%s\n", varnames[i]);
         *e
         *e    pose_override->free_var_names(varnames);
         */
        int get_var_names( char** var_names );

        /*l
         *b  Description:
         **
         **    This function frees the array of strings allocated by
         **    allocate_var_names().
         **
         *b  Arguments:
         **
         *a    var_names - an array of strings as allocated by
         *a                allocate_var_names()
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int free_var_names( char** var_names );

        /*l
         *b  Description:
         **
         **    Get the index of the given variable in the array of pose angles.
         **
         *b  Arguments:
         **
         *a    varname - the name of the pose angle variable whose index is desired
         **
         *b  Returns:
         **
         **    index of the pose variable, if it exists, -1 if not
         **
         *b  Callable From:
         **
         *-    - C++
         **
         *b  C++ Example:
         **
         **    See example for set_pose_in_radians().
         */
        int get_var_index( const char* varname );

        /*l
         *b  Description:
         **
         **    This function fills out the passed array of floats with the most
         **    recent values passed in a call to set_pose_in_radians().
         **
         **    Note that this may not be the actual pose of the character; this
         **    is only the pose angles for this specific pose override.  Other
         **    pose overrides, gazing, etc., will also affect the pose of the
         **    character.  Use the function diguyCharacter::get_pose_in_radians()
         **    to read the "real" pose of the character, as computed by the DI-Guy
         **    motion engine.
         **
         *b  Arguments:
         **
         *a    pose_array - array of floats allocated by allocate_pose_array()
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         */
        int get_pose_in_radians( float* pose_array );

        int get_pose_in_quaternions( float* pose_array );

        /*l
         *b  Description:
         **
         **    This function specifies the joint angle data that will modify
         **    or override the joint angles the character normally computes.
         **    The replacement data is in pose_array.
         **
         **    If weights array is non-NULL, then each element specifies the
         **    proportion of the value on pose array to mix in with the value
         **    normally computed by the character.  A weight of 0.0 means to
         **    ignore the value in pose_array.  A weight of 1.0 means fully
         **    override the value computed by the character.
         **
         **    If weights_array is NULL, then default_weight will be used for
         **    *all* of the joint angles.
         **
         **    Note that all weights for an Euler triple (e.g. -
         **    q.cervical_rz/rx/ry)  must be equal to ensure proper
         **    interpolation.
         **
         **    Also note that the first six variables that contain the character's
         **    overall position and orientation cannot be changed using a pose
         **    override.  These values must be changed using the functions
         **    diguyCharacter::set_position() and
         **    diguyCharacter::set_orientation().
         **
         *b  Arguments:
         **
         *a    pose_array     - the array containing the pose angles for this
         *a                     override object
         *a    weight_array   - the multiplier used to determine how the new
         *a                     pose_array values are to be combined with the
         *a                     existing pose
         *a    default_weight - the value to be used to set the weights if
         *a                     weights_array is NULL
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         **
         *b  C++ Example:
         **
         *e    //
         *e    // Create a pose override for character.
         *e    //
         *e    pose_override = character1->create_pose_override();
         *e
         *e    //
         *e    // Allocate an array for pose angles.
         *e    //
         *e    pose_array = pose_override->allocate_pose_array();
         *e    for (i=0; i<pose_override->get_num_vars(); i++)
         *e        pose_array[i] = 0.0f;
         *e
         *e    //
         *e    // Allocate a weights_array, and initialize it to all 0s.
         *e    //
         *e    weights_array = pose_override->allocate_pose_array();
         *e    for (i=0; i<pose_override->get_num_vars(); i++)
         *e        weights_array[i] = 0.0f;
         *e
         *e    //
         *e    // Find the indices of the character's back angles.  Set the
         *e    //  weights for these angles in weights_array to 1.0.  This
         *e    //  means that when we call set_pose_in_radians(), the values
         *e    //  in pose_array will completely override the original
         *e    //  data for the back.
         *e    //
         *e    back_rz_index = pose_override->get_var_index("q.back_rz");
         *e    back_rx_index = pose_override->get_var_index("q.back_rx");
         *e    back_ry_index = pose_override->get_var_index("q.back_ry");
         *e
         *e    pose_array[back_rz_index] = 0.57f; // angle measured in radians
         *e    pose_array[back_rx_index] = 0.0f;  // angle measured in radians
         *e    pose_array[back_ry_index] = 0.0f;  // angle measured in radians
         *e
         *e    weights_array[back_rz_index] = 1.0f;
         *e    weights_array[back_rx_index] = 1.0f;
         *e    weights_array[back_ry_index] = 1.0f;
         *e
         *e    pose_override->set_pose_in_radians(pose_array,
         *e        weights_array,
         *e        0.0f);
         */
        int set_pose_in_radians( float* pose_array, float* weights_array = NULL,
                float default_weight = 1.0f );

        int set_pose_in_quaternions( float* pose_array, float* weights_array = NULL,
                float default_weight = 1.0f );

#endif

        /*l
         *b  Description:
         **
         **    Get the default weight for pose angles.
         **
         *b  Returns:
         **
         **    the default pose angle weight
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        float get_default_weight();

        /*l
         *b  Description:
         **
         **    Set the default weight for pose angles.
         **
         **    The default weight will be used to set values in a pose's weights
         **    array if the array passed in, for instance, set_pose_in_radians(),
         **    is NULL.
         **
         *b  Arguments:
         **
         *a    default_weight - the desired default weight
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_default_weight( float default_weight );


        /*l
         *b  Description:
         **
         **    Sets an additional multiplier on the entire weight array. Defaults to 1.0f
         **
         *b  Arguments:
         **
         *a    weight_array_modifier - the desired weight
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_weight_array_modifier( float weight_array_modifier );

        float get_weight_array_modifier();

#ifdef CPLUSPLUS_ONLY

        bdiPoseOverride* get_scripted_object() { return m_scripted_object; }

private:

        /*
         *  private constructor
         */
        diguyCharacterPoseOverride( bdiPoseOverride* scripted_object,
                bdiScenarioCharacter* character );

        /*
         *  private destructor
         */
        virtual ~diguyCharacterPoseOverride();

private:

        friend class bdiPoseOverride;
        friend class diguyCharacter;
        friend class bdiScenarioCharacter;

        /*
         *  internal data
         */
        bdiPoseOverride* m_scripted_object;
        bdiScenarioCharacter* m_character;

#endif

};