diguyChainSimulation.h

Go to the documentation of this file.

/*********************************************************************
 ** Copyright (c) 1992-2014 VT MAK
 ** All rights reserved. 
 *********************************************************************/


/*********************************************************************
 **
 *t  diguyChainSimulation
 **
 */

#ifndef __diguyChainSimulation_H
#define __diguyChainSimulation_H


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

#ifdef CPLUSPLUS_ONLY
class bdiScenarioChain;
class bdiScenarioChainSettings;
class diguyChainSettings;
class diguyPathShape;
#endif


#include <declspec_diguy.h>

/****************************************************************************/
class BDI_DECLSPEC_diguy diguyChainSimulation
{

public:

        /*l
         *b  Description:
         **
         **    This function returns the chain settings this chain simulation is
         **    using.
         **
         *b  Returns:
         **
         **    object of type diguyChainSettings; will never be NULL
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        diguyChainSettings* get_settings();

        /*l
         *b  Description:
         **
         **    This function sets the settings this chain simulation will use.
         **
         *b  Arguments:
         **
         *a    settings - name of new settings to use
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int update_settings(const char* settings);

        /*l
         *b  Description:
         **
         **    This function runs the simulation forward the specified number of
         **    seconds, to let the chain settle into a stable configuration.
         **
         **    Note that the chain will appear to achieve the new configuration
         **    instantly.
         **
         **    Specifying a large amount of time can result in a frame rate
         **    hitch.
         **
         *b  Arguments:
         **
         *a    time_runoff - how much time to run off, in seconds
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int do_stabilization_time_runoff(float time_runoff);

        /*l
         *b  Description:
         **
         **    This function can 'freeze' or 'unfreeze' a chain.
         **
         **    If a chain is frozen, all chain masses will remain in their
         **    current positions and will not move until the chain is unfrozen.
         **
         **    A frozen chain requires no simulation time.
         **
         *b  Arguments:
         **
         *a    is_frozen  - pass 1 to freeze the chain; 0 to unfreeze
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        void set_is_frozen(int is_frozen);

        /*l
         *b  Returns:
         **
         **    1 if chain is frozen, 0 if not
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_is_frozen();

        /*l
         *b  Description:
         **
         **    This function connects a chain mass to a character, or disconnects
         **    a chain mass if the passed character_name is NULL.
         **
         **    As the character moves the chain mass will move with it, dragging
         **    adjacent masses along.  This allows a firefighter to pick up one
         **    end of a hose and drag the hose to a new location, for example.
         **
         **    In each time-step of the scenario a new position for the specified
         **    chain mass will be computed based on the position of the
         **    character.
         **
         **    When the chain sim is created, and when the scenario is reset, one
         **    chain mass will be automatically connected to the chain's
         **    character.  The index of the mass that will be connected is set by
         **    a call to
         **    diguyChainSettings::set_index_of_chain_mass_connected_to_character().
         **
         **    Chain masses can be connected to a specific link of the connection
         **    character by passing the link's name.  If NULL is passed, the
         **    connection will be made to the character's "position" link.  Note
         **    that a non-NULL link name must be used for the link offset
         **    arguments to have an effect.
         **
         **    The chain mass can gradually be shifted from its current position
         **    to the connection position using the connection_smoothing_period
         **    argument.  Passing in 0.5, for example, will cause the link to
         **    shift to its new connection point within approximately 0.5
         **    seconds, avoiding an abrupt and potentially ugly impulse to the
         **    simulation.
         **
         *b  Arguments:
         **
         *a    chain_mass_index  - index of chain mass
         *a    character_name    - name of character to attach to; must not be NULL
         *a    link_name         - name of link to attach to; can be NULL; if
         *a                        so, will attach to character's base position
         *a    link_offset_x     - link attachment offset in X
         *a    link_offset_y     - link attachment offset in Y
         *a    link_offset_z     - link attachment offset in Z
         *a    connection_smoothing_period - how much time to take, in seconds,
         *a                                  to gradually shift the chain mass
         *a                                  to its new connection point
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_chain_mass_connection_character(int chain_mass_index,
                const char* character_name,
                const char* link_name = NULL,
                float link_offset_x = 0.0f,
                float link_offset_y = 0.0f,
                float link_offset_z = 0.0f,
                float connection_smoothing_period = 0.1f);

        /*l
         *b  Description:
         **
         **    This function sets the position of one chain mass, and optionally
         **    fixes it there.
         **
         **    The passed position is always relative to the chain character's
         **    parent, if there is one.
         **
         **    If the fix_mass_position argument is 1, the chain mass will remain
         **    fixed in the new position, as if
         **    set_chain_mass_position_is_fixed(1) were called.
         **
         *b  Arguments:
         **
         *a    chain_mass_index  - index of chain mass; pass -1 to
         *a                        affect all chain masses
         *a    mass_x            - position x
         *a    mass_y            - position y
         *a    mass_z            - position z
         *a    fix_mass_position - pass 1 to fix chain mass in place;
         *a                        0 to leave it free to move
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_chain_mass_position(int chain_mass_index,
                float mass_x,
                float mass_y,
                float mass_z,
                int fix_mass_position);

        /*l
         *b  Description:
         **
         **    This function sets the positions of all chain masses to lie along
         **    the passed path shape.
         **
         **    If the stretch_to_fit argument is 1, chain masses will be spaced
         **    along the entire length of the path shape.  If the path shape is
         **    longer than the nominal length of the chain, the chain will be
         **    stretched out.  If the path shape is shorter, the chain will be
         **    compressed.
         **
         *b  Arguments:
         **
         *a    path_shape     - path shape for new chain mass positions
         *a    stretch_to_fit - pass 1 to stretch chain to take up entire
         *a                     length of path_shape; pass 0 to leave
         *a                     chain at its nominal length
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_chain_mass_positions_along_path_shape(diguyPathShape* path_shape,
                int stretch_to_fit = 1);

        /*l
         *b  Description:
         **
         **    This function can fix or unfix a chain mass in place.  If it is
         **    fixed the chain mass will remain in its current position until it
         **    is unfixed.
         **
         **    Fixed chain masses do not require simulation time, so the more
         **    masses in a chain that are fixed, the lower the computational load
         **    of the chain simulation.
         **
         *b  Arguments:
         **
         *a    chain_mass_index - index of chain mass; pass -1 to
         *a                       affect all chain masses
         *a    is_fixed         - pass 1 to fix chain mass position;
         *a                       0 to unfix it
         **
         *b  Returns:
         **
         **    0 on success, -1 on failure
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int set_chain_mass_position_is_fixed(int chain_mass_index,
                int is_fixed);

        /*l
         *b  Returns:
         **
         **    1 if chain mass is fixed, 0 if not
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        int get_chain_mass_position_is_fixed(int mass_index);

        /*l
         *b  Returns:
         **
         **    length of the chain
         **
         *b  Callable From:
         **
         *-    - C++
         *-    - Script
         */
        float get_length();


#ifdef CPLUSPLUS_ONLY

        bdiScenarioChain* get_scripted_object() {return m_scripted_object;}

private:

        /*l
         **    A private constructor.
         */
        diguyChainSimulation(bdiScenarioChain* scripted_object);

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

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

        friend class bdiScenarioChain;

#endif

};


#endif /* __diguyChainSimulation_H */


/*********************************************************************
 ** Copyright (c) 1992-2014 VT MAK
 ** All rights reserved. 
 *********************************************************************/