GA_CEAttribute.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:        GA_CEAttribute.h ( GA Library, C++)
 *
 * COMMENTS:
 *      A GA_Attribute backed on the Compute Engine
 */

#ifndef __GA_CEAttribute__
#define __GA_CEAttribute__

#include "GA_API.h"

#include <CE/CE_Context.h>
#include <CE/CE_BufferDevice.h>
#include <CE/CE_HotSwapPoolEntry.h>
#include "GA_Detail.h"
#include "GA_Attribute.h"
#include <UT/UT_WorkBuffer.h>

class GA_CEAttribute;
using GA_CEAttributePtr = UT_SharedPtr<GA_CEAttribute>;
using GA_CEAttributeUPtr = UT_UniquePtr<GA_CEAttribute>;
using GA_CEAttributeConstPtr = UT_SharedPtr<const GA_CEAttribute>;

class GA_CEAttributeAccessor;
using GA_CEAttributeAccessorPtr = UT_SharedPtr<GA_CEAttributeAccessor>;

class GA_API GA_CEAttribute : public CE_HotSwapPoolEntry
{
public:
    GA_CEAttribute();

    /// Create an attribute from existing buffers.
    GA_CEAttribute(GA_Size entries, GA_StorageClass storage, GA_Precision precision,
                   GA_Size tuplesize, bool isarray,
                   cl::Buffer buffer, cl::Buffer indexbuffer,
                   bool leave_on_gpu = false);

    /// Construct unallocated array of this size and type
    GA_CEAttribute(GA_Size entries, GA_StorageClass storage, GA_Precision precision,
                   GA_Size tuplesize, bool isarray);

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

    virtual ~GA_CEAttribute() override;

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

    void                copy(const GA_CEAttribute &other);
    GA_CEAttribute     &operator=(const GA_CEAttribute &other) { copy(other); return *this; }

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

    /// Returns true for successful save.
    bool                 saveJSON(UT_JSONWriter &w) const;
    bool                 rawData(UT_WorkBuffer &data) const;
    bool                 setRawData(const char *data, exint length);

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

    void                clearBuffers();

    bool                isValid() const
    {
        // Valid if we have cpu or gpu buffer.
        return isOnGPU() || isOnCPU();
    }

    bool                isOnGPU() const
    { return myOnGPU; }
    bool                isOnCPU() const
    { return myOnCPU; }

    /// Ensures the CPU version of the attribute is valid.
    void                copyToCPU() 
    { unloadFromGPU(); }

    int64               getDeviceMemoryUsage() const;
    int64               getMemoryUsage(bool inclusive=false) const;

    /// Acquire accessors to the GPU data.  Extend the liftetime of
    /// these until any kernels they are bound to are dispatched.
    /// These handle pinning the GPU buffer from eviction from the
    /// hot swap pool, and also extending the cl::Buffer lifetime.
    /// You must test to see if these are null.  If they are non-null,
    /// they will be isValid().
    static GA_CEAttributeAccessorPtr makeAccessor(GA_CEAttributePtr attrib, bool read, bool write);
    static GA_CEAttributeAccessorPtr makeAccessorR(GA_CEAttributeConstPtr attrib) { return makeAccessor(UTconst_pointer_cast<GA_CEAttribute>(attrib), true, false); }
    static GA_CEAttributeAccessorPtr makeAccessorRW(GA_CEAttributePtr attrib) { return makeAccessor(attrib, true, true); }
    static GA_CEAttributeAccessorPtr makeAccessorW(GA_CEAttributePtr attrib) { return makeAccessor(attrib, false, true); }

    GA_Size             entries() const { return myEntries; }
    int                 tupleSize() const { return myTupleSize; }
    GA_StorageClass     storage() const { return myStorage; }
    GA_Precision        precision() const { return myPrecision; }
    bool                isArray() const { return myIsArray; }

    ///
    /// attributeToOCL populates our own data from the attribute.
    /// It will be loaded onto the GPU.
    /// If it fails, returns false.
    ///
    bool                attributeToOCL(const GA_Detail *gdp,
                                    GA_AttributeOwner owner,
                                    const char *aname,
                                    GA_StorageClass storage,
                                    int &tuplesize,
                                    bool isarray,
                                    bool docopy = true)
    {
        return attributeToOCL(gdp, owner, aname, storage, GA_PRECISION_32,
                              tuplesize, isarray, docopy);
    }
    bool                attributeToOCL(const GA_Detail *gdp,
                                    GA_AttributeOwner owner,
                                    const char *aname,
                                    GA_StorageClass storage,
                                    GA_Precision precision,
                                    int &tuplesize,
                                    bool isarray,
                                    bool docopy = true)
    {
        if (!gdp) return false;
        if (!UTisstring(aname))
            return false;
        const GA_Attribute *attrib = gdp->getAttributes().findAttribute(owner, aname);
        if (!attrib)
            return false;
        return attributeToOCL(attrib, storage, precision, tuplesize, isarray, docopy);
    }
    bool                attributeToOCL(const GA_Attribute *attrib,
                                    GA_StorageClass storage,
                                    GA_Precision precision,
                                    int &tuplesize,
                                    bool isarray,
                                    bool docopy = true);

