SIM_FieldSampler.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_FieldSampler.h ( SIM Library, C++)
 *
 * COMMENTS:
 *  This file contains relative sampler classes for probing field values at
 *  index coordinates of the reference field. The sampler backend will select
 *  the best probing method for the given field pair.
 *  The common approach to working on fields involves iterating over voxels of
 *  the destination grid. At these voxel locations, values of other fields may
 *  be required. Here, field samplers declared in this header can be used for
 *  efficient sampling, without having to worry about matching and alignment.
 *  In addition to getValue() methods, samplers also support checking if target
 *  tiles lie in a constant area of the source field.
 */

#ifndef __SIM_FieldSampler__
#define __SIM_FieldSampler__

#include "SIM_API.h"
#include "SIM_ScalarField.h"

#include <UT/UT_NonCopyable.h>
#include <UT/UT_VoxelArray.h>

#include <SYS/SYS_TypeDecorate.h>

class SIM_RawField;
class SIM_RawIndexField;

/// This internal abstract class implements sampling for scalar fields. Hidden
/// concrete subclasses take care of actual probing.
/// The createSampler static method should be used to instantiate a sampler.
class SIM_SFSImplementation
{
protected:
    SIM_SFSImplementation() {}

public:
    virtual ~SIM_SFSImplementation() {}

    /// This static method creates an appropriate sampler for the given fields. 
    template <typename FIELD_TYPE>
    static SIM_API UT_UniquePtr<SIM_SFSImplementation>
    createSampler(const FIELD_TYPE* target,
                  const SIM_RawField* source);
    /// This static method creates an appropriate sampler for reading the source
    /// field as cells of target are iterated at target_sample locations.
    static SIM_API UT_UniquePtr<SIM_SFSImplementation>
    createSampler(const SIM_VectorField* target,
                  const SIM_RawField* source,
                  SIM_FieldSample target_sample);

    virtual float getValue(int x, int y, int z) = 0;
    virtual float getValue(float x, float y, float z) = 0;
    virtual bool isTileConstant(int tx, int ty, int tz,
                                const UT_VoxelTile<float>* tile,
                                float& val) = 0;

protected:
    const UT_VoxelArrayF*           mySourceArray;
};

/// This internal abstract class implements sampling for vector fields.
/// The createSampler static method should be used to instantiate a sampler.
class SIM_VFSImplementation
{
protected:
    SIM_VFSImplementation() {}

public:
    virtual ~SIM_VFSImplementation() {}

    template <typename FIELD_TYPE>
    static SIM_API UT_UniquePtr<SIM_VFSImplementation>
    createSampler(const FIELD_TYPE* target,
                  const SIM_VectorField* source);

    virtual UT_Vector3 getValue(int x, int y, int z) = 0;
    virtual UT_Vector3 getValue(float x, float y, float z) = 0;
    virtual bool isTileConstant(int tx, int ty, int tz,
                                const UT_VoxelTile<float>* tile,
                                UT_Vector3& val) = 0;

protected:
    const UT_VoxelArrayF*           mySourceArrays[3];
};

/// This class is an efficient relative scalar field sampler. It samples the
/// source field, given coordinates in index space of the target (or an iterator
/// running over the target field).
class SIM_API SIM_ScalarFieldSampler : UT_NonCopyable
{
public:
    /// Default constructor; init() method must be called before the sampler is
    /// usable.
    SIM_ScalarFieldSampler()
    {
    }

    /// These constructors also initialize the sampler for immediate use.
    SIM_ScalarFieldSampler(const SIM_RawField* target,
                           const SIM_RawField* source)
    {
        init(target, source);
    }
    SIM_ScalarFieldSampler(const SIM_RawField* target,
                           const SIM_ScalarField* source)
    {
        init(target, source->getField());
    }
    SIM_ScalarFieldSampler(const SIM_RawIndexField* target,
                           const SIM_RawField* source)
    {
        init(target, source);
    }
    SIM_ScalarFieldSampler(const SIM_RawIndexField* target,
                           const SIM_ScalarField* source)
    {
        init(target, source->getField());
    }
    /// These constructors initialize the sampler for immediate use, when
    /// iterating over the target vector field with sampling given by
    /// target_sample.
    SIM_ScalarFieldSampler(const SIM_VectorField* target,
                           const SIM_RawField* source,
                           SIM_FieldSample target_sample)
    {
        init(target, source, target_sample);
    }
    SIM_ScalarFieldSampler(const SIM_VectorField* target,
                           const SIM_ScalarField* source,
                           SIM_FieldSample target_sample)
    {
        init(target, source->getField(), target_sample);
    }

    /// The destructor.
    ~SIM_ScalarFieldSampler()
    {
    }

