diguyChainSettings.h

Go to the documentation of this file.

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


/*********************************************************************
 **
 *t  diguyChainSettings
 **
 */

#ifndef __diguyChainSettings_H
#define __diguyChainSettings_H


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

#ifdef CPLUSPLUS_ONLY
class bdiScenarioChainSettings;
#endif


#include <declspec_diguy.h>

class BDI_DECLSPEC_diguy diguyChainSettings
{

public:

/*****************************************************************************/
        /*l
         *b  Returns:
         **
         **    name of this object; this value will never be NULL
         */
        const char* get_name();

        /*l
         *b  Description:
         **
         **    This function sets the name of this object.
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         */
        int set_name(const char* name);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets how many masses will in a chain using these
         **    settings.
         **
         **    The default is 80 masses.
         **
         *b  Arguments:
         **
         *a    num_masses - number of masses
         */
        void set_num_masses(int num_masses);

        /*l
         *b  Returns:
         **
         **    number of masses; see set_num_masses()
         */
        int get_num_masses();

        /*l
         *b  Description:
         **
         **    This function sets which chain mass will be connected to the
         **    chain's associated character when a chain using these settings is
         **    created or reset.
         **
         **    Pass -1 for no mass to be connected.
         **
         **    The default is chain mass 0.
         **
         *b  Arguments:
         **
         *a    chain_mass_index - index of chain mass
         */
        void set_index_of_chain_mass_connected_to_character(int chain_mass_index);

        /*l
         *b  Returns:
         **
         **    which mass to connect on reset; see
         **    set_index_of_chain_mass_connected_to_character()
         */
        int get_index_of_chain_mass_connected_to_character();

        /*l
         *b  Description:
         **
         **    This function sets the dt of the chain simulation using these
         **    settings.
         **
         **    Higher dt values will provide faster simulations at the risk of
         **    instabilities.  Conversely, lower dt values result in more
         **    simulation computational overhead, but the simulation will be more
         **    stable.
         **
         **    The default is 0.002 seconds.
         **
         *b  Arguments:
         **
         *a    simulation_dt - dt of each simulation time step, in seconds
         */
        void set_simulation_dt(float simulation_dt);

        /*l
         *b  Returns:
         **
         **    dt of chain simulation; see set_simulation_dt()
         */
        float get_simulation_dt();

        /*l
         *b  Description:
         **
         **    This function sets the mass of each chain mass of the chain
         **    simulation using these settings.
         **
         **    Heavier mass will result in chain masses that have more momentum
         **    when moving.
         **
         **    The default is 0.5 kg.
         **
         *b  Arguments:
         **
         *a    mass - mass of each chain mass, in kg
         */
        void set_mass(float mass);

        /*l
         *b  Returns:
         **
         **    mass of each chain mass; see set_mass()
         */
        float get_mass();

        /*l
         *b  Description:
         **
         **    This function sets the nominal length of the springs connecting
         **    adjacent chain masses of the chain simulation using these
         **    settings.
         **
         **    Adjacent chain masses will try to keep this distance between them.
         **    A longer spring length will result in a longer chain.
         **
         **    The default is 0.2 meters
         **
         *b  Arguments:
         **
         *a    spring_length - nominal length between adjacent chain masses,
         *a                    in meters
         */
        void set_spring_length(float spring_length);

        /*l
         *b  Returns:
         **
         **    nominal length between adjacent chain masses;
         **    see set_spring_length()
         */
        float get_spring_length();

        /*l
         *b  Description:
         **
         **    This function sets the spring constant of the springs connecting
         **    adjacent chain masses of the chain simulation using these
         **    settings.
         **
         **    A higher spring constant will result in a more rigid chain, as
         **    adjacent masses will try to maintain their nominal spring length
         **    between them, as set by set_spring_length().
         **
         **    A hose would have a high spring constant, while a "slinky" would
         **    have a low spring constant.
         **
         **    This spring constant only applies between adjacent masses.
         **
         **    The default is 10000.
         **
         *b  Arguments:
         **
         *a    spring_k - spring constant of springs between adjacent masses
         */
        void set_spring_k(float spring_k);