    ///
    /// The int*ToOCL copy integer data into our own data.
    /// It will beloaded onto the GPU.
    /// If it fails, returns false.
    ///
    bool                intToOCL(const UT_Array<int64> &data,
                                   GA_StorageClass storage,
                                   GA_Precision precision,
                                   bool docopy = true);

    bool                intArrayToOCL(const UT_Array<UT_Array<int64>> &data,
                                   GA_StorageClass storage,
                                   GA_Precision precision,
                                   bool docopy = true);

    bool                packedIntArrayToOCL(
                                   const UT_PackedArrayOfArrays<int64> &data,
                                   GA_StorageClass storage,
                                   GA_Precision precision,
                                   bool docopy = true);

    ///
    /// oclToAttribute writes back our data to the specified attribute.
    /// If it is not compatible, returns false.
    ///
    bool                oclToAttribute(GA_Detail *gdp, GA_AttributeOwner owner, const char *aname)
    {
        if (!gdp) return false;
        if (!UTisstring(aname))
            return false;
        GA_Attribute *attrib = gdp->getAttributes().findAttribute(owner, aname);
        if (!attrib)
            return false;
        return oclToAttribute(attrib);
    }
    bool                oclToAttribute(GA_Attribute *attrib);

    bool                isWriteBackRequired() const { return myWriteBackRequired; }
    void                setWriteBackRequired(bool isrequired) { myWriteBackRequired = isrequired; }

protected:
    /// bufferRW() will ensure COW is respected and create a new GPU
    /// buffer if this was shared.  It also resets the OnCPU flag as
    /// it is assumed the data will be written to.
    /// bufferW() ensures the GPU buffer is unique, but does not copy
    /// the data when doing so.
    /// bufferR() will return a shared buffer without uniquing.  Caution
    /// should be taken to ensure you don't get both a read & write buffer,
    /// as your read buffer may be then orphaned (If you hold onto the 
    /// cl::Buffer object it is safe other than out of date data.  NOTE:
    /// binding to a kernel does NOT preserve the cl::Buffer object)
    cl::Buffer          bufferW() { return buffer(false, true); }
    cl::Buffer          bufferRW() { return buffer(true, true); }
    cl::Buffer          bufferR() const { return SYSconst_cast(this)->buffer(true, false); }
    cl::Buffer          buffer(bool read, bool write);

    /// Index buffer is immutable, so no writable variant:
    cl::Buffer          indexBufferR() const { return myIndexBuffer ? myIndexBuffer->buffer() : cl::Buffer(); }

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

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

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

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

protected:

    // Utility to trigger a callback on the correct data array type.
    template <typename OP>
    void                dispatchToArray(const OP &op)
    {
        switch (myStorage)
        {
            case GA_STORECLASS_FLOAT:
                switch (myPrecision)
                {
                    case GA_PRECISION_16: op(myFloat16Array); break;
                    case GA_PRECISION_32: op(myFloat32Array); break;
                    case GA_PRECISION_64: op(myFloat64Array); break;
                    default: break;
                }
                break;
            case GA_STORECLASS_INT:
                switch (myPrecision)
                {
                    case GA_PRECISION_1:  op(myInt8Array); break;
                    case GA_PRECISION_8:  op(myInt8Array); break;
                    case GA_PRECISION_16: op(myInt16Array); break;
                    case GA_PRECISION_32: op(myInt32Array); break;
                    case GA_PRECISION_64: op(myInt64Array); break;
                    default: break;
                }
                break;
            default:
                break;
        }
    }
    template <typename OP>
    void                dispatchToArray(const OP &op) const
    {
        switch (myStorage)
        {
            case GA_STORECLASS_FLOAT:
                switch (myPrecision)
                {
                    case GA_PRECISION_16: op(myFloat16Array); break;
                    case GA_PRECISION_32: op(myFloat32Array); break;
                    case GA_PRECISION_64: op(myFloat64Array); break;
                    default: break;
                }
                break;
            case GA_STORECLASS_INT:
                switch (myPrecision)
                {
                    case GA_PRECISION_1:  op(myInt8Array); break;
                    case GA_PRECISION_8:  op(myInt8Array); break;
                    case GA_PRECISION_16: op(myInt16Array); break;
                    case GA_PRECISION_32: op(myInt32Array); break;
                    case GA_PRECISION_64: op(myInt64Array); break;
                    default: break;
                }
                break;
            default:
                break;
        }
    }