    /// Initialization routines that must be called before the sampler can be
    /// used. Note that constructors that accept field pointers call init() to
    /// ensure that the object is ready for use.
    void init(const SIM_RawField* target, const SIM_RawField* source)
    {
        mySampler = SIM_SFSImplementation::createSampler(target, source);
    }
    void init(const SIM_RawIndexField* target, const SIM_RawField* source)
    {
        mySampler = SIM_SFSImplementation::createSampler(target, source);
    }
    /// This version of initialization is for sampling source with respect to
    /// cells of target at locations given by target_sample.
    void init(const SIM_VectorField* target, const SIM_RawField* source,
              SIM_FieldSample target_sample)
    {
        mySampler = SIM_SFSImplementation::createSampler(target, source,
                                                         target_sample);
    }

    /// Returns value of the source field at the given (exact) coordinates of
    /// the target field.
    SYS_FORCE_INLINE float getValue(int x, int y, int z)
    {
        return mySampler->getValue(x, y, z);
    }

    /// Returns value of the source field at the current voxel of the iterator.
    SYS_FORCE_INLINE float getValue(const UT_VoxelArrayIteratorF& iter)
    {
        return mySampler->getValue(iter.x(), iter.y(), iter.z());
    }

    /// Returns value of the source field at the given coordinates of the target
    /// field.
    SYS_FORCE_INLINE float getValue(float x, float y, float z)
    {
        return mySampler->getValue(x, y, z);
    }

    /// Returns value of the source field at the given coordinates of the target
    /// field.
    SYS_FORCE_INLINE float getValue(const UT_Vector3& p)
    {
        return mySampler->getValue(p.x(), p.y(), p.z());
    }

    /// Returns true if the source field is constant within the current tile of
    /// the target iterator. If it's constant, the constant value is stored in
    /// val. Note that this method doesn't exhaustively look into voxels, but
    /// only checks for compressed ones.
    SYS_FORCE_INLINE bool isTileConstant(const UT_VoxelArrayIteratorF& iter,
                                         float& val)
    {
        return mySampler->isTileConstant(iter.myTilePos[0], iter.myTilePos[1],
                                         iter.myTilePos[2], iter.getTile(),
                                         val);
    }

protected:
    UT_UniquePtr<SIM_SFSImplementation>
                                    mySampler;
};

SYS_DECLARE_LEGACY_TR(SIM_ScalarFieldSampler)

/// This class is an efficient relative vector field sampler. It samples the
/// source field, given coordinates in index space of the target (or an iterator
/// running over the target field).
class SIM_API SIM_VectorFieldSampler : UT_NonCopyable
{
public:
    /// Default constructor; init() method must be called before the sampler is
    /// usable.
    SIM_VectorFieldSampler()
    {
    }

    /// These constructors also initialize the sampler for immediate use.
    SIM_VectorFieldSampler(const SIM_RawField* target,
                           const SIM_VectorField* source)
    {
        init(target, source);
    }
    SIM_VectorFieldSampler(const SIM_RawIndexField* target,
                           const SIM_VectorField* source)
    {
        init(target, source);
    }

    /// The destructor.
    ~SIM_VectorFieldSampler()
    {
    }

    /// Initialization routines that must be called before the sampler can be
    /// used. Note that constructors that accept field pointers call init() to
    /// ensure that the object is ready for use.
    void init(const SIM_RawField* target, const SIM_VectorField* source)
    {
        mySampler = SIM_VFSImplementation::createSampler(target, source);
    }
    void init(const SIM_RawIndexField* target, const SIM_VectorField* source)
    {
        mySampler = SIM_VFSImplementation::createSampler(target, source);
    }

    /// Returns value of the source field at the given (exact) coordinates of
    /// the target field.
    SYS_FORCE_INLINE UT_Vector3 getValue(int x, int y, int z)
    {
        return mySampler->getValue(x, y, z);
    }

    /// Returns value of the source field at the current voxel of the iterator.
    SYS_FORCE_INLINE UT_Vector3 getValue(const UT_VoxelArrayIteratorF& iter)
    {
        return mySampler->getValue(iter.x(), iter.y(), iter.z());
    }

    /// Returns value of the source field at the given coordinates of the target
    /// field.
    SYS_FORCE_INLINE UT_Vector3 getValue(float x, float y, float z)
    {
        return mySampler->getValue(x, y, z);
    }
    
    /// Returns value of the source field at the given coordinates of the target
    /// field.
    SYS_FORCE_INLINE UT_Vector3 getValue(const UT_Vector3& p)
    {
        return mySampler->getValue(p.x(), p.y(), p.z());
    }

    /// Returns true if the source field is constant within the current tile of
    /// the target iterator. If it's constant, the constant value is stored in
    /// val. Note that this method doesn't exhaustively look into voxels, but
    /// only checks for compressed ones.
    SYS_FORCE_INLINE bool isTileConstant(const UT_VoxelArrayIteratorF& iter,
                                         UT_Vector3& val)
    {
        return mySampler->isTileConstant(iter.myTilePos[0], iter.myTilePos[1],
                                         iter.myTilePos[2], iter.getTile(),
                                         val);
    }

protected:
    UT_UniquePtr<SIM_VFSImplementation> 
                                    mySampler;
};

#endif