CE_Image.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.
 *
 */

#ifndef __CE_IMAGE__
#define __CE_IMAGE__

#include "CE_API.h"

#include <UT/UT_NonCopyable.h>
#include <UT/UT_VectorTypes.h>
#include <UT/UT_VoxelArray.h>

#include <SYS/SYS_Inline.h>
#include <SYS/SYS_Types.h>

/// This class represents OpenCL storage of an image (a 2-dimensional
/// rectangular grid of pixels with 1-4 floating point channels).
class CE_API CE_Image
{
public:
    /// Type of data stored in this buffer. This enum must be in sync with
    /// storage types defined in the imx.h OpenCL header.
    enum StorageType
    {
        INT8 = 0,
        INT16,
        INT32,
        FLOAT16,
        FLOAT32,
        FIXED8,
        FIXED16
    };
    static const char* getName(StorageType);
    static StorageType storageTypeFromName(const char *name);
    /// String used in snippets to identify the storage type.
    static const char* getStorageString(StorageType);
    static bool storesIntegers(StorageType t) { return t < FLOAT16; }
    static bool isFixedPoint(StorageType t) { return t >= FIXED8; }
    static int getBytes(StorageType t)
    { return (t == INT8 || t == FIXED8) ? 1 :
             ((t == INT16 || t == FLOAT16 || t == FIXED16) ? 2 : 4); }

public:
    /// Creates a new uninitialized object. Call setSize() to allocate memory.
    CE_Image();
    ~CE_Image();

    UT_NON_COPYABLE(CE_Image)

    /// Copies data into this image from other. If sizes are different between
    /// the two,
    ///     - nothing is done if force is false,
    ///     - this buffer is resized, then the copy performed if force is true.
    /// Returns true if copying was done, false otherwise.
    bool copy(const CE_Image& other, bool force = false);

    /// Swaps the backing buffers between the two objects.
    void swap(CE_Image& other);

    /// Returns true if this buffer is allocated and usable.
    SYS_FORCE_INLINE bool isValid() const
    {
        return myBuffer() != 0;
    }

    /// Resizes this buffer; allocated memory is uninitialized.
    void setSize(int width, int height, int channels,
                 StorageType storage);
    
    /// Resizes this buffer to match the other image. Allocated memory is not
    /// initialized.
    void match(const CE_Image& other);
    
    /// Resizes this buffer to match the voxel array and copies its data into
    /// the image. Z-resolution of src should be 1.
    /// Number of channels is set based on T (which can be float, UT_Vector2F,
    /// UT_Vector3F, UT_Vector4F, or int64).
    template <typename T>
    void initFromVoxels(const UT_VoxelArray<T>& src);

    /// Releases memory held by this buffer. setSize() must be called to make
    /// this object usable again.
    void destroy();

    /// Upload data into this image from src. If blocking is true, the copying
    /// will be complete by the time the function returns; otherwise, the
    /// operation is simply queued up.
    void readIn(const void* src, bool blocking = true);

    /// Download data from this image into dst. If blocking is true, the copying
    /// will be complete by the time the function returns; otherwise, the
    /// operation is only queued up.
    void writeOut(void* dst, bool blocking = true) const;
    
    /// Resizes dest to match dimensions of this image (its Z-resolution is set
    /// to 1). Number of channels in this image should equal tuple size of T.
    /// This function also downloads the image's data into dest.
    template <typename T>
    void matchAndCopyToVoxels(UT_VoxelArray<T>& dest) const;

    /// Returns this buffer descriptor.
    const cl::Buffer& buffer() const
    {
        return myBuffer;
    }

    /// Total memory in bytes needed to hold this image's data.
    int64 totalMemory() const;
    /// Total memory in bytes needed to hold an image with the given properties.
    static int64 totalMemory(exint width, exint height, exint channels,
                             StorageType storage);

    /// Returns the image's width.
    int getWidth() const
    {
        return myWidth;
    }

    /// Returns the image's height.
    int getHeight() const
    {
        return myHeight;
    }

    /// Returns the number of channels per pixel.
    int getChannels() const
    {
        return myChannels;
    }

