KWayland::Client::ShmPool

KWayland::Client::ShmPool Class Reference

#include <shm_pool.h>

Inheritance diagram for KWayland::Client::ShmPool:

Signals

void poolResized ()
 
void removed ()
 

Public Member Functions

 ShmPool (QObject *parent=nullptr)
 
Buffer::Ptr createBuffer (const QImage &image)
 
Buffer::Ptr createBuffer (const QSize &size, int32_t stride, const void *src, Buffer::Format format=Buffer::Format::ARGB32)
 
void destroy ()
 
EventQueueeventQueue ()
 
Buffer::Ptr getBuffer (const QSize &size, int32_t stride, Buffer::Format format=Buffer::Format::ARGB32)
 
bool isValid () const
 
void * poolAddress () const
 
void release ()
 
void setEventQueue (EventQueue *queue)
 
void setup (wl_shm *shm)
 
wl_shm * shm ()
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (QObject *object)
 
qobject_cast (const QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () const const
 

Additional Inherited Members

- Properties inherited from QObject
 objectName
 
- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 
- Public Attributes inherited from QObject
typedef QObjectList
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 

Detailed Description

Wrapper class for wl_shm interface.

This class holds a shared memory pool together with the Wayland server.

To use this class one needs to interact with the Registry. There are two possible ways to create a ShmPool instance:

ShmPool *s = registry->createShmPool(name, version);

This creates the ShmPool and sets it up directly. As an alternative this can also be done in a more low level way:

ShmPool *s = new ShmPool;
s->setup(registry->bindShm(name, version));

The ShmPool holds a memory-mapped file from which it provides Buffers. All Buffers are held by the ShmPool and can be reused. Whenever a Buffer is requested the ShmPool tries to reuse an existing Buffer. A Buffer can be reused if the following conditions hold

  • it's no longer marked as used
  • the server released the buffer
  • the size matches
  • the stride matches
  • the format matches

The ownership of a Buffer stays with ShmPool. The ShmPool might destroy the Buffer at any given time. Because of that ShmPool only provides QWeakPointer for Buffers. Users should always check whether the pointer is still valid and only promote to a QSharedPointer for a short time, e.g. to set new data.

The ShmPool can provide Buffers for different purposes. One can create a Buffer from an existing QImage. This will use a Buffer with same size, stride and image format as the QImage and copy the content of the QImage into the Buffer. The memory is not shared:

QImage image(24, 24, QImage::Format_ARG32);
image.fill(Qt::transparent);
Buffer::Ptr buffer = s->createBuffer(image);

It is also possible to create a Buffer and copy the content from a generic location. Like above this doesn't share the content but copies it:

QImage image(24, 24, QImage::Format_ARG32);
image.fill(Qt::transparent);
Buffer::Ptr buffer = s->createBuffer(image.size(), image.bytesPerLine(), image.constBits());

Last but not least it is possible to get a Buffer without copying content directly to it. This means an empty area is just reserved and can be used to e.g. share the memory with a QImage:

const QSize size = QSize(24, 24);
const int stride = size.width() * 4;
Buffer::Ptr buffer = s->getBuffer(size, stride, Buffer::Format::RGB32);
if (!buffer) {
qDebug() << "Didn't get a valid Buffer";
return;
}
QImage image(buffer.toStrongRef()->address(), size.width(), size.height(), stride, QImage::Format_RGB32);
image.fill(Qt::black);

A Buffer can be attached to a Surface:

Compositor *c = registry.createCompositor(name, version);
Surface *s = c->createSurface();
s->attachBuffer(buffer);
s->damage(QRect(QPoint(0, 0), size));

Once a Buffer is attached to a Surface and the Surface is committed, it might be released by the Wayland server and thus is free to be reused again. If the client code wants to continue using the Buffer it must call Buffer::setUsed on it. This is important if the memory is shared for example with a QImage as the memory buffer for a QImage must remain valid throughout the life time of the QImage:

buffer.toStrongRef()->setUsed(true);

This is also important for the case that the shared memory pool needs to be resized. The ShmPool will automatically resize if it cannot provide a new Buffer. During the resize all existing Buffers are unmapped and any shared objects must be recreated. The ShmPool emits the signal poolResized() after the pool got resized.

See also
Buffer

Definition at line 116 of file shm_pool.h.

Member Function Documentation

Buffer::Ptr KWayland::Client::ShmPool::createBuffer ( const QImage image)

Provides a Buffer with:

  • same size as image
  • same stride as image
  • same format as image

If the ShmPool fails to provide such a Buffer a null Buffer::Ptr is returned. The content of the image is copied into the buffer. The image and returned Buffer do not share memory.

Parameters
imageThe image which should be copied into the Buffer
Returns
Buffer with copied content of image in success case, a null Buffer::Ptr otherwise
See also
getBuffer

Definition at line 173 of file shm_pool.cpp.

Buffer::Ptr KWayland::Client::ShmPool::createBuffer ( const QSize size,
int32_t  stride,
const void *  src,
Buffer::Format  format = Buffer::Format::ARGB32 
)

Provides a Buffer with size, stride and format.

If the ShmPool fails to provide such a Buffer a null Buffer::Ptr is returned. A memory copy is performed from src into the Buffer. The Buffer does not share memory with src.

Parameters
sizeThe requested size for the Buffer
strideThe requested stride for the Buffer
srcThe source memory location to copy from
formatThe requested format for the Buffer
Returns
Buffer with copied content of src in success case, a null Buffer::Ptr otherwise
See also
getBuffer

Definition at line 192 of file shm_pool.cpp.

void KWayland::Client::ShmPool::destroy ( )

Destroys the data held by this ShmPool.

This method is supposed to be used when the connection to the Wayland server goes away. If the connection is not valid anymore, it's not possible to call release anymore as that calls into the Wayland connection and the call would fail. This method cleans up the data, so that the instance can be deleted or set up to a new wl_shm interface once there is a new connection available.

All Buffers are destroyed!

This method is automatically invoked when the Registry which created this ShmPool gets destroyed.

See also
release

Definition at line 79 of file shm_pool.cpp.

EventQueue * KWayland::Client::ShmPool::eventQueue ( )
Returns
The event queue to use for creating a Buffer.

Definition at line 109 of file shm_pool.cpp.

Buffer::Ptr KWayland::Client::ShmPool::getBuffer ( const QSize size,
int32_t  stride,
Buffer::Format  format = Buffer::Format::ARGB32 
)

Provides a Buffer with size, stride and format.

If the ShmPool fails to provide such a Buffer a null Buffer::Ptr is returned. Unlike with createBuffer there is no memory copy performed. This provides a bare Buffer to be used by the user.

Parameters
sizeThe requested size for the Buffer
strideThe requested stride for the Buffer
formatThe requested format for the Buffer
Returns
Buffer as requested in success case, a null Buffer::Ptr otherwise.
See also
createBuffer

Definition at line 218 of file shm_pool.cpp.

bool KWayland::Client::ShmPool::isValid ( ) const
Returns
true if the ShmPool references a wl_shm interface and the shared memory pool is setup.

Definition at line 261 of file shm_pool.cpp.

void KWayland::Client::ShmPool::poolResized ( )
signal

This signal is emitted whenever the shared memory pool gets resized.

Any used Buffer must be remapped.

void KWayland::Client::ShmPool::release ( )

Releases the wl_shm interface.

After the interface has been released the ShmPool instance is no longer valid and can be setup with another wl_shm interface.

This also destroys the shared memory pool and all Buffers are destroyed.

Definition at line 65 of file shm_pool.cpp.

void KWayland::Client::ShmPool::removed ( )
signal

The corresponding global for this interface on the Registry got removed.

This signal gets only emitted if the Compositor got created by Registry::createShmPool

Since
5.5
void KWayland::Client::ShmPool::setEventQueue ( EventQueue queue)

Sets the queue to use for creating a Buffer.

Definition at line 104 of file shm_pool.cpp.

void KWayland::Client::ShmPool::setup ( wl_shm *  shm)

Setup this ShmPool to manage the shm.

This also creates the shared memory pool. When using Registry::createShmPool there is no need to call this method.

Definition at line 96 of file shm_pool.cpp.


The documentation for this class was generated from the following files:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Fri Aug 14 2020 22:50:01 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.