SIM_VolumeInstanceSource.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.
 *
 * NAME:        SIM_VolumeInstanceSource.h ( SIMZ Library, C++)
 *
 * COMMENTS:
 *      SIM_SourceRule is a representation of a sourcing operation. This is
 *      based on the features available on the Volume Source DOP.
 *      SIM_SourceInstanceIterator can be used to iterate over source instances
 *      of its given geometry.
 *      SIM_VolumeInstanceSource implements a DOP that is able to perform
 *      instanced field sourcing on the CPU (using packed source sets and
 *      instance points). See SIM_OpenCLMergeVDB for a node that does the same
 *      on the GPU (using NanoVDB).
 */

#ifndef __SIM_VolumeInstanceSource__
#define __SIM_VolumeInstanceSource__

#include "SIMZ_API.h"

#include <GAS/GAS_SubSolver.h>
#include <SIM/SIM_RawField.h>

/// This class encapsulates a volume merging rule.
class SIMZ_API SIM_SourceRule
{
public:
    /// Creates a default, invalid rule.
    SIM_SourceRule();
    /// Populates the fields of this rule with values from the dictionary. Keys
    /// are parameter names from the Volume Source DOP.
    void createFromDictionary(const UT_OptionsHolder& dict);

    /// Returns the scale that takes timestep normalization into account.
    fpreal32 getScale(fpreal32 timestep) const;
    /// Converts the respective pull strength into a blend value, taking the
    /// timestep into account.
    fpreal32 getAccGuideBlend(fpreal32 timestep) const;
    fpreal32 getDecGuideBlend(fpreal32 timestep) const;
    fpreal32 getDirGuideBlend(fpreal32 timestep) const;

    /// Returns true if this rule needs to work on the entire vector at once
    /// (that is, the rule cannot be correctly applied to each component of the
    /// vector separately).
    bool needsEntireVector() const;

    /// Initializes the internal coefficients for the given timestep. This
    /// function must be called before applyOperation(), blendValues(), or
    /// blendValuesNoWeight() functions are useable.
    void setTimestep(fpreal32 timestep);

    /// Applies the operation encoded in this rule and puts the result in dest.
    /// Use blendValues() functions instead if this rule prescribes the BLEND
    /// operation.
    void applyOperation(fpreal32 source, fpreal32& dest) const;
    void applyOperation(const UT_Vector3F& source,
                        UT_Vector3F& dest) const;

    /// Applies the blend operation of this rule and puts the results in dest,
    /// dest_weight.
    /// Use applyOperation() functions instead if this rule does not prescribe
    /// the BLEND operation.
    void blendValues(fpreal32 source, fpreal32& dest,
                     fpreal32 source_weight, fpreal32& dest_weight) const;
    void blendValues(const UT_Vector3F& source, UT_Vector3F& dest,
                     fpreal32 source_weight, fpreal32& dest_weight) const;

    /// Returns a source rule to apply the weight update part of this blend
    /// operation. The functor's applyOperation method can be used, but the rule
    /// may not be fully initialized for other purposes!
    SIM_SourceRule getWeightUpdateRule() const;

public:
    /// This enumeration lists the supported field ranks. Token order should
    /// match the respective menu.
    enum FieldRank
    {
        SCALAR = 0,
        VECTOR
    };

    /// This enumeration lists the available sourcing operations. Token order
    /// should match the respective menu.
    enum SourceOperation
    {
        COPY = 0,
        ADD,
        SUBTRACT,
        MULTIPLY,
        DIVIDE,
        MAXIMUM,
        MINIMUM,
        AVERAGE,
        PULL,
        BLEND,
        NONE
    };

protected:
    /// Coefficients for internal use. These values incorporate the timestep.
    fpreal32            myFinalScale;
    fpreal32            myFinalAccBlend;
    fpreal32            myFinalDecBlend;
    fpreal32            myFinalDirBlend;

public:
    /// Rank of the target and source fields.
    FieldRank           myRank;
    /// Name of the source volume.
    UT_StringHolder     mySourceField;
    /// Name of the source weight volume.
    UT_StringHolder     mySourceWeight;
    /// Name of the target DOP field.
    UT_StringHolder     myTargetField;
    /// Name of the target DOP weight field.
    UT_StringHolder     myTargetWeight;
    /// The merging operation.
    SourceOperation     myOperation;
    /// Pull strength for acceleration.
    fpreal32            myAccGuideStr;
    /// Pull strength for deceleration.
    fpreal32            myDecGuideStr;
    /// Pull strength for directional guiding.
    fpreal32            myDirGuideStr;
    /// The final scale applied while merging.
    fpreal32            myScale;

