CE_BufferDevice.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: CE_BufferDevice.h ( CE Library, C++)
 *
 * COMMENTS: Simple buffer class that works with CE_MemoryPool.
 */

#ifndef __CE_BufferDevice__
#define __CE_BufferDevice__

#include "CE_ArrayView.h"
#include "CE_Context.h"
#include "CE_Tracing.h"
#include <SYS/SYS_Inline.h>
#include <SYS/SYS_TypeTraits.h>

template <typename T>
class CE_BufferDevice
{
public:

    typedef T    value_type;

    /// Empty buffer constructor.
    CE_BufferDevice() { mySize = 0; }

    /// Allocated an uninitialized buffer of specified size (if > 0).
    CE_BufferDevice(exint size)
    {
        if (size > 0)
            init(size);
        else
            mySize = size;
    }

    /// Initialize from a raw cl::Buffer, which this object now owns.
    /// If size is not provided, calc from the buffer size and type.
    /// The input cl::Buffer is empty after this call.
    CE_BufferDevice(cl::Buffer &&buf, exint size = -1):
        myBuffer(buf), mySize(size)
    {
        if (buf())
        {
            if (mySize < 0)
                mySize = buf.getInfo<CL_MEM_SIZE>() / sizeof(T);
            UT_ASSERT(mySize * sizeof(T) == buf.getInfo<CL_MEM_SIZE>());
        }
        else
        {
            UT_ASSERT(mySize <= 0);
            mySize = 0;
        }
        buf = cl::Buffer();
    }

    /// No copy constructor.
    CE_BufferDevice(const CE_BufferDevice<T> &b) = delete;

    // Move constructor.
    CE_BufferDevice(CE_BufferDevice<T> &&b) noexcept
    {
        releaseBuffer();
        initInternal(b.size(), false);
        myBuffer = b.myBuffer;
        b.myBuffer = cl::Buffer();
        b.init(0);
    }

    ~CE_BufferDevice() { releaseBuffer(); }

    // Reinterpret this buffer as a fixed array of the given type.
    // Note: it's unsafe to use this view after the buffer has been reallocated.
    // The array type must be numeric. @see CE_ArrayView the supported types.
    template <typename V>
    CE_ArrayView<V> arrayView()
    {
        if constexpr (SYS_IsSame_v<T, V>)
            return CE_ArrayView<T>(*this);
        
        exint bytes = size() * sizeof(T);
        if (bytes % sizeof(V))
        {
            UT_ASSERT(!"Buffer does not fit evenly into reinterpreted type. "
                       "Array view was shortened!");
        }

        return CE_ArrayView<V>(buffer(), bytes / sizeof(V));
    }

    template <typename V>
    const CE_ArrayView<V> arrayView() const
    {
        return SYSconst_cast(this)->template arrayView<V>();
    }

    /// Release and return the underlying buffer without deleting,
    /// after which this object is empty (similar to unique_ptr).
    cl::Buffer  release()
    {
        cl::Buffer tmp = myBuffer;
        myBuffer = cl::Buffer();
        init(0);
        return tmp;
    }

    /// Reset to own the provided raw cl::Buffer.
    /// If size is not provided, calc from the buffer size and type.
    /// The input cl::Buffer is empty after this call.
    void        reset(cl::Buffer &&buf, exint size = -1)
    {
        releaseBuffer();
        myBuffer = buf;
        mySize = size;
        if (buf())
        {
            if (mySize < 0)
                mySize = buf.getInfo<CL_MEM_SIZE>() / sizeof(T);
            UT_ASSERT(mySize * sizeof(T) == buf.getInfo<CL_MEM_SIZE>());
        }
        else
        {
            UT_ASSERT(mySize <= 0);
            mySize = 0;
        }
        buf = cl::Buffer();
    }

    /// Initialize to given size.
    /// NOTE- values are undefined.
    void        init(exint size);

    /// Initialize from a UT_Array. If len >= 0, only len elements are copied.
    void        initFromArray(const UT_Array<T> &src, exint len = -1,
                              bool block = true);

    /// Resize the provided UT_Array to fit and copy this vector's data there.
    /// If len >= 0 then only len elements are copied.
    void        matchAndCopyToArray(UT_Array<T> &dst, exint len = -1,
                                    bool block = true) const;

    /// Initialize from raw data block of T elements of length nelem.
    void        initFromData(const T *data, exint nelem, bool block = true);

    /// Returns the buffer length.
    exint       size() const { return mySize; }

    /// Returns true iff there are no occupied elements in the buffer.
    bool        isEmpty() const  { return mySize == 0; }

    /// Returns the underlying OpenCL buffer.
    /// Note: This is meant for directly passing to OpenCL functions.
    /// holding ownership over long times.
    const cl::Buffer &buffer() const { return myBuffer; }

    /// Copy from the input buffer.  If len >= 0, only len elements are copied.
    /// NOTE:  This object must already be initialized to a buffer of
    /// sufficient size.
    void        copyFrom(const CE_BufferDevice<T> &b, exint len = -1);

