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_BufferDevice.h"
#include "CE_Context.h"

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

/// 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 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() {}

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

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

        exint src_nelem = src.size() / src_tuplesize;
        exint dst_nelem = size() / dst_tuplesize;
        if (nelements < 0)
            nelements = SYSmin(src_nelem - src_offset, dst_nelem - dst_offset);

        UT_ASSERT(src_offset >= 0 && dst_offset >= 0 &&
                  (src_nelem - src_offset) >= nelements &&
                  (dst_nelem - dst_offset) >= nelements);

        if (nelements > 0)
        {
            UT_WorkBuffer wb;
            wb.append(" -D CEARRAY_VALUE_");
            appendElemType<V>(wb);
            const char *opt = wb.buffer();
            cl::Kernel k = loadKernel("convertFrom", opt);

            CE_Context *context = CE_Context::getContext();
            cl::NDRange global_range, local_range;
            context->get1DRanges(k, nelements, global_range, local_range);
            cl::KernelFunctor convert_from = k.bind(context->getQueue(),
                                                    global_range, local_range);

            convert_from(src.buffer(), buffer(),
                         src_tuplesize, dst_tuplesize,
                         src_offset, dst_offset,
                         nelements, scalarKernelArg(default_value));
        }
    }

    /// 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, 
                   bool oneifnonzero=false);

    void 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.  Note the underlying buffer object could
    /// change for an odd number of internal sorting passes.
    /// maxbits limits the number of significant bits to consider
    /// if greater than zero.
    void sort(bool is_descending = false, int maxbits = 0)
    {
        CE_Array<T> emptyvals;
        sortInternal(emptyvals, is_descending, maxbits);
    }

    /// Sort the array and the values.  Note the underlying buffer
    /// objects could change for an odd number of internal sorting passes.
    /// maxbits limits the number of significant bits to consider
    /// if greater than zero.
    template <typename V>
    void sortValues(CE_Array<V> &vals, bool is_descending = false, int maxbits = 0)
    {
        UT_ASSERT(vals.size() == CE_BufferDevice<T>::size());
        sortInternal(vals, 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;
    reduce_t minAbs(int tuplesize = 1, int comp = 0) const ;
    reduce_t max(int tuplesize = 1, int comp = 0) const;
    reduce_t maxAbs(int tuplesize = 1, int comp = 0) const;
    reduce_t sum(int tuplesize = 1, int comp = 0) const;
    reduce_t sumAbs(int tuplesize = 1, int comp = 0) const;
    reduce_t sumSqr(int tuplesize = 1, int comp = 0) const;

    fpreal64 average(int tuplesize = 1, int comp = 0) const
    {
        exint tuplecount = CE_BufferDevice<T>::size() / tuplesize;
        fpreal64 fsum = static_cast<fpreal64>(sum(tuplesize, comp));
        return fsum / tuplecount;
    }

    fpreal64 rms(int tuplesize = 1, int comp = 0) const
    {
        exint tuplecount = CE_BufferDevice<T>::size() / tuplesize;
        fpreal64 ms = static_cast<fpreal64>(sumSqr(tuplesize, comp));
        ms /= tuplecount;
        return SYSsqrt(ms);
    }

    reduce_t dot(const CE_Array<T> &b) const;

    void constant(T cval);

    // Reorder the array to the ordering in the supplied
    // order array.
    void reorder(const CE_Array<uint32_t> &order);

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

protected:

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

    reduce_t doReduce(const char *reduce_flags, const CE_Array<T> *a,
                   int tuplesize = 1, int comp = 0) const;

    template <typename V>
    V reduceGroup(CE_Array<V> &out, uint groupsize,
                  const char *reduce_flags) const;

    // Internal sort functions.
    template <typename V>
    void sortInternal(CE_Array<V> &vals, bool is_descending, int maxbits);

    // Appends a type name we use as part of type defines in array.cl
    template <typename V>
    static void appendElemType(UT_WorkBuffer &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 reorderBuffer(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());
}

// We need to include this here since it is templated
// on the value type as well.
#include "CE_ArraySortImpl.h"

#endif