    /// Is the rule active?
    bool                myActivate;
    /// If using the pull operation with a vector field, independently pull the
    /// vector magnitudes and directions towards the goal? If false, each vector
    /// component is pulled separately.
    bool                myEnableDirBlend;
    /// When comparing vectors, use their norms? If false, each component is
    /// compared separately.
    bool                myUseNorm;
    /// Should instance velocities be added to the source values? Only relevant
    /// if rank is set to vector.
    bool                myAddInstanceVel;
    /// Clamp negative numbers to 0 after merging? Only has an effect with the
    /// SUBTRACT operation.
    bool                myClampZero;
    /// Use the timestep while merging?
    bool                myNormalizeTimestep;

    /// Was the rule fully initialized? This flag will be false if a critical
    /// part of the rule was missing when this rule was created.
    bool                myIsValid;
};

/// This class can be used to iterate over source instances in the given
/// geometry.
class SIMZ_API SIM_SourceInstanceIterator
{
public:
    /// Creates an invalid iterator. setGeometry() must be called before this
    /// iterator can be used. need_rules must be true if source rules will be
    /// required later. need_vel must be true if instance velocities are
    /// required.
    SIM_SourceInstanceIterator(bool need_rules = true, bool need_vel = false);
    /// Creates the iterator and initializes it for the given geometry.
    /// need_rules must be true if source rules will be required later. need_vel
    /// must be true if instance velocities are required.
    SIM_SourceInstanceIterator(const GA_Detail* gdp, bool need_rules = true,
                               bool need_vel = false);

    /// Initializes this iterator for the given geometry.
    void setGeometry(const GA_Detail* gdp);
    /// Returns true if and only if this iterator is valid. That is, if the
    /// instance geometry has all of the required attributes.
    bool isValid() const;

    /// Restarts the iterator. Must be called to start iteration.
    void rewind();
    /// Returns true if and only if the iterator is at the ned of the list of
    /// instances.
    bool atEnd() const;
    /// Advances the iterator to the next instance.
    void advance();

    /// Returns the name of the current instance.
    UT_StringHolder getName() const;
    /// Returns the frame offset for the current instance.
    fpreal32 getFrameOffset() const;
    /// Returns the position for the current instance.
    UT_Vector3F getPosition() const;
    /// Returns the orientation of the current instance.
    UT_QuaternionF getOrientation() const;
    /// Returns the pivot of the current instance.
    UT_Vector3F getPivot() const;

    /// Get the number of rules that the current instance prescribes. The
    /// iterator needs to be told on creation that rules are needed to use this
    /// method.
    int getNumberOfRules() const;
    /// Get a specific rule for the current instance. rule is the index of to
    /// acquire, and must be between 0 and getNumberOfRules()-1 (inclusive). The
    /// iterator needs to be told on creation that rules are needed to use this
    /// method.
    SIM_SourceRule getRule(int rule) const;

    /// Do the instances have linear or angular velocity? Will return false if
    /// this iterator was told velocities aren't needed on creation.
    bool hasVelocity() const;
    /// Returns linear velocity of this instance. The iterator needs to be told
    /// on creation that velocities are needed to use this method.
    UT_Vector3F getLinearVelocity() const;
    /// Returns angular velocity of this instance. The iterator needs to be told
    /// on creation that velocities are needed to use this method.
    UT_Vector3F getAngularVelocity() const;

protected:
    /// Updates the internal array of rules when the iterator shifts position.
    void updateRulesArray();

protected:
    GA_ROHandleS        myInstName;
    GA_ROHandleF        myInstFrame;
    GA_ROHandleV3       myInstPos;
    GA_ROHandleV4       myInstOrient;
    GA_ROHandleV3       myInstPivot;
    