    /// Identifies the type of data stored for each channel of every pixel.
    StorageType getStorage() const
    {
        return myStorage;
    }

    /// Bind a 2D kernel with one work item per pixel.
    cl::KernelFunctor bind(cl::Kernel k) const;

    /// Sets this buffer to the given constant value.
    void setValue(const UT_Vector4F& val);
    void setValue(int val);

    /// Converts the given voxel coordinates to the normalized [0..1]^3 space in
    /// the same way as done in UT_VoxelArray.
    bool indexToPos(int x, int y, int z, UT_Vector3F& pos) const
    {
        return indexToPos(x, y, z, pos, myWidth, myHeight);
    }
    /// Converts the given voxel coordinates to the normalized [0..1]^3 space in
    /// the same way as done in UT_VoxelArray. This static version of the method
    /// must be provided with width and height.
    static bool indexToPos(int x, int y, int z, UT_Vector3F& pos, int w, int h);

protected:
    /// OpenCL descriptor for the actual GPU buffer.
    cl::Buffer                  myBuffer;
    /// Sizes of the buffer.
    int                         myWidth;
    int                         myHeight;
    int                         myChannels;
    StorageType                 myStorage;
};

/// This function can be used to convert a flat array (of specified storage)
/// into a 2D voxel array of vectors, integers, or floats. The destination voxel
/// array must have its size already initialized. src must be of size
///     X_RES * Y_RES * TUPLE_SIZE_OF_T * BYTES_FOR_STORAGE
/// and its layout must be {layers of x-pixels}, where each is {pixel data}, and
/// each one of those is {component0, component1, ...} (every component's type
/// is controlled by the storage specifier), everything tightly packed.
template <typename T>
void CE_API CEfillVoxelArrayFromFlatStorage(UT_VoxelArray<T>& dest,
                                            const void* src,
                                            CE_Image::StorageType storage);
/// This function can be used to convert a 2D voxel array of vectors, integers,
/// or floats into a flat array of specified storage. The source array must have
/// Z-resolution of 1. dest must be of size
///     X_RES * Y_RES * TUPLE_SIZE_OF_T * BYTES_FOR_STORAGE
/// and its final layout will be
///     {layers of y-pixels: {layers of x-pixels: {comp0, comp1, ...}}}
/// That is, every component of every pixel along the first row, followed by the
/// second row, etc.
template <typename T>
void CE_API CEfillFlatStorageFromVoxelArray(void* dest,
                                            const UT_VoxelArray<T>& src,
                                            CE_Image::StorageType storage);

/// Type traits for a given storage type...
template <CE_Image::StorageType STORAGE>
struct CE_StorageTypeTraits
{
    typedef void            DataType;
    static const int        DataSize = 0;
};
// ...and its concrete specializations.
template <>
struct CE_StorageTypeTraits<CE_Image::FIXED16>
{
    typedef short           DataType;
    static const int        DataSize = sizeof(DataType);
};
template <>
struct CE_StorageTypeTraits<CE_Image::FIXED8>
{
    typedef unsigned char   DataType;
    static const int        DataSize = sizeof(DataType);
};
template <>
struct CE_StorageTypeTraits<CE_Image::FLOAT32>
{
    typedef fpreal32        DataType;
    static const int        DataSize = sizeof(DataType);
};
template <>
struct CE_StorageTypeTraits<CE_Image::FLOAT16>
{
    typedef fpreal16        DataType;
    static const int        DataSize = sizeof(DataType);
};
template <>
struct CE_StorageTypeTraits<CE_Image::INT32>
{
    typedef int             DataType;
    static const int        DataSize = sizeof(DataType);
};
template <>
struct CE_StorageTypeTraits<CE_Image::INT16>
{
    typedef short           DataType;
    static const int        DataSize = sizeof(DataType);
};
template <>
struct CE_StorageTypeTraits<CE_Image::INT8>
{
    typedef unsigned char   DataType;
    static const int        DataSize = sizeof(DataType);
};

/******************************************************************************
 * DATA CONVERTERS
 ******************************************************************************/

