BRAY_Procedural.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:        BRAY_Procedural.h (BRAY Library, C++)
 *
 * COMMENTS:
 */

#ifndef __BRAY_Procedural__
#define __BRAY_Procedural__

#include "BRAY_API.h"
#include "BRAY_AttribList.h"
#include "BRAY_Interface.h"
#include "BRAY_ProceduralFactory.h"
#include <UT/UT_SmallObject.h>

class UT_JSONWriter;

class BRAY_API BRAY_Procedural
{
public:
    /// Templatized on `fpreal32` or `fpreal64`
    /// This structure is used in the intersect() function to compute an
    /// intersection with the procedural primitive.
    template <typename PREC>
    struct Ray
    {
        // RayType
        const UT_Vector3T<PREC> &org;
        const UT_Vector3T<PREC> &dir;
        fpreal                   tnear;
        fpreal                   tfar;
        BRAYtime                 time;
    };
    using Ray32 = Ray<fpreal32>;
    using Ray64 = Ray<fpreal64>;

    /// This class stores information about the hit.  The information is passed
    /// back to the procedural primitive when evaluating attributes.
    /// The procedural object can store any data it wants in the @c u, @c v,
    /// @c w and @c prim_id fields.  These are passed through to the primitive
    /// when looking up shading variables/attributes.  At the current time,
    /// @c prim_id must be >= 0.
    ///
    /// If a custom procedural needs to store information, the procedural can
    /// subclass from this class.  In the attribute evaluation methods, you can
    /// safely cast to your subclass.
    ///
    /// When the ray hits, the procedural should fill out
    /// - @c distance : the distance from the origin to the hit point
    /// - @c zback : For volume primitives, @c distance represents the start of
    ///   the shading interval while @c zback represents the farthest extent of
    ///   the shading sample, so for volumes, @zback should be >= @distance.
    ///   For non-volume shading information, @zback should be left at 0.
    /// - @c Ng : The geometric normal at the hit surface
    class HitPtr;
    class BRAY_API Hit
        : public UT_SmallObject<Hit>
    {
    public:
        Hit(fpreal d=SYS_FPREAL_MAX)
            : distance(d)
            , zback(0)
            , prim_id(0)
            , ref_count(0)
        {
        }
        virtual ~Hit();

        fpreal          distance;       // Distance to hit
        fpreal          zback;          // Distance to zback (0=solid surface)
        fpreal          u, v, w;        // Parametric coordinates
        UT_Vector3      Ng;             // Geometric normal
        uint            prim_id;        // ID of primitive in procedural
        uint            tri0 : 1;       // s+t < 1 in triangulated quad

        // @{
        // A convenience method to get a reference to a sub-class type
        // For example: @code
        //   MyHit &hit = src_hit.castTo<MyHit>();
        //   const MyHit &hit2 = src_hit.castTo<const MyHit>();
        // @endcode
        template <typename T>
        T       &castTo() { return *reinterpret_cast<T *>(this); }
        template <typename T>
        const T &castTo() const { return *reinterpret_cast<T *>(this); }
        // @}


    private:
        // Private data for internal use only.
        void    inc_ref() { ++ref_count; }
        void    dec_ref()
        {
            --ref_count;
            if (!ref_count)
                releaseHit();
        }
        void             releaseHit();  // Private method
        int              ref_count; // Order before pointer for alignment
        friend class     HitPtr;
        friend class     BRAY_Procedural;
    };

    // Smart pointer for hits
    class BRAY_API HitPtr
    {
    public:
        HitPtr() noexcept
            : myHit(nullptr)
        {
        }
        HitPtr(Hit *ptr) noexcept
            : myHit(ptr)
        {
            if (myHit)
                myHit->inc_ref();
        }
        HitPtr(const HitPtr &src) noexcept
            : myHit(src.myHit)
        {
            if (myHit)
                myHit->inc_ref();
        }
        HitPtr(HitPtr &&src) noexcept
            : myHit(src.myHit)
        {
            src.myHit = nullptr;
        }
        ~HitPtr()
        {
            reset();
        }
        HitPtr  &operator=(const HitPtr &src)
        {
            reset(src.myHit);
            return *this;
        }
        HitPtr &operator=(HitPtr &&src)
        {
            swap(src);
            src.reset();
            return *this;
        }

