IMX_Attribute.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_Attribute.h
 *
 * COMMENTS: 
 *      Holder for Detached Attributes, either on GPU or CPU
 */

#ifndef __IMX_Attribute_h__
#define __IMX_Attribute_h__

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

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

#include <GA/GA_CEAttribute.h>
#include <GA/GA_Types.h>
#include <GA/GA_Defaults.h>
#include <UT/UT_Lock.h>
#include <UT/UT_Options.h>
#include <UT/UT_SharedPtr.h>
#include <UT/UT_UniquePtr.h>
#include <UT/UT_Vector2.h>
#include <UT/UT_Vector3.h>
#include <UT/UT_Vector4.h>
#include <UT/UT_WorkBuffer.h>
#include <SYS/SYS_AtomicInt.h>

class IMX_Attribute;
using IMX_AttributePtr = UT_SharedPtr<IMX_Attribute>;
using IMX_AttributeConstPtr = UT_SharedPtr<const IMX_Attribute>;

class GU_Detail;

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

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

    ~IMX_Attribute();

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

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

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

    bool                 buildFromAttribute(const GA_Attribute *attrib, GA_AttributeOwner owner);

    /// If the storage/tuple match we get a direct copy, otherwise
    /// zero init.
    void                 buildFromEntries(GA_StorageClass storage,
                                          int tuplesize,
                                          const IMX_Attribute *src);
    void                 buildFromEntries(GA_StorageClass storage,
                                          int tuplesize,
                                          GA_Precision precision,
                                          GA_TypeInfo typeinfo,
                                          bool isarray,
                                          exint entries);

    /// Returns a newly created Attribute loaded from the stream, or null
    /// if load failure.
    static IMX_AttributePtr    load(UT_IStream &is);
    static IMX_AttributePtr    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);

    /// Builds an accessor to the underlying GA_CEAttribute.
    /// NOTE: The GA_CEAttributeAccessor should have its lifetime go until
    /// *after* the kernel has been dispatched.
    GA_CEAttributeAccessorPtr    getCEAttributeAccessor(bool read, bool write);
    GA_CEAttributeAccessorPtr    getCEAttributeAccessorR() const
         { return SYSconst_cast(this)->getCEAttributeAccessor(true, false); }
    GA_CEAttributeAccessorPtr    getCEAttributeAccessorW()
         { return getCEAttributeAccessor(false, true); }
    GA_CEAttributeAccessorPtr    getCEAttributeAccessorRW()
         { return getCEAttributeAccessor(true, true); }

    // Lift from underlying attribute:
    GA_Size             entries() const { return myData ? myData->entries() : 0; }
    int                 tupleSize() const { return myData ? myData->tupleSize() : 0; }
    int                 getChannels() const { return tupleSize(); }
    GA_StorageClass     storage() const { return myData ? myData->storage() : GA_STORECLASS_INVALID; }
    GA_Precision        precision() const { return myData ? myData->precision() : GA_PRECISION_INVALID; }
    bool                isArray() const { return myData ? myData->isArray() : false; }

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

    void                setDefaults(const GA_Defaults &def) { myDefaults = def; }
    const GA_Defaults  &defaults() const { return myDefaults; }

    /// The owner represents what they came from, that can be help
    /// in debugging and tracking.
    GA_AttributeOwner   owner() const { return myOwner; }
    void                setOwner(GA_AttributeOwner owner) { myOwner = owner; }

    bool isOnGPU() const { return myData ? myData->isOnGPU() : false; }
    bool isOnCPU() const { return myData ? myData->isOnCPU() : false; }

    /// In Use flags pass through to the underlying structure.
    /// This is suspect, you should be holding an accessor instead.
    void setInUseGPUFlag() const;
    void clearInUseGPUFlag() const;

    /// The actual attribute data.  This should be accessed via an accessor
    /// normally but can be used to trigger sharing.
    GA_CEAttributePtr           data() { return myData; }
    GA_CEAttributeConstPtr      data() const { return myData; }

    /// 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; }

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

    /// 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 myData ? true : false; }

    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); }

    /// Returns the contiguous raw bytes for a numeric non-array attribute.
    bool             rawData(UT_WorkBuffer &data) const;
    /// Replaces the contiguous raw bytes for a numeric non-array attribute.
    bool             setRawData(const char *data, exint length);

    /// Attribute 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       registerAttribute(IMX_AttributeConstPtr vdb, UT_IntArray &registered);
    /// Unregister all vdbs corresponding to the provided list,
    /// erase the list afterwards.   Assertion if handle wasn't regsitered
    static void      unregisterAttributes(UT_IntArray &registered);
    /// Look up a registered vdb by handle.
    static IMX_AttributeConstPtr lookupAttribute(int handle);

    /// This function calls operator() on op with a zero-initialized value
    /// matching the attribute's storage type and number of channels.
    template <typename OP>
    void dispatch(const OP &op) const
    {
        int n = getChannels();
        switch (GAgetDefaultStorage(storage(), precision()))
        {
            case GA_STORE_UINT8:    dispatch<uint8>(op, n); break;
            case GA_STORE_INT8:     dispatch<int8>(op, n); break;
            case GA_STORE_INT16:    dispatch<int16>(op, n); break;
            case GA_STORE_INT32:    dispatch<int32>(op, n); break;
            case GA_STORE_INT64:    dispatch<int64>(op, n);  break;
            case GA_STORE_REAL16:   dispatch<fpreal16>(op, n);break;
            case GA_STORE_REAL32:   dispatch<fpreal32>(op, n); break;
            case GA_STORE_REAL64:   dispatch<fpreal64>(op, n); break;
            case GA_STORE_BOOL:
            case GA_STORE_STRING:
            case GA_STORE_DICT:
            case GA_STORE_INVALID:
                UT_ASSERT(!"Invalid storage type.");
                break;
        }
    }

    /// This function calls operator() on op with a zero-initialized value
    /// matching the storage type and number of channels.
    template <typename T, typename OP>
    static void dispatch(const OP &op, int channels)
    {
        switch (channels)
        {
            case 1: op((T) 0); break;
            case 2: op(UT_Vector2T<T>(0, 0)); break;
            case 3: op(UT_Vector3T<T>(0, 0, 0)); break;
            case 4: op(UT_Vector4T<T>(0, 0, 0, 0)); break;
            default:
                UT_ASSERT(!"Unexpected number of channels.");
                break;
        }
    }

    fpreal64    computeMin(int channel = 0) const;
    fpreal64    computeMax(int channel = 0) const;
    fpreal64    computeMinLength() const;
    fpreal64    computeMaxLength() const;
    fpreal64    computeAverage(int channel = 0) const;
    exint       computeMinI(int channel = 0) const;
    exint       computeMaxI(int channel = 0) const;

protected:
    UT_SharedPtr<GA_CEAttribute> myData;
    UT_OptionsHolder            myProperties;

    GA_TypeInfo                 myTypeInfo = GA_TypeInfo::GA_TYPE_VOID;
    GA_AttributeOwner           myOwner = GA_ATTRIB_INVALID;
    GA_Defaults                 myDefaults;

    /// 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_Attribute &v);
};

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

#endif