VRAY/VRAY_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.
 *
 * Produced by:
 *      Mark Elendt
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        VRAY_Procedural.h ( VRAY Library, C++)
 *
 * COMMENTS:    VRAY Procedural Primitive
 *
 *      This primitive is used to generate procedural geometry during the
 *      rendering process.
 *
 *      The procedural primitive can generate further procedural primitives, or
 *      as a leaf node, generate a GU_Detail.
 *
 *      Shaders for the geometry are inherited from the instance of the detail
 *      unless additional shaders are specified using the vm_surface or
 *      vm_displace attributes.
 */

#ifndef __VRAY_Procedural__
#define __VRAY_Procedural__

#include "VRAY_API.h"
#include <SYS/SYS_Types.h>
#include <UT/UT_Matrix4.h>
#include <UT/UT_String.h>

class UT_BoundingBox;
class GU_Detail;
class vray_ProcInstance;
class VRAY_Procedural;
class VRAY_ProceduralArg;
class VGEO_Volume;

/// @brief Mantra procedural primitives
///
/// When a procedural is defined as a dynamic object, the allocProcedural()
/// function is called to build a new instance of the procedural.  The name
/// passed in will be the name defined by the table entry.  This can be used
/// for:
///     a)  Error checking -- you can verify that you're name is what you
///             expect.  However, this isn't manditory.
///     b)  To have more than one procedural defined per C++ class.  Using
///             the name, you can create procedurals of different types.
///
/// The argument list for the procedural is specified by a list of arguments.
/// The getProceduralArgs() method should return a pointer to an array of
/// VRAY_ProceduralArg's.  The list should be terminated by an entry with
/// default arguments (i.e. null pointers).  For example:
/// Arguments can then be queried using the argValue() methods in the procedural
///
extern "C" {
    /// Dynamic load entry point to create an instance
    SYS_VISIBILITY_EXPORT extern VRAY_Procedural *allocProcedural(const char *name);
    /// Dynamic load entry point to query arguments for a procedural
    SYS_VISIBILITY_EXPORT extern const VRAY_ProceduralArg *getProceduralArgs(const char *n);
}

/// @brief Parameter definition for arguments to VRAY_Procedural
/// 
/// Each VRAY_Procedural has its arguments defined by a table of
/// VRAY_ProceduralArg objects.  The procedural can query the value of these
/// parameters using VRAY_Procedural::import() at run time (without having to
/// parse argument lists).  The list of arguments should be terminated by an
/// entry constructed with default arguments. For example:
/// @code
///     static VRAY_ProceduralArg       theArgs[] = {
///        VRAY_ProceduralArg("intarg",         "int",          "0" },
///        VRAY_ProceduralArg("realarg",        "real",         "3.1415" },
///        VRAY_ProceduralArg("stringarg",      "string",       "foo bar" },
///        VRAY_ProceduralArg("vectorarg",      "real",         "1 2 3" },
///        VRAY_ProceduralArg()
///     }
///     const VRAY_ProceduralArg *getProceduralArgs() { return theArgs; }
/// @endcode
class VRAY_API VRAY_ProceduralArg {
public:
    /// @param name @n The name of the parameter (must be unique)
    /// @param type @n
    /// The storage type of the parameter.  This should be one of
    ///    - @c int = Integer
    ///    - @c real = Floating point (fpreal) value
    ///    - @c string = String value
    /// @param value @n A @b string representing the default values for the
    ///    argument.  For @c int and @c real types, the string is tokenized and
    ///    the number of tokens in the trin determines the vector/tuple size of
    ///    the argument.  For example @code
    ///      VRAY_ProceduralArg("a", "int", "1 2 3 4")
    ///    @endcode
    ///    would specify a parameter named "a" which consists of 4 integers,
    ///    and has a default value of {1,2,3,4}. @n
    ///    For string types, the vector size is always 1, and the string is
    ///    used as the default value.
    ///
    /// @warning The procedural keeps shallow references to the
    ///   <tt>const char *</tt> passed in.
    VRAY_ProceduralArg(const char *name=0, const char *type=0,
                        const char *value=0)
    {
         myName = name;
         myType = type;
         myValue = value;
    }
    ~VRAY_ProceduralArg()
    {
    }