    bool                myNeedRules;
    GA_ROHandleDictA    myInstRules;
    UT_Array<UT_OptionsHolder>
                        myRulesArray;

    bool                myNeedVelocity;
    GA_ROHandleV3       myInstLinV;
    GA_ROHandleV3       myInstAngV;

    GA_Iterator         myIterator;
};

/// This class can be used to check if tiles of the given raw field intersect
/// the bounding box of the instanced primitive.
class sim_TileIntersectionTester
{
public:
    /// Create a new tester. initTester() must be called on the created object
    /// before intersections can be checked.
    sim_TileIntersectionTester();

    /// Gets this object ready to perform intersection tests. Intersection tests
    /// are done for tiles of the field, against the oriented bounding box of
    /// the instanced primitive.
    void initTester(const SIM_RawField* field, const GEO_Primitive* prim,
                    const UT_Vector3& pos, const UT_Quaternion& orient,
                    const UT_Vector3& pivot);

    /// Returns true if the tile (a chunk of 16x16x16 voxels) of field starting
    /// at the given world location intersects the instanced primitive.
    /// This function checks the tile as if it were complete; it is thus a
    /// conservative test.
    bool intersectsTile(const UT_Vector3& p) const;

private:
    /// Center of the instanced primitive (offset by half tile size).
    UT_Vector3F                     myPrimCenter;
    /// Basis vectors rotated per the instancing attributes.
    UT_Vector3F                     myPrimX, myPrimY, myPrimZ;

    /// The 15 interval overlap constants used for queries.
    float                           myTileCompare[15];    
};

/// This class implements the intanced sourcing logic.
class SIMZ_API SIM_VolumeInstanceSource : public GAS_SubSolver
{
public:
    GET_DATA_FUNC_B("createmissing", CreateMissingFields);
    GET_DATA_FUNC_S("matchfield", FieldToMatch);
    GET_DATA_FUNC_B("resizefields", EnlargeFields);
    GET_DATA_FUNC_B("fulltiles", FullTiles);

    GET_DATA_FUNC_I("referenceframe", CollectFrame);
    GET_DATA_FUNC_I("input", Input);
    GET_DATA_FUNC_S("soppath", SopPath);
    GET_DATA_FUNC_S("instgeo", InstanceGeo);

protected:
    explicit SIM_VolumeInstanceSource(const SIM_DataFactory* factory);
            ~SIM_VolumeInstanceSource() override;

    bool solveGasSubclass(SIM_Engine& engine,
                          SIM_Object* obj,
                          SIM_Time time,
                          SIM_Time timestep) override;

private:
    /// This struct holds the maximum conainer bounds. When AStatus(i) is
    /// nonzero, ALoc(i) corresponds to the location of the barrier beyond which
    /// we may not resize.
    struct sim_ContainerBounds
    {
        UT_Vector3          myMaxLoc;
        UT_Vector3          myMaxStatus;
        UT_Vector3          myMinLoc;
        UT_Vector3          myMinStatus;
    };
    /// This struct holds the position, orientation, and pivot of an instance.
    struct sim_InstanceLocation
    {
        UT_Vector3          myPosition;
        UT_Quaternion       myOrientation;
        UT_Vector3          myPivot;
    };
    /// This struct holds the linear and angular velocities of an instance.
    struct sim_InstanceVelocity
    {
        UT_Vector3          myLinVelocity;
        UT_Vector3          myAngVelocity;
    };

    /// Reads the container bounds data on the object and puts the result in a
    /// sim_ContainerBounds. Returns true if the data could all be read in the
    /// right format. If false is returned, bounds may have partial edits.
    static bool getContainerBounds(const SIM_Object* obj,
                                   sim_ContainerBounds& bounds);

    /// Merges a single scalar field. Returns true if the target field was
    /// modified.
    bool mergeNthScalarField(SIM_ScalarField* target, SIM_ScalarField* weight,
                             const sim_ContainerBounds* bounds,
                             const GU_Detail* gdp, const SIM_SourceRule& rule,
                             const sim_InstanceLocation& location, int n) const;
    /// Merges a single vector field. Returns true if the target field was
    /// modified.
    bool mergeNthVectorField(SIM_VectorField* target, SIM_ScalarField* weight,
                             const sim_ContainerBounds* bounds,
                             const GU_Detail* gdp, const SIM_SourceRule& rule,
                             const sim_InstanceLocation& location, 
                             const sim_InstanceVelocity& vel, int n) const;