        /*l
         *b  Returns:
         **
         **    spring constant of springs between adjacent masses; see
         **    set_spring_k()
         */
        float get_spring_k();

        /*l
         *b  Description:
         **
         **    This function sets the damping constant of the springs connecting
         **    adjacent chain masses of the chain simulation using these
         **    settings.
         **
         **    A higher damping constant will result in a chain that doesn't
         **    oscillate as much; movement between masses will quickly die down.
         **
         **    A hose would have a high damping constant, while a "slinky" would
         **    have a low damping constant.
         **
         **    The default is 15.
         **
         *b  Arguments:
         **
         *a    damping constant of springs between adjacent masses
         */
        void set_spring_b(float spring_b);

        /*l
         *b  Returns:
         **
         **    damping constant of springs between adjacent masses; see
         **    set_spring_b()
         */
        float get_spring_b();

        /*l
         *b  Description:
         **
         **    This function sets the nominal length of the springs connecting
         **    '2nd neighbor' chain masses of the chain simulation using these
         **    settings.
         **
         **    2nd neighbor chain masses are two masses apart instead of one.
         **    (Adjacent masses are one mass apart.)
         **
         **    A longer 2nd neighbor spring length will result in a chain that is
         **    stiffer and doesn't droop.  A lower value will result in a chain
         **    that can droop a lot from mass to mass.
         **
         **    A garden hose would have a high 2nd neighbor spring length, while
         **    a metal chain made of linked chain links would have a low 2nd
         **    neighbor spring length.
         **
         **    The default is 0.8 meters
         **
         *b  Arguments:
         **
         *a    spring_length - nominal length between adjacent chain masses,
         *a                    in meters
         */
        void set_neighbor2_spring_length(float neighbor2_spring_length);

        /*l
         *b  Returns:
         **
         **    nominal distance between each mass and its '2nd neighbor'; see
         **    set_neighbor2_spring_length()
         */
        float get_neighbor2_spring_length();

        /*l
         *b  Description:
         **
         **    This function sets the spring constant of springs connecting 2nd
         **    neighbor chain masses of the chain simulation using these
         **    settings.
         **
         **    See set_spring_k() for a discussion of what this value means.
         **
         **    The default is 600.
         **
         *b  Arguments:
         **
         *a    neighbor2_spring_k - spring constant of springs between
         **                         2nd neighbor masses
         */
        void set_neighbor2_spring_k(float neighbor2_spring_k);

        /*l
         *b  Returns:
         **
         **    spring constant of springs between 2nd neighbor masses; see
         **    set_neighbor2_spring_k()
         */
        float get_neighbor2_spring_k();

        /*l
         *b  Description:
         **
         **    This function sets the damping constant of springs connecting 2nd
         **    neighbor chain masses of the chain simulation using these
         **    settings.
         **
         **    See set_spring_b() for a discussion of what this value means.
         **
         **    The default is 5.
         **
         *b  Arguments:
         **
         *a    neighbor2_spring_b - damping constant of springs between
         **                         2nd neighbor masses
         */
        void set_neighbor2_spring_b(float neighbor2_spring_b);

        /*l
         *b  Returns:
         **
         **    damping constant of springs between 2nd neighbor masses; see
         **    set_neighbor2_spring_b()
         */
        float get_neighbor2_spring_b();

        /*l
         *b  Description:
         **
         **    This function sets the spring constant of the ground model.
         **
         **    A higher spring constant will result in a harder ground that
         **    bounces chain masses higher when they come in contact with the
         **    ground.  Also, chain masses will not sink as far into the ground
         **    when they come to rest.
         **
         **    A tile floor would have a high spring constant, while a mattress
         **    would have a low spring constant.
         **
         **    The default is 5000.
         **
         *b  Arguments:
         **
         *a    ground_k - spring constant of ground model
         */
        void set_ground_k(float ground_k);

        /*l
         *b  Returns:
         **
         **    spring constant of ground model; see set_ground_k()
         */
        float get_ground_k();

        /*l
         *b  Description:
         **
         **    This function sets the damping constant of the ground model.
         **
         **    A higher damping constant will result in a ground that absorbs
         **    impacts and doesn't bounce masses as much when they hit the
         **    ground.
         **
         **    A tile floor would have a low damping constant, while an exercise
         **    mat would have a high damping constant.
         **
         **    The default is 100.
         **
         *b  Arguments:
         **
         *a    ground_b - vertical damping constant of ground model
         */
        void set_ground_b(float ground_b);