    /// Return the name of the argument
    const char  *getName() const        { return myName; }
    /// Return the storage type of the argument
    const char  *getType() const        { return myType; }
    /// Return the default value
    const char  *getValue() const       { return myValue; }

private:
    const char  *myName;
    const char  *myType;
    const char  *myValue;
};

/// @brief Procedural primitive for mantra (VRAY)
///
/// The VRAY_Procedural class provides a means to create procedural geometry
/// during the rendering process.
class VRAY_API VRAY_Procedural {
public:
             VRAY_Procedural();
    virtual ~VRAY_Procedural();

    /// The class name is used in diagnostic messages.  It can simply be the
    /// name of the class, or alternatively, you can choose a unique name for
    /// each procedural instance.
    virtual const char  *getClassName() = 0;

    /// The initialize method is called when the procedural is created.
    /// Returning zero (failure) will abort the rendering of this procedural.
    ///
    /// The bounding box passed in is the user defined bounding box.  If the
    /// user didn't specify a bounding box, then the box will be NULL.
    virtual int          initialize(const UT_BoundingBox *box) = 0;

    /// The bounding box is the "object space" bounds of the procedural.
    virtual void         getBoundingBox(UT_BoundingBox &box) = 0;

    /// Returns true when the render() method of this procedural is
    /// thread-safe - that is, the render() method on different
    /// VRAY_Procedural objects can be called simultaneously by different
    /// threads.  By default, procedurals are assumed to thread unsafe.
    virtual bool         isThreadSafe() const   { return false; }

    /// The render method is called when the procedural is required to either
    /// generate geometry or split into more procedurals.  The level of detail
    /// passed in represents the rough screen space projection of the
    /// procedural's bounding box.  The value is roughly the number of pixels
    /// that the bounding box occupies (modified by the LEVEL OF DETAIL rate).
    ///
    /// For example, if a box occupies 10 horizontal pixels and 20 vertical
    /// pixels, the lod passed in will be roughly 20 (the maximum bounds
    /// occupied in screen space).  If the object surrounds the camera, the lod
    /// will be clamped at a large number.
    /// @note The render method may be called more than once during a render to
    /// regenerate the geometry.
    virtual void         render() = 0;

    /// The getParm() methods evaluate parameters attached to the procedural.
    /// The lookup may be performed by name or by token.  Each parameter has a
    /// unique token associated with it.  The token lookup methods are more
    /// efficient than the name lookups and should be almost as efficient as
    /// accessing member data.

    /// Parameters to the procedural are stored as a list of VRAY_ProceduralArg
    /// objects.  Each parameter is given a unique integer.  This allows for
    /// more efficient evaluation (avoiding comparing strings).
    int                   lookupParmToken(const char *name);

    /// @{
    /// Get the raw data pointers for a parameter by either name or value.
    /// @see import()
    ///
    const int            *getIParm(const char *name) const;
    const fpreal         *getFParm(const char *name) const;
    const char          **getSParm(const char *name) const;
    const int            *getIParm(int token) const;
    const fpreal         *getFParm(int token) const;
    const char          **getSParm(int token) const;
    /// @}

    /// @{
    /// The import functions can be used as a general purpose query mechanism.
    /// This will import values from:
    /// - The argument list for the procedural
    /// - The argument list for the object defining the procedural
    /// - A global rendering setting.
    /// Aside from a parameter name, the name could be "object:name",
    /// "object:shadingquality", "camera:pixelaspect", or any of the other
    /// setting defined in mantra.
    bool         import(const char *name, int *value, int vectorsize);
    bool         import(const char *name, fpreal32 *value, int vectorsize);
    bool         import(const char *name, fpreal64 *value, int vectorsize);
    bool         import(const char *name, UT_String &result, int idx=0);
    /// @}

