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

#pragma once

#include "IMX_API.h"

#include <CE/CE_Image.h>
#include <CE/CE_Precision.h>
#include <SYS/SYS_Align.h>
#include <SYS/SYS_Compiler.h>
#include <SYS/SYS_Inline.h>
#include <UT/UT_Vector4.h>
#include <UT/UT_Matrix4.h>
#include <UT/UT_SharedPtr.h>

class PXL_Raster;
class TIL_Raster;

// The following enums and the stat structure must exactly match the definitions
// in the imx.h OpenCL header.
/// Controls returned values for coordinates that fall outside the image.
enum class IMX_BorderType
{
    IMX_CONSTANT = 0,
    IMX_CLAMP,
    IMX_MIRROR,
    IMX_WRAP
};
IMX_API size_t format(char *buffer, size_t buffer_size, const IMX_BorderType &v);

enum class IMX_TypeInfo
{
    IMX_NONE = 0,
    IMX_COLOR,
    IMX_POSITION,
    IMX_VECTOR,
    IMX_NORMAL,
    IMX_OFFSETNORMAL,
    IMX_TEXTURE_COORD,
    IMX_ID,
    IMX_MASK,
    IMX_SDF,
    IMX_HEIGHT
};
IMX_API size_t format(char *buffer, size_t buffer_size, const IMX_TypeInfo &v);

/// This structure contains the metadata of an image, including its buffer
/// transform, resolution, and border properties.
struct IMX_Stat
{
    UT_Matrix4F             myImageToWorld;
    UT_Matrix4F             myWorldToImage;

    CEfloatD<CE_32>         myBufferToImage[4] = {0, 0, 0, 0};
    CEfloatD<CE_32>         myImageToBuffer[4] = {0, 0, 0, 0};
    CEfloatD<CE_32>         myBufferToPixel[4] = {0, 0, 0, 0};

    CEfloatD<CE_32>         myDefaultFColor[4] = {0, 0, 0, 0};
    CEintD<CE_32>           myDefaultIColor[4] = {0, 0, 0, 0};

    CEintD<CE_32>           myResolution[2] = {0, 0};
    int                     myChannels = 0;
    int                     myStrideX = 0;
    int                     myStrideY = 0;

    IMX_BorderType          myBorder = IMX_BorderType::IMX_WRAP;
    IMX_TypeInfo            myTypeInfo = IMX_TypeInfo::IMX_NONE;
    CE_Image::StorageType   myStorage = CE_Image::StorageType::FLOAT16;

    bool operator==(const IMX_Stat& other) const
    {
        for (int i = 0; i < 4; i++)
        {
            if (myBufferToImage[i] != other.myBufferToImage[i] || 
                myImageToBuffer[i] != other.myImageToBuffer[i] ||
                myBufferToPixel[i] != other.myBufferToPixel[i] ||
                myDefaultFColor[i] != other.myDefaultFColor[i] ||
                myDefaultIColor[i] != other.myDefaultIColor[i])
            {
                return false;
            }
        }

        if (myImageToWorld != other.myImageToWorld ||
            myWorldToImage != other.myWorldToImage)
        {
            return false;
        }

        if (myResolution[0] != other.myResolution[0] ||
            myResolution[1] != other.myResolution[1])
        {
            return false;
        }

        if (myChannels != other.myChannels || 
            myStrideX != other.myStrideX ||
            myStrideY != other.myStrideY ||
            myBorder != other.myBorder ||
            myTypeInfo != other.myTypeInfo ||
            myStorage != other.myStorage)
        {
            return false;
        }

        return true;
    }

    bool operator!=(const IMX_Stat& other) const
    {
        return !(*this == other);
    }
};

/// The traditional allocator will align to the size of the type, which in this
/// case is char - however, in order to maximize the chances of vectorized
/// instructions being generated, we'll align to the size of the cache line.
///
/// Note: We don't have a cross-platform method to determine the size of the
///       cache line, so we'll just assume 64 bytes.
class IMX_CPU_Image
{
public:
    explicit IMX_CPU_Image() = default;

