IMX_VDB.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:        IMX_VDB.h
 *
 * COMMENTS: 
 *      Holder for NanoVDBs, either on GPU or CPU
 */

#ifndef __IMX_VDB_h__
#define __IMX_VDB_h__

#include "IMX_API.h"
#include "IMX_Types.h"

#include <CE/CE_HotSwapPoolEntry.h>
#include <CE/CE_BufferHost.h>

#include <GA/GA_PrimVolumeXform.h>
#include <CE/CE_VDBGrid.h>
#include <UT/UT_Lock.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_Options.h>
#include <SYS/SYS_AtomicInt.h>

#include <openvdb/Platform.h>
#include <openvdb/openvdb.h>


class IMX_VDB;
using IMX_VDBPtr = UT_SharedPtr<IMX_VDB>;
using IMX_VDBConstPtr = UT_SharedPtr<const IMX_VDB>;

class IMX_API IMX_VDB : public CE_HotSwapPoolEntry
{
public:
    /// An un-allocated null-VDB, but with default meta data.
    IMX_VDB();

    IMX_VDB(const IMX_VDB &other) { copy(other); }
    IMX_VDB(IMX_VDB && other) noexcept { swap(other); }

    ~IMX_VDB() override;

    EntryType poolTypeID() const override { return EntryType::VDB; }

    /// Assignment operators
    void copy(const IMX_VDB &other);
    IMX_VDB &operator=(const IMX_VDB &other) { copy(other); return *this; }

    void swap(IMX_VDB &other);
    IMX_VDB &operator=(IMX_VDB &&other) { swap(other); return *this; }

    /// Conversion to/from openvdb.
    /// Can throw CE exceptions.
    openvdb::GridBase::Ptr createVDB() const;

    /// Returns true for successful save.
    bool                 save(std::ostream &os) const;
    bool                 saveJSON(UT_JSONWriter &w) const;

    /// Returns a newly created VDB loaded from the stream, or null
    /// if load failure.
    static IMX_VDBPtr    load(UT_IStream &is);
    static IMX_VDBPtr    loadJSON(UT_JSONParser &p);

    /// Write our fields into the provided options:
    /// THis does not include properties.
    void        copyMetadataToOptions(UT_Options &opt) const;
    /// Load ourselves from the options, ignoring fields we don't know
    void        updateMetadataFromOptions(const UT_Options &opt);

    /// Copies a VDB into ourselves, creating both CPU and GPU buffers
    /// by default.
    /// Can throw CE exceptions.
    void                 copyFromVDB(const openvdb::GridBase &vdb,
                                  const UT_Vector3 &voxelsize,
                                  const GA_PrimVolumeXform &indexspace,
                                  bool ontocpu=true, bool ontogppu=true);
    void                 cpuCopyFromVDB(const openvdb::GridBase &vdb,
                                  const UT_Vector3 &voxelsize,
                                  const GA_PrimVolumeXform &indexspace)
    { copyFromVDB(vdb, voxelsize, indexspace, true, false); }
    void                 gpuCopyFromVDB(const openvdb::GridBase &vdb,
                                  const UT_Vector3 &voxelsize,
                                  const GA_PrimVolumeXform &indexspace)
    { copyFromVDB(vdb, voxelsize, indexspace, false, true); }

    /// Replaces self with a vdb using the provided source's
    /// topology.
    /// If same type this is just a copy(). Otherewise it is zeroed.
    /// Copies transform & metadata options.
    void                 buildFromTopology(UT_VDBType storage, 
                                           const IMX_VDB *refvdb);

    /// Returns this vdb's GPU storage object. If read is true, isDirty must
    /// be false. If write is true then it turns off isDirty by setting
    /// isOnGPU() and turning off isOnCPU() (it is assuming caller will actually
    /// write the buffer)
    /// When using one of these methods, this buffer must be guarded with the
    /// in-use GPU flag. See setInUseGPUFlag() documentation for more
    /// information.
    /// Can throw CE exceptions.
    CE_VDBGrid *getGPUBuffer(bool read, bool write);
    const CE_VDBGrid *getGPUBufferR() const;
    CE_VDBGrid *getGPUBufferW() { return getGPUBuffer(false, true); }

