CE_Array.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_Array.h ( CE Library, C++)
 *
 * COMMENTS: UT_Array style class on GPU.
 */

#ifndef __CE_Array__
#define __CE_Array__


#include "CE_API.h"
#include "CE_ArrayView.h"
#include "CE_BufferDevice.h"
#include "CE_Context.h"

#include <SYS/SYS_TypeTraits.h>
#include <UT/UT_Array.h>
#include <UT/UT_WorkBuffer.h>

#include <limits>

/// A simple OpenCL-based array class.
template <typename T>
class CE_API CE_Array: public CE_BufferDevice<T>
{
public:

    typedef T    value_type;

    exint       size() const { return CE_BufferDevice<T>::size(); }
    bool        isEmpty() const { return CE_BufferDevice<T>::isEmpty(); }
    void        init(exint size) { return CE_BufferDevice<T>::init(size); }
    const cl::Buffer &buffer() const { return CE_BufferDevice<T>::buffer(); }

    /// Initialize to empty,
    /// and init must be called later with the desired size.
    CE_Array():
        CE_BufferDevice<T>() {}

    /// Initialize to given size.
    /// Size can be zero in which case no allocation is done,
    /// and init must be called later with the desired size.
    CE_Array(exint size):
        CE_BufferDevice<T>(size) {}

    /// Move construct 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_Array(cl::Buffer &&buf, exint size = -1):
        CE_BufferDevice<T>(std::move(buf), size) {}

    /// Copy constructor. It duplicates the data.
    /// It's marked explicit so that it's not accidentally passed by value.
    explicit CE_Array(const CE_Array<T> &a): CE_BufferDevice<T>()
    {
        CE_BufferDevice<T>::init(a.size());
        CE_BufferDevice<T>::copyFrom(a);
    }
    
    /// Move constructor. Steals the buffer from the original.
    CE_Array(CE_Array<T> &&a) noexcept:
        CE_BufferDevice<T>(std::move(a)) {}

    /// Move constructor. Steals the buffer from the original.
    CE_Array(CE_BufferDevice<T> &&b) noexcept:
        CE_BufferDevice<T>(std::move(b)) {}

    /// Move assignment.  Note that copy assignment is intentionally
    /// deleted.
    CE_Array<T> &operator=(CE_Array<T> &&other)
    { swap(*this, other); other.init(0);  return *this; }
    CE_Array<T> &operator=(const CE_Array<T> &other) = delete;

    /// CE_BufferDevice base class will release buffer.
    ~CE_Array() {}

    // Returns a fixed view of this array, which cannot resize or reallocate.
    CE_ArrayView<T>         view() 
                            { return CE_BufferDevice<T>::template arrayView<T>(); }
    const CE_ArrayView<T>   view() const
                            { return CE_BufferDevice<T>::template arrayView<T>(); }

    /// Initalize the array of elements of type T that are at the offset
    /// within type V in the buffer.
    template <typename V>
    void initFromBuffer(const CE_BufferDevice<V> &src, int offset)
    {
        CE_BufferDevice<T>::init(src.size());
        cl::size_t<3> src_origin, dst_origin, region;
        // 2D copy starts at offset in src.
        src_origin[0] = offset;
        src_origin[1] = 0;
        src_origin[2] = 0;
        
        // Destination is origin of this array.        
        dst_origin[0] = 0;
        dst_origin[1] = 0;
        dst_origin[2] = 0;
        
        // The region is sizeof(T) bytes across, and size() long.
        region[0] = sizeof(T);
        region[1] = src.size();
        region[2] = 1;

        // Each src row is sizeof<V> bytes across, each dst row is sizeof(T).
        size_t src_row_pitch = sizeof(V);
        size_t dst_row_pitch = sizeof(T);

        const cl::CommandQueue &q = CE_Context::getContext()->getQueue();
        q.enqueueCopyBufferRect(src.buffer(), CE_BufferDevice<T>::buffer(),
                                src_origin, dst_origin, region,
                                src_row_pitch, 0, dst_row_pitch, 0);
    }

