VRAY/VRAY_Volume.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:
 *      Andrew Clinton
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        VRAY_Volume.h ( RAY Library, C++)
 *
 * COMMENTS:    Procedurally defined volumetric rendering data
 */

#ifndef __VRAY_Volume__
#define __VRAY_Volume__

#include "VRAY_API.h"
#include <SYS/SYS_Types.h>

template <class T> class UT_RefArray;

// We have to include voxel array as we can't forward declare
// UT_VoxelArrayF, I think.
#include <UT/UT_VoxelArray.h>

class UT_StringArray;
class UT_IntArray;
class UT_FloatArray;
class UT_BoundingBox;
class UT_Vector3;
class UT_Matrix4;
class UT_Filter;
class VEX_LateBinding;
class GEO_Primitive;
class GEO_Vertex;
class VRAY_Octree;

class VRAY_API VRAY_Volume {
public:
             VRAY_Volume();
    virtual ~VRAY_Volume();

    /// Return the geometric primitive or vertex associated with the
    /// volume.  These can be used to fill in primitive and detail
    /// attributes associated with the volume.
    virtual GEO_Primitive       *getGeoPrimitive() const        { return 0; }
    virtual GEO_Vertex          *getGeoVertex() const           { return 0; }
    
    /// Return a local transform on the volume.  All volume evaluations
    /// will be performed within this transform space.  Defaults to the
    /// identity transform.
    virtual void         getXform(UT_Matrix4 &xform) const;

    /// Return a set of bounding boxes that define the structure of the
    /// volumetric data.  Each box has an associated weight, which
    /// represents the relative importance of that part of the volume (such
    /// as the density).  The boxes are used to accelerate intersection
    /// testing with the volume and to perform adaptive sampling.  They
    /// need not be an exact representation of the volume, though more
    /// accurate boxes will lead to more efficient renders.
    ///
    /// Boxes should be defined locally, and need to incorporate the
    /// displacement bound.
    /// - radius: filter radius in voxels
    /// - dbound: displacement bound in local space
    virtual void         getWeightedBoxes(UT_RefArray<UT_BoundingBox> &boxes,
                                          UT_FloatArray &weights,
                                          fpreal radius,
                                          fpreal dbound) const = 0;

    /// Return a list of attributes present in this volume.  These
    /// attributes will be bound to surface shader variables when the
    /// volume is rendered.  The "idx" passed into evaluation routines will
    /// be the array index returned by this operation.
    /// - sizes: number of floats in each attribute
    virtual void         getAttributeBinding(UT_StringArray &names,
                                             UT_IntArray &sizes) const = 0;

    /// Evaluate a volume attribute at a given position.
    /// - radius: filter radius in voxels
    virtual void         evaluate(const UT_Vector3 &pos,
                                  const UT_Filter &filter,
                                  fpreal radius, fpreal time,
                                  int idx, fpreal *data) const = 0;

    /// Evaluate the minimum and maximum values for an attribute within a
    /// given box.  If this operation is not supported, the caller will
    /// assume that the interval is unbounded.
    virtual bool         evaluateInterval(const UT_BoundingBox &box,
                                          const UT_Filter &filter,
                                          fpreal radius,
                                          fpreal time, int idx,
                                          fpreal *minval,
                                          fpreal *maxval) const
                         {
                             return false;
                         }

    /// Evaluate the gradient of a volume attribute at a given position.
    /// - radius: filter radius in voxels
    virtual UT_Vector3   gradient(const UT_Vector3 &pos,
                                  const UT_Filter &filter,
                                  fpreal radius, fpreal time,
                                  int idx) const;

    /// Returns a local distance for use in default gradient calculations.
    virtual fpreal       getGradientDelta() const       { return 1e-3F; }

    /// Returns the volume attribute index to be used for normal vector
    /// calculations.
    virtual int          getNormalAttribute() const     { return 0; }

    /// Returns the voxel size in the same space as 'pos' in evaluate.
    virtual fpreal       getVoxelSize() const           { return 0; }

public:
    void                 bumpRef(int dir)
                         {
                             myRefCount += dir;
                             if (myRefCount == 0)
                                 delete this;
                         }
    
    /// Function used internally to get an octree
    VRAY_Octree         *getTree() const                { return myTree; }
    void                 setTree(VRAY_Octree *tree)     { myTree = tree; }
    VRAY_Octree         *getDisplaceTree() const        { return myTree; }
    void                 setDisplaceTree(VRAY_Octree *tree) { myTree = tree; }

    /// Function used internally to create a late binding
    void                 fillBinding(VEX_LateBinding &bind) const;

protected:
    /// Utility method to create bounding boxes for every nonzero voxel in
    /// the voxel array.
    static void          addVoxelBoxes(UT_VoxelArrayF &voxels,
                                       UT_RefArray<UT_BoundingBox> &boxes,
                                       UT_FloatArray &weights,
                                       fpreal radius, fpreal dbound);

private:
    VRAY_Octree         *myTree;
    VRAY_Octree         *myDisplaceTree;
    int                  myRefCount;
};

#endif

---