    /// Merges a single component of the vector field, for operations that don't
    /// need the entire vector.
    THREADED_METHOD8_CONST(SIM_VolumeInstanceSource, dest->shouldMultiThread(),
                           mixEachVoxelVC,
                           SIM_RawField*, dest,
                           const GEO_Primitive**, sources,
                           int, component,
                           const SIM_SourceRule&, rule,
                           const sim_InstanceLocation&, location,
                           bool, use_vel,
                           const sim_InstanceVelocity&, velocity,
                           const sim_TileIntersectionTester&, tester);
    void mixEachVoxelVCPartial(SIM_RawField* dest,
                               const GEO_Primitive* sources[3], int component,
                               const SIM_SourceRule& rule,
                               const sim_InstanceLocation& location,
                               bool use_vel,
                               const sim_InstanceVelocity& velocity,
                               const sim_TileIntersectionTester& tester,
                               const UT_JobInfo& info) const;
    
    /// Merges a single component of the vector field, for operations that don't
    /// need the entire vector. This function treats the source vector field as
    /// contravariant.
    THREADED_METHOD8_CONST(SIM_VolumeInstanceSource, dest->shouldMultiThread(),
                           mixEachVoxelVCContravariant,
                           SIM_RawField*, dest,
                           const GEO_Primitive**, sources,
                           int, component,
                           const SIM_SourceRule&, rule,
                           const sim_InstanceLocation&, location,
                           bool, use_vel,
                           const sim_InstanceVelocity&, velocity,
                           const sim_TileIntersectionTester&, tester);
    void mixEachVoxelVCContravariantPartial(SIM_RawField* dest,
                               const GEO_Primitive* sources[3], int component,
                               const SIM_SourceRule& rule,
                               const sim_InstanceLocation& location,
                               bool use_vel,
                               const sim_InstanceVelocity& velocity,
                               const sim_TileIntersectionTester& tester,
                               const UT_JobInfo& info) const;
    
    /// Merges a single component of the vector field, for operations that need
    /// the entire vector.
    THREADED_METHOD10_CONST(SIM_VolumeInstanceSource, dest->shouldMultiThread(),
                            mixEachVoxelVC,
                            SIM_RawField*, dest,
                            SIM_RawField**, old_fields,
                            const GEO_Primitive**, sources,
                            int, component,
                            const SIM_SourceRule&, rule,
                            const sim_InstanceLocation&, location,
                            bool, use_vel, 
                            const sim_InstanceVelocity&, velocity,
                            const sim_TileIntersectionTester&, tester,
                            bool, contravariant);
    void mixEachVoxelVCPartial(SIM_RawField* dest,
                               SIM_RawField* old_fields[3],
                               const GEO_Primitive* sources[3], int component,
                               const SIM_SourceRule& rule,
                               const sim_InstanceLocation& location,
                               bool use_vel,
                               const sim_InstanceVelocity& velocity,
                               const sim_TileIntersectionTester& tester,
                               bool contravariant,
                               const UT_JobInfo& info) const;

    /// Merges all components of a vector field. The components must have
    /// collocated samples.
    THREADED_METHOD8_CONST(SIM_VolumeInstanceSource,
                           dest[0]->shouldMultiThread(),
                           mixEachVoxelV,
                           SIM_RawField**, dest,
                           const GEO_Primitive**, sources,
                           const SIM_SourceRule&, rule,
                           const sim_InstanceLocation&, location,
                           bool, use_vel,
                           const sim_InstanceVelocity&, velocity,
                           const sim_TileIntersectionTester&, tester,
                           bool, contravariant);
    void mixEachVoxelVPartial(SIM_RawField* dest[3],
                              const GEO_Primitive* sources[3],
                              const SIM_SourceRule& rule,
                              const sim_InstanceLocation& location,
                              bool use_vel,
                              const sim_InstanceVelocity& velocity,
                              const sim_TileIntersectionTester& tester,
                              bool contravariant,
                              const UT_JobInfo& info) const;

