diguyCharacterPoseOverride.h

Go to the documentation of this file.

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

};