    /// Initialize the array from an array of another type and/or tuple size.
    /// Extra tuple components in the source array are discarded. 
    /// Extra tuple components in the destination array are set to the default.
    /// It's up to the caller to ensure that the types can convert with
    /// sufficient precision.
    template <typename V>
    void initAndConvertFrom(const CE_Array<V> &src,
                            int src_tuplesize = 1, int dst_tuplesize = 1,
                            T default_value = 0)
    {
        UT_ASSERT(src_tuplesize >= 1 && dst_tuplesize >= 1);
        if (!(src_tuplesize >= 1 && dst_tuplesize >= 1))
            return;

        exint nelem = src.size() / src_tuplesize;
        init(nelem * dst_tuplesize);
        convertFrom(src, src_tuplesize, dst_tuplesize, 0, 0, nelem, default_value);
    }

    /// The same as initAndConvertFrom(), except this converts a selection of
    /// tuples listed in the index array. The indices should be in the range
    /// [0, src.size()/src_tuplesize - 1].
    template <typename V, typename I>
    void initAndConvertFromIndices(const CE_Array<V> &src,
                                   const CE_Array<I> &indices,
                                   int src_tuplesize = 1, int dst_tuplesize = 1,
                                   T default_value = 0)
    {
        SYS_STATIC_ASSERT(SYS_IsIntegral_v<I>);
        UT_ASSERT(src_tuplesize >= 1 && dst_tuplesize >= 1);
        if (!(src_tuplesize >= 1 && dst_tuplesize >= 1))
            return;

        init(indices.size() * dst_tuplesize);
        convertFromIndices(src, indices,
                           src_tuplesize, dst_tuplesize,
                           0, default_value);
    }

    /// Copy/convert data from an array of another type and/or tuple size.
    /// Does not allocate or reallocate this array's underlying cl::Buffer.
    /// Extra tuple components in the source array are discarded.
    /// Extra tuple components in the destination array are set to the default.
    /// It's up to the caller to ensure that the types can convert with
    /// sufficient precision.
    /// src_offset, dst_offset, and nelements each expect a number of tuples.
    /// If nelements >= 0, only the given number of tuples are copied.
    template <typename V>
    void convertFrom(const CE_Array<V> &src,
                     int src_tuplesize = 1, int dst_tuplesize = 1,
                     exint src_offset = 0, exint dst_offset = 0,
                     exint nelements = -1, T default_value = 0)
    {
        UT_ASSERT(src_tuplesize >= 1 && dst_tuplesize >= 1);
        if (!(src_tuplesize >= 1 && dst_tuplesize >= 1))
            return;

        view().convertFrom(src.view(),
                           src_tuplesize, dst_tuplesize,
                           src_offset, dst_offset,
                           nelements, default_value);
    }

    /// The same as convertFrom(), except this converts a selection of
    /// tuples listed in the index array. The indices should be in the range
    /// [0, src.size()/src_tuplesize - 1].
    template <typename V, typename I>
    void convertFromIndices(const CE_Array<V> &src,
                            const CE_Array<I> &indices,
                            int src_tuplesize = 1, int dst_tuplesize = 1,
                            exint dst_offset = 0,
                            T default_value = 0)
    {
        view().convertFromIndices(src.view(), indices.view(),
                                  src_tuplesize, dst_tuplesize,
                                  dst_offset,
                                  default_value);
    }

    /// Extract the channel from this into dst.
    void extractChannel(CE_Array<T> &dst, int tuplesize, int comp) const;

    /// Insert the channel from src into this.
    void insertChannel(const CE_Array<T> &src, int tuplesize, int comp);

    /// Sum entries of this into dst.  exclusive true will have dst
    /// elements only include the values of this strictly prior to itself.
    /// oneifnonzero will count number of non-zero entries in this.
    void prefixSum(CE_Array<T> &dst, bool exclusive=true, 
                   CE_ScanOp op = CE_ScanOp::ADD) const
    {
        CE_ArrayView<T> dstview = dst.view();
        view().prefixSum(dstview, exclusive, op);
    }

    void iota()
    {
        view().iota();
    }

    /// Reads a single value from the array, blocking.
    ///  May throw CE Exceptions
    T           readValue(int idx) const;
    /// Writes a single value to the array.
    ///  May throw CE Exceptions
    void        writeValue(int idx, const T &val, bool blocking=true);

    /// Sort the array.
    void sort(bool is_descending = false, int maxbits = 0)
    {
        view().sort(is_descending, maxbits);
    }

    /// Sort the array and the values.
    template <typename V>
    void sortValues(CE_Array<V> &vals, bool is_descending = false, int maxbits = 0)
    {
        CE_ArrayView<V> valsview = vals.view();
        view().sortValues(valsview, is_descending, maxbits);
    }

