IMX_PoolEntry.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.
 *
 * COMMENTS:
 *      Base class for things that can be tracked by the IMX_CEMemoryPool
 */

#pragma once

#include "IMX_API.h"

#include "IMX_Types.h"

#include <UT/UT_SharedPtr.h>
;

/// Base class for objects that can be managed by the
/// IMX_CEMemoryPool
/// This handles the registration / unloading /etc of the GPU buffers.

class IMX_API IMX_PoolEntry
{
public:
    /// To avoid the need for dynamic casts:
    enum class EntryType
    {
        BUFFER = 0,
        VDB,
    };

    /// Creates a new buffer. You must call setSize to make this buffer usable.
    IMX_PoolEntry() {}
    virtual ~IMX_PoolEntry() {}
    IMX_PoolEntry(const IMX_PoolEntry &) = delete;
    IMX_PoolEntry &operator=(const IMX_PoolEntry &) = delete;

    virtual EntryType poolTypeID() const = 0;

    /// Returns whether the GPU data for this image is currently being used by
    /// someone.
    bool isInUseGPU() const
    {
        return myGPUInUseCount > 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();
    /// Alternatively, you can use the RAII wrapper for this:
    ///     {
    ///         // Set the in-use flag before grabbing the GPU buffer.
    ///         IMX_ScopedBufferInUseGPU scoped_gpu_use(buffer);
    ///         CE_Image& img = buffer.getGPUBufferW();
    ///         // Do stuff with the CE_Image (i.e. queue up an OpenCL command
    ///         // with it, can be asynchronous).
    ///         ...
    ///         // Destructor automatically clears the flag that we set earlier.
    ///     }
    void setInUseGPUFlag() const;
    /// 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;

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

    /// Resets the GPU Buffer pointer.
    virtual void poolResetGPUBuffer() = 0;
    /// CHnages the OnGPU status.
    virtual void poolSetOnGPU(bool ongpu) = 0;
    /// True if the gpu buffer is null.
    virtual bool poolIsGPUBufferEmpty() const = 0;
    /// True if the gpu buffer is not null and valid.
    virtual bool poolIsGPUBufferValid() const = 0;
    /// Swap two GPU buffers.  Returns true if it did something.
    virtual bool poolSwapGPUBuffer(IMX_PoolEntry *other) = 0;
    /// Copies GPU buffer from source, shallow copy so it shares.
    virtual void poolShallowCopyGPUBuffer(const IMX_PoolEntry *src) = 0;


    /// Number of current users of the GPU memory from this buffer. All changes
    /// to this member must be done by the memory pool!!!
    mutable int                 myGPUInUseCount = 0;

    friend class IMX_CEMemoryPool;
};

class IMX_ScopedPoolEntryInUseGPU
{
public:
    explicit                IMX_ScopedPoolEntryInUseGPU(const IMX_PoolEntry &buffer)
                                : myBuffer(buffer)
                            { myBuffer.setInUseGPUFlag(); }

                           ~IMX_ScopedPoolEntryInUseGPU()
                            { myBuffer.clearInUseGPUFlag(); }

private:
    const IMX_PoolEntry       &myBuffer;
};