CE_ArrayView.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_ArrayView.h ( CE Library, C++)
 *
 * COMMENTS: Compute Engine Array View.
 */

#ifndef __CE_ArrayView__
#define __CE_ArrayView__


#include "CE_API.h"
#include "CE_Context.h"

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

#include <limits>

template <typename T>
class CE_BufferDevice;

template <typename T>
class CE_Array;

/// CE_Array prefix sum operators.
enum class CE_ScanOp
{
    ADD,
    MIN,
    MAX,
    COUNT_NONZERO
};

/// Shares an existing OpenCL buffer and views it as an array.
/// The lifetime of the shared buffer must exceed the lifetime of this object.
template <typename T>
class CE_API CE_ArrayView
{
public:
    typedef T    value_type;

    /// Returns the number of elements in the array.
    exint                size() const { return mySize; }
    bool                 isEmpty() const { return mySize == 0; }
    const cl::Buffer    &buffer() const { return myBuffer; }

    /// Size expects the number of elements in the buffer.
    /// If size is not provided, it is calculated from the buffer size.
    CE_ArrayView(const cl::Buffer &b, exint size = -1);
    explicit CE_ArrayView(const CE_BufferDevice<T> &b);

    /// Harden the view into a buffer, which now owns a copy of the array data.
    /// You must include CE_BufferDevice.h to use this.
    CE_BufferDevice<T>   harden() const;

    /// Copy/convert data 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.
    /// 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_ArrayView<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);

    /// 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_ArrayView<V> &src,
                            const CE_ArrayView<I> &indices,
                            int src_tuplesize = 1, int dst_tuplesize = 1,
                            exint dst_offset = 0,
                            T default_value = 0);

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

    /// Insert the channel from src into this.
    void insertChannel(const CE_ArrayView<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_ArrayView<T> &dst, bool exclusive=true, 
                   CE_ScanOp op = CE_ScanOp::ADD) const;

    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);
    /// Reads the entire array into a UT_Array, resizing UT_Array
    /// to be our size.
    /// May throw CE Exceptions.
    void        readIntoArray(UT_Array<T> &array) const;

    /// Sort the array.
    void sort(bool is_descending = false, int maxbits = 0)
    {
        cl::Buffer emptybuf;
        CE_ArrayView<T> emptyvals(emptybuf);
        sortInternal(emptyvals, is_descending, maxbits);
    }

    /// Sort the array and the values.
    template <typename V>
    void sortValues(CE_ArrayView<V> &vals, bool is_descending = false, int maxbits = 0)
    {
        UT_ASSERT(vals.size() == 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 minLength(int tuplesize = 1) const;
    reduce_t max(int tuplesize = 1, int comp = 0) const;
    reduce_t maxAbs(int tuplesize = 1, int comp = 0) const;
    reduce_t maxLength(int tuplesize = 1) 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 = size() / tuplesize;
        fpreal64 fsum = static_cast<fpreal64>(sum(tuplesize, comp));
        return fsum / tuplecount;
    }

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

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

    void constant(T cval);

    // Reorder the array to the ordering in the supplied order array.
    template <typename I>
    void reorder(const CE_ArrayView<I> &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_ArrayView<T> *a,
                   int tuplesize = 1, int comp = 0) const;

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

    // Internal sort functions.
    template <typename V>
    void sortInternal(CE_ArrayView<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); }

    template <typename V>
    class Buffer;

    template <typename V>
    friend class CE_Array;

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

// Exported instantiantions from libCE:
CE_EXTERN_TEMPLATE(CE_ArrayView<uint8>);
CE_EXTERN_TEMPLATE(CE_ArrayView<uint16>);
CE_EXTERN_TEMPLATE(CE_ArrayView<uint32>);
CE_EXTERN_TEMPLATE(CE_ArrayView<uint64>);
CE_EXTERN_TEMPLATE(CE_ArrayView<int8>);
CE_EXTERN_TEMPLATE(CE_ArrayView<int16>);
CE_EXTERN_TEMPLATE(CE_ArrayView<int32>);
CE_EXTERN_TEMPLATE(CE_ArrayView<int64>);
CE_EXTERN_TEMPLATE(CE_ArrayView<fpreal16>);
CE_EXTERN_TEMPLATE(CE_ArrayView<fpreal32>);
CE_EXTERN_TEMPLATE(CE_ArrayView<fpreal64>);

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

#endif