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 "IMX_Types.h"
#include "IMX_PoolEntry.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>

#include <CE/CE_BufferHost.h>
#include <CE/CE_BufferDevice.h>

class PXL_Raster;
class TIL_Raster;

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

    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>         myCameraImagePos[4] = {0, 0, 0, 0}; // Last float is padding

    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;
    IMX_Projection          myProjection = IMX_Projection::IMX_ORTHOGRAPHIC;

    /// Write our fields into the provided options:
    void        copyToOptions(UT_Options &opt) const;
    /// Load ourselves from the options, ignoring fields we don't know
    void        updateFromOptions(const UT_Options &opt);

    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;
            }
        }
        
        for (int i = 0; i < 3; ++i) // Don't compare the padding float
        {
            if (myCameraImagePos[i] != other.myCameraImagePos[i])
            {
                return false;
            }
        }

        if (myImageToWorld != other.myImageToWorld ||
            myWorldToImage != other.myWorldToImage ||
            myCameraToWorld != other.myCameraToWorld)
        {
            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 ||
            myProjection != other.myProjection)
        {
            return false;
        }

        return true;
    }

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

/// 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 : public IMX_PoolEntry
{
    friend class IMX_Layer;
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() override;

    EntryType poolTypeID() const override { return EntryType::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, isFixedPoint, bytes, channels
    void copyStorageType(const IMX_Buffer& i)
    { setStorageType(i.getStorageType(), i.getChannels()); }
    /// Set storesIntegers, isFixedPoint, bytes, channels
    void setStorageType(CE_Image::StorageType storage, int channels);
    /// Set storesIntegers, isFixedPoint, bytes
    void setStorageType(CE_Image::StorageType storage);
    /// Set number of bytes per channel, don't change storesIntegers,
    /// isFixedPoint, or channels
    void setStorageBytes(int);
    /// Set bytes per channel and isFixedPoint, doesn't change channels. Also
    /// sets storesIntegers to false. TODO: should this fail if storesIntegers()
    /// is already true? (FIXED_POINT_STORAGE)
    void setStorageBytes(int, bool);
    /// Set channels, don't change storesIntegers, isFixedPoint, or bytes
    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); }
    /// Does this buffer use fixed point to store non-integer data?
    bool isFixedPoint() const { return CE_Image::isFixedPoint(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.
    exint bufferWidth() const { return myCPUStat.myResolution[0]; }
    /// Get height (number of rows) of the buffer.
    exint 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,
        const UT_Matrix4F &camera_to_world,
        const UT_Vector3F &camera_image_pos
    );

    /// 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 the semantic type.
    IMX_TypeInfo getTypeInfo() const;

    /// These are the projections in the stat, you want to actually
    /// work at imx layer to ensure you update the transforms.
    /// Sets the projection of this image. 
    void setStatProjection(IMX_Projection projection);
    /// Returns the projection type
    IMX_Projection statProjection() 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);


    /// Copies the buffer into the provided flat destination buffer.
    /// The provided size is checked against required size and ASSERT
    /// and no copy & return false if a mis-match.
    bool        extract(void *dst, exint dstsize,
                        CE_Image::StorageType dststorage,
                        int dstchannels) const;
    /// Copies the provided flat buffer into this buffer.
    /// The provided size is checked against required size and ASSERT
    /// and no copy & return false if a mis-match.
    bool        insert(const void *src, exint srcsize,
                        CE_Image::StorageType srcstorage,
                        int srcchannels);

    /// 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<CE_BufferHostByte> &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;
    // Fetches the raw buffer at x, y
    void getPixelRaw(UT_Array<uint8> &dest, int x, int 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 int16* getCPUBufferRFixed16() const { return getCPUBufferR<CE_Image::FIXED16>(); }
    int16* getCPUBufferWFixed16() { return getCPUBuffer<CE_Image::FIXED16>(false,true); }
    const uint8* getCPUBufferRFixed8() const { return getCPUBufferR<CE_Image::FIXED8>(); }
    uint8* getCPUBufferWFixed8() { return getCPUBuffer<CE_Image::FIXED8>(false,true); }
    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); }
    void *getCPUBufferR() const { return getCPUBufferRInternal(); };
    void *getCPUBufferW() { return getCPUBuffer(false, true); }
    /// 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 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; }
private:
    /// Turn on isDirty(). It is turned off by getCPU/GPUBuffer with write=true
    /// This is internal only as isConstant should not be adjusted by
    /// external users.
    void setDirty() { myOnGPU = myOnCPU = myIsConstant = false; }
public:
    /// 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; }

    bool validateBuffer() const;

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

    int64       getMemoryUsage() const;
    int64       getDeviceMemoryUsage() const;

protected:
    /// These implement methods required by the pool.

    /// Resets the GPU Buffer pointer.
    void poolResetGPUBuffer() override
    {
        myGPUBuffer.reset();
    }
    /// Update OnGPU
    void poolSetOnGPU(bool ongpu) override
    {
        myOnGPU = ongpu;
    }
    /// True if the gpu buffer is null.
    bool poolIsGPUBufferEmpty() const override
    {
        return myGPUBuffer.get() == nullptr;
    }
    /// True if the gpu buffer is not null and valid.
    bool poolIsGPUBufferValid() const override
    {
        return myGPUBuffer.get() && myGPUBuffer->isValid();
    }
    /// True if the swap does something
    bool poolSwapGPUBuffer(IMX_PoolEntry *otherbase) override
    {
        IMX_Buffer *other = UTverify_cast<IMX_Buffer *>(otherbase);

        if (myGPUBuffer == other->myGPUBuffer)
            return false;

        myGPUBuffer.swap(other->myGPUBuffer);
        return true;
    }
    /// Shallow copy
    void poolShallowCopyGPUBuffer(const IMX_PoolEntry *srcbase) override
    {
        const IMX_Buffer *src = UTverify_cast<const IMX_Buffer *>(srcbase);

        myGPUBuffer = src->myGPUBuffer;
    }

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

    /// Allocates a GPU Buffer, doing proper synchronization with
    /// the CE Pool.  NOTE: If the GPU buffer is the right size, it will
    /// be re-used.
    void allocateCEBuffer(exint width, exint height);

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

    /// 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. 
    void unloadFromGPU() override;

    /// 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<CE_BufferHostByte> 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, considered not-writable so
    /// only update in-place if unique.
    mutable UT_SharedPtr<CE_BufferDeviceByte> 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;

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

using IMX_ScopedBufferInUseGPU = IMX_ScopedPoolEntryInUseGPU;

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

IMX_API CE_Image::StorageType IMXgetStorageTypeFromRaster(const PXL_Raster &rp);