        Hit             &operator*() const noexcept { return *myHit; }
        Hit             *operator->() const noexcept { return myHit; }
        Hit             *get() const noexcept { return myHit; }
        SYS_SAFE_BOOL   operator bool() const noexcept { return myHit != nullptr; }
        void            swap(HitPtr &s) noexcept { UTswap(myHit, s.myHit); }
        void            reset() noexcept
                        {
                            if (myHit)
                            {
                                myHit->dec_ref();
                                myHit = nullptr;
                            }
                        }
        void            reset(Hit *hit) noexcept
                        {
                            if (hit)
                                hit->inc_ref();
                            if (myHit)
                                myHit->dec_ref();
                            myHit = hit;
                        }

    private:
        Hit     *myHit;
    };

    BRAY_Procedural();
    virtual ~BRAY_Procedural();

    /// Return a name for this procedural.  This defaults to factory()->name();
    const UT_StringHolder       &className() const { return myFactory->name(); }

    /// Return the factory definition
    const BRAY_ProceduralFactory *factory() const { return myFactory; }

    /// Return an attribute list for the attributes supported by this primitive.
    virtual const BRAY_AttribList       *attribList() const = 0;

    /// Return a parameter list that the procedural exposes to the outside
    /// world that could be set using the @c setParameter() methods
    /// The default implementation calls factory()->paramList();
    virtual const BRAY_AttribList       *paramList() const
    {
        return myFactory->paramList();
    }

    /// Return the bounding box for the object at a given time
    virtual void        bounds(UT_BoundingBox &bounds, BRAYtime time) const = 0;

    /// @{
    /// Set parameters on procedurals in addition to attributes that the
    /// procedural might provide. One way to think of parameters and attributes
    /// is that attributes are what procedurals bring to the table internally,
    /// where as parameters are something that can be applied onto procedurals.
    /// For example, a 'Sphere' object is a procedural.  It's attributes could
    /// be like 'color', 'normal' on vertices.  whereas 'parameters' could be
    /// 'radius', etc. Depending upon the procedural the meaning of these two
    /// terms change contextually.
    ///
    /// The templates are specialized for:
    /// - int32, int64, fpreal32, fpreal64, UT_StringHolder
    template <typename T>
    void setParameter(const UT_StringRef &key, const T &val)
    {
        doSetParameter(key, &val, 1);
    }

    template <typename T>
    void setParameter(const UT_StringRef& key, const T* values, int n)
    {
        doSetParameter(key, values, n);
    }
    /// @}

    /// @{
    /// Signal the procedural
    ///
    /// We allow for the Procedural to update itself and do any further
    /// processing in case any parameters have been set.  The set parameter
    /// methods are generally invoked on the procedural, which might be
    /// implemented by the procedural to copy data, precompute stuff, validate
    /// parameter ranges etc.  Once these have been set, the begin/end update
    /// methods can be used by the procedural to perform operations that can be
    /// performed only when there's nothing more to set as parameters to the
    /// procedural. The procedural can now start working on doing other things
    /// with the set parameters because it can be sure that the parameters now
    /// have become immutable.
    void beginUpdate()
    {
        doBeginUpdate();
    }

    void endUpdate()
    {
        doEndUpdate();
    }
    /// @}

    /// Check whether the procedural is valid
    bool isValid() const
    {
        return checkIsValid();
    }

    /// @{
    /// Perform ray-intersection
    ///
    /// If the distanct to the closest intersection point for the procedural
    /// object is closer than the @c distance already stored in the @c
    /// hit_info, the hit information should be replaced and the @c intersect()
    /// method should return @c true.
    ///
    /// If the distance to the closest intersection point is farther than the
    /// existing @c distance, then the @c hit_info should remain unchanged.
    ///
    /// NOTE:
    /// The ray's direction vector CANNOT be expected to be unit length
    /// Hence the procedural is responsible for accounting and returning
    /// the correct 't' in the hit_info struct if it ever scaled
    /// it internally to unit length.
    virtual HitPtr      intersect(const Ray32 &ray) const = 0;
    virtual HitPtr      intersect(const Ray64 &ray) const = 0;
    /// @}

    /// Return a display color for low-quality rendering
    virtual UT_Vector3  displayColor() const { return UT_Vector3(1, 1, 1); }