    /// Merges a vector field, when the operation is set to blend. This method
    /// works on a single component and doesn't update the weight field.
    THREADED_METHOD10_CONST(SIM_VolumeInstanceSource,
                            target->shouldMultiThread(),
                            blendEachVoxelVCNoWeight,
                            SIM_RawField*, target,
                            const SIM_RawField*, weight,
                            const GEO_Primitive**, prims,
                            const GEO_Primitive*, weight_prim,
                            int, component,
                            const SIM_SourceRule&, rule,
                            const sim_InstanceLocation&, location,
                            bool, use_vel,
                            const sim_InstanceVelocity&, velocity,
                            const sim_TileIntersectionTester&, tester);
    void blendEachVoxelVCNoWeightPartial(SIM_RawField* target,
                                         const SIM_RawField* weight,
                                         const GEO_Primitive* prims[3],
                                         const GEO_Primitive* weight_prim,
                                         int component,
                                         const SIM_SourceRule& rule,
                                         const sim_InstanceLocation& location, 
                                         bool use_vel,
                                         const sim_InstanceVelocity& velocity,
                                         const sim_TileIntersectionTester& test,
                                         const UT_JobInfo& info) const;

    /// Merges a vector field, when the operation is set to blend. This method
    /// works on a single component (from a contravariant source) and doesn't
    /// update the weight field.
    THREADED_METHOD10_CONST(SIM_VolumeInstanceSource,
                            target->shouldMultiThread(),
                            blendEachVoxelVCNoWeightContravariant,
                            SIM_RawField*, target,
                            const SIM_RawField*, weight,
                            const GEO_Primitive**, prims,
                            const GEO_Primitive*, weight_prim,
                            int, component,
                            const SIM_SourceRule&, rule,
                            const sim_InstanceLocation&, location,
                            bool, use_vel,
                            const sim_InstanceVelocity&, velocity,
                            const sim_TileIntersectionTester&, tester);
    void blendEachVoxelVCNoWeightContravariantPartial(SIM_RawField* target,
                                         const SIM_RawField* weight,
                                         const GEO_Primitive* prims[3],
                                         const GEO_Primitive* weight_prim,
                                         int component,
                                         const SIM_SourceRule& rule,
                                         const sim_InstanceLocation& location,
                                         bool use_vel,
                                         const sim_InstanceVelocity& velocity,
                                         const sim_TileIntersectionTester& test,
                                         const UT_JobInfo& info) const;
    
    /// Merges a vector field, when the operation is set to blend. This method
    /// works on all components of the field at once (so the field must be
    /// collocated), but does not update the weight field.
    THREADED_METHOD10_CONST(SIM_VolumeInstanceSource,
                            targets[0]->shouldMultiThread(),
                            blendEachVoxelVNoWeight,
                            SIM_RawField**, targets,
                            const SIM_RawField*, weight,
                            const GEO_Primitive**, prims,
                            const GEO_Primitive*, weight_prim,
                            const SIM_SourceRule&, rule,
                            const sim_InstanceLocation&, location,
                            bool, use_vel,
                            const sim_InstanceVelocity&, velocity,
                            const sim_TileIntersectionTester&, test,
                            bool, contravariant);
    void blendEachVoxelVNoWeightPartial(SIM_RawField* targets[3],
                                        const SIM_RawField* weight,
                                        const GEO_Primitive* prims[3],
                                        const GEO_Primitive* weight_prim,
                                        const SIM_SourceRule& rule,
                                        const sim_InstanceLocation& location,
                                        bool use_vel,
                                        const sim_InstanceVelocity& velocity,
                                        const sim_TileIntersectionTester& test,
                                        bool contravariant,
                                        const UT_JobInfo& info) const;