    /// @{
    /// If you've opened an object handle using queryObject(), it's possible
    /// to query the settings of that object.  This makes it possible to query
    /// the parameters/values/settings of other objects in the scene.
    bool          import(void *handle, const char *name, int *value,
                                        int vectorsize);
    bool          import(void *handle, const char *name, fpreal32 *value,
                                        int vectorsize);
    bool          import(void *handle, const char *name, fpreal64 *value,
                                        int vectorsize);
    bool          import(void *handle, const char *name, UT_String &result,
                                        int idx = 0);
    /// @}

protected:
    /// @warning
    ///
    /// Mantra uses a sub-class of GU_Detail.  It is imperative that all
    /// geometry to be rendered be allocated and free'd using the following
    /// methods.  Otherwise, crashes will ensue.
    GU_Detail           *allocateGeometry();

    /// Normally freeGeometry() should never be called since you'll usually
    /// use allocateGeometry() to create a new geometry that is later
    /// passed off to the procedural using addGeometry().  However, if you
    /// need to keep a reference to the geometry using referenceGeometry()
    /// it is possible to free or clear the reference using freeGeometry().
    /// freeGeometry() may also be used to deallocate geometry that was
    /// never passed off with addGeometry().
    void                 freeGeometry(GU_Detail *gdp);

    /// This method allows a single geometry object to be added multiple
    /// times with addGeometry().  For each addGeometry() operation, first
    /// call referenceGeometry() to allow the caller to keep a reference to
    /// the geometry, then use freeGeometry() to release the referenced
    /// geometry when you're done with it.  For example:
    /// @code
    ///         GU_Detail       *gdp;
    ///         // Allocate the geometry
    ///         gdp = allocateGeometry();
    ///         // Create 2 instances of the geometry.  Normally these
    ///         // should be created with differing transforms.
    ///         referenceGeometry(gdp);
    ///         addGeometry(gdp);
    ///         referenceGeometry(gdp);
    ///         addGeometry(gdp);
    ///         // Unreference the local copy
    ///         freeGeometry(gdp);
    /// @endcode
    void                 referenceGeometry(GU_Detail *gdp);

    // The following methods are now obsolete.  The settings/flags should be
    // set by calling changeSetting()
    //  - setGeometryFlag()
    //  - copyGeometryFlags()

    /// This method allows you to compute the level of detail of an arbitrary
    /// bounding box.  The shading_quality parameter is a multiplier on the
    /// computed level of detail.  Higher shading_qalities will result in
    /// higher level of details.
    fpreal               getLevelOfDetail(const UT_BoundingBox &box);

    /// When the render method is called, the procedural can add objects to
    /// the scene.  It is possible for the render() method to add multiple
    /// objects.
    ///
    /// The process for adding a geometry object: 
    ///  - open a geometry object (openGeometryObject())
    ///  - add geometry to the object (addGeometry())
    ///  - modify any settings (changeSetting())
    ///  - close the object (closeObject())
    ///
    /// The process for adding a new procedural is fairly similar:
    ///  - open a procedural object (openProcecuralObject())
    ///  - add procedural(s) to the object (addProcedural())
    ///  - modify any settings (changeSetting())
    ///  - close the object (closeObject())
    ///
    /// For a geometry object, deformation motion blur is done by adding
    /// multiple geometry objects.
    ///
    /// If settings are not overridden by the procedural, they will be
    /// inherited from the object defining the procedural.
    ///
    /// The shutter time should be between 0 and 1.
    ///
    /// The renderer assumes ownership of any geometry or procedurals written
    /// to objects.  Thus, the geometry and procedurals should not be free'd
    /// by the user.
    void         openGeometryObject();

    /// Before adding the geometry, you can change @b geometry settings by
    /// calling changeSettings().  For example, if you want to force
    /// computation of N, you can call:
    ///         changeSetting("computeN", "true", "geometry");
    /// This needs to be done @b BEFORE the addGeometry() call is made.
    /// Object settings can be changed after the geometry has been added.
    void         addGeometry(GU_Detail *gdp, fpreal shutter);

