Beatmup::BitmapContentLock Class Reference

Makes sure the bitmap content is accessible within an image processing task. More...

#include <content_lock.h>

Inheritance diagram for Beatmup::BitmapContentLock:

Classes
struct	LockDescriptor

Public Member Functions
	BitmapContentLock ()
	~BitmapContentLock ()
void	readLock (GraphicPipeline *gpu, AbstractBitmap *bitmap, ProcessingTarget target)
	Locks content of a bitmap for reading using a specific processing target device. More...
void	writeLock (GraphicPipeline *gpu, AbstractBitmap *bitmap, ProcessingTarget target)
	Locks content of a bitmap for writing using a specific processing target device. More...
void	unlock (AbstractBitmap *bitmap)
	Drops a lock to the bitmap. More...
void	unlockAll ()
	Unlocks all the locked bitmaps unconditionally. More...
template<const ProcessingTarget target>
void	lock (GraphicPipeline *gpu, AbstractBitmap *input, AbstractBitmap *output)
void	lock (GraphicPipeline *gpu, ProcessingTarget target, AbstractBitmap *input, AbstractBitmap *output)
template<const ProcessingTarget target>
void	lock (GraphicPipeline *gpu, std::initializer_list< AbstractBitmap * > read, std::initializer_list< AbstractBitmap * > write)
template<typename ... Args>
void	unlock (AbstractBitmap *first, Args ... others)

Private Member Functions
	BitmapContentLock (const BitmapContentLock &)=delete

Private Attributes
std::map< AbstractBitmap *, LockDescriptor >	bitmaps

Detailed Description

Makes sure the bitmap content is accessible within an image processing task.

To enable direct access to pixels, a specific operation of locking the bitmap content is typically required. When done, the bitmap content needs to be unlocked. Depending on the access type (reading/writing) an the processing target (CPU or GPU), a memory allocation and/or data transfer may be required. BitmapContentLock performs the data transfer if necessary. It also handles multiple locking of the same bitmap by reference counting.

Definition at line 34 of file content_lock.h.

Constructor & Destructor Documentation

BitmapContentLock() [1/2]

Beatmup::BitmapContentLock::BitmapContentLock ( const BitmapContentLock &  )

privatedelete

BitmapContentLock() [2/2]

Beatmup::BitmapContentLock::BitmapContentLock ( )

inline

Definition at line 48 of file content_lock.h.

{}

~BitmapContentLock()

BitmapContentLock::~BitmapContentLock

(

)

Definition at line 29 of file content_lock.cpp.

                                      {
#ifdef BEATMUP_DEBUG
    if (!bitmaps.empty())
        BEATMUP_DEBUG_E("Destroying a content lock having %d locked bitmaps", (int)bitmaps.size());
#endif
}

Member Function Documentation

readLock()

void BitmapContentLock::readLock	(	GraphicPipeline *	gpu,
		AbstractBitmap *	bitmap,
		ProcessingTarget	target
	)

Locks content of a bitmap for reading using a specific processing target device.

If the lock is already acquired, only increases the counter. If the bitmap was previously locked for a different target device, an exception is thrown.

Parameters

gpu	A graphic pipeline instance. Used to transfer the pixel data between CPU and GPU if needed.
bitmap	The bitmap to lock
target	Target processing device to make the pixel content readable for (CPU or GPU)

Definition at line 37 of file content_lock.cpp.

                                                                                                      {
#ifdef BEATMUP_DEBUG
    DebugAssertion::check(!bitmap->isDirty(), "Reading a dirty bitmap");
    if (target == ProcessingTarget::GPU)
        DebugAssertion::check(gpu, "Cannot lock a bitmap on GPU: no graphic pipeline instance available");
#endif
 
    bool transferToGpuNeeded = false;
    bool transferFromGpuNeeded = false;
 
    auto it = bitmaps.find(bitmap);
    if (it == bitmaps.end()) {
        // creating a lock descriptor
        LockDescriptor lock{
            true, false,
            target == ProcessingTarget::CPU,
            target == ProcessingTarget::GPU,
            false,
            1
        };
 
        // pixel transfer to GPU is needed if the bitmap is not up to date on GPU
        transferToGpuNeeded = lock.gpu && !bitmap->isUpToDate(ProcessingTarget::GPU);
        transferFromGpuNeeded = lock.cpu && !bitmap->isUpToDate(ProcessingTarget::CPU);
 
        // locking pixel data in RAM
        if (lock.cpu || transferToGpuNeeded || transferFromGpuNeeded) {
            bitmap->lockPixelData();
            lock.isDataLocked = true;
        }
        
        bitmaps.emplace(bitmap, lock);
    }
 
    else {
        // already locked, just increase reference counter
        auto& lock = it->second;
 
        RuntimeError::check(((target == ProcessingTarget::CPU) == lock.cpu) && ((target == ProcessingTarget::GPU) == lock.gpu),
            "Lock target mismatch: a bitmap was previously locked for a different target");
 
        // It is allowed to lock a bitmap for writing first and for reading later.
        if (!lock.read) {
            transferToGpuNeeded = lock.gpu && !bitmap->isUpToDate(ProcessingTarget::GPU);
            transferFromGpuNeeded = lock.cpu && !bitmap->isUpToDate(ProcessingTarget::CPU);
 
            if (!lock.isDataLocked && (transferToGpuNeeded || transferFromGpuNeeded)) {
                bitmap->lockPixelData();
                lock.isDataLocked = true;
            }
 
            lock.read = true;
        }
        lock.refs++;
    }
 
    // do pixel transfer if required
    if (transferToGpuNeeded)
        gpu->pushPixels(*bitmap);
    else if (transferFromGpuNeeded)
        gpu->pullPixels(*bitmap);
}

writeLock()

void BitmapContentLock::writeLock	(	GraphicPipeline *	gpu,
		AbstractBitmap *	bitmap,
		ProcessingTarget	target
	)

Locks content of a bitmap for writing using a specific processing target device.

If the lock is already acquired, only increases the counter. If the bitmap was previously locked for reading, an exception is thrown. However, it is allowed to lock for different devices, or to lock for writing first and reading later.

Parameters

gpu	A graphic pipeline instance
bitmap	The bitmap to lock
target	Target processing device to make the pixel content readable for (CPU or GPU)

Definition at line 101 of file content_lock.cpp.

                                                                                                       {
#ifdef BEATMUP_DEBUG
    if (target == ProcessingTarget::GPU)
        DebugAssertion::check(gpu, "Cannot lock a bitmap on GPU: no graphic pipeline instance available");
#endif
 
    auto it = bitmaps.find(bitmap);
    if (it == bitmaps.end()) {
        // creating a lock descriptor
        LockDescriptor lock{
            false, true,
            target == ProcessingTarget::CPU,
            target == ProcessingTarget::GPU,
            target == ProcessingTarget::CPU,    // data is locked if writing on CPU
            1
        };
        bitmaps.emplace(bitmap, lock);
 
        // locking pixel data in RAM
        if (lock.isDataLocked)
            bitmap->lockPixelData();
    }
 
    else {
        // already locked, just increase reference counter
        auto& lock = it->second;
 
        if (lock.read && !lock.write)
            throw RuntimeError("Cannot a bitmap for writing: it was locked for reading before. Lock it for writing first.");
 
        // lock data if needed and not yet
        if (!lock.isDataLocked && target == ProcessingTarget::CPU) {
            bitmap->lockPixelData();
            lock.isDataLocked = true;
        }
 
        lock.gpu |= (target == ProcessingTarget::GPU);
        lock.cpu |= (target == ProcessingTarget::CPU);
 
        lock.refs++;
    }
}

unlock() [1/2]

void BitmapContentLock::unlock

(

AbstractBitmap *

bitmap

)

Drops a lock to the bitmap.

If no other locks own the content, the bitmap is unlocked.

Definition at line 145 of file content_lock.cpp.

                                                     {
    auto it = bitmaps.find(bitmap);
#ifdef BEATMUP_DEBUG
    DebugAssertion::check(it != bitmaps.end(), "Trying to unlock a bitmap that is not locked.");
#endif
 
    auto& lock = it->second;
    lock.refs--;
    if (lock.refs == 0) {
        if (lock.isDataLocked)
            bitmap->unlockPixelData();
 
        if (lock.write) {
            bitmap->upToDate[ProcessingTarget::CPU] = lock.cpu;
            bitmap->upToDate[ProcessingTarget::GPU] = lock.gpu;
        }
 
        bitmaps.erase(it);
    }
}

unlockAll()

void BitmapContentLock::unlockAll

(

)

Unlocks all the locked bitmaps unconditionally.

Definition at line 167 of file content_lock.cpp.

                                  {
    for (auto it : bitmaps) {
        auto& lock = it.second;
        if (lock.isDataLocked)
            it.first->unlockPixelData();
 
        if (lock.write) {
            it.first->upToDate[ProcessingTarget::CPU] = lock.cpu;
            it.first->upToDate[ProcessingTarget::GPU] = lock.gpu;
        }
    }
 
    bitmaps.clear();
}

lock() [1/3]

template<const ProcessingTarget target>

void Beatmup::BitmapContentLock::lock ( GraphicPipeline *  gpu, AbstractBitmap *  input, AbstractBitmap *  output  )

inline

Definition at line 84 of file content_lock.h.

                                                                                              {
            writeLock(gpu, output, target);
            readLock(gpu, input, target);
        }

lock() [2/3]

void Beatmup::BitmapContentLock::lock ( GraphicPipeline *  gpu, ProcessingTarget  target, AbstractBitmap *  input, AbstractBitmap *  output  )

inline

Definition at line 89 of file content_lock.h.

                                                                                                                       {
            writeLock(gpu, output, target);
            readLock(gpu, input, target);
        }

lock() [3/3]

template<const ProcessingTarget target>

void Beatmup::BitmapContentLock::lock ( GraphicPipeline *  gpu, std::initializer_list< AbstractBitmap * >  read, std::initializer_list< AbstractBitmap * >  write  )

inline

Definition at line 95 of file content_lock.h.

                                                                                                                                      {
            for (auto bmp : write)
                writeLock(gpu, bmp, target);
            for (auto bmp : read)
                readLock(gpu, bmp, target);
        }

unlock() [2/2]

template<typename ... Args>

void Beatmup::BitmapContentLock::unlock ( AbstractBitmap *  first, Args ...  others  )

inline

Definition at line 103 of file content_lock.h.

                                                                   {
            unlock(first);
            unlock(others...);
        }

Member Data Documentation

bitmaps

std::map<AbstractBitmap*, LockDescriptor> Beatmup::BitmapContentLock::bitmaps

private

Definition at line 45 of file content_lock.h.

---

The documentation for this class was generated from the following files:

• core/bitmap/content_lock.h
• core/bitmap/content_lock.cpp