    explicit IMX_CPU_Image(const exint size)
        : myData((uint8*)SYSamalloc(size, ALIGNMENT))
        , myDataSize(size)
        , myStorageMode(StorageMode::STORE_ALIGNED)
    {
    }

    IMX_CPU_Image(const IMX_CPU_Image &other)
    {
        adoptFromAlignedMalloc(
            (uint8*)SYSamalloc(other.myDataSize, ALIGNMENT), other.myDataSize);
        memcpy(myData, other.myData, other.myDataSize);
    }

    IMX_CPU_Image(IMX_CPU_Image &&other) noexcept
        : myData(other.myData)
        , myDataSize(other.myDataSize)
        , myStorageMode(other.myStorageMode)
    {
        other.myData        = nullptr;
        other.myDataSize    = 0;
        other.myStorageMode = StorageMode::STORE_UNDEFINED;
    }

    IMX_CPU_Image& operator=(const IMX_CPU_Image &other)
    {
        adoptFromAlignedMalloc(
            (uint8*)SYSamalloc(other.myDataSize, ALIGNMENT), other.myDataSize);
        memcpy(myData, other.myData, other.myDataSize);
        return *this;
    }

    void adoptFromAlignedMalloc(void *data, const exint size)
    {
        freeData();

        myData        = (uint8*)data;
        myDataSize    = size;
        myStorageMode = StorageMode::STORE_ALIGNED;
    }

    void adoptFromMalloc(void *data, const exint size)
    {
        freeData();

        myData        = (uint8*)data;
        myDataSize    = size;
        myStorageMode = StorageMode::STORE_MALLOC;
    }

    void adoptFromNew(void *data, const exint size)
    {
        freeData();

        myData        = (uint8*)data;
        myDataSize    = size;
        myStorageMode = StorageMode::STORE_NEW;
    }

    ~IMX_CPU_Image()
    {
        freeData();
    }

    /// The buffer data. It's the user's responsibility to interpret this in
    /// the correct data type. The IMX_CPU_Image retains ownership of this
    /// buffer.
    void *data() const { return myData; }

    /// The size of the buffer data in bytes.
    exint size() const { return myDataSize; }
private:
    const int ALIGNMENT = 64;   // bytes

    enum class StorageMode
    {
        STORE_UNDEFINED,
        STORE_NEW,
        STORE_MALLOC,
        STORE_ALIGNED
    };

    void freeData()
    {
        if (!myData)
            return;

        switch (myStorageMode)
        {
            case StorageMode::STORE_MALLOC:    free(myData);     break;
            case StorageMode::STORE_NEW:       delete[] myData;  break;
            case StorageMode::STORE_ALIGNED:   SYSafree(myData); break;
            case StorageMode::STORE_UNDEFINED: SYS_FALLTHROUGH;
            default: UT_ASSERT(0 && "Unknown storage mode");
        }

        myStorageMode = StorageMode::STORE_UNDEFINED;
        myData        = nullptr;
        myDataSize    = 0;
    }

    uint8       *myData        = nullptr;
    exint        myDataSize    = 0;   // bytes
    StorageMode  myStorageMode = StorageMode::STORE_UNDEFINED;
};

/// The per-pixel data for a single IMX_Layer
///
/// Buffer has several formats to store data in, for instance whether it is on the
/// GPU or CPU. Buffers are converted by copying, or snippets are used to change the
/// OpenCL code reading them. As some translators can work in-place, the format is
/// considered a setting of the Buffer, rather than having different Buffer
/// subclasses for each format.
///
/// This is a first working version of such a buffer, though it's missing a lot
/// of features. There's only one supported format (32-bit float), between 1 and
/// 4 channels. This is stored in an array, flattened over the rows first. There
/// is also GPU storage that this buffer uses. States of these buffers (i.e. do
/// they contain up-to-date information?) are encoded in the two boolean flags
/// (myOnCPU and myOnGPU). When the user asks IMX_Buffer
/// something that must access its storage, that storage is first automatically
/// synchronized before the request is fulfilled.

