SIM/SIM_Solver.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Side Effects Software Inc.
 *      477 Richmond Street West, Suite 1001
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 */

#ifndef __SIM_Solver_h__
#define __SIM_Solver_h__

#include "SIM_API.h"
#include "SIM_DataUtils.h"
#include "SIM_PhysicalParms.h"

class SIM_Solver;
class SIM_Engine;
class SIM_ObjectArray;

typedef UT_PtrArray<SIM_Solver *>        SIM_SolverArray;
typedef UT_PtrArray<const SIM_Solver *>  SIM_ConstSolverArray;

/// This is the base class for all Solvers. Solvers are the classes that
/// perform the actual simulation for objects. The solver is passed a
/// set of objects with mutual affector relationships.
class SIM_API SIM_Solver : public SIM_Data
{
public:
    /// The possible return codes from a solve operation. These are kept in
    /// order of priority to make multi-solvers easier to write. Any result
    /// value from a subsolver that is greater than the previous highest
    /// subsolver result becmoes the new overall return value.
    typedef enum {
        SIM_SOLVER_SUCCESS,
        SIM_SOLVER_REPEAT,
        SIM_SOLVER_SUBSTEP,
        SIM_SOLVER_FAIL
    } SIM_Result;

    /// Solve for the given objects. This function is called for each timestep
    /// after the one where the objects are first created. This function calls
    /// solveObjectSubclass to perform the real work.
    SIM_Result           solveObjects(SIM_Engine &engine,
                                SIM_ObjectArray &objects,
                                SIM_ObjectArray &newobjects,
                                SIM_ObjectArray &feedbacktoobjects,
                                const SIM_Time &timestep);

    SIM_Result           postSolveObjects(SIM_Engine &engine,
                                SIM_ObjectArray &objects,
                                SIM_ObjectArray &newobjects,
                                SIM_ObjectArray &feedbacktoobjects,
                                const SIM_Time &timestep);

    /// Get the number of cached time steps we want to solve for these objects.
    /// This function calls getRequestedCacheSubclass to get the real value.
    int                  getRequestedCache();
    /// Gets the impulse mass matrix of an object for an impulse at the
    /// provided world space position. This function simply calls
    /// getImpulseMassMatrixSubclass().
    void                 getImpulseMassMatrix(const SIM_Object &object,
                                const UT_Vector3 &impulseworldpos,
                                UT_DMatrix3 &immatrix) const;
    /// Gets the impulse mass matrix of an object for an impulse at the
    /// provided point on the geometry of the object. This function simply
    /// calls getPointImpulseMassMatrixSubclass().
    void                 getPointImpulseMassMatrix(const SIM_Object &object,
                                int ptnum, UT_DMatrix3 &immatrix) const;
    /// Gets the value of some physical property for the supplied object
    /// at a given position in world space. This function simply calls
    /// getPropertyAtPositionSubclass().
    fpreal               getPropertyAtPosition(const SIM_Object &object,
                                const UT_Vector3 &worldpos,
                                const SIM_Property &property) const;
    /// Gets the value of some physical property for the supplied object
    /// at a given point on the object's geometry. This function simply
    /// calls getPropertyAtPointSubclass().
    fpreal               getPropertyAtPoint(const SIM_Object &object,
                                int ptnum, const SIM_Property &property) const;

    /// Builds a resolver to efficiently compute property values
    SIM_PropertyResolver *getPropertyResolver(const SIM_Object &object,
                                    const SIM_Property &property) const;
    /// Gets the default collider label for an object using this solver.
    void                 getDefaultColliderLabel(const SIM_Object &object,
                                UT_String &label) const;
    /// Gets the default collider type for use on an object with a
    /// particular collider label. This information is used by
    /// SIM_Object::getCollider() to create a SIM_Collider to use
    /// for collision detection betweena pair of objects. The
    /// collidertype value returns the name of the SIM_Collider
    /// subclass to use, and the collidereverseobjectroles parameter
    /// returns whether the reverse object roles flag should be turned
    /// on for the new collider. See the ReverseObjectRoles flag in
    /// SIM_Collider for an explanation of this parameter.
    void                 getDefaultCollider(const SIM_Object &object,
                                const UT_String &colliderlabel,
                                UT_String &collidertype,
                                bool &colliderreverseobjectroles) const;

    /// Returns the standard attribute name that corresponds to a given
    /// SIM_Property value.
    static const char   *getPropertyAttribName(const SIM_Property &property);
    /// Static method that implements a good standard approach to getting
    /// a property at a given position.
    static fpreal        getPropertyAtPositionStatic(const SIM_Object &object,
                                const UT_Vector3 &worldpos,
                                const SIM_Property &property);
    /// Static method that implements a good standard approach to getting
    /// a property at a given point number.
    static fpreal        getPropertyAtPointStatic(const SIM_Object &object,
                                int ptnum, const SIM_Property &property);
    /// Static resolver for getting property values.
    static SIM_PropertyResolver *getPropertyResolverStatic(
                                    const SIM_Object &object,
                                    const SIM_Property &property);