    /// Reduce to long for integral types and fpreal64 for floats,
    /// since the caller can always downcast after the fact if desired.
    using reduce_t = typename std::conditional<std::is_integral<T>::value,
                                                   exint, fpreal64>::type;

    reduce_t min(int tuplesize = 1, int comp = 0) const
             { return view().min(tuplesize, comp); }
    reduce_t minAbs(int tuplesize = 1, int comp = 0) const
             { return view().minAbs(tuplesize, comp); }
    reduce_t minLength(int tuplesize = 1) const
             { return view().minLength(tuplesize); }
    reduce_t max(int tuplesize = 1, int comp = 0) const
             { return view().max(tuplesize, comp); }
    reduce_t maxAbs(int tuplesize = 1, int comp = 0) const
             { return view().maxAbs(tuplesize, comp); }
    reduce_t maxLength(int tuplesize = 1) const
             { return view().maxLength(tuplesize); }
    reduce_t sum(int tuplesize = 1, int comp = 0) const
             { return view().sum(tuplesize, comp); }
    reduce_t sumAbs(int tuplesize = 1, int comp = 0) const
             { return view().sumAbs(tuplesize, comp); }
    reduce_t sumSqr(int tuplesize = 1, int comp = 0) const
             { return view().sumSqr(tuplesize, comp); }

    fpreal64 average(int tuplesize = 1, int comp = 0) const
             { return view().average(tuplesize, comp); }
    fpreal64 rms(int tuplesize = 1, int comp = 0) const
             { return view().rms(tuplesize, comp); }

    reduce_t dot(const CE_Array<T> &b) const
             { return view().dot(b.view()); }
            
    void     constant(T cval)
             { return view().constant(cval); }

    // Reorder the array to the ordering in the supplied order array.
    template <typename I>
    void     reorder(const CE_Array<I> &order)
             { return view().reorder(order.view()); }
         

    cl::KernelFunctor bind(cl::Kernel &k) const;
    cl::KernelFunctor bind(const char *kernel_name) const;

private:

    cl::Kernel loadKernel(const char *kernel_name,
                          const char *opt = NULL) const;

    // Appends a type name we use as part of type defines in array.cl
    template <typename V>
    static void appendElemType(UT_WorkBuffer &wb)
    {
        CE_ArrayView<T>::template appendElemType<V>(wb);
    }
    
    // Promote 16-bit float kernel arguments to 32-bit float.
    using scalar_arg_t = typename std::conditional_t<
                    std::is_same_v<T, fpreal16>,
                    fpreal32, T>;

    scalar_arg_t scalarKernelArg(T v) { return static_cast<scalar_arg_t>(v); }
};
// Exported instantiantions from libCE:
CE_EXTERN_TEMPLATE(CE_Array<uint8>);
CE_EXTERN_TEMPLATE(CE_Array<uint16>);
CE_EXTERN_TEMPLATE(CE_Array<uint32>);
CE_EXTERN_TEMPLATE(CE_Array<uint64>);
CE_EXTERN_TEMPLATE(CE_Array<int8>);
CE_EXTERN_TEMPLATE(CE_Array<int16>);
CE_EXTERN_TEMPLATE(CE_Array<int32>);
CE_EXTERN_TEMPLATE(CE_Array<int64>);
CE_EXTERN_TEMPLATE(CE_Array<fpreal16>);
CE_EXTERN_TEMPLATE(CE_Array<fpreal32>);
CE_EXTERN_TEMPLATE(CE_Array<fpreal64>);

// Convenience array names
typedef CE_Array<int>       CE_Int32Array;
typedef CE_Array<uint32_t>  CE_UInt32Array;
typedef CE_Array<float>     CE_FloatArray;

// Reorder the input buffer to the ordering in the supplied
// order array.
template <typename V>
void
CEreorderBuffer(
        const CE_BufferDevice<V> &src,
        CE_BufferDevice<V> &dst,
        const CE_UInt32Array &order)
{
    exint nelem = src.size();
    UT_ASSERT(nelem == order.size());
    dst.init(nelem);
    cl::KernelFunctor reorder = order.bind("buffer_reorder");
    int elemsize = sizeof(V);
    reorder(src.buffer(), dst.buffer(), nelem, elemsize, order.buffer());
}

#endif