class IMX_API IMX_Buffer
{
    friend class IMX_Layer;
    friend class COP_OpenFXImage;
public:
    /// Creates a new buffer. You must call setSize to make this buffer usable.
    IMX_Buffer();
    /// Create and call setSize
    IMX_Buffer(int width, int height, CE_Image::StorageType storage, int channels);
    IMX_Buffer(const IMX_Buffer &other) { copy(other); }
    IMX_Buffer(IMX_Buffer && other) noexcept { swap(other); }
    IMX_Buffer(const PXL_Raster &rp);
    ~IMX_Buffer();

    /// Copy everything except the buffer allocations, leaving the buffers dirty.
    /// This avoids any chance that writing pixels to this will modify the original.
    /// It also avoids shared pointer overhead and keeping buffers around longer than needed.
    void copyMetadata(const IMX_Buffer& source);

    /// Set storesIntegers, bytes, channels
    void copyStorageType(const IMX_Buffer& i)
    { setStorageType(i.getStorageType(), i.getChannels()); }
    /// Set storesIntegers, bytes, channels
    void setStorageType(CE_Image::StorageType storage, int channels);
    /// Set storesIntegers, bytes
    void setStorageType(CE_Image::StorageType storage);
    /// Set number of bytes per channel, don't change storesIntegers or channels
    void setStorageBytes(int);
    /// Set channels, don't change storesIntegers or bits
    void setChannels(int channels);
    /// Get the data type used to store pixel data for each channel.
    CE_Image::StorageType getStorageType() const { return myCPUStat.myStorage; }
    /// Does this buffer store integers?
    bool storesIntegers() const { return CE_Image::storesIntegers(myCPUStat.myStorage); }
    /// Get the number of channels per pixel.
    int getChannels() const { return myCPUStat.myChannels; }
    /// Number of bytes per channel
    int getStorageBytes() const { return CE_Image::getBytes(myCPUStat.myStorage); }

    /// Sets size of this buffer.
    void setBufferSize(int width, int height);
    /// Get width (number of columns in a row) of the buffer.
    int bufferWidth() const { return myCPUStat.myResolution[0]; }
    /// Get height (number of rows) of the buffer.
    int bufferHeight() const { return myCPUStat.myResolution[1]; }
    /// Returns the number of bytes required to store the entire buffer.
    int64 getBufferSize() const;

    /// Set transform between image and buffer space
    void setBufferXforms(
        const UT_Vector2F &buffer_to_image_scale,
        const UT_Vector2F &buffer_to_image_xlate,
        const UT_Vector2F &buffer_from_image_scale,
        const UT_Vector2F &buffer_from_image_xlate,
        const UT_Vector2F &buffer_to_pixel_scale,
        const UT_Vector2F &buffer_to_pixel_xlate,
        const UT_Matrix4F &image_to_world,
        const UT_Matrix4F &world_to_image
    );

    /// Sets the border type of this image. Constant means it is zero.
    void setBorder(IMX_BorderType border);
    /// Returns type of the border.
    IMX_BorderType getBorderType() const;

    /// Sets the semantic type info of this image. 
    void setTypeInfo(IMX_TypeInfo typeinfo);
    /// Returns type of the border.
    IMX_TypeInfo getTypeInfo() const;

    /// Set the default color. This is returned for uncalculatable pixels, and
    /// to expand integer vectors from 2,3 to 4.  Other usage is not yet
    /// determined. Initial value is 0,0,0,1 (may change)
    void setDefaultColor(const UT_Vector4F&);
    UT_Vector4F getDefaultColor() const;
    /// return the current integer value, which might be different
    UT_Vector4I getDefaultColorI() const;

    /// Assignment operators; after executing these functions, this buffer will
    /// have the same size and data as other.
    void copy(const IMX_Buffer &other);
    IMX_Buffer &operator=(const IMX_Buffer &other) { copy(other); return *this; }
    /// Deep copy operator. Unlike copy() (which shares the buffers of the
    /// source), this version allocates a new buffer and copies the data into
    /// it.
    /// This can throw CE exceptions.
    void deepCopy(const IMX_Buffer &other);

    void swap(IMX_Buffer &other);
    IMX_Buffer &operator=(IMX_Buffer &&other) { swap(other); return *this; }