    /// Transfers this CPU data onto the GPU.  Will set myOnGPu true
    /// on success, if docopy is false we only allocate the gpu buffer.
    void loadToGPU(bool docopy);

    // GPU Buffers:
    /// All changes to this member (the shared pointer) must be done by the
    /// memory pool!!!
    UT_SharedPtr<CE_BufferDeviceByte>   myBuffer;
    // Currently not part of pool?
    UT_SharedPtr<CE_BufferDeviceByte>   myIndexBuffer;

    // CPU Buffers:
    // Note that index arrays are considered to be immutable, so always
    // are on the CPU.
    UT_SharedPtr<UT_Array<cl_int>>      myIndexArray;
    // It would be much more proper to use cl_half here, but that
    // is not a computable type so it is easy to accidentally cast
    // fprealy16 to short silently.  Instead we rely on bit equivalency.
    UT_SharedPtr<UT_Array<fpreal16>>    myFloat16Array;
    UT_SharedPtr<UT_Array<cl_float>>    myFloat32Array;
    UT_SharedPtr<UT_Array<cl_double>>   myFloat64Array;
    UT_SharedPtr<UT_Array<cl_char>>     myInt8Array;
    UT_SharedPtr<UT_Array<cl_short>>    myInt16Array;
    UT_SharedPtr<UT_Array<cl_int>>      myInt32Array;
    UT_SharedPtr<UT_Array<cl_long>>     myInt64Array;

    // Number of entries.
    GA_Size             myEntries = 0;
    GA_Size             myDataEntries = 0;
    GA_Size             myTupleSize = 0;
    GA_StorageClass     myStorage = GA_STORECLASS_INVALID;
    GA_Precision        myPrecision = GA_PRECISION_INVALID;
    bool                myIsArray = false;

    // GA_CEAttributes are (usually) a clone of some GA_Attribute.
    // It is important to track where the authorative information lies.
    // If the GA_CEAttribute is written to, the GA_Attribute is out of date.
    // If the GA_Attribute is written to, it is expected for the 
    // GA_CEAttribute to be cleared.  (This is why naive algorithms should
    // flush all ce buffers)

    // The WriteBackRequired flag marks that the GA_Atttribute is out of
    // date.
    // The OnGPU and OnCPU track where the GA_CEAttribute currently lives.
    // So it is possible for the GA_CEAttribute data itself to be only on the
    // CPU, but out of date on the GA_Attribute.

    /// This pair stores whether correct data is on the CPU or GPU buffers
    /// or both.
    bool                myOnCPU = false;
    bool                myOnGPU = false;

    /// Whether the buffer has been written to by CE.  This implies
    /// GA_Attribute is out of date.
    bool                myWriteBackRequired = false;

    friend class GA_CEAttributeAccessor;
};

class GA_API GA_CEAttributeAccessor
{
public:
    GA_CEAttributeAccessor() = default;  // Invalid reader.
    GA_CEAttributeAccessor(GA_CEAttributePtr ceattrib, bool read, bool write);
    ~GA_CEAttributeAccessor();

    /// These should exist, along with move constructors, but do require
    /// work to ensure the gpuinuse flag is handled.
    GA_CEAttributeAccessor(const GA_CEAttributeAccessor &) = delete;
    GA_CEAttributeAccessor &operator=(const GA_CEAttributeAccessor &) = delete;

    cl::Buffer          bufferR() const { return buffer(true, false); }
    cl::Buffer          indexBufferR() const { return myIndexBuffer; }
    cl::Buffer          bufferW() const { return buffer(false, true); }
    cl::Buffer          bufferRW() const { return buffer(true, true); }
    cl::Buffer          buffer(bool read, bool write) const;

    bool                isValid() const
    {
        if (!myCEAttrib) return false;
        if (!myBuffer()) return false;
        return true;
    }
    bool                isInvalid() const { return !isValid(); }

    GA_Size             entries() const { return myCEAttrib ? myCEAttrib->entries() : 0; }
    int                 tupleSize() const { return myCEAttrib ? myCEAttrib->tupleSize() : 0; }
    GA_StorageClass     storage() const { return myCEAttrib ? myCEAttrib->storage() : GA_STORECLASS_INVALID; }
    GA_Precision        precision() const { return myCEAttrib ? myCEAttrib->precision() : GA_PRECISION_INVALID; }
    bool                isArray() const { return myCEAttrib ? myCEAttrib->isArray() : false; }

protected:
    /// We extend lifetime of our attribute that we have our
    /// in-use flag for.
    GA_CEAttributePtr   myCEAttrib;


    /// Whether we have been acquired for read or write, this is
    /// used to allow run-time validation of our requirments.
    bool                myRead = false;
    bool                myWrite = false;

    /// We explcitly extend the cl::Buffer lifetimes as this
    /// must be done until the kernel is executed, so this allows
    /// one to only extend one thing.
    cl::Buffer          myBuffer, myIndexBuffer;
};

#endif