/// Templated functions for converting to and from values that are stored in a
/// CE_Image (storage-aware).
template <CE_Image::StorageType STORAGE, typename SCALAR_TYPE>
struct CE_ImageValueConverter
{
    using CE_SCALAR_TYPE = typename CE_StorageTypeTraits<STORAGE>::DataType;

    static SYS_FORCE_INLINE CE_SCALAR_TYPE
    toCEImage(SCALAR_TYPE v)
    {
        return CE_SCALAR_TYPE(v);
    }
    static SYS_FORCE_INLINE SCALAR_TYPE
    fromCEImage(CE_SCALAR_TYPE v)
    {
        return SCALAR_TYPE(v);
    }
};
/// Fixed points specialization for 8-bit.
template <typename SCALAR_TYPE>
struct CE_ImageValueConverter<CE_Image::StorageType::FIXED8, SCALAR_TYPE>
{
    static constexpr CE_Image::StorageType STORAGE =
        CE_Image::StorageType::FIXED8;
    using CE_SCALAR_TYPE = typename CE_StorageTypeTraits<STORAGE>::DataType;
    static constexpr CE_SCALAR_TYPE ONE_POINT =
        std::numeric_limits<CE_SCALAR_TYPE>::max();

    static SYS_FORCE_INLINE CE_SCALAR_TYPE
    toCEImage(SCALAR_TYPE v)
    {
        return CE_SCALAR_TYPE(SYSclamp(v, SCALAR_TYPE(0), SCALAR_TYPE(1))
                              * ONE_POINT);
    }
    static SYS_FORCE_INLINE SCALAR_TYPE
    fromCEImage(CE_SCALAR_TYPE v)
    {
        return SCALAR_TYPE(v) / SCALAR_TYPE(ONE_POINT);
    }
};
/// Fixed points specialization for 16-bit.
template <typename SCALAR_TYPE>
struct CE_ImageValueConverter<CE_Image::StorageType::FIXED16, SCALAR_TYPE>
{
    static constexpr CE_Image::StorageType STORAGE =
        CE_Image::StorageType::FIXED16;
    using CE_SCALAR_TYPE = typename CE_StorageTypeTraits<STORAGE>::DataType;
    static constexpr CE_SCALAR_TYPE ONE_POINT =
        std::numeric_limits<CE_SCALAR_TYPE>::max();

    static SYS_FORCE_INLINE CE_SCALAR_TYPE
    toCEImage(SCALAR_TYPE v)
    {
        return CE_SCALAR_TYPE(SYSclamp(v, SCALAR_TYPE(-1), SCALAR_TYPE(1))
                              * ONE_POINT);
    }
    static SYS_FORCE_INLINE SCALAR_TYPE
    fromCEImage(CE_SCALAR_TYPE v)
    {
        return SCALAR_TYPE(v) / SCALAR_TYPE(ONE_POINT);
    }
};

/// Templated function for converting between different storage types.
template <CE_Image::StorageType FROM, CE_Image::StorageType TO>
struct CE_ImageDataConverter
{
    using FROM_SCALAR_TYPE = typename CE_StorageTypeTraits<FROM>::DataType;
    using TO_SCALAR_TYPE = typename CE_StorageTypeTraits<TO>::DataType;
    using INTERMEDIATE_CONVERTER = CE_ImageValueConverter<FROM, float>;
    using FINAL_CONVERTER = CE_ImageValueConverter<TO, float>;

    static SYS_FORCE_INLINE TO_SCALAR_TYPE
    convert(FROM_SCALAR_TYPE v)
    {
        return FINAL_CONVERTER::toCEImage(
                    INTERMEDIATE_CONVERTER::fromCEImage(v));
    }
};
/// Optimized specialization to forego all conversion if source and destination
/// storage types are the same.
template <CE_Image::StorageType STORAGE>
struct CE_ImageDataConverter<STORAGE, STORAGE>
{
    using FROM_SCALAR_TYPE = typename CE_StorageTypeTraits<STORAGE>::DataType;
    using TO_SCALAR_TYPE = typename CE_StorageTypeTraits<STORAGE>::DataType;

    static SYS_FORCE_INLINE TO_SCALAR_TYPE
    convert(FROM_SCALAR_TYPE v)
    {
        return v;
    }
};

#endif