    /// True if data in this buffer may be stolen from (or changed) by the verbs
    /// even if it's an input.
    bool stealable() const { return myStealable; }
    /// Can be used to control what stealable() subsequently returns. If set to
    /// true, indicates to the verbs that this buffer may be stolen from.
    void setStealable(bool v) const { myStealable = v; }
    /// True if the buffer pixels line up: width and the transforms from image space match.
    bool isAligned(const IMX_Buffer &src) const;

    /// Only copy the buffer pointers, the stat data is left unchanged
    void copyBuffer(const IMX_Buffer &other);
    /// Move the buffer to this from src, src is left dirty
    void moveBuffer(IMX_Buffer &src);
    /// Stop sharing the buffers (so that writes don't affect other layers that
    /// have called copyBuffer() on this or vice versa).
    void makeBufferUnique();

    /// Adopt a PXL_Raster into the underlying IMX_Buffer. The buffer's storage
    /// type and number of channels must be set before calling.
    /// Steals the PXL_Raster data if compatible.  
    /// Does OCIO transform from raster's space to scene linear if
    /// convert is set.
    void adoptRaster(PXL_Raster &raster, bool convert_colorspace);

    /// copy the buffer, converting betwen storage types if needed and doing a shallow copy
    /// if possible
    void copyOrConvert(const IMX_Buffer& other);

    /// Constructs a TIL_Raster matching our storage/channel depth.
    /// Will be packed.
    /// TIL_Raster is subclass from PXL_Raster.
    UT_UniquePtr<TIL_Raster>    buildRaster() const;

    /// for debugging
    const UT_SharedPtr<IMX_CPU_Image> & CPUBufferPtr() const { return myCPUBuffer; }
    const UT_SharedPtr<CE_Image> & GPUBufferPtr() const { return myGPUBuffer; }

    /// Sets an individual pixel.
    void setPixelV4(int x, int y, const UT_Vector4F& c)
    {
        setPixelV4Internal(x, y, c, true);
    }
    void setPixelF(int x, int y, fpreal32 i)
    {
        setPixelV4Internal(x, y, UT_Vector4F(i, i, i, i), true);
    }
    void setPixelI(int x, int y, int i)
    {
        setPixelIInternal(x, y, i, true);
    }

    /// Fetches the value of an individual pixel.
    UT_Vector4F getPixelV4(int x, int y) const;
    int         getPixelI(int x, int y) const;
    /// Fetches the value at the provided coordinates, using bilinear filtering.
    /// Returns value of the nearest pixel for integer buffers.
    UT_Vector4F getPixelV4(fpreal64 x, fpreal64 y) const;

    /// Return pointer to CPU buffer (caller must ask for correct data type)
    /// If a read buffer is requested and this buffer is constant, the buffer
    /// will be compressed (i.e. of size equal to the number of channels)!
    const fpreal16* getCPUBufferRF16() const { return getCPUBufferR<CE_Image::FLOAT16>(); }
    fpreal16* getCPUBufferWF16() { return getCPUBuffer<CE_Image::FLOAT16>(false,true); }
    const fpreal32* getCPUBufferRF32() const { return getCPUBufferR<CE_Image::FLOAT32>(); }
    fpreal32* getCPUBufferWF32() { return getCPUBuffer<CE_Image::FLOAT32>(false,true); }
    const unsigned char* getCPUBufferRI8() const { return getCPUBufferR<CE_Image::INT8>(); }
    unsigned char* getCPUBufferWI8() { return getCPUBuffer<CE_Image::INT8>(false,true); }
    const int16* getCPUBufferRI16() const { return getCPUBufferR<CE_Image::INT16>(); }
    int16* getCPUBufferWI16() { return getCPUBuffer<CE_Image::INT16>(false,true); }
    const int32* getCPUBufferRI32() const { return getCPUBufferR<CE_Image::INT32>(); }
    int32* getCPUBufferWI32() { return getCPUBuffer<CE_Image::INT32>(false,true); }
    /// Returns a void pointer to the CPU buffer.
    /// If a read-only buffer is requested and this buffer is constant, the
    /// buffer will be compressed (i.e. of size equal to the number of
    /// channels)!
    void* getCPUBuffer(bool read, bool write)
    { return getCPUBufferInternal(read, write, write); }
    /// Returns this buffer's read-only data array.
    /// If this buffer is constant, the buffer will be compressed (i.e. of size
    /// equal to the number of channels)!
    template <CE_Image::StorageType STORAGE>
    const typename CE_StorageTypeTraits<STORAGE>::DataType *getCPUBufferR() const
    {
        return cast<STORAGE>(getCPUBufferRInternal());
    }