        /*l
         *b  Returns:
         **
         **    vertical damping constant of ground model; see set_ground_b()
         */
        float get_ground_b();

        /*l
         *b  Description:
         **
         **    This function sets how much the ground model slows down masses
         **    that are sliding on it.
         **
         **    A higher lateral damping constant will quickly slow down masses
         **    sliding along the ground.
         **
         **    Dirt or grass ground would have a high lateral damping constant.
         **    Ice would have a very low damping constant.
         **
         **    The default is 0.5.
         **
         *b  Arguments:
         **
         *a    ground_lateral_b - lateral damping constant of ground model
         */
        void set_ground_lateral_b(float ground_lateral_b);

        /*l
         *b  Returns:
         **
         **    lateral damping constant of ground model; see
         **    set_ground_lateral_b()
         */
        float get_ground_lateral_b();

        /*l
         *b  Description:
         **
         **    This function sets how slow a mass in contact with the ground must
         **    go in order for the mass to stop moving and "stick" to the ground.
         **    This is a simple form of "stiction".
         **
         **    A mass will unstick if the force being applied to it exceeds the
         **    stiction release force as set by
         **    set_ground_stiction_release_force().
         **
         **    The default is 0.05 m/s.
         **
         *b  Arguments:
         **
         *a    ground_stiction_engage_vel - velocity at stiction will engage
         */
        void set_ground_stiction_engage_vel(float ground_stiction_engage_vel);

        /*l
         *b  Returns:
         **
         **    velocity at stiction will engage; see
         **    set_ground_stiction_engage_vel()
         */
        float get_ground_stiction_engage_vel();

        /*l
         *b  Description:
         **
         **    This function sets how much force is required to cause a mass that
         **    has stuck to the ground because of stiction to be released.
         **
         **    The default is 10 newtons.
         **
         *b  Arguments:
         **
         *a    ground_stiction_release_force - force at which masses will
         *a                                    release from stiction
         */
        void set_ground_stiction_release_force(float ground_stiction_release_force);

        /*l
         *b  Returns:
         **
         **    force at which masses will release from stiction; see
         **    set_ground_stiction_release_force()
         */
        float get_ground_stiction_release_force();

        /*l
         *b  Description:
         **
         **    This function sets the height of the ground model.  Chain masses
         **    below this height will be repelled upward based on their mass and
         **    the ground spring and damping constants.
         **
         **    Currently the ground is a level plane.
         **
         **    The default is 0 meters.
         **
         *b  Arguments:
         **
         *a    ground_height - height of the ground model, in meters
         */
        void set_ground_height(float ground_height);

        /*l
         *b  Returns:
         **
         **    height of the ground model; see set_ground_height()
         */
        float get_ground_height();

        /*l
         *b  Description:
         **
         **    This function sets the damping constant caused by air resistance.
         **
         **    A higher air damping constant will result in chains that don't
         **    swing as much.  A low air damping constant will result in chains
         **    that swing freely for a long time.
         **
         **    Water would have a very high "air" damping constant.  A clock
         **    pendulum would have a very low air damping constant.
         **
         **    The default is 0.1.
         **
         *b  Arguments:
         **
         *a    air_b - damping constant of air, or air resistance
         */
        void set_air_b(float air_b);

        /*l
         *b  Returns:
         **
         **    damping constant of air; see set_air_b()
         */
        float get_air_b();

        /*l
         *b  Description:
         **
         **    This function sets how strongly link masses will be accelerated in
         **    the gravity direction, typically downward.
         **
         **    The default is (0, 0, -9.8), in meters per second squared.
         **
         *b  Arguments:
         **
         *a    x, y, z - accelerations due to gravity
         */
        void set_gravity(float x, float y, float z);

        /*l
         *b  Returns:
         **
         **    x, y, and z components of gravity; see set_gravity()
         */
        void get_gravity(float* x, float* y, float* z);


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    This function sets the radius of the chain visual.
         **
         **    The default is 0.05 meters.
         **
         *b  Arguments:
         **
         *a    radius - radius of chain visual, in meters
         */
        void set_radius(float radius);