    UT_VDBType          storageType() const { return myStorageType; }
    int                 getChannels() const;
    bool                storesIntegers() const;
    static const char  *cnanovdbStorageDefine(UT_VDBType storagetype);

    void                setTypeInfo(IMX_TypeInfo typeinfo) { myTypeInfo = typeinfo; }
    IMX_TypeInfo        typeInfo() const { return myTypeInfo; }


    UT_Vector3          voxelSize() const { return myVoxelSize; }
    UT_Vector3          origin() const { return myIndexSpace.myCenter; }
    GA_PrimVolumeXform  indexSpace() const { return myIndexSpace; }

    /// True if the two vdbs map the same indices to the same positions.
    bool                 isAligned(const IMX_VDB *vdb) const
    { return indexSpace() == vdb->indexSpace(); }

    /// Transform the vdb, this REQUIRES updating the nanovdb
    /// structure so will run OpenCL.
    void                transform(const UT_Matrix4D& m);

    /// Sets the underlying GPU buffer to provided grid, taking
    /// ownership of it.
    void                adoptGrid(UT_UniquePtr<CE_VDBGrid> grid,
                                  cl::Buffer tilestarts,
                                  exint leafcount,
                                  exint lowercount,
                                  exint uppercount,
                                  const UT_Vector3 &voxelsize,
                                  const GA_PrimVolumeXform &indexspace);

    /// If onCPU, returns a shared pointer to the cpu buffer
    /// If onGPU, copy to CPU and return the shared pointer, keeping
    /// GPU copy.
    /// If dirty, return null.
    /// Can throw CE exceptions.
    UT_SharedPtr<CE_BufferHostByte>       getCPUBufferR() const;

    /// If onCPU, ensure unique and return the raw pointer that is
    /// our own buffer.
    /// If onGPU, copies to the CPU and returns that, resetting onGPU to false
    /// If dirty, return null.
    CE_BufferHostByte                    *getCPUBufferRW();

    /// Replace VDB with raw NanoVDB buffer.
    /// Can throw CE exceptions for malformed or unhandled data.
    void                setFromRawNanoVDB(const void *data, exint size);

    /// Returns true if this vdb's data is currently on the GPU.
    bool isOnGPU() const
    {
        return myOnGPU;
    }

    /// Returns true if this vdb's data is currently on the CPU (this is not
    /// necessarily !isOnGPU()).
    bool isOnCPU() const
    {
        return myOnCPU;
    }

    /// True if data in this buffer may be stolen from (or changed) by the verbs
    /// even if it's an input.
    bool stealable() const { return myStealable; }

    /// Can be used to control what stealable() subsequently returns. If set to
    /// true, indicates to the verbs that this buffer may be stolen from.
    void setStealable(bool v) const { myStealable = v; }

    bool        hasTopology() const;    // No topology is an incomplete vdb
    exint       leafCount() const 
    { return myTopology ? myTopology->leafCount() : 0; }
    exint       lowerCount() const 
    { return myTopology ? myTopology->lowerCount() : 0; }
    exint       upperCount() const 
    { return myTopology ? myTopology->upperCount() : 0; }

    /// Half-inclusive bounds of the volume in voxels; using only the leaf
    /// information.  Requires possibly copying back tilestarts and running
    /// over, so not fast.  Voxels are in [lower, upper)
    void        voxelBounds(UT_Vector3i &lower, UT_Vector3i &upper) const
    {
        lower = upper = 0;
        if (myTopology) myTopology->voxelBounds(lower, upper);
    }

    /// Build topology from provided grid.  These are built onto
    /// the GPU & CPU.    This could be delayed since we share
    /// the topology pointer so would only upload once.
    void buildTopology(const openvdb::GridBase &grid);

    /// Build topology from our own cpu buffer.
    void buildTopologyFromCPU(bool denseleaves);