    /// Returns this buffer's data array. If read is true, isDirty must
    /// be false. If write is true then it turns off isDirty by setting
    /// isOnCPU() and turning off isOnGPU() (it is assuming caller will actually
    /// write the buffer)
    /// If a read-only buffer is requested and this buffer is constant, the
    /// buffer will be compressed (i.e. of size equal to the number of
    /// channels)!
    template <CE_Image::StorageType STORAGE>
    typename CE_StorageTypeTraits<STORAGE>::DataType *getCPUBuffer(bool read, bool write)
    {
        return cast<STORAGE>(getCPUBufferInternal(read, write, write));
    }

    /// Returns this buffer's GPU storage object. If read is true, isDirty must
    /// be false. If write is true then it turns off isDirty by setting
    /// isOnGPU() and turning off isOnCPU() (it is assuming caller will actually
    /// write the buffer)
    /// When using one of these methods, this buffer must be guarded with the
    /// in-use GPU flag. See setInUseGPUFlag() documentation for more
    /// information.
    /// Can throw CE exceptions.
    CE_Image &getGPUBuffer(bool read, bool write);
    const CE_Image &getGPUBufferR() const;
    CE_Image &getGPUBufferW() { return getGPUBuffer(false, true); }

    /// Returns true if this buffer's data is currently on the GPU.
    bool isOnGPU() const
    {
        return myOnGPU;
    }

    /// Returns true if this buffer's data is currently on the CPU (this is not
    /// necessarily !isOnGPU()).
    bool isOnCPU() const
    {
        return myOnCPU;
    }

    /// Returns whether the GPU data for this image is currently being used by
    /// someone.
    bool isInUseGPU() const
    {
        return myGPUInUseCount.relaxedLoad() != 0;
    }
    /// Increments the user count of our GPU data. If there are no active users
    /// of the GPU data, the memory pool will be able to unload the buffer.
    /// When using one of the getGPUBuffer() methods, the in-use GPU flag must
    /// be set to prevent the GPU data from getting unloaded:
    ///     // Set the in-use flag before grabbing the GPU buffer.
    ///     buffer.setInUseGPUFlag();
    ///     CE_Image& img = buffer.getGPUBufferW();
    ///     // Do stuff with the CE_Image (i.e. queue up an OpenCL command with
    ///     // it, can be asynchronous).
    ///     ...
    ///     // Flip the flag that we set earlier.
    ///     buffer.clearInUseGPUFlag();
    void setInUseGPUFlag() const
    {
        myGPUInUseCount.add(1);
    }
    /// Decrements the user count of our GPU data. If there are no active users
    /// of the GPU data, the memory pool will be able to unload this buffer.
    /// See setInUseGPUFlag() documentation for how these methods must be used.
    /// This method also refreshes the buffer in the eyes of the memory pool,
    /// making it less likely to get evicted.
    void clearInUseGPUFlag() const;

    /// Returns the stat buffer on the GPU, copying it there if necessary.
    /// This can throw CE exceptions.
    cl::Buffer getGPUStat() const;

    /// False if there are computed pixels in the CPU or GPU buffer
    bool isDirty() const { return !myOnGPU && !myOnCPU; }
    /// Turn on isDirty(). It is turned off by getCPU/GPUBuffer with write=true
    void setDirty() { myOnGPU = myOnCPU = myIsConstant = false; }
    /// Frees the pixel memory (also does setDirty())
    void freeBuffers();
    /// Frees all the memory used by buffer
    void destroy();
    /// True if getCPU/GPUBuffer has been done since last freeBuffers()
    bool allocated() const { return myCPUBuffer || myGPUBuffer; }

