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

#ifndef __BRAY_Interface__
#define __BRAY_Interface__

#include "BRAY_API.h"
#include <UT/UT_Array.h>
#include <UT/UT_StringHolder.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_StringMap.h>
#include <UT/UT_NonCopyable.h>
#include <UT/UT_Options.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_IntrusivePtr.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_Rect.h>
#include <UT/UT_Set.h>
#include <UT/UT_Map.h>
#include <UT/UT_VectorTypes.h>
#include <GT/GT_Handles.h>
#include <GT/GT_DataArray.h>
#include <PXL/PXL_Common.h>
#include "BRAY_Types.h"
#include "BRAY_Stats.h"

// Classes referenced by the interface
class BRAY_Procedural;
class BRAY_ProceduralFactory;
class BRAY_AOVBuffer;
class BRAY_Camera;
class BRAY_Object;
class BRAY_Renderer;
class BRAY_Light;
class BRAY_Scene;
class BRAY_ShaderGraph;
class BRAY_ShaderInstance;
class BRAY_VexMaterial;
class VPRM_Space;
class VPRM_OptionSet;
class UT_JSONWriter;
class UT_JSONValue;

using VPRM_OptionSetPtr = UT_IntrusivePtr<VPRM_OptionSet>;
using VPRM_SpacePtr = UT_IntrusivePtr<VPRM_Space>;

namespace BRAY
{

class InstancablePtr;
class CameraPtr;
class CoordSysPtr;
class LightPtr;
class LightInstancer;
class LightInstancerPtr;
class MaterialPtr;
class ObjectPtr;
class RendererPtr;
class ScenePtr;
class ShaderGraphPtr;

class BRAY_API SpacePtr
{
public:
    enum class MBStyle
    {
        MB_LINEAR,
        MB_ROTATE,
    };
    SpacePtr();
    SpacePtr(const VPRM_SpacePtr &s);
    SpacePtr(const SpacePtr &s);
    SpacePtr(const UT_Matrix4D &xforms);
    SpacePtr(const UT_Matrix4D *xforms, size_t num_motion_segments,
                        MBStyle style);
    ~SpacePtr();
    SpacePtr    &operator=(const SpacePtr &s);

    /// @{
    /// Private access
    bool                isValid() const { return mySpace.get() != nullptr; }
    VPRM_SpacePtr       &space() { return mySpace; }
    const VPRM_SpacePtr &space() const { return mySpace; }
    /// @}
    /// Bool operator to test validity of pointer
    explicit            operator bool() const { return isValid(); }

    /// Multiply by the given space (i.e. this * sp)
    SpacePtr            mulSpace(const SpacePtr &sp) const;

    /// Return the number of motion segments
    int         motionSegments() const;
    UT_Matrix4D getTransform(int segment) const;
    void        getTransform(UT_Matrix4D &x, BRAYtime shutter) const;
    void        dump() const;
    void        dump(UT_JSONWriter &w) const;
private:
    VPRM_SpacePtr       mySpace;
};

/// The OptionSet acts as a pointer to an underlying set of options for various
/// different object types.
class BRAY_API OptionSet
{
public:
    OptionSet();
    /// The copy c-tor will copy the underlying pointer, but refer to the same
    /// underlying object.
    OptionSet(const OptionSet &src);
    explicit OptionSet(const VPRM_OptionSetPtr &o);
    ~OptionSet();

    /// The assignment operator will change the pointer to the underlying
    /// object.  Both OptionSets will point to the same underlying object.
    OptionSet   &operator=(const OptionSet &o);

    /// This will create a new OptionSet, inheriting state information from the
    /// this option set.  Note that changing values in the this set @b may
    /// result in unexpected changes in the new option set.
    OptionSet   duplicate() const;

    /// Returns true if property can be erased to revert back to default value.
    /// If the options aren't inherited (i.e. offline render), it cannot be
    /// erased.
    bool        canErase(int token) const;

    /// Erase properties
    void        erase(const UT_Set<int> &tokens);

    /// @{
    /// Private access
    bool                isValid() const { return myOptions.get() != nullptr; }
    VPRM_OptionSetPtr           &options() { return myOptions; }
    const VPRM_OptionSetPtr     &options() const { return myOptions; }
    /// @}
    /// Bool operator to test validity of pointer
    explicit            operator bool() const { return isValid(); }

    /// Return the number of pre-defined properties in the option set
    exint               numProperties() const;

    /// Return the name associated with a given option (i.e. dicingquality)
    const UT_StringHolder       &name(int token) const;

    /// Return the fully qualified name (i.e. karma::object::dicingquality)
    UT_StringHolder             fullName(int token) const;

    /// Return the token associated with a given name (or -1 if invalid)
    int                          find(const UT_StringRef &name) const;

    /// Import a property value.  Method is specialized for T in:
    /// - bool
    /// - int32/int64
    /// - fpreal32/fpreal64
    /// - UT_StringHolder
    template <typename T>
    const T     *import(int token, T *val, size_t n) const;

    /// Interface to set an property.  This template class is specialized for:
    /// - bool
    /// - int32
    /// - int64
    /// - fpreal32
    /// - fpreal64
    /// - UT_StringHolder
    template <typename T>
    bool        set(int token, const T *value, exint tuple_size);

    /// Simple interface to set a scalar property
    template <typename T>
    SYS_FORCE_INLINE bool set(int token, const T &value)
    {
        return set(token, &value, 1);
    }

    /// Test whether a value is the same as the current property
    template <typename T>
    bool        isEqual(int token, const T *value, exint tuple_size) const;

    /// Simple interface for equality of a scalar value.
    template <typename T>
    SYS_FORCE_INLINE bool       isEqual(int token, const T &value) const
    {
        return isEqual(token, &value, 1);
    }

    /// Test whether an option has variadic arguments
    bool        isVariadic(int token) const;

    /// Return the size of an option.  This can be used for variadics
    exint       size(int token) const;

    /// Return the storage of an option.  This will only be one of:
    /// - GT_STORE_INVALID
    /// - GT_STORE_UINT8 (for bool storage)
    /// - GT_STORE_INT64
    /// - GT_STORE_REAL64
    /// - GT_STORE_STRING
    GT_Storage  storage(int token) const;

