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_Procedural;
class VRAY_ProceduralArg;
class VRAY_Volume;

//
// When the 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 dynamic object.  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:
//      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; }
// Arguments can then be queried using the argValue() methods in the procedural
//
extern "C" {
    DLLEXPORT extern VRAY_Procedural *allocProcedural(const char *name);
    DLLEXPORT extern const VRAY_ProceduralArg *getProceduralArgs(const char *n);
}

//
// 
class VRAY_API VRAY_ProceduralArg {
public:
    //
    // name  := The name of the parameter
    // type  := The storage type of the parameter.  This may be one of
    //          "int"    = Integer
    //          "real"   = Floating point (fpreal) value
    //          "string" = String value
    // value := A string representing the default values for the argument
    //          For int and real types, the string is tokenized, and the number
    //          of tokens in the string determines the vector size of the
    //          argument.  For example:
    //                  VRAY_ProceduralArg("a", "int", "1 2 3 4")
    //          Would specify a parameter named "a" which consists of 4
    //          integers with a default value of {1, 2, 3, 4}.
    //          For string types, the vector size is always defined as 1 and
    //          the string is used verbatim as the default.
    //          
    VRAY_ProceduralArg(const char *name=0, const char *type=0,
                        const char *value=0)
    {
         myName = name;
         myType = type;
         myValue = value;
    }
    ~VRAY_ProceduralArg()
    {
    }

    const char  *getName() const        { return myName; }
    const char  *getType() const        { return myType; }
    const char  *getValue() const       { return myValue; }

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

//
// The ProcInstance class is used by the Procedural class to allow the
// Procedural to contain multiple geometry details.
//
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 a null pointer.
    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;

    //
    // 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 2.0E6.  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.
    int                   lookupParmToken(const char *name);
    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.
    // For example, 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, fpreal *value, int vectorsize);
    bool          import(const char *name, UT_String &result, int idx=0);

    // Or, if you've opened an object handle using queryObject(), it's possible
    // to query the settings of that object.
    bool          import(void *handle, const char *name, int *value,
                                        int vectorsize);
    bool          import(void *handle, const char *name, fpreal *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();

    // The freeGeometry() method should probably never be called since the
    // geometry created by the procedural is usually passed off.  However, it
    // is provided for completeness.
    void                 freeGeometry(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 basically 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 objects is:
    //     a)   open a geometry object
    //          add geometry to the object
    //          modify flags on the geometry
    //          modify any settings (changeSetting())
    //          close the object
    //
    //     b)   open a procedural object
    //          add procedurals to the object
    //          modify any settings (changeSetting())
    //          close the object
    //
    // By writing multiple geometries to the object, deformation blur can be
    // accomplished.  There are two ways that deformation blur can be
    // implemented in a procedural.  There can be a single procedural entity
    // which generates multiple geometry entities, or there can be multiple
    // procedural entities which generate a single geometry each.
    //
    // 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 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 BEFORE the addGeometry() call is made.
    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:
    //          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;
    // Then, during the rendering process:
    //          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);
    //
    // 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();
    void         addProcedural(VRAY_Procedural *proc);
    // When passing argc/argv, the initialize method will be called on the
    // procedural.  The method returns 0 if there was an error on the
    // procedural, 1 on success.
    int          addProcedural(int argc, char *argv[],
                                const UT_BoundingBox *box=0);

    // Add primitive volumes.
    void         openVolumeObject();
    void         addVolume(VRAY_Volume *volume, fpreal shutter);

    //
    // The following functions will set attributes of the object currently
    // open.
    //
    // Transform the geometry/procedural at the shutter time specified.
    void         setTransform(const UT_Matrix4 &transform, fpreal shutter);

    //
    // Change any setting on the object (geometry or procedural)
    //   * changeSetting(const char *name, const char *value)
    //          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);
    //  * changeSetting(const char *name, int argc, char **argv)
    //  * changeSetting(const char *name, int argc, int *argv)
    //  * changeSetting(const char *name, int argc, fpreal *argv)
    // 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 three methods are for backwards compatibility and are
    // simply wrappers around changeSettings().
    void        setSurface(const char *shader, fpreal =0)
                    { changeSetting("surface", shader, "object"); }
    void        setDisplacement(const char *shader, fpreal =0)
                    { changeSetting("displace", shader, "object"); }
    void        setDisplacementBounds(fpreal bounds)
                    { changeSetting("displacebound", 1, &bounds, "object"); }

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

    // After all geometry/procedurals 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.
    //

    // Find out how many transforms are associated with the object.  For
    // transformation blurred geometry, there will be more than one sample.
    int                  queryTransformSamples(void *object_handle);
    const UT_Matrix4    &queryTransform(void *object_handle, int sample);
    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))
    const char          *queryObjectName(void *handle);

    // Get the name of our root object.
    const char          *queryRootName();

    // Find out how many geometry samples associated with the object.  For
    // deformation blurred geometry, there will be more than one sample.
    int                  queryGeometrySamples(void *object_handle);
    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).
    void        querySurfaceShader(void *handle, UT_String &shader)
                {
                     if (!import(handle, "object:surface", shader, 0))
                         shader = 0;
                }
    void        queryDisplacementShader(void *handle, UT_String &shader)
                {
                    import(handle, "object:displace", shader, 0);
                         shader = 0;
                }
    fpreal      queryDisplacementBounds(void *handle)
                {
                    fpreal      dbound;
                    if (!import(handle, "object:displacebound",
                                    &dbound, 1))
                        dbound = 0;
                    return dbound;
                }
    int         queryPhantom(void *handle)
                {
                    int         phantom;
                    if (!import(handle, "object:phantom", &phantom, 1))
                        phantom = 0;
                    return phantom;
                }
    int         queryReflectBounce(void *handle)
                {
                    int         bounce;
                    if (!import(handle, "object:reflectbounce", &bounce, 1))
                        bounce = 0;
                    return bounce;
                }
    int         queryRefractBounce(void *handle)
                {
                    int         bounce;
                    if (!import(handle, "object:refractbounce", &bounce, 1))
                        bounce = 0;
                    return bounce;
                }
    void        queryReflectScope(void *handle, UT_String &mask)
                {
                     if (!import(handle, "object:reflectmask", mask, 0))
                         mask = 0;
                }
    void        queryRefractScope(void *handle, UT_String &mask)
                {
                     if (!import(handle, "object:refractmask", mask, 0))
                         mask = 0;
                }

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

#endif

---