diguyMathHelper.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2022 MAK Technologies, Inc.
 ** All rights reserved. 
 *********************************************************************/

/*********************************************************************
 **
 *t  diguyMathHelper
 **
 *b    Link against: libdiguy
 */

#ifndef __diguyMathHelper_H
#define __diguyMathHelper_H

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

#ifdef CPLUSPLUS_ONLY
#include <declspec_diguy.h>
#include <diguy_constants.h>
#include <diguy_typedefs.h>
#include <diguy_vector_classes.h>

class bdiScenarioCharacter;
class diguyAgentParams;
class diguyCharacter;
class diguyCharacterGuide;

#endif


/****************************************************************************/
class BDI_DECLSPEC_diguy diguyMathHelper
{

public:
        diguyMathHelper();
        ~diguyMathHelper();

/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    Helper function to determine if a ballistic weapon (e.g. artillery) can hit its target,
         **        given a target point, projectile speed, max and min elevation. If the designated target
         **    can't be hit (too close or far), this function will offer the closest possible point that
         **    can be hit.
         **
         *b  Arguments:
         **
         *a    delta_x,delta_y,delta_z - position of target relative to start point
         *a        initial_speed - how fast the projectile is going out of the barrel
         *a    max_elevation - the maximum elevation of the weapon above horizontal
         *a    min_elevation - the minimum elevation of the weapon above horizontal
         *a    ret_vel_x,ret_vel_y,ret_vel_z - output parameters; the velocity the projectile must have
         *a    ret_delta_x,ret_delta_y,ret_delta_z - output parameters; the relative pos of point that
         *a                             will be hit (if preferred target can't be reached)
         **
         *b  Returns:
         **
         **    1 on success, 0 on failure
         **    (float * arguments converted to return values in Lua)
         */
        static int get_ballistic_arc_velocity(float delta_x, float delta_y, float delta_z, float initial_speed, float max_elevation, float min_elevation, 
                        float *ret_vel_x, float *ret_vel_y, float *ret_vel_z, float *ret_delta_x, float *ret_delta_y, float *ret_delta_z);

        /*l
         *b  Description:
         **
         **    Helper function to solve the quadratic equation (http://en.wikipedia.org/wiki/Quadratic_formula)
         **    or to report that there is no solution.
         **
         *b  Arguments:
         **
         *a    a,b,c - see link above
         *a    ret1,ret2 - output parameters; the solutions, if any exist
         **
         *b  Returns:
         **
         **    1 if there's a solution; 0 otherwise
         **    (float * arguments converted to return values in Lua)
         */
        static int quadratic_formula(float a, float b, float c, float *ret1, float *ret2);

        /*l
         *b  Description:
         **
         **    Given a vector and a roll value, calculate the Euler angles of yaw and pitch.
         **
         *b  Arguments:
         **
         *a    x,y,z - the vector
         *a    roll - roll in degrees, clockwise is positive direction
         *a    yaw, pitch - return parameters, degrees
         **
         *b  Returns:
         **
         **    1 if results are valid; 0 otherwise
         **    (float * arguments converted to return values in Lua)
         */
        static int calculate_euler_angles_from_vector(float x, float y, float z, float roll, float *yaw, float *pitch);

        /*l
         *b  Description:
         **
         **    Given a vector and a roll value, calculate the Euler angles of yaw and pitch.
         **
         *b  Arguments:
         **
         *a    x,y,z - the vector
         *a    roll - roll in degrees, clockwise is positive direction
         *a    yaw, pitch - return parameters, degrees
         **
         *b  Returns:
         **
         **    1 if results are valid; 0 otherwise
         **    (float * arguments converted to return values in Lua)
         */
        static void calculate_vector_from_euler_angles(float yaw, float pitch, float *x, float *y, float *z);
                
        /*l
         *b  Description:
         **
         **    A helper function for when there is an object approaching a target, and the goal is for it to slow
         **  down in a realistic-looking way. If the object is infinitely far away from the target, the returned
         **  slide-in rate will be infinite (in theory, not practice, obviously). If the object is at the base
         **  distance, the slide-in rate will be the base rate. If the object is closer than that, the slide-in
         **  rate will approach zero.
         **
         *b  Arguments:
         **
         *a    current_distance - distance to target (can be distance in the conventional sense, or any kind of quantity)
         *a    base_rate - the base rate of travel, per second, in the same units
         *a    base_distance - the exact distance at which the base rate applies
         *a    acceptable_remainder - how much distance can be left for the target to have been "reached"
         **
         *b  Returns:
         **
         **    The new rate to assign to the object
         **
         *b  Usage Notes:
         **
         *-    - If current_distance is negative, it will simply be assumed that the object is on the other side of the 
         *-      target. Thus, the returned rate will be negative.
         *-    - One can easily apply a cap to the rate returned, so it's not too high
         *-    - To find time to decel from base rate, use t = 2 * base_distance / base_rate 
         *-    - If we want to calculate a slide-OUT rate, use distance from starting point, rather than to target
         *-    - This function can even be used to calculate a deceleration value, if the "distances" are deltas between
         *-      two speed values, and the base rate is the base deceleration value
         */
        static float calculate_slide_in_rate(float current_distance, float base_rate, float base_distance, float acceptable_remainder = 0.0f);

        /*l
         *b  Description:
         **
         **    Calculates the value of the exponential formula at time t
         **
         **    The formula is: y = c * e ^ (k * t)
         **    Its derivative is: y' = k * c * e ^ (k * t)
         **                          = k * y
         **
         *b  Calculating k:
         **
         **    ln(y) = ln(c) + k * t
         **    k = (ln(y) - ln(c)) / t
         **    to grow/decay to y1 in t = 1, c = 1: k = ln(y1) 
         **
         *b  Arguments:
         **
         *a    c - the starting quantity at time 0
         *a    k - the constant, positive for growth, negative for decay
         *a    t - time
         **
         *b  Returns:
         **
         **    The value of the formula at given time
         **
         */
        static float exponential_formula(float c, float k, float t);

        /*l
         *b  Description:
         **
         **    Calculates the value of k for the exponential growth/decay formula
         **
         *b  Arguments:
         **
         *a    multiplier - a value relative to starting value (>1 for growth, <1 for decay)
         *a    t - number of seconds it takes for exponential formula to reach that multiple 
         **
         *b  Returns:
         **
         **    Value of k
         **
         */
        static float calculate_exponential_growth_constant(float relative_value, float t);

        /*l
         *b  Description:
         **
         **    Rotate a vector by the given Euler angles
         **
         *b  Arguments:
         **
         *a    x, y, z of vector to be rotated
         *a    rx, ry, rz degrees to rotate by
         *a    result x, y, z
         **
         *b  Returns:
         **
         **    (float * arguments converted to return values in Lua)
         **
         */
        static void rotate_vector(float in_x, float in_y, float in_z, 
                                                                          float rz, float rx, float ry, 
                                                                          float* out_x, float* out_y, float* out_z);

        /*l
         *b  Description:
         **
         **    Rotate a vector by the inverse of the orientation
         **    defined by three Euler angles
         **
         *b  Arguments:
         **
         *a    x, y, z of vector to be rotated
         *a    rx, ry, rz degrees to rotate by
         *a    result x, y, z
         **
         *b  Returns:
         **
         **    (float * arguments converted to return values in Lua)
         **
         */
        static void unrotate_vector(float in_x, float in_y, float in_z, 
                                                                                 float rz, float rx, float ry, 
                                                                                 float* out_x, float* out_y, float* out_z);
};


#endif /* __diguyMathHelper_H */