    /// @{
    /// Direct access to internal option data.  There are no checks on these
    /// methods
    const bool                  *bval(int token) const;
    const int64                 *ival(int token) const;
    const fpreal64              *fval(int token) const;
    const UT_StringHolder       *sval(int token) const;
    /// @}

    /// @private Debug the options (only available in debug builds)
    void        dump(UT_JSONWriter &w) const;

private:
    VPRM_OptionSetPtr   myOptions;
};

/// When defining materials for face sets, the material specification is
/// given by a pair of the @c MaterialPtr and an array of integers.  The
/// integers specify the list of faces to material and must appear in
/// sorted order (smallest to largest).
/// Interface to the scene manager
class BRAY_API ScenePtr
{
public:
    ScenePtr() = default;
    ~ScenePtr();

    /// Allocate a new scene
    static ScenePtr     allocScene();

    /// Force an exit when there's a failed license check failure.  The normal
    /// behaviour is to render a black image.
    static void         setExitOnFailedLicense(bool state=true);

    /// Check to see whether a rendering engine is supported
    static bool         isEngineSupported(const UT_StringRef &name);

    /// convenience methods to determine which renderer is active (tests
    /// the value of the BRAY_OPT_DELEGATE option)
    bool        isKarmaCPU() const;
    bool        isKarmaXPU() const;

    /// Start edits/loading of the scene
    void        startEdits(BRAY::RendererPtr &renderer);

    /// Test validity
    bool        isValid() const { return myScene.get() != nullptr; }

    /// Test whether the scene is thread-safe
    bool        threadSafe() const;

    /// Test whether the renderer supports nested instancing
    bool        nestedInstancing() const;

    /// Update an object in the scene
    void        updateObject(const ObjectPtr &ptr, BRAY_EventType event);

    /// Update light object in the scene
    void        updateLight(const LightPtr &ptr, BRAY_EventType event);

    /// Update camera object in the scene
    void        updateCamera(const CameraPtr &ptr, BRAY_EventType event);

    /// Update material object in the scene
    void        updateMaterial(const MaterialPtr &ptr, BRAY_EventType event);

    /// Update coord sys object
    void        updateCoordSys(const CoordSysPtr &ptr, BRAY_EventType event);

    /// @{
    /// Set the unit scale for the scene - this is in meters/unit.  For
    /// example, centimeters would be 0.01.
    void        setSceneUnits(fpreal64 units);
    fpreal64    sceneUnits() const;
    /// @}

    /// Forcibly save checkpoint as soon as possible (if checkpointing is enabled)
    void        saveCheckpointASAP();

    /// Set camera ray visibility.  The mask should be a combination of
    ///   - BRAY_RAY_CAMERA
    ///   - BRAY_PROXY_CAMERA
    ///   - BRAY_GUIDE_CAMERA
    /// For example, (BRAY_RAY_CAMERA|BRAY_GUIDE_CAMERA) will cause guide and
    /// renderable object to be visible to camera rays, but not proxy objects
    void        setCameraRayMask(BRAY_RayVisibility mask);

    /// Set shadow ray visibility.  The mask should be a combination of
    ///   - BRAY_RAY_SHADOW
    ///   - BRAY_PROXY_SHADOW
    ///   - BRAY_GUIDE_SHADOW
    /// For example, (BRAY_RAY_SHADOW|BRAY_PROXY_SHADOW) will cause proxy and
    /// renderable object to cast shadows, but not GUIDE objects.
    void        setShadowRayMask(BRAY_RayVisibility mask);

    /// Force redicing of displacement and subd surfaces on the next render.
    /// This will only take effect on the next call to beginRender().
    void        forceRedice();

    /// @{
    /// Private access to the underling scene
    explicit             operator bool() const { return isValid(); }
    const BRAY_Scene    *scenePtr() const { return myScene.get(); }
    BRAY_Scene          *scenePtr() { return myScene.get(); }
    /// @}

    /// After changing any options, must commit prior to rendering
    void        commitOptions();

    /// @{
    /// Grab a copy of the current scene options
    OptionSet           sceneOptions();
    const OptionSet     constSceneOptions() const;
    /// @}

    /// @{
    /// Grab a copy of the current object properties.
    OptionSet           objectProperties();
    const OptionSet     constObjectProperties() const;
    /// @}

    /// @{
    /// Grab a copy of the current light properties
    OptionSet           lightProperties();
    const OptionSet     constLightProperties() const;

    /// @{
    /// Grab a copy of the current camera properties
    OptionSet           cameraProperties();
    const OptionSet     constCameraProperties() const;
    /// @}

    /// Grab a copy of the current image plane properties
    OptionSet           planeProperties();
    const OptionSet     constPlaneProperties() const;
    /// @}

    /// Grab a the default properties for a given type.  Changing their values
    /// will cause all future objects created to inherit the new values.
    OptionSet   defaultProperties(BRAY_PropertyType type) const;

    /// @{
    /// Convenience methods to look up scene and scene options.
    /// Get an scene option value.
    template <typename T>
    SYS_FORCE_INLINE const T    *optionImport(BRAY_SceneOption token,
                                        T *val, size_t n) const
    {
        return constSceneOptions().import(token, val, n);
    }

    /// Interface to set an option.  This template class is specialized for:
    template <typename T>
    SYS_FORCE_INLINE bool       setOption(BRAY_SceneOption token,
                                        const T *value,
                                        exint tuple_size)
    {
        return sceneOptions().set(token, value, tuple_size);
    }

    /// Simple interface to set a scalar option
    template <typename T>
    SYS_FORCE_INLINE bool
    setOption(BRAY_SceneOption token, const T &value)
    {
        return setOption(token, &value, 1);
    }

    /// Return the size of an option.  This can be used for variadics
    /// (e.g. shading quality will be 1)
    SYS_FORCE_INLINE exint      optionSize(BRAY_SceneOption token) const
    {
        return constSceneOptions().size(token);
    }