    friend void swap(CE_BufferDevice<T>& a, CE_BufferDevice<T> &b)
    {
        UTswap(a.myBuffer, b.myBuffer);
        UTswap(a.mySize, b.mySize);
    }

private:

    void                initInternal(exint size, bool doalloc=true);

    const cl::Buffer    &allocBuffer() const;

    void                releaseBuffer();

    mutable cl::Buffer  myBuffer;
    exint               mySize;
};

template <typename T>
SYS_FORCE_INLINE void
CE_BufferDevice<T>::initInternal(exint size, bool doalloc)
{
    releaseBuffer();
    mySize = size;
    if (mySize > 0 && doalloc)
        allocBuffer();
}

// Some of these methods *MUST* be forced inline to avoid windows MSVC/clang
// bugs that result in linker errors about multiply-defined symbols found on
// Opt/Release builds.
template <typename T>
SYS_FORCE_INLINE void
CE_BufferDevice<T>::init(exint size)
{
    initInternal(size, true);
}

template <typename T>
void
CE_BufferDevice<T>::initFromArray(const UT_Array<T> &src, exint len, bool blocking)
{
    utZoneScopedFlag(CL_MEMORY);
    size_t size = src.size();
    // len < 0 (the default) indicates copy the whole array.
    UT_ASSERT(len < 0 || len <= size);
    if (len >= 0 && len <= size)
        size = len;
    init(size);
    if (!size)
        return;
    size_t totalsize = size * sizeof(T);
    CE_Context *context = CE_Context::getContext();
    context->writeBuffer(myBuffer, totalsize, src.data(), blocking);
}

template <typename T>
void
CE_BufferDevice<T>::matchAndCopyToArray(UT_Array<T> &dst, exint len,
                                        bool blocking) const
{
    utZoneScopedFlag(CL_MEMORY);
    size_t size = mySize;
    // len < 0 (the default) indicates copy the whole array.
    UT_ASSERT(len < 0 || len <= size);
    if (len >= 0 && len <= size)
        size = len;
    dst.setSizeNoInit(size);
    if (size == 0)
        return;
    CE_Context *context = CE_Context::getContext();
    size_t totalsize = size * sizeof(T);
    context->readBuffer(myBuffer, totalsize, dst.data(), blocking);
}

template <typename T>
void
CE_BufferDevice<T>::initFromData(const T *data, exint nelem, bool blocking)
{
    utZoneScopedFlag(CL_MEMORY);
    init(nelem);
    if (!nelem)
        return;
    size_t totalsize = nelem * sizeof(T);
    CE_Context *context = CE_Context::getContext();
    context->writeBuffer(myBuffer, totalsize, data, blocking);
}

template <typename T>
SYS_FORCE_INLINE const cl::Buffer&
CE_BufferDevice<T>::allocBuffer() const
{
    UT_ASSERT(mySize > 0);
    CE_Context *context = CE_Context::getContext();
    myBuffer = context->allocBuffer(mySize * sizeof(T));
    return myBuffer;
}

template <typename T>
SYS_FORCE_INLINE void
CE_BufferDevice<T>::releaseBuffer()
{
    // This is a no-op for a null buffer.
    CE_Context::getContext()->releaseBuffer(std::move(myBuffer));
    myBuffer = cl::Buffer();
}

template <typename T>
void
CE_BufferDevice<T>::copyFrom(const CE_BufferDevice<T> &v, exint len)
{
    CE_Context *context = CE_Context::getContext();
    size_t size = v.size();
    // len < 0 (the default) indicates copy the whole array.
    UT_ASSERT(len < 0 || len <= size);
    if (len >= 0)
        size = len;
    // Make sure we are allocated and large enough for the copy.
    UT_ASSERT(myBuffer() && size <= mySize);
    size_t totalsize = size * sizeof(T);
    context->copyBuffer(v.buffer(), myBuffer, totalsize);
}

using CE_BufferDeviceByte = CE_BufferDevice<uint8>;

CE_EXTERN_TEMPLATE(CE_BufferDevice<uint8>);
CE_EXTERN_TEMPLATE(CE_BufferDevice<uint16>);
CE_EXTERN_TEMPLATE(CE_BufferDevice<uint32>);
CE_EXTERN_TEMPLATE(CE_BufferDevice<uint64>);
CE_EXTERN_TEMPLATE(CE_BufferDevice<int8>);
CE_EXTERN_TEMPLATE(CE_BufferDevice<int16>);
CE_EXTERN_TEMPLATE(CE_BufferDevice<int32>);
CE_EXTERN_TEMPLATE(CE_BufferDevice<int64>);
CE_EXTERN_TEMPLATE(CE_BufferDevice<fpreal16>);
CE_EXTERN_TEMPLATE(CE_BufferDevice<fpreal32>);
CE_EXTERN_TEMPLATE(CE_BufferDevice<fpreal64>);

#endif