    /// Make entire image the same color. This is optimized internally to a 1x1
    /// buffer
    void setConstantV4(const UT_Vector4F &i);
    void setConstantV3(const UT_Vector3F &i) { setConstantV4(UT_Vector4F(i, 1)); }
    void setConstantF(fpreal32 i = 0.0f) { setConstantV4(UT_Vector4F(i, i, i, i)); }
    void setConstantI(int32 i = 0);

    /// Marks that this buffer is not initialized. This means that when a read
    /// buffer is requested, we won't bother doing any copying or data
    /// validation. This is useful if you bind this as a read-write layer to a
    /// kernel, but will be doing the initialization in the same kernel. Copying
    /// from an unitialized buffer will inherit this flag without moving any
    /// data. This flag gets cleared when someone writes to this buffer.
    void setUninitialized() { myIsUninitialized = true; }

    bool isConstant() const { return myIsConstant; }

    /// Resizes dest to match dimensions of this image (its Z-resolution is set
    /// to 1) and copies this buffer's data into it. Number of channels in the
    /// image should equal tuple size of T.
    /// If this layer is dirty, simply sizes the voxel array without touching
    /// its values.
    template <typename T>
    void matchAndCopyToVoxels(UT_VoxelArray<T>& dest) const;

private:
    /// Initialize all the fields (used by constructors)
    void init(int width, int height, CE_Image::StorageType storage, int channels);

    /// Gets the CPU buffer, allocate and/or copy the GPU one if necessary. If
    /// expand_constant is true and this buffer is constant, the storage will be
    /// uncompressed before returning a pointer.
    void *getCPUBufferInternal(bool read, bool write, bool expand_constant);
    void *getCPUBufferRInternal() const;
    void *getCPUBufferW()
    {
        return getCPUBufferInternal(false, true, true);
    }
    /// Internal methods to set the pixel value. If expand_constant is true and
    /// this buffer is constant, the storage will be uncompressed first,
    /// retaining any previous data.
    void setPixelV4Internal(int x, int y, const UT_Vector4F& val,
                            bool expand_constant);
    void setPixelIInternal(int x, int y, int val, bool expand_constant);

    /// Queues up commands that transfer this buffer's GPU storage to main
    /// memory. TODO: this is non-blocking, make sure that's okay...
    void unloadFromGPU();

    /// Cast void* pointer to correct type for storage. Includes an assert to make
    /// sure the storage type is the same one this buffer is using.
    template <CE_Image::StorageType STORAGE>
    typename CE_StorageTypeTraits<STORAGE>::DataType *
    cast(void *p)
    {
        UT_ASSERT(STORAGE == myCPUStat.myStorage);
        return (typename CE_StorageTypeTraits<STORAGE>::DataType *) p;
    }
    template <CE_Image::StorageType STORAGE>
    const typename CE_StorageTypeTraits<STORAGE>::DataType *
    cast(const void *p) const
    {
        UT_ASSERT(STORAGE == myCPUStat.myStorage);
        return (const typename CE_StorageTypeTraits<STORAGE>::DataType *) p;
    }

    UT_SharedPtr<IMX_CPU_Image> myCPUBuffer;
    /// All changes to this member (the shared pointer) must be done by the
    /// memory pool!!!
    UT_SharedPtr<CE_Image>      myGPUBuffer;

    /// CPU version of the stat buffer; this is always assumed to be clean.
    IMX_Stat                    myCPUStat;
    /// GPU backing of stat buffer.
    mutable cl::Buffer          myGPUStat;
    mutable bool                myGPUStatClean = false;

    /// This pair of flags hold the state of data that lives in the two storage
    /// spots.
    bool                        myOnCPU = false;
    bool                        myOnGPU = false;

    /// Number of current users of the GPU memory from this buffer.
    mutable SYS_AtomicInt32     myGPUInUseCount;

    /// If true only allocate a 1x1 buffer
    bool myIsConstant = false;
    /// If true, we won't actually do any data copying or validation when a read
    /// is requested.
    bool myIsUninitialized = false;
    /// Can data of this buffer be stolen by the verbs? TODO: who should reset
    /// this and when?
    mutable bool myStealable = true;

    friend class IMX_CEMemoryPool;
};

/// Returns the label for the supplied border type
IMX_API const char *COPgetBorderTypeString(const IMX_BorderType &border);