    /// Return the storage class of an option.
    SYS_FORCE_INLINE GT_Storage
    optionStorage(BRAY_SceneOption token) const
    {
        return constSceneOptions().storage(token);
    }

    /// Return whether an option has variadic arguments
    SYS_FORCE_INLINE bool
    optionIsVariadic(BRAY_SceneOption token) const
    {
        return constSceneOptions().isVariadic(token);
    }
    bool                optionB(BRAY_SceneOption t) const
                                { return *constSceneOptions().bval(t); }
    int64               optionI(BRAY_SceneOption t) const
                                { return *constSceneOptions().ival(t); }
    fpreal64            optionF(BRAY_SceneOption t) const
                                { return *constSceneOptions().fval(t); }
    UT_StringHolder     optionS(BRAY_SceneOption t) const
                                { return *constSceneOptions().sval(t); }
    /// @}

    /// @{
    /// Convenience methods to look up object properties.
    /// Get an object property value.
    template <typename T>
    SYS_FORCE_INLINE const T    *propertyImport(BRAY_ObjectProperty token,
                                        T *val, size_t n) const
    {
        return constObjectProperties().import(token, val, n);
    }

    /// Interface to set an property.  This template class is specialized for:
    template <typename T>
    SYS_FORCE_INLINE bool       setProperty(BRAY_ObjectProperty token,
                                        const T *value,
                                        exint tuple_size)
    {
        return objectProperties().set(token, value, tuple_size);
    }

    /// Locking the object property prevents any overriding of the property
    /// after the fact, essentially turning the property into a read-only
    /// property.  This method is intended to lock default properties.  The
    /// current value of the property is used as the value.
    ///
    /// The return value is the previous lock state of the property.
    bool                lockProperty(BRAY_ObjectProperty token, bool state);

    /// Lock properties based on a string pattern of parameter names.  This
    /// method returns the number of properties modified.
    exint               lockProperties(const char *pattern, bool state);

    /// Lock or unlock all object properties.
    SYS_FORCE_INLINE exint      lockAllObjectProperties(bool state)
                                    { return lockProperties("*", state); }

    /// Simple interface to set a scalar property
    template <typename T>
    SYS_FORCE_INLINE bool
    setProperty(BRAY_ObjectProperty token, const T &value)
    {
        return setProperty(token, &value, 1);
    }

    /// Return the size of an option.  This can be used for variadics
    /// (e.g. shading quality will be 1)
    SYS_FORCE_INLINE exint      propertySize(BRAY_ObjectProperty token) const
    {
        return constObjectProperties().size(token);
    }

    /// Return the storage class of an option.
    SYS_FORCE_INLINE GT_Storage
    propertyStorage(BRAY_ObjectProperty token) const
    {
        return constObjectProperties().storage(token);
    }

    /// Return whether an property has variadic arguments
    SYS_FORCE_INLINE bool
    propertyIsVariadic(BRAY_ObjectProperty token) const
    {
        return constObjectProperties().isVariadic(token);
    }
    bool                propertyB(BRAY_SceneOption t) const
                                { return *constObjectProperties().bval(t); }
    int64               propertyI(BRAY_SceneOption t) const
                                { return *constObjectProperties().ival(t); }
    fpreal64            propertyF(BRAY_SceneOption t) const
                                { return *constObjectProperties().fval(t); }
    UT_StringHolder     propertyS(BRAY_SceneOption t) const
                                { return *constObjectProperties().sval(t); }
    /// @}

    /// Create a light
    LightPtr            createLight(const UT_StringHolder &name);

    /// Create a detached light, which is not added to the scene
    LightPtr            createDetachedLight(const UT_StringHolder &name);

    /// Create a camera
    CameraPtr           createCamera(const UT_StringHolder &name);

    /// Create a coordinate system
    CoordSysPtr         createCoordSys(const UT_StringHolder &name);

    /// Create a material
    MaterialPtr         createMaterial(const UT_StringHolder &name);

    /// Create an object given a GT_Primitive handle.
    /// At the current time, the only classes supported are:
    /// - GT_PrimPolygonMesh
    /// - GT_PrimSubdivisionMesh
    /// - GT_PrimCurveMesh
    /// - GT_PrimPointMesh
    /// The method will return a nullptr if it can't create a primitive
    ObjectPtr   createGeometry(const GT_PrimitiveHandle &prim);

    /// For polygonal meshes, use this to create geometry to handle holes
    ObjectPtr   createGeometry(const GT_PrimitiveHandle &prim,
                                const GT_DataArrayHandle &holes);

    /// Create a volume given its detail attribute and the names and
    /// GT_PrimitiveHandles of the corresponding fields in the volume
    ObjectPtr   createVolume(const UT_StringHolder &name);

    /// Create an instance of an object (not a light)
    ObjectPtr   createInstance(const ObjectPtr &obj,
                                const UT_StringHolder &name);

    /// Create a nested scene graph
    ObjectPtr   createScene();

    /// Create a light instancer
    LightInstancerPtr   createLightInstancer(const UT_StringHolder &name);

    /// Create a procedural object.
    /// Ownership of the procedural is passed to the object.
    ObjectPtr   createProcedural(UT_UniquePtr<BRAY_Procedural> proc);

    /// Find a material.
    MaterialPtr         findMaterial(const UT_StringRef &name) const;

    /// Destroy/Delete a material (returns false if material wasn't found)
    bool                destroyMaterial(const UT_StringRef &name);

    /// Add traceset name to global list (categories on objects that do not
    /// belong to this list will be ignored)
    /// Returns true if added, false if already exists.
    bool                addTraceset(const UT_StringHolder &name);

    /// Check to see if a traceset exists.
    bool                isTraceset(const UT_StringHolder &name);

    /// Create a shader nodegraph
    ShaderGraphPtr      createShaderGraph(const UT_StringHolder &name);