    /// If you want to perform velocity motion blur on the geometry, you can add
    /// all the detail at once, calling this convenience function.
    /// Note:  The "shutter" is really a scale on the velocity.  However, since
    /// velocity is typically specified in units/second, you usually need to
    /// scale by the shutter time of the frame.  To do this, you should multiply
    /// by the "object:velocityscale" property of the object.
    ///
    /// Assume that we have a procedural where the user can specify an
    /// individual shutter time in a parameter called "shutter".  Then, the
    /// initialization code might look something like:
    /// @code
    ///         float   shutter, vscale;
    ///         if (!import("shutter", &shutter, 1))
    ///                 shutter = 1;    // Default to full shutter
    ///         if (!import("object:velocityscale", &vscale, 1))
    ///         {
    ///                 // This should never happen since it's a property
    ///                 vscale = 0;
    ///         }
    ///         this->myShutter = shutter * vscale;
    /// @endcode
    /// Then, during the rendering process:
    /// @code
    ///         gdp = allocateGeometry();
    ///         createGeometry(gdp);    // Create the render geometry
    ///         addGeometry(gdp, 0);    // Add geometry for beginning of frame
    ///         // Add the motion blur geometry
    ///         addVelocityBlurGeometry(gdp, this->myShutter);
    /// @endcode
    ///
    /// The maximum velocity displacement is returned (so that bounding boxes
    /// may be computed).
    float        addVelocityBlurGeometry(GU_Detail *gdp, fpreal shutter,
                                const char *velocity_attribute="v");

    /// If the procedural has been split too many times, it will not be
    /// possible to generate further procedurals.  This can happen if the
    /// procedural is centered around the origin (i.e. cuts the camera
    /// clipping plane) and hasn't shrunk itself enough to isolate itself.
    int          openProceduralObject();
    /// Add a procedural to the opened procedural object.  Use this method when
    /// allocating a "private" procedural (i.e. a procedural object which isn't
    /// registered with mantra).
    /// @see openProceduralObject()
    void         addProcedural(VRAY_Procedural *proc);
    /// Add a procedural the the opened procedural object.  This method allows
    /// you to create any registered procedural by passing @c argc and @c argv
    /// arguments to initialize the procedural.
    /// @return 0 or 1 for failure/success
    /// @see openProceduralObject()
    int          addProcedural(int argc, char *argv[],
                                const UT_BoundingBox *box=0);

    /// Open a volume object
    void         openVolumeObject();
    /// Add a volume primitive to the currently open volume object
    void         addVolume(VGEO_Volume *volume, fpreal shutter);

    /// Transform the currently open object (geometry, procedural, volume) at
    /// the shutter time specified.
    void         setTransform(const UT_Matrix4 &transform, fpreal shutter);

    /// @{
    /// Change any setting on the object (geometry, procedural, volume)
    /// - <tt>changeSetting(const char *name, const char *value)</tt> @n
    ///   Parses the string into arguments and changes the setting If you want
    ///   to change a setting to a single string value, it is better to call:
    ///   changeSettings(name, 1, &value);
    /// - <tt>changeSetting(const char *name, int argc, char **argv)</tt>
    /// - <tt>changeSetting(const char *name, int argc, int *argv)</tt>
    /// - <tt>changeSetting(const char *name, int argc, fpreal *argv)</tt>
    /// If the setting specified by "name" isn't found, the function will fail
    /// (return false).
    bool         changeSetting(const char *name, const char *value,
                                const char *style = "object");
    bool         changeSetting(const char *name, int argc, char **argv,
                                const char *style = "object");
    bool         changeSetting(const char *name, int argc, const int *argv,
                                const char *style = "object");
    bool         changeSetting(const char *name, int argc, const fpreal *argv,
                                const char *style = "object");
    /// @}

    /// The following methods are for backwards compatibility and are
    /// simply wrappers around changeSettings().
    /// @private
    void        setSurface(const char *shader, fpreal =0)
                    { changeSetting("surface", shader, "object"); }
    /// @private
    void        setDisplacement(const char *shader, fpreal =0)
                    { changeSetting("displace", shader, "object"); }
    /// @private
    void        setDisplacementBounds(fpreal bounds)
                    { changeSetting("displacebound", 1, &bounds, "object"); }