        /*l
         *b  Returns:
         **
         **    radius of chain visual; see set_radius()
         */
        float get_radius();

        /*l
         *b  Description:
         **
         **    This function sets the ambient color of the chain visual.  Passed
         **    values should be between 0 and 1.
         **
         **    The default values are (0.4, 0.4, 0.4, 1).
         **
         *b  Arguments:
         **
         *a    r, g, b, a - red, green, blue, and alpha components
         */
        void set_ambient_color(float r, float g, float b, float a);

        /*l
         *b  Description:
         **
         **    This function gets the ambient color of the chain visual.  Values
         **    are returned via the passed pointers.
         **
         *b  Arguments:
         **
         *a    r, g, b, a - red, green, blue, and alpha components
         */
        void get_ambient_color(float* r, float* g, float* b, float* a);

        /*l
         *b  Description:
         **
         **    This function sets the diffuse color of the chain visual.  Passed
         **    values should be between 0 and 1.
         **
         **    The default values are (1, 1, 1, 1).
         **
         *b  Arguments:
         **
         *a    r, g, b, a - red, green, blue, and alpha components
         */
        void set_diffuse_color(float r, float g, float b, float a);

        /*l
         *b  Description:
         **
         **    This function gets the diffuse color of the chain visual.  Values
         **    are returned via the passed pointers.
         **
         *b  Arguments:
         **
         *a    r, g, b, a - red, green, blue, and alpha components
         */
        void get_diffuse_color(float* r, float* g, float* b, float* a);

        /*l
         *b  Description:
         **
         **    This function sets the specular color of the chain visual.  Passed
         **    values should be between 0 and 1.
         **
         **    The default values are (1, 1, 1, 1).
         **
         *b  Arguments:
         **
         *a    r, g, b, a - red, green, blue, and alpha components
         */
        void set_specular_color(float r, float g, float b, float a);

        /*l
         *b  Description:
         **
         **    This function gets the specular color of the chain visual.  Values
         **    are returned via the passed pointers.
         **
         *b  Arguments:
         **
         *a    r, g, b, a - red, green, blue, and alpha components
         */
        void get_specular_color(float* r, float* g, float* b, float* a);

        /*l
         *b  Description:
         **
         **    This function sets the shininess of the chain visual.
         **
         **    The default is 20.
         **
         *b  Arguments:
         **
         *a    shininess - the shininess of the chain visual
         */
        void set_shininess(float shininess);

        /*l
         *b  Returns:
         **
         **    the shininess of the chain visual; see set_shininess()
         */
        float get_shininess();

        /*l
         *b  Description:
         **
         **    This function sets the filename of the texture that will be used
         **    for the chain visual.
         **
         **    Common textures are:
         **
         *-    - "chain_link.rgba"
         *-    - "firefighter_hose2.rgb"
         **
         **    The default is "" (no texture).
         **
         *b  Arguments:
         **
         *a    texture_filename - filename of texture of chain visual
         */
        void set_texture_filename(const char* texture_filename);

        /*l
         *b  Returns:
         **
         **    filename of texture of chain visual; see set_texture_filename()
         */
        const char* get_texture_filename();

        /*l
         *b  Description:
         **
         **    This function sets how many times the texture will be repeated
         **    along the length of the chain.
         **
         **    The default is 1 rep.
         **
         *b  Arguments:
         **
         *a    num_texture_repetitions - how many times texture will be
         *a                              repeated on chain visual
         */
        void set_num_texture_repetitions(int num_texture_repetitions);

        /*l
         *b  Returns:
         **
         **    how many times texture will be repeated on chain visual; see
         **    set_num_texture_repetitions()
         */
        int get_num_texture_repetitions();

        /*l
         *b  Description:
         **
         **    This function sets what the "cross section" of the chain visual
         **    will be.
         **
         **    See the documentation for diguyChainCrossSection for information
         **    on what the different cross sections mean.
         **
         **    The default is DIGUY_CHAIN_CROSS_SECTION_SQUARE.
         **
         *b  Arguments:
         **
         *a    cs - cross section of the chain visual
         */
        void set_cross_section(diguyChainCrossSection cs);