    // Sets a temporary start time which may be used by this solver in
    // place of the global simulation time.  This is useful when
    // handling substeps or multi-phase integration schemes.  It is up
    // to each solver to use this start time.
    void                 setStartTime(const SIM_Time &starttime);

protected:
    /// Basic SIM_Solver constructor.
    explicit             SIM_Solver(const SIM_DataFactory *factory);
    /// Basic SIM_Solver destructor.
    virtual             ~SIM_Solver();

    // Gets the currently stored start time.  Returns false if the start time
    // is invalid.
    bool                 getStartTime(SIM_Time &time, bool invalidate = false);
 
    /// Gets an array of SIM_Solver subdata attached to this data.
    /// Useful for solvers which switch between or run other solvers.
    void                 getSolverSubdata(SIM_SolverArray &subsolvers,
                                        UT_StringArray *subsolvernames);
    /// Gets an array of const SIM_Solver subdata attached to this data.
    /// Useful for solvers which switch between or run other solvers.
    void                 getConstSolverSubdata(SIM_ConstSolverArray &subsolvers,
                                        UT_StringArray *subsolvernames) const;

    /// This method solves for some objects. It performs whatever processing
    /// is necessary to take objects from their state at one time to another.
    /// The default implementation does nothing. The objects parameter holds
    /// all the objects that should be solved for this timestep. The
    /// newobjects parameter is a set of objects that were just created in
    /// this timestep, and so should in most cases not be solved on this
    /// timestep so that they maintain correct initial conditions.
    virtual SIM_Result   solveObjectsSubclass(SIM_Engine &engine,
                                        SIM_ObjectArray &objects,
                                        SIM_ObjectArray &newobjects,
                                        SIM_ObjectArray &feedbacktoobjects,
                                        const SIM_Time &timestep) = 0;

    // return success?
    virtual SIM_Result   postSolveObjectsSubclass(SIM_Engine &engine,
                                                  SIM_ObjectArray &objects,
                                                  SIM_ObjectArray &newobjects,
                                                  SIM_ObjectArray &feedbacktoobjects,
                                                  const SIM_Time &timestep){ return SIM_SOLVER_SUCCESS; };

    /// Returns the amount of history required by this solver. Override
    /// this function if your solver requires past data to calculate the
    /// next time step. The default implementation returns 0.
    virtual int          getRequestedCacheSubclass();
    /// Gets the impulse mass matrix of an object for an impulse at the
    /// provided world space position. The default implementation gets the
    /// closest point in the geometry and calls getPointImpulseMassMatrix().
    virtual void         getImpulseMassMatrixSubclass(
                                const SIM_Object &object,
                                const UT_Vector3 &impulseworldpos,
                                UT_DMatrix3 &immatrix) const;
    /// Gets the impulse mass matrix of an object for an impulse at the
    /// provided point on the geometry of the object. The default
    /// implementation finds the world space position of the point and
    /// calls getImpulseMassMatrix().
    virtual void         getPointImpulseMassMatrixSubclass(
                                const SIM_Object &object,
                                int ptnum, UT_DMatrix3 &immatrix) const;
    /// Gets the value of some physical property for the supplied object
    /// at a given position in world space.
    virtual fpreal       getPropertyAtPositionSubclass(const SIM_Object &object,
                                const UT_Vector3 &worldpos,
                                const SIM_Property &property) const;
    /// Gets the value of some physical property for the supplied object
    /// at a given point on the object's geometry.
    virtual fpreal       getPropertyAtPointSubclass(const SIM_Object &object,
                                int ptnum, const SIM_Property &property) const;
    /// Builds a resolver for evaulating properties swiftly
    virtual SIM_PropertyResolver *getPropertyResolverSubclass(
                                const SIM_Object &object, 
                                const SIM_Property &property) const;
    /// Gets the default collider label for an object using this solver.
    virtual void         getDefaultColliderLabelSubclass(
                                const SIM_Object &object,
                                UT_String &label) const;
    /// Gets the default collider type for use on an object with a
    /// particular collider label.
    virtual void         getDefaultColliderSubclass(
                                const SIM_Object &object,
                                const UT_String &colliderlabel,
                                UT_String &collidertype,
                                bool &colliderreverseobjectroles) const;

private:
    DECLARE_STANDARD_GETCASTTOTYPE();
    DECLARE_CLASSNAME(SIM_Solver, SIM_Data);

    // Holds the current time - ie. the time at the beginning
    // of the timestep currently being processed.  This can be
    // used (by using calls to setStartTime and getStartTime)
    // to inform solvers of when they should use a time other
    // than the global simulation time when processing a timestep
    SIM_Time                    myCurrentStartTime;
    bool                        myCurrentStartTimeValid;
 
};

#endif

---