    /// @private
    void        setComputeN(int value)
                    { changeSetting("computeN", 1, &value, "geometry"); }

    /// After all geometry, procedurals, volumes have been added and all the
    /// attributes have been set, the object can be closed.
    void         closeObject();

protected:
    /// It is possible to query information about other objects in the scene to
    /// some extent.  This is done using the following query methods.

    /// Find a handle to a given object in the scene.  Note that for objects
    /// which are rendered using point instances, the object handle will be a
    /// single instance rather than all of the instances.
    /// If a null pointer is passed in for the name, then the object refers to
    /// the object containing this procedural.  The object handle does not need
    /// to be closed.
    void        *queryObject(const char *name);

    //
    // Given an object handle, it is now possible to query information about
    // the object.
    //

    /// Query the number of transform samples for a given query object
    /// @see queryObject()
    int                  queryTransformSamples(void *object_handle);
    /// Get the transform associated with an object in the scene
    /// @see queryObject()
    const UT_Matrix4    &queryTransform(void *object_handle, int sample);
    /// Get the shading transform associated with an object in the scene
    /// @see queryObject()
    const UT_Matrix4    &queryShaderTransform(void *object_handle, int sample);

    /// Find out the name of the object queried.  This is useful when trying to
    /// find out which object the procedural belongs to (i.e. queryObject(0))
    /// @see queryObject()
    const char          *queryObjectName(void *handle);

    /// Get the name of the object which owns this procedural.
    const char          *queryRootName();

    /// Find out how many geometry samples associated with the object.
    /// @see queryObject()
    int                  queryGeometrySamples(void *object_handle);
    /// Get the geometry from another object
    /// @see queryObject()
    const GU_Detail     *queryGeometry(void *object_handle, int sample);

    /// Find out shader information about the object.  This information is only
    /// roughly accurate since the object shaders may be overridden by geometry
    /// attributes.  The shader information returned is the object level
    /// shaders.  The shaders returned are simply the setting bound at the
    /// instance level (including arguments).
    /// @private: Use import()
    void        querySurfaceShader(void *handle, UT_String &shader)
                {
                     if (!import(handle, "object:surface", shader, 0))
                         shader = 0;
                }
    /// @private: Use import()
    void        queryDisplacementShader(void *handle, UT_String &shader)
                {
                    import(handle, "object:displace", shader, 0);
                         shader = 0;
                }
    /// @private: Use import()
    fpreal      queryDisplacementBounds(void *handle)
                {
                    fpreal      dbound;
                    if (!import(handle, "object:displacebound",
                                    &dbound, 1))
                        dbound = 0;
                    return dbound;
                }
    /// @private: Use import()
    int         queryPhantom(void *handle)
                {
                    int         phantom;
                    if (!import(handle, "object:phantom", &phantom, 1))
                        phantom = 0;
                    return phantom;
                }
    /// @private: Use import()
    int         queryReflectBounce(void *handle)
                {
                    int         bounce;
                    if (!import(handle, "object:reflectbounce", &bounce, 1))
                        bounce = 0;
                    return bounce;
                }
    /// @private: Use import()
    int         queryRefractBounce(void *handle)
                {
                    int         bounce;
                    if (!import(handle, "object:refractbounce", &bounce, 1))
                        bounce = 0;
                    return bounce;
                }
    /// @private: Use import()
    void        queryReflectScope(void *handle, UT_String &mask)
                {
                     if (!import(handle, "object:reflectmask", mask, 0))
                         mask = 0;
                }
    /// @private: Use import()
    void        queryRefractScope(void *handle, UT_String &mask)
                {
                     if (!import(handle, "object:refractmask", mask, 0))
                         mask = 0;
                }

private:
    void                *myObject, *myRoot;
    void                *myArguments;
    void                *myGeoSettings;
    vray_ProcInstance   *myHandle;
    friend class         VRAY_Instance;
    friend class         VRAY_Scene;
    friend class         VRAY_ProcDef;
};

#endif

---