    /// Merges the vector field, when the operation is set to blend. This method
    /// works on all components at once and updates the weights as well (so all
    /// raw fields must be aligned).
    THREADED_METHOD10_CONST(SIM_VolumeInstanceSource,
                            targets[0]->shouldMultiThread(),
                            blendEachVoxelV,
                            SIM_RawField**, targets,
                            SIM_RawField*, weight,
                            const GEO_Primitive**, prims,
                            const GEO_Primitive*, weight_prim,
                            const SIM_SourceRule&, rule,
                            const sim_InstanceLocation&, location,
                            bool, use_vel,
                            const sim_InstanceVelocity&, velocity,
                            const sim_TileIntersectionTester&, tester,
                            bool, contravariant);
    void blendEachVoxelVPartial(SIM_RawField* targets[3],
                                SIM_RawField* weight,
                                const GEO_Primitive* prims[3],
                                const GEO_Primitive* weight_prim,
                                const SIM_SourceRule& rule,
                                const sim_InstanceLocation& location,
                                bool use_vel,
                                const sim_InstanceVelocity& velocity,
                                const sim_TileIntersectionTester& tester,
                                bool contravariant, const UT_JobInfo& info)
        const;

    /// Merges a scalar field.
    THREADED_METHOD5_CONST(SIM_VolumeInstanceSource, dest->shouldMultiThread(),
                           mixEachVoxel,
                           SIM_RawField*, dest,
                           const GEO_Primitive*, source,
                           const SIM_SourceRule&, rule,
                           const sim_InstanceLocation&, location,
                           const sim_TileIntersectionTester&, tester);
    void mixEachVoxelPartial(SIM_RawField* dest, const GEO_Primitive* source,
                             const SIM_SourceRule& rule,
                             const sim_InstanceLocation& location,
                             const sim_TileIntersectionTester& tester,
                             const UT_JobInfo& info) const;
    
    /// Merges a scalar field, when the operation is set to blend. This method
    /// also updates the weight field (so target and weight must be aligned).
    THREADED_METHOD7_CONST(SIM_VolumeInstanceSource, dest->shouldMultiThread(),
                           blendEachVoxel,
                           SIM_RawField*, dest,
                           SIM_RawField*, weight,
                           const GEO_Primitive*, prim,
                           const GEO_Primitive*, weight_prim,
                           const SIM_SourceRule&, rule,
                           const sim_InstanceLocation&, location,
                           const sim_TileIntersectionTester&, tester);
    void blendEachVoxelPartial(SIM_RawField* target, SIM_RawField* weight,
                               const GEO_Primitive* prim,
                               const GEO_Primitive* weightp,
                               const SIM_SourceRule& rule,
                               const sim_InstanceLocation& location,
                               const sim_TileIntersectionTester& tester,
                               const UT_JobInfo& info) const;

    /// Merges a scalar field, when operation is set to blend. This method does
    /// not write to the weight field.
    THREADED_METHOD7_CONST(SIM_VolumeInstanceSource, dest->shouldMultiThread(),
                           blendEachVoxelNoWeight,
                           SIM_RawField*, dest,
                           const SIM_RawField*, weight,
                           const GEO_Primitive*, prim,
                           const GEO_Primitive*, weight_prim,
                           const SIM_SourceRule&, rule,
                           const sim_InstanceLocation&, location,
                           const sim_TileIntersectionTester&, tester);
    void blendEachVoxelNoWeightPartial(SIM_RawField* target,
                                       const SIM_RawField* weight,
                                       const GEO_Primitive* prim,
                                       const GEO_Primitive* weightp,
                                       const SIM_SourceRule& rule,
                                       const sim_InstanceLocation& location,
                                       const sim_TileIntersectionTester& tester,
                                       const UT_JobInfo& info) const;
    
    /// Creates a new field (of type FIELD) that matches scalar or vector (one
    /// of the two must be valid).
    template <typename FIELD>
    void createField(FIELD*& f, const SIM_ScalarField* scalar,
                     const SIM_VectorField* vector, const UT_StringHolder& name,
                     SIM_Object& obj);
    
    /// Enlarges the given field to make sure its bounding box contains the
    /// instanced primitive.
    template <typename FIELD>
    void resizeFieldIfNeeded(FIELD* field,
                             const sim_ContainerBounds* bounds,
                             const GEO_Primitive* prim,
                             const sim_InstanceLocation& location) const;
                            
private:
    static const SIM_DopDescription* getDopDescription();

    DECLARE_STANDARD_GETCASTTOTYPE();
    DECLARE_DATAFACTORY(SIM_VolumeInstanceSource, GAS_SubSolver,
                        "Volume Instance Source",
                        getDopDescription());
};

#endif