        /*l
         *b  Returns:
         **
         **    cross section type of chain visual; see set_cross_section()
         */
        diguyChainCrossSection get_cross_section();

        /*l
         *b  Description:
         **
         **    Set the shape that will be attached to the beginning end of the
         **    chain.  Options are:
         **
         *-    - "chain_cap_firehose_nozzle"
         *-    - "chain_cap_fuel_hose_nozzle"
         *-    - "chain_cap_taser_probe"
         *-    - "chain_cap_chain_hook"
         **
         **    The default is "" (no begin cap).
         **
         *b  Arguments:
         **
         *a    appearance_begin_cap - name of begin cap
         */
        void set_appearance_begin_cap(const char* appearance_begin_cap);

        /*l
         *b  Returns:
         **
         **    name of cap appearance at beginning of chain; see
         **    set_appearance_begin_cap()
         */
        const char* get_appearance_begin_cap();

        /*l
         *b  Description:
         **
         **    Sets the shape that will be attached to the end of the chain.  See
         **    set_appearance_begin_cap().
         **
         **    The default is "" (no end cap).
         **
         *b  Arguments:
         **
         *a    appearance_end_cap - name of end cap
         */
        void set_appearance_end_cap(const char* appearance_end_cap);

        /*l
         *b  Returns:
         **
         **    name of cap appearance at end of chain; see
         **    set_appearance_end_cap()
         */
        const char* get_appearance_end_cap();


/*****************************************************************************/
        /*l
         *b  Description:
         **
         **    For chains with the DIGUY_CHAIN_CROSS_SECTION_COIL cross section,
         **    sets the number of coil windings of the chain.
         **
         **    The default is 4 coils.
         **
         *b  Arguments:
         **
         *a    num_coils - number of coil windings
         */
        void set_num_coils(int num_coils);

        /*l
         *b  Returns:
         **
         **    number of coils for chain visual of type
         **    DIGUY_CHAIN_CROSS_SECTION_COIL; see set_num_coils()
         */
        int get_num_coils();

        /*l
         *b  Description:
         **
         **    Sets how thick the coil will be.
         **
         **    The default is 0.02 meters.
         **
         *b  Arguments:
         **
         *a    coil_thickness - thickness of coil
         */
        void set_coil_thickness(float coil_thickness);

        /*l
         *b  Returns:
         **
         **    thickness of coils for chain visual of type
         **    DIGUY_CHAIN_CROSS_SECTION_COIL; see set_coil_thickness()
         */
        float get_coil_thickness();

        /*l
         *b  Description:
         **
         **    Sets at which mass in the coil the thickness of the coil will
         **    reach its full radius.
         **
         **    The default is 6.
         **
         *b  Arguments:
         **
         *a    coil_taper_begin_mass_count - chain mass at which to begin taper
         */
        void set_coil_taper_begin_mass_count(int coil_taper_begin_mass_count);

        /*l
         *b  Returns:
         **
         **    mass at which the coil will reach its full radius at the beginning
         **    of chain; see set_coil_taper_begin_mass_count()
         */
        int get_coil_taper_begin_mass_count();

        /*l
         *b  Description:
         **
         **    Similar to set_coil_taper_begin_mass_count(), but for the end of
         **    the chain.
         **
         **    The default is 0.
         **
         *b  Arguments:
         **
         *a    coil_taper_end_mass_count - chain mass at which to end taper
         */
        void set_coil_taper_end_mass_count(int coil_taper_end_mass_count);

        /*l
         *b  Returns:
         **
         **    mass at which the coil will reach its full radius at end of chain;
         **    see set_coil_taper_end_mass_count()
         */
        int get_coil_taper_end_mass_count();

#ifdef CPLUSPLUS_ONLY

        bdiScenarioChainSettings* get_scripted_object() {return m_scripted_object;}

private:

        /*l
         **    A private constructor.
         */
        diguyChainSettings(bdiScenarioChainSettings* scripted_object);

        /*l
         **    A private destructor.
         */
        ~diguyChainSettings();

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

        friend class bdiScenarioChainSettings;

#endif

};


#endif /* __diguyChainSettings_H */


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