    /// Load an HDA to define shader code.  Not all applications support this
    /// feature.
    bool        loadHDA(const char *path);

private:
    UT_SharedPtr<BRAY_Scene>    myScene;
};

/// Input connector for materials.  This defines the name of the geometry
/// attribute (@c myInputName) to bind to the VEX shader parameter (@c myParmName)
struct BRAY_API MaterialInput
{
    enum class Storage
    {
        FLOAT,
        INTEGER,
        STRING
    };
    MaterialInput(const UT_StringHolder &primvar,
            const UT_StringHolder &shader_parm,
            Storage store,
            int tsize,
            bool is_array)
        : myGeometry(primvar)
        , myParmName(shader_parm)
        , myStorage(store)
        , myTupleSize(tsize)
        , myIsArray(is_array)
    {
    }

    UT_StringHolder     myGeometry;     // Input name (primvar name)
    UT_StringHolder     myParmName;     // Parameter Name (VEX parameter name)
    Storage             myStorage;      // Base storage type
    int                 myTupleSize;    // Element tuple size
    bool                myIsArray;      // Whether parameter is an array
};

using MaterialInputList = UT_Array<MaterialInput>;

class BRAY_API PrimvarSet
    : UT_NonCopyable
{
public:
    PrimvarSet(const UT_Set<UT_StringHolder> *primvars)
        : myPrimvars(primvars)
    {
    }
    ~PrimvarSet() {}

    // Check if Karma can't pre-determine the primvars for a material
    bool                useAllPrimvars() const { return myPrimvars == nullptr; }

    // Check to see whether the primvar set is valid
    bool                isValid() const { return myPrimvars != nullptr; }
    explicit            operator bool() const { return isValid(); }

    // Return a list of all primvars used by a material
    const UT_Set<UT_StringHolder>       *primvars() const { return myPrimvars; }
private:
    const UT_Set<UT_StringHolder>       *myPrimvars;
};

/// Interface to scene materials
class BRAY_API MaterialPtr
{
public:
    MaterialPtr(BRAY_VexMaterial *mat = nullptr)
        : myMat(mat)
    {
    }
    ~MaterialPtr() {}

    bool        isValid() const { return myMat != nullptr; }
    explicit    operator bool() const { return isValid(); }

    /// Access to the underling material
    const BRAY_VexMaterial      *materialPtr() const { return myMat; }

    /// Update the surface shader and arguments
    void        updateSurface(const ScenePtr &scene,
                        const UT_StringArray &arguments);
    /// Update the displacement shader and arguments
    /// Returns true if arguments changed.
    bool        updateDisplace(ScenePtr &scene,
                        const UT_StringArray &arguments);
    /// Update the lens shader and arguments
    void        updateLens(const ScenePtr &scene,
                        const UT_StringArray &arguments);

    /// Update surface shader VEX code.  The @c preload flag is used when other
    /// shaders in the network might depend on the code being updated.
    void        updateSurfaceCode(const ScenePtr &scene,
                        const UT_StringHolder &name,
                        const UT_StringRef &code,
                        bool preload=false);
    /// Update displacement shader VEX code The @c preload flag is used when
    /// other shaders in the network might depend on the code being updated.
    /// Returns true if the name or the code changed.
    bool        updateDisplaceCode(const ScenePtr &scene,
                        const UT_StringHolder &name,
                        const UT_StringRef &code,
                        bool preload=false);
    /// Update surface shader VEX code.  The @c preload flag is used when other
    /// shaders in the network might depend on the code being updated.
    void        updateLensCode(const ScenePtr &scene,
                        const UT_StringHolder &name,
                        const UT_StringRef &code,
                        bool preload=false);

    /// Update the surface shader graph
    void        updateSurfaceGraph(const ScenePtr &scene,
                        const UT_StringHolder &name,
                        const ShaderGraphPtr &graphptr);
    /// Update the displacement shader graph
    /// Returns true if the name or the code changed.
    bool        updateDisplaceGraph(ScenePtr &scene,
                        const UT_StringHolder &name,
                        const ShaderGraphPtr &graphptr);
    /// Update the lens shader graph
    void        updateLensGraph(const ScenePtr &scene,
                        const UT_StringHolder &name,
                        const ShaderGraphPtr &graphptr);

    /// Set the material input list
    void        setInputs(const ScenePtr &scene,
                        const MaterialInputList &inputs,
                        bool for_surface);

    /// Set stable name to use with built-in cryptomatte material name layer.
    void        setNiceName(const UT_StringHolder &nicename);

    /// Return the primvars required by this material.  If a @c nullptr is
    /// returned, it means that Karma wasn't able to determine primvars and all
    /// primvars might be required.
    PrimvarSet           primvars() const;

    /// Return the primvars used by the default material
    static PrimvarSet   defaultPrimvars();

private:
    BRAY_VexMaterial    *myMat;
};

struct BRAY_API FacesetMaterial
{
    FacesetMaterial(const GT_DataArrayHandle &facelist = GT_DataArrayHandle(),
            const MaterialPtr &material = MaterialPtr())
        : myFaceList(facelist)
        , myMaterial(material)
    {
    }
    GT_DataArrayHandle  myFaceList;
    MaterialPtr         myMaterial;
};

enum class InstancableType
{
    Object,
    Light,
    LightInstancer,
};

/// Pure virtual class which can be either:
///     ObjectPtr
///     LightPtr
///     LightInstancerPtr
/// use isA and dyn_cast to find out the type
class BRAY_API InstancablePtr
{
public:
    InstancablePtr(InstancableType type)
        : myType(type)
    {
    }
    virtual ~InstancablePtr() = 0;