    /// @{
    /// Evaluate an attribute on this primitive.  The methods should return a
    /// pointer to the attribute data.  If there isn't a direct raw pointer to
    /// the data, the buffer passed in can be used to store the data and that
    /// pointer can be returned.
    /// The @c element is the element
    virtual const int32         *attribVal(int attrib, BRAYtime time,
                                    const Hit &hit_info,
                                    int32 *buf, int size) const = 0;
    virtual const int64         *attribVal(int attrib, BRAYtime time,
                                    const Hit &hit_info,
                                    int64 *buf, int size) const = 0;
    virtual const fpreal32      *attribVal(int attrib, BRAYtime time,
                                    const Hit &hit_info,
                                    fpreal32 *buf, int size) const = 0;
    virtual const fpreal64      *attribVal(int attrib, BRAYtime time,
                                    const Hit &hit_info,
                                    fpreal64 *buf, int size) const = 0;
    virtual const UT_StringHolder *attribVal(int attrib, BRAYtime time,
                                    const Hit &hit_info,
                                    UT_StringHolder *buf, int size) const = 0;


    /// @}

    /// @{
    /// Evaluation of array attributes (each attribute can have an arbitrary
    /// number of entries.  By default, the array attribute evaluators set the
    /// arrays to a size of 0 and return the storage array.
    virtual const UT_ValArray<int32>    *attribVal(int attrib,
                                            BRAYtime time,
                                            const Hit &hit_info,
                                            UT_ValArray<int32> *buf,
                                            int size) const;
    virtual const UT_ValArray<int64>    *attribVal(int attrib,
                                            BRAYtime time,
                                            const Hit &hit_info,
                                            UT_ValArray<int64> *buf,
                                            int size) const;
    virtual const UT_ValArray<fpreal32> *attribVal(int attrib,
                                            BRAYtime time,
                                            const Hit &hit_info,
                                            UT_ValArray<fpreal32> *buf,
                                            int size) const;
    virtual const UT_ValArray<fpreal64> *attribVal(int attrib,
                                            BRAYtime time,
                                            const Hit &hit_info,
                                            UT_ValArray<fpreal64> *buf,
                                            int size) const;
    virtual const UT_StringArray        *attribVal(int attrib,
                                            BRAYtime time,
                                            const Hit &hit_info,
                                            UT_StringArray *buf,
                                            int size) const;
    /// @}

    /// This method can be used to be notified of changes to the object
    virtual void        update(BRAY_EventType event) = 0;

    /// Dump out information about the procedural for debugging.  By default, a
    /// null is written to the stream.
    virtual void        dumpInfo(UT_JSONWriter &w) const;

    /// @private
    void        setFactory(BRAY_ProceduralFactory *f) { myFactory = f; }

protected:
    /// @c Hit objects are virtual which allows you to create a sub-class that
    /// stores information specific to your procedural type.  The Hit structure
    /// should be kept relatively small if possible.  When you need to allocate
    /// a Hit object for your intersect method, you should call @c getHit().
    ///
    /// To implement the actual allocation of the custom @c Hit object, you
    /// need to implement @c newHit().
    HitPtr      getHit() const;

    /// The @c newHit() method is used to allocate a custom @c Hit type.  The
    /// typical way this is done is: @code
    ///    class MyHit : public Hit { };
    ///    HitPtr    newHit() const override { return HitPtr(new MyHit(...)); }
    /// @endcode
    virtual HitPtr      newHit() const;

    /// This method will be called to print out an error if the procedural isn't
    /// set up properly.  You can override it to silence the errors.
    virtual void        errorMessage(const char *fmt, ...)
                                SYS_PRINTF_CHECK_ATTRIBUTE(2, 3);

    /// These functions are the ones that each procedural will override
    /// for doing preupdate/post update operations.
    virtual void    doBeginUpdate() = 0;
    virtual void    doEndUpdate() = 0;

    /// Check to see whether the procedural is valid
    virtual bool    checkIsValid() const = 0;

    /// These methods will be used by the implementing classes to set
    /// parameters that the procedural will support
    virtual void    doSetParameter(const UT_StringRef& key,
                                const int32* values, int n = 1) = 0;
    virtual void    doSetParameter(const UT_StringRef& key,
                                const int64* values, int n = 1) = 0;
    virtual void    doSetParameter(const UT_StringRef& key,
                                const fpreal32* values, int n = 1) = 0;
    virtual void    doSetParameter(const UT_StringRef& key,
                                const fpreal64* value, int n = 1) = 0;
    virtual void    doSetParameter(const UT_StringRef& key,
                                const UT_StringHolder* value, int n = 1) = 0;

private:
    const BRAY_ProceduralFactory        *myFactory;
};

#endif