    /// Return a gpu version
    cl::Buffer  getGPUTileStarts(exint &tilecount) const
    { if (myTopology) return myTopology->getGPUTileStarts(tilecount);
      tilecount = 0; return  {}; }
    UT_SharedPtr<UT_Array<UT_Vector3i>> getCPUTileStarts() const
    { if (myTopology) return myTopology->getCPUTileStarts();
      return {}; }

    /// If we know all leaves are fully activated, we can avoid
    /// doing activation tests per voxel.  This can be set at build
    /// time and then cleared if any topology change op occurs.
    bool        denseLeaves() const 
    { return myTopology ? myTopology->denseLeaves() : true; }
    void        setDenseLeaves(bool dense)
    { UT_ASSERT(myTopology); if (myTopology) myTopology->setDenseLeaves(dense); }

    /// NOTE: These only set leaf values.
    void setConstantV3(UT_Vector3 v);
    void setConstantF(fpreal32 f = 0.0f) { setConstantV3(UT_Vector3(f,f,f)); }
    void setConstantI(int32 i = 0);

    /// True if there are no VDB grids on GPU or CPU
    bool isDirty() const { return !myOnGPU && !myOnCPU; }

    /// Flag all grids as dirty without freeing them.
    void setDirty() { myOnGPU = myOnCPU = false; }

    /// Frees all buffers and marks dirty.
    void freeBuffers();

    /// Frees all the memory
    void destroy();

    /// True if there are any CPU or GPU buffers, they may not have
    /// valid data - use isDirty() to see that.
    bool allocated() const { return myCPUBuffer || myGPUBuffer; }

    int64       getMemoryUsage() const;
    int64       getDeviceMemoryUsage() const;

    void             setProperties(const UT_OptionsHolder &props) 
                     { myProperties = props; }
    UT_OptionsHolder properties() const 
                     { return myProperties; }

    /// Updates the contents of the properties, first making sure it is
    /// unique.  The provided operator should take a reference to
    /// a UT_Options that it will update.
    /// this->update([](UT_Options &opt) { opt.setOptionS("test", "bar"); });
    template <typename OP>
    void             updateProperties(const OP &op)
                     { myProperties.update(op); }

    /// VDB registration to allow vdbs to be converted
    /// to integers across HOM boundaries.
    
    /// Registers & returns the handle, adding the handle to the registered
    /// list
    static int       registerVDB(IMX_VDBConstPtr vdb, UT_IntArray &registered);
    /// Unregister all vdbs corresponding to the provided list,
    /// erase the list afterwards.   Assertion if handle wasn't regsitered
    static void      unregisterVDBs(UT_IntArray &registered);
    /// Look up a registered vdb by handle.
    static IMX_VDBConstPtr lookupVDB(int handle);

    class       Topology
    {
    public:
        Topology() = default;
        Topology(cl::Buffer tilestarts, 
                 exint leafcount, exint lowercount, exint uppercount)
        {
            myGPUTileStarts = tilestarts;
            myGPUTileStartsCount = leafcount;
            myLeafCount = leafcount;
            myLowerCount = lowercount;
            myUpperCount = uppercount;
        }
        Topology(const openvdb::GridBase &grid);
        Topology(const CE_BufferHostByte *cpugrid);
        ~Topology();

        /// Return a gpu version
        cl::Buffer  getGPUTileStarts(exint &tilecount) const;
        UT_SharedPtr<UT_Array<UT_Vector3i>> getCPUTileStarts() const;;

        void        setDenseLeaves(bool isdense) { myDenseLeaves = isdense; }
        bool        denseLeaves() const { return myDenseLeaves; }

        exint           leafCount() const { return myLeafCount; }
        exint           lowerCount() const { return myLowerCount; }
        exint           upperCount() const { return myUpperCount; }

        void            voxelBounds(UT_Vector3i &lower, UT_Vector3i &upper) const;

        int64           getMemoryUsage() const;
        int64           getDeviceMemoryUsage() const;

    protected:
        UT_SharedPtr<UT_Array<UT_Vector3i>> myCPUTileStarts;
        /// Tile starts is a shared buffer, so isn't re-written to
        cl::Buffer                  myGPUTileStarts;
        exint                       myGPUTileStartsCount = -1;

        /// Required to rebuild:
        exint                       myLeafCount = 0;
        exint                       myLowerCount = 0;
        exint                       myUpperCount = 0;

        // True if all the leaves are dense.
        bool                                myDenseLeaves = false;
    };

    /// Compute useful aggregate properties of the layer.
    /// For integer vdb, use computeMinI() and computeMaxI().
    fpreal64    computeMin(int channel = 0) const;
    fpreal64    computeMax(int channel = 0) const;
    fpreal64    computeAverage(int channel = 0) const;
    fpreal64    computeMinLength() const;
    fpreal64    computeMaxLength() const;

protected:
    /// These implement methods required by the pool.
    /// Resets the GPU Buffer pointer.
    void poolResetGPUBuffer() override
    {
        myGPUBuffer.reset();
    }
    /// Update OnGPU
    void poolSetOnGPU(bool ongpu) override
    {
        myOnGPU = ongpu;
    }
    /// True if the gpu buffer is null.
    bool poolIsGPUBufferEmpty() const override
    {
        return myGPUBuffer.get() == nullptr;
    }
    /// True if the gpu buffer is not null and valid.
    bool poolIsGPUBufferValid() const override
    {
        return myGPUBuffer.get() && myGPUBuffer->isValid();
    }
    /// True if the swap does something
    bool poolSwapGPUBuffer(CE_HotSwapPoolEntry *otherbase) override
    {
        IMX_VDB *other = UTverify_cast<IMX_VDB *>(otherbase);

        if (myGPUBuffer == other->myGPUBuffer)
            return false;

        myGPUBuffer.swap(other->myGPUBuffer);
        return true;
    }
    /// Shallow copy
    void poolShallowCopyGPUBuffer(const CE_HotSwapPoolEntry *srcbase) override
    {
        const IMX_VDB *src = UTverify_cast<const IMX_VDB *>(srcbase);

        myGPUBuffer = src->myGPUBuffer;
    }
    /// Queues up commands that transfer this buffer's GPU storage to main
    /// memory. 
    void unloadFromGPU() override;

    UT_SharedPtr<CE_BufferHostByte>       getCPUBufferRInternal();

    UT_SharedPtr<CE_BufferHostByte> myCPUBuffer;

    /// Tracks the leaf starts & node counts.  Stores GPU and CPU
    /// versions of these.
    UT_SharedPtr<Topology>      myTopology;

    /// Because the nanovdb buffers are somewhat opaque, we store
    /// some meta data locally. 
    UT_Vector3                  myVoxelSize;
    GA_PrimVolumeXform          myIndexSpace;

    /// All changes to this member (the shared pointer) must be done by the
    /// memory pool!!!
    UT_SharedPtr<CE_VDBGrid>    myGPUBuffer;

    UT_OptionsHolder            myProperties;
    IMX_TypeInfo                myTypeInfo = IMX_TypeInfo::IMX_NONE;

    /// The type of the grid so we can avoid unpacking it to find out.
    /// Note this is ALSO on the CE_VDBGrid, but that might not exist
    /// for CPU buffers so it is duplicated here.
    UT_VDBType                  myStorageType = UT_VDB_INVALID;

    /// This pair of flags hold the state of data that lives in the two storage
    /// spots.
    bool                        myOnCPU = false;
    bool                        myOnGPU = false;

    /// Can data of this buffer be stolen by the verbs? TODO: who should reset
    /// this and when?
    mutable bool myStealable = true;

    friend IMX_API size_t
    UTformatBuffer(char *buffer, size_t buffer_size, const IMX_VDB &v);
};

using IMX_ScopedVDBInUseGPU = CE_ScopedPoolEntryInUseGPU;

IMX_API size_t
UTformatBuffer(char *buffer, size_t buffer_size, const IMX_VDB &v);

#endif