    InstancableType instancableType() const
    {
        return myType;
    }

private:
    InstancableType myType;
};

/// Casting operators inspired by LLVM:@n
/// isA<> checks the type of the object (but no nullptr check).
template <typename X> SYS_FORCE_INLINE bool
isA(const InstancablePtr *o)
{
    UT_ASSERT(o && "isA<> called with nullptr - use isAValid<>");
    return X::classof(o);
}

/// Casting operators inspired by LLVM:@n
/// isAValid<> checks the pointer is not a nullptr and is the given type.
template <typename X> SYS_FORCE_INLINE bool
isAValid(const InstancablePtr *o)
{
    return o && X::classof(o);
}

/// Casting operators inspired by LLVM:@n
/// cast<> is a static cast with an assert.
template <typename X> SYS_FORCE_INLINE const X *
cast(const InstancablePtr *o)
{
    UT_ASSERT(o && isA<X>(o));
    return static_cast<const X *>(o);
}

/// Casting operators inspired by LLVM:@n
/// cast<> is a static cast with an assert.
template <typename X> SYS_FORCE_INLINE X *
cast(InstancablePtr *o)
{
    UT_ASSERT(o && isA<X>(o));
    return static_cast<X *>(o);
}

/// @{
/// Casting operators inspired by LLVM:@n
/// dyn_cast<> is a fast dynamic cast.
template <typename X> SYS_FORCE_INLINE const X *
dyn_cast(const InstancablePtr *o)
{
    return isAValid<X>(o) ? static_cast<const X *>(o) : nullptr;
}
template <typename X> SYS_FORCE_INLINE const X *
dyn_cast(const InstancablePtr &o)
{
    return isA<X>(&o) ? static_cast<const X *>(&o) : nullptr;
}
template <typename X> SYS_FORCE_INLINE X *
dyn_cast(InstancablePtr *o)
{
    return isAValid<X>(o) ? static_cast<X *>(o) : nullptr;
}
template <typename X> SYS_FORCE_INLINE X *
dyn_castValid(InstancablePtr &o)
{
    return isA<X>(&o) ? static_cast<X *>(&o) : nullptr;
}
/// @}

class BRAY_API ObjectPtr : public InstancablePtr
{
public:
    ObjectPtr()
        : InstancablePtr(InstancableType::Object)
    {
    }
    ~ObjectPtr() override;

    /// Test if Instancable is of this type
    static SYS_FORCE_INLINE bool classof(const InstancablePtr *o)
    {
        return o->instancableType() == InstancableType::Object;
    }

    /// Test validity
    /// @{
    bool        isValid() const { return myObject != nullptr; }
    explicit    operator bool() const { return isValid(); }
    /// @}

    /// Query if object is a leaf node (ie not scenegraph or instance)
    bool        isLeaf() const;

    /// @{
    /// Access to the underlying object
    const BRAY_Object   *objectPtr() const { return myObject.get(); }
    BRAY_Object         *objectPtr() { return myObject.get(); }
    /// @}

    /// Bind a material to the object.  The method will fail if the underlying
    /// object cannot set the material.
    bool        setMaterial(ScenePtr &scene,
                        const MaterialPtr &mat,
                        const OptionSet &opts,
                        exint nfacesets=0,
                        const FacesetMaterial *faceset_mat=nullptr);

    /// Set the mapping for transform space aliases.  This allows shaders to
    /// reference a simple space name rather than the fully qualified path to
    /// the space (e.g. "paintSpace" instead of "/World/Obj/PaintObj/Xform")
    bool        setCoordSysAliases(const ScenePtr &scene,
                    UT_UniquePtr<UT_StringMap<UT_StringHolder>> map);

    /// Set the prototype for an instance object
    void        setInstancePrototype(const ObjectPtr &proto);

    /// Set the transform on the instance
    void        setInstanceTransforms(ScenePtr &scene,
                        const UT_Array<SpacePtr> &xforms);

    /// Set attributes on instances
    void        setInstanceAttributes(const ScenePtr &scene,
                        const GT_AttributeListHandle &alist);

    /// Set property overrides for instances.  The array must have an entry for
    /// every instance.  It's possible to have default options.  Each
    /// attribute's name should match an object property name.  Warnings will
    /// be output if an attribute doesn't match.
    void        setInstanceProperties(const ScenePtr &scene,
                        const GT_AttributeListHandle &alist);

    /// Set instance IDs. If not set (or given an empty array), it is assumed
    /// that the ids are contiguous 0...N-1 where N is the number of xforms.
    void        setInstanceIds(UT_Array<exint> ids);

    /// Add an object to a scene
    void        addInstanceToScene(ObjectPtr &obj);

    /// Check to make sure that number of xforms, attribute list, ids all match
    bool        validateInstance() const;

    /// @{
    /// This will return the object's base properties, or the scene defaults if
    /// the object isn't defined yet.
    OptionSet           objectProperties(ScenePtr &scene);
    const OptionSet     objectProperties(const ScenePtr &scene) const;
    /// @}

    /// Get the underlying GT_PrimitiveHandle (if possible).  This method may
    /// return a nullptr.
    GT_PrimitiveHandle  geometry() const;

    /// Pointer to the contained procedural.  This may return a nullptr.
    BRAY_Procedural     *procedural();

    /// Update the geometry for the object.  The method will fail if you're
    /// trying to change the underlying primitive type.
    bool                setGeometry(const ScenePtr &scene,
                                    const GT_PrimitiveHandle &prim);

    /// Set the list of "holes" for a polygon mesh (subdivision meshes have the
    /// list of holes specified in the subdivision tags).
    bool                setGeometry(const ScenePtr &scene,
                                    const GT_PrimitiveHandle &prim,
                                    const GT_DataArrayHandle &holes);

    /// Update volume fields.  This method will fail if the underlying
    /// primitive isn't a volume (see createVolume())
    /// Extents are unused for ordinary voxel-based volumes since the bounds
    /// are computed from field data and velocity blur.
    using FieldList = UT_Array<std::pair<UT_StringHolder, GT_PrimitiveHandle>>;
    bool                setVolume(const ScenePtr &scene,
                                  const GT_AttributeListHandle &clist,
                                  const FieldList& fields,
                                  const UT_BoundingBox &extent);

    /// Return the detail attributes for a volume primitive
    const GT_AttributeListHandle        &volumeDetailAttributes() const;

    /// TODO: Deprecate this
    void        takeOwnership(BRAY_Object *obj);

protected:
    UT_SharedPtr<BRAY_Object>   myObject;
    friend class ScenePtr;
};

class BRAY_API LightPtr : public InstancablePtr
{
public:
    LightPtr(const UT_SharedPtr<BRAY_Light> &lp = UT_SharedPtr<BRAY_Light>())
        : InstancablePtr(InstancableType::Light),
          myLight(lp)
    {
    }
    ~LightPtr() override;

    /// Test if Instancable is of this type
    static SYS_FORCE_INLINE bool classof(const InstancablePtr *o)
    {
        return o->instancableType() == InstancableType::Light;
    }

    /// Test validity
    /// @{
    bool        isValid() const { return myLight != nullptr; }
    explicit    operator bool() const { return isValid(); }
    /// @}

    /// Access to the underlying object
    /// @{
    const BRAY_Light    *lightPtr() const { return myLight.get(); }
    BRAY_Light          *lightPtr() { return myLight.get(); }
    /// @}

    /// Return the type of light
    BRAY_LightType      type() const;

    /// Return the name of the light
    const UT_StringHolder   &name() const;

    /// Return the transform of the light
    SpacePtr                transform() const;  

    /// Set the transform of the light
    void        setTransform(const SpacePtr &xforms);

    /// Set the shader for the light
    void        setShader(const ScenePtr &scene, const UT_StringArray &args);

    /// Get the current object properties for modification.
    OptionSet   objectProperties();

    /// Set the object properties
    void        setObjectProperties(const OptionSet &oprops);

    /// Get the current light properties for modification.
    OptionSet   lightProperties();

    /// Set the light properties
    void        setLightProperties(const OptionSet &lprops);

    /// After changing any options, must lock prior to rendering
    void        commitOptions(ScenePtr &scene);

    /// Update the light shader graph
    void        updateShaderGraph(const ScenePtr &scene,
                        const ShaderGraphPtr &graphptr,
                        const UT_Array<ShaderGraphPtr> &light_filters);

    /// If a light filter has been modified, this method should be called to
    /// notify the light.  The set should contain the names of the dirty light
    /// filter shader graphs.
    void        updateFilters(const ScenePtr &scene,
                        const UT_Array<ShaderGraphPtr> &filters);

    /// Notify the light that a filter has been deleted
    void        eraseFilter(const ScenePtr &scene,
                        const UT_StringRef &shader_graph_name);

    ///
    static UT_Vector3 computeEmission(
                        const UT_Vector3& color,
                        float   intensity,
                        float   exposure,
                        bool    enable_color_temperature,
                        float   color_temperature);

protected:
    UT_SharedPtr<BRAY_Light>    myLight;
private:
    friend class LightInstancer;
};

class BRAY_API LightInstancerPtr : public InstancablePtr
{
public:
    LightInstancerPtr(UT_SharedPtr<LightInstancer> p = nullptr)
        : InstancablePtr(InstancableType::LightInstancer),
          myInstancer(p)
    {
    }
    ~LightInstancerPtr() override;

    /// Test if Instancable is of this type
    static SYS_FORCE_INLINE bool classof(const InstancablePtr *o)
    {
        return o->instancableType() == InstancableType::LightInstancer;
    }

    // Test validity
    bool    isValid() const { return myInstancer != nullptr; }

    /// Convenient validity testing
    explicit operator bool() const { return isValid(); }

    /// Return the name of the instancer
    const UT_StringHolder       &name() const;

    /// Set the instance transforms
    void        setInstanceTransforms(ScenePtr &scene,
                        const UT_Array<SpacePtr> &xforms);

    /// Set the instance properties
    void        setInstanceProperties(ScenePtr &scene,
                        const GT_AttributeListHandle &alist);

    /// Add a light prototype for instancing
    /// If a light prototype with the same name exists,
    /// the new prototype is not added, but the instances
    /// belonging to that name are updated on the next commit
    void        addPrototype(ScenePtr &scene,
                        const LightPtr &light);

    /// Add a light instancer prototype for instancing
    /// If a light prototype with the same name exists,
    /// the new prototype is not added, but the instances
    /// belonging to that name are updated on the next commit
    void        addPrototype(ScenePtr &scene,
                        const LightInstancerPtr &inst);

    /// Commit the current prototypes to the scene
    void        commit(ScenePtr &scene);

    /// Clear all instances from the Scene
    void        clear(ScenePtr &scene);

protected:
    UT_SharedPtr<LightInstancer>        myInstancer;
private:
    friend class LightInstancer;
};

class BRAY_API CameraPtr
{
public:
    CameraPtr(const UT_SharedPtr<BRAY_Camera> &cp = UT_SharedPtr<BRAY_Camera>())
        : myCamera(cp)
    {
    }
    ~CameraPtr();

    /// Test validity
    /// @{
    bool        isValid() const { return myCamera != nullptr; }
    explicit    operator bool() const { return isValid(); }
    /// @}

    /// Access to the underlying object
    /// @{
    const BRAY_Camera   *cameraPtr() const { return myCamera.get(); }
    BRAY_Camera         *cameraPtr() { return myCamera.get(); }
    /// @}

    /// Set the transform on the camera
    void        setTransform(ScenePtr &ptr, const SpacePtr &xforms);

    /// Set the lens shader for the camera
    void        setShader(const ScenePtr &scene, const UT_StringArray &args);

    /// Set the lens shader material for the camera
    void        setShaderMaterial(const ScenePtr &scene,
                                  const MaterialPtr &mat);

    /// Get the current object properties for modification.
    OptionSet   objectProperties();

    /// Set number of motion samples for animated camera properties (1 upon
    /// construction). The last motion sample is assumed to have time offset of
    /// 1.0. (eg. if there are 3 samples, the time offsets are: 0, 0.5, 1.0)
    void        resizeCameraProperties(int nseg);

    /// Get the current camera properties for modification.
    UT_Array<OptionSet> cameraProperties();

    /// Clear the camera's user defined clipping planes
    void        clearClippingPlanes();

    /// Add a user defined clipping plane
    void        addClippingPlane(const UT_Vector4D *plane, int nsegments);

    /// After changing any options, must lock prior to rendering
    void        commitOptions(ScenePtr &scene);

protected:
    UT_SharedPtr<BRAY_Camera>   myCamera;

};

class BRAY_API CoordSysPtr
{
public:
    CoordSysPtr(const UT_SharedPtr<BRAY_Camera> &sp = UT_SharedPtr<BRAY_Camera>())
        : mySpace(sp)
    {
    }
    ~CoordSysPtr();

    /// Test validity
    /// @{
    bool        isValid() const { return mySpace != nullptr; }
    explicit    operator bool() const { return isValid(); }
    /// @}

    /// Access to underlying object
    /// @{
    const BRAY_Camera           *spacePtr() const { return mySpace.get(); }
    BRAY_Camera                 *spacePtr() { return mySpace.get(); }
    /// @}

    const UT_StringHolder       &name() const;

    /// Set transform
    void        setTransform(ScenePtr &scn, const SpacePtr &xforms);

    /// The current object properties for modification (primarily for motion
    /// blur settings)
    OptionSet   objectProperties();

    /// When a transform space has camera properties (for projection spaces),
    /// it's possible the projection can be motion blurred.  This allows you to
    /// specify the motion segments for properties.
    void        resizeCameraProperties(int nseg);

    /// Get the current camera properties for modification
    UT_Array<OptionSet> cameraProperties();

    /// After changing options, make sure to commit
    void        commit(ScenePtr &scene);

private:
    UT_SharedPtr<BRAY_Camera>    mySpace;
};

class BRAY_API AOVBufferPtr
{
public:
    AOVBufferPtr() = default;

    AOVBufferPtr(const UT_SharedPtr<BRAY_AOVBuffer> &aov)
        : myAOVBuffer(aov)
    {}

    ~AOVBufferPtr() {};

    bool        operator==(const AOVBufferPtr &aov) const
                    { return aov.myAOVBuffer == myAOVBuffer; }
    bool        operator!=(const AOVBufferPtr &aov) const
                    { return !(*this == aov); }

    const UT_StringHolder       &getName() const;
    const UT_StringHolder       &getVariable() const;

    int              getXres() const;
    int              getYres() const;
    PXL_DataFormat   getFormat() const;
    PXL_Packing      getPacking() const;
    float            getDefaultValue() const;

    void            *map();
    void             unmap();
    bool             isMapped() const;

    // For extra channels
    int              getNumExtra() const;
    const UT_StringHolder &nameExtra(int idx) const;
    PXL_DataFormat   getFormatExtra(int idx) const;
    PXL_Packing      getPackingExtra(int idx) const;
    void            *mapExtra(int idx);
    void             unmapExtra(int idx);

    // metadata to write to header of output file
    const UT_Options &getMetadata() const;

    bool             isConverged() const;
    void             setConverged();
    void             clearConverged();

    // Valid only after raster is allocated (ie render started)
    bool             isValid() const;
    explicit         operator bool() const { return isValid(); }

private:
    UT_SharedPtr<BRAY_AOVBuffer> myAOVBuffer;
};

/// A render product represents an output file
class BRAY_API OutputFile
{
public:
    // Test whether the type is understook by karma
    // For example "karma:checkpoint"
    static bool isKnownType(const UT_StringRef &type);

    // Clear all existing output files
    static void clearFiles(BRAY::ScenePtr &scene);

    struct BRAY_API AOV
    {
        AOV(const UT_StringHolder &name)
            : myName(name)
        {
        }
        /// Method is specialized for T in:
        /// - bool
        ///     - int32/int64
        ///     - fpreal32/fpreal64
        ///     - UT_StringHolder
        template <typename T>
        bool        setOption(const UT_StringHolder &name,
                            const T *value,
                            exint size);
        template <typename T>
        bool        setOption(const UT_StringHolder &name, const T &value)
                        { return setOption(name, &value, 1); }

        /// Copy over options from those passed in
        bool    setOptions(const UT_Options &options);

        const UT_StringHolder   &name() const { return myName; }
        const UT_Options        &options() const { return myOptions; }

        /// Dump method for debugging
        void    dump(UT_JSONWriter &w) const;
    private:
        UT_StringHolder myName;
        UT_Options      myOptions;
    };
    OutputFile(BRAY::ScenePtr &scene,
            const UT_StringHolder &filename,
            const UT_StringHolder &type)
        : myScene(scene)
        , myFilename(filename)
        , myType(type)
    {
    }

    ~OutputFile()
    {
        if (myFilename)
            commit();
    }

    /// @{
    /// Method is specialized for T in:
    /// - bool
    /// - int32/int64
    /// - fpreal32/fpreal64
    /// - UT_StringHolder
    template <typename T>
    bool        setOption(const UT_StringHolder &name,
                        const T *value,
                        exint size);
    template <typename T>
    bool        setOption(const UT_StringHolder &name, const T &value)
                    { return setOption(name, &value, 1); }
    /// @}

    /// Copy over options from those passed in
    bool    setOptions(const UT_Options &options);

    /// Add an AOV to this output file
    AOV         &appendAOV(const UT_StringHolder &name)
    {
        myAOVs.emplace_back(name);
        return myAOVs.last();
    }

    /// Commit and add this output file to the render
    bool        commit()
    {
        bool    result = doCommit();
        cancel();       // Once committed, no more changes
        return result;
    }
    /// Cancel this output file for some reason
    void        cancel() { myFilename.clear(); }

    /// Access member data
    const UT_StringHolder       &filename() const { return myFilename; }
    const UT_StringHolder       &type() const { return myType; }
    const UT_Array<AOV>         &aovs() const { return myAOVs; }
    const UT_Options            &options() const { return myOptions; }

    /// @{
    /// Dump information (used by karma:debug)
    void        dump() const;
    void        dump(UT_JSONWriter &w) const;
    /// @}

private:
    bool        doCommit();
    BRAY::ScenePtr      &myScene;
    UT_StringHolder      myFilename;
    UT_StringHolder      myType;
    UT_Array<AOV>        myAOVs;
    UT_Options           myOptions;
};


/// Interface to the renderer
class BRAY_API RendererPtr
{
public:
    /// Class used to define image planes
    struct ImagePlane
    {
        UT_StringHolder myName;
        UT_StringHolder myVariable;
        int             mySize;
        PXL_DataFormat  myDataFormat;
        OptionSet       myOptions;
    };

    RendererPtr() = default;
    ~RendererPtr() {};

    /// Allocate renderer
    static RendererPtr  allocRenderer(BRAY::ScenePtr &sceneptr);

    explicit     operator bool() const { return myRenderer.get(); }

    /// @{
    /// Define image planes for rendering
    void         clearOutputPlanes();
    AOVBufferPtr addOutputPlane(const ImagePlane &plane);
    int          getAOVCount() const;
    /// @}

    /// Access the stats for this render
    const BRAY::Stats   &stats() const;

    /// Call before rendering begins.  This lets the renderer prepare data
    /// structures before render() is called.  For example, this will ensure
    /// all AOV buffers are allocated and active.  The method returns false if
    /// there were errors setting up the render.
    bool        prepareRender();

    /// Start rendering a scene
    void        render(bool (*stopreq)(void *) = nullptr, void *data = nullptr);

    /// Test to see whether the current renderer is active
    bool        isRendering() const;

    /// Test to see if there was an error rendering
    bool        isError() const;

    /// Test to see if the renderer is paused
    bool        isPaused() const;

    /// Tells the renderer to prepare to be stopped
    void        prepareForStop();

    /// Pause rendering -- Returns true if the renderer is paused
    bool        pauseRender();

    /// Restart rendering  -- Returns true if @c isRendering();
    bool        resumeRender();

    /// Set a point in the image to give priority to rendering
    void        setPriority(int x, int y);

    /// Set a region in the image which should have priority
    void        setPriority(const UT_DimRect &region);

    /// Clear the priority focus
    void        clearPriority();

    /// Enables image filters by the given option. 
    /// The is_render_settings_prim indicates whether the filter
    /// belongs to render settings prim or the display options.
    bool        enableImageFilters(
                    const UT_StringHolder &filters_opt,
                    bool is_render_settings_prim);

    /// Set whether to use render settings prim or display options.
    void        setUseRenderSettingsPrim(bool use_render_settings_prim);

    /// JSON map containing common render product metadata from husk.
    void        setConvergedMetadata(const UT_JSONValue &value);

    /// @private method
    BRAY_Renderer       *renderer() { return myRenderer.get(); }

private:
    UT_SharedPtr<BRAY_Renderer> myRenderer;
};

class BRAY_API ShaderGraphPtr
{
public:
    ShaderGraphPtr(UT_SharedPtr<BRAY_ShaderGraph> graph)
    : myGraph(graph)
    {}
    ~ShaderGraphPtr() {};

    /// Make new node based on type and add to list of nodes in the current
    /// graph. Returns NULL if unknown type.
    /// Note that the root node (ie with surface/displace output) must be the
    /// first node added to the graph.
    BRAY_ShaderInstance *createNode(const UT_StringHolder &type,
                                    const UT_StringHolder &name);

    /// Returns OptionSet that contains input parameters for given shader node.
    /// Can be used to read and write values.
    OptionSet            nodeParams(BRAY_ShaderInstance *node);

    /// Return the name of the shader instance
    static const UT_StringHolder        &nodeName(const BRAY_ShaderInstance *n);

    /// Return the type of the shader instance
    static const UT_StringHolder        &nodeType(const BRAY_ShaderInstance *n);

    /// Make connection between two nodes
    bool                 wireNodes(const UT_StringHolder &srcnode,
                                   const UT_StringHolder &srcoutput,
                                   const UT_StringHolder &dstnode,
                                   const UT_StringHolder &dstinput);

    // Definition of a shader node
    class NodeDecl
        : UT_NonCopyable
    {
    public:
        NodeDecl() {}
        NodeDecl(const UT_StringHolder &n)
            : myName(n)
        {
        }

        struct Parameter
        {
            UT_StringHolder     myName; // Name of parameter

            bool        isBool() const { return myType == 0; }
            bool        isInt() const { return myType == 1; }
            bool        isReal() const { return myType == 2; }
            bool        isFloat() const { return myType == 2; }
            bool        isString() const { return myType == 3; }
            bool        isVariadic() const { return myVariadic; }

            exint       size() const
            {
                return myB.size() + myI.size() + myF.size() + myS.size();
            }

            UT_Array<bool>              myB;    // Bool defaults
            UT_Array<int64>             myI;    // Integer defaults
            UT_Array<fpreal64>          myF;    // Real defaults
            UT_Array<UT_StringHolder>   myS;    // String defaults
            bool                        myVariadic; // Array valued (variadic)
            bool                        myInvisible;
            uint8                       myType;
            uint8                       myTupleSize;

            void        dump(UT_JSONWriter &w) const;
        };

        const UT_StringHolder                name() const
                                             { return myName; }
        const UT_Array<Parameter>           &inputs() const
                                             { return myInputs; }
        const UT_Array<Parameter>           &outputs() const
                                             { return myOutputs; }
        const UT_StringMap<UT_StringHolder> &metadata() const
                                             { return myMetadata; }

        void    setName(const UT_StringHolder &n)
                { myName = n; }
        void    addInput(const Parameter &parm)
                { myInputs.append(parm); }
        void    addOutput(const Parameter &parm)
                { myOutputs.append(parm); }
        void    setMetadata(const UT_StringMap<UT_StringHolder> &metadata)
                { myMetadata = metadata; }

        void    dump() const;
        void    dump(UT_JSONWriter &w) const;

    private:
        UT_StringHolder                 myName;
        UT_StringMap<UT_StringHolder>   myMetadata;
        UT_Array<Parameter>             myInputs;
        UT_Array<Parameter>             myOutputs;
    };

    // Extract the definition of all supported nodes
    static const UT_Array<const NodeDecl *>     &allNodes();
    // Find a node given the name
    static const NodeDecl       *findNode(const UT_StringRef &name);

    /// Access the object properties on the shader graph.  It's possible the
    /// shader graph has no options, so please check `isValid()`
    const OptionSet     getObjectProperties() const;
    /// Create object properties for read/write
    OptionSet           createObjectProperties(const BRAY::ScenePtr &scene);
    /// Clear any existing object properties
    void                clearObjectProperties();


private:
    friend class MaterialPtr;
    friend class LightPtr;
    UT_SharedPtr<BRAY_ShaderGraph>  myGraph;
};

};      // End of namespace

#endif