295 lines
13 KiB
C++
295 lines
13 KiB
C++
/****************************************************************************
|
|
**
|
|
** Copyright (C) 2016 The Qt Company Ltd.
|
|
** Contact: https://www.qt.io/licensing/
|
|
**
|
|
** This file is part of the QtGui module of the Qt Toolkit.
|
|
**
|
|
** $QT_BEGIN_LICENSE:LGPL$
|
|
** Commercial License Usage
|
|
** Licensees holding valid commercial Qt licenses may use this file in
|
|
** accordance with the commercial license agreement provided with the
|
|
** Software or, alternatively, in accordance with the terms contained in
|
|
** a written agreement between you and The Qt Company. For licensing terms
|
|
** and conditions see https://www.qt.io/terms-conditions. For further
|
|
** information use the contact form at https://www.qt.io/contact-us.
|
|
**
|
|
** GNU Lesser General Public License Usage
|
|
** Alternatively, this file may be used under the terms of the GNU Lesser
|
|
** General Public License version 3 as published by the Free Software
|
|
** Foundation and appearing in the file LICENSE.LGPL3 included in the
|
|
** packaging of this file. Please review the following information to
|
|
** ensure the GNU Lesser General Public License version 3 requirements
|
|
** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
|
|
**
|
|
** GNU General Public License Usage
|
|
** Alternatively, this file may be used under the terms of the GNU
|
|
** General Public License version 2.0 or (at your option) the GNU General
|
|
** Public license version 3 or any later version approved by the KDE Free
|
|
** Qt Foundation. The licenses are as published by the Free Software
|
|
** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
|
|
** included in the packaging of this file. Please review the following
|
|
** information to ensure the GNU General Public License requirements will
|
|
** be met: https://www.gnu.org/licenses/gpl-2.0.html and
|
|
** https://www.gnu.org/licenses/gpl-3.0.html.
|
|
**
|
|
** $QT_END_LICENSE$
|
|
**
|
|
****************************************************************************/
|
|
|
|
#include "qplatformsharedgraphicscache.h"
|
|
|
|
QT_BEGIN_NAMESPACE
|
|
|
|
/*!
|
|
\class QPlatformSharedGraphicsCache
|
|
\since 5.0
|
|
\internal
|
|
\preliminary
|
|
\ingroup qpa
|
|
\brief The QPlatformSharedGraphicsCache is an abstraction of a cross-process graphics cache.
|
|
|
|
If supported, it is possible to retrieve a QPlatformSharedGraphicsCache object from the
|
|
platform integration. This is typically used to store graphical items which should be shared
|
|
between several processes.
|
|
|
|
Items are requested from the cache by calling requestItems(). If the cache contains the
|
|
requested items in the requested cache, the itemsAvailable() signal is emitted with the ID of
|
|
the graphical buffer and each item's coordinates inside the buffer. Before requesting items
|
|
from a cache, the user must call ensureCacheInitialized() to set the correct parameters for
|
|
the cache.
|
|
|
|
If the cache does not yet contain the requested items, it will emit a similar itemsMissing()
|
|
signal. The client can then call updateItems() with rasterizations of the items and they will be
|
|
entered into the shared cache. As the items are rendered into the cache, itemsAvailable() signals
|
|
will be emitted for each of the items which have previously been requested and which have not
|
|
yet been reported as ready.
|
|
|
|
Using beginRequestBatch() and endRequestBatch(), it's possible to batch glyph requests, which
|
|
could improve performance in cases where you have a sequence of requests pending, and you
|
|
do not need the results during this sequence.
|
|
*/
|
|
|
|
/*!
|
|
\enum QPlatformSharedGraphicsCache::BufferType
|
|
|
|
Defines how the type of buffer required to contain a cache.
|
|
|
|
\value OpenGLTexture The buffer will be allocated in graphics memory, and an OpenGL texture
|
|
for a buffer belonging to the cache can be requested using
|
|
textureIdForBuffer().
|
|
*/
|
|
|
|
/*!
|
|
\enum QPlatformSharedGraphicsCache::PixelFormat
|
|
|
|
Defines the pixel format of a cache.
|
|
|
|
\value Alpha8 The cache will use 8 bits to represent the alpha value of each pixel. If an
|
|
OpenGL texture is created for a buffer belong to the cache, it will have the
|
|
pixel format GL_ALPHA.
|
|
*/
|
|
|
|
/*!
|
|
\fn void QPlatformSharedGraphicsCache::ensureCacheInitialized(const QByteArray &cacheId, BufferType bufferType, PixelFormat pixelFormat)
|
|
|
|
Initializes a cache named \a cacheId if it has not yet been initialized. The \a bufferType and
|
|
\a pixelFormat gives the format of the buffers that will be used to contain the items in the
|
|
cache. If a cache with the same \a cacheId has previously been initialized, the call will be
|
|
ignored. The cache will keep its previously set buffer type and pixel format.
|
|
*/
|
|
|
|
/*!
|
|
\fn void QPlatformSharedGraphicsCache::requestItems(const QByteArray &cacheId, const QList<quint32> &itemIds)
|
|
|
|
Requests all the items in \a itemIds from the cache with the name \a cacheId.
|
|
|
|
If any or all of the items are available in the cache, one or more itemsAvailable() signals will be
|
|
emitted corresponding to the items. If the cache does not contain all of the items in question,
|
|
then an itemsMissing() signal will be emitted corresponding to the missing items. The user
|
|
is at this point expected to call insertItems() to insert the missing items into the cache. If
|
|
the inserted items have previously been requested by the user, at which point an itemsAvailable()
|
|
signal will be emitted corresponding to the items.
|
|
|
|
Before requesting items from a cache, the user must call ensureCacheInitialized() with the
|
|
correct parameters for the cache.
|
|
*/
|
|
|
|
/*!
|
|
\fn void QPlatformSharedGraphicsCache::insertItems(const QByteArray &cacheId, const QList<quint32> &itemIds, const QList<QImage> &items)
|
|
|
|
Inserts the items in \a itemIds into the cache named \a cacheId. The appearance of
|
|
each item is stored in \a items. The format of the QImage objects is expected to match the
|
|
pixel format of the cache as it was initialized in ensureCacheInitialized().
|
|
|
|
When the items have been successfully entered into the cache, one or more itemsAvailable() signals
|
|
will be emitted for the items.
|
|
|
|
If the cache already contains the items, the behavior is implementation-specific. The
|
|
implementation may choose to ignore the items or it may overwrite the existing instances in
|
|
the cache. Either way, itemsAvailable() signals corresponding to the inserted items will be
|
|
emitted.
|
|
*/
|
|
|
|
/*!
|
|
\fn void QPlatformSharedGraphicsCache::releaseItems(const QByteArray &cacheId, const QList<quint32> &itemIds)
|
|
|
|
Releases the reference to the items in \a itemIds from the cache named \a cacheId. This should
|
|
only be called when all references to the items have been released by the user, and they are no
|
|
longer needed.
|
|
*/
|
|
|
|
/*!
|
|
\fn void QPlatformSharedGraphicsCache::itemsMissing(const QByteArray &cacheId, const QList<quint32> &itemIds)
|
|
|
|
This signal is emitted when requestItems() has been called for one or more items in the
|
|
cache named \a cacheId which are not yet available in the cache. The user is then expected to
|
|
call insertItems() to update the cache with the respective items, at which point they will
|
|
become available to all clients of the shared cache.
|
|
|
|
The \a itemIds list contains the IDs of the items that need to be inserted into the cache.
|
|
|
|
\sa itemsAvailable(), insertItems(), requestItems()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QPlatformSharedGraphicsCache::itemsAvailable(const QByteArray &cacheId, void *bufferId, const QList<quint32> &itemIds, const QList<QPoint> &positionsInBuffer)
|
|
|
|
This signal can be emitted at any time when either requestItems() or insertItems() has been
|
|
called by the application for one or more items in the cache named \a cacheId, as long as
|
|
releaseItems() has not subsequently been called for the same items. It instructs the application
|
|
on where to find the items that have been entered into the cache. When the application receives
|
|
a buffer, it is expected to reference it using referenceBuffer() on it if it keeps a reference
|
|
to the buffer.
|
|
|
|
The \a bufferId is an ID for the buffer that contains the items. The \a bufferId can be
|
|
converted to a format usable by the application depending on which format it was given at
|
|
initialization. If it is a OpenGLTexture, its texture ID can be requested using the
|
|
textureIdForBuffer() function. The dimensions of the buffer are given by \a bufferSize.
|
|
|
|
The items provided by the cache are identified in the \a itemIds list. The
|
|
\a positionsInBuffer list contains the locations inside the buffer of each item. Each entry in
|
|
\a positionsInBuffer corresponds to an item in \a itemIds.
|
|
|
|
The buffer and the items' locations within the buffer can be considered valid until an
|
|
itemsInvalidated() signal has been emitted for the items, or until releaseItems() is called
|
|
for the items.
|
|
|
|
\sa itemsMissing(), requestItems(), bufferType()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QPlatformSharedGraphicsCache::itemsUpdated(const QByteArray &cacheId, void *bufferId, const QList<quint32> &itemIds, const QList<QPoint> &positionsInBuffer)
|
|
|
|
This signal is similar in usage to the itemsAvailable() signal, but will be emitted when
|
|
the location of a previously requested or inserted item has been updated. The application
|
|
must update its data for the respective items and release any references to old buffers held
|
|
by the items.
|
|
|
|
If the application no longer holds any references to previously referenced items in a given
|
|
cache, it should call releaseItems() for these items, at which point it will no longer receive
|
|
any itemsUpdated() signal for these items.
|
|
|
|
\sa requestItems(), insertItems(), itemsAvailable()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QPlatformSharedGraphicsCache::itemsInvalidated(const QByteArray &cacheId, const QList<quint32> &itemIds)
|
|
|
|
This signal is emitted when the items given by \a itemIds in the cache named \a cacheId have
|
|
been removed from the cache and the previously reported information about them is considered
|
|
invalid. It will only be emitted for items for which a buffer has previously been identified
|
|
through the itemsAvailable() signal (either as response to a requestItems() call or an
|
|
insertItems() call.)
|
|
|
|
The application is expected to throw away information about the items in the \a itemIds array
|
|
and drop any references it might have to the memory held by the buffer. If the items are still
|
|
required by the application, it can re-commit them to the cache using the insertItems() function.
|
|
|
|
If the application no longer holds any references to previously referenced items in a given
|
|
cache, it should call releaseItems() for these items, at which point it will no longer receive
|
|
any itemsInvalidated() signal for these items.
|
|
*/
|
|
|
|
/*!
|
|
\fn void QPlatformSharedGraphicsCache::beginRequestBatch()
|
|
|
|
This is a hint to the cache that a burst of requests is pending. In some implementations, this
|
|
will improve performance, as the cache can focus on handling the requests and wait with the
|
|
results until it is done. It should typically be called prior to a sequence of calls to
|
|
requestItems() and releaseItems().
|
|
|
|
Any call to beginRequestBatch() must be followed at some point by a call to endRequestBatch().
|
|
Failing to do this may lead to the results of requests never being emitted.
|
|
|
|
\note beginRequestBatch() and endRequestBatch() have no stacking logic. Calling
|
|
beginRequestBatch() twice in a row has no effect, and the single existing batch will be ended
|
|
by the earliest call to endRequestBatch().
|
|
|
|
\sa endRequestBatch(), requestBatchStarted()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QPlatformSharedGraphicsCache::endRequestBatch()
|
|
|
|
Signals to the cache that the request sequence which has previously been commenced using
|
|
beginRequestBatch() has now finished.
|
|
|
|
\sa beginRequestBatch(), requestBatchStarted()
|
|
*/
|
|
|
|
/*!
|
|
\fn bool QPlatformSharedGraphicsCache::requestBatchStarted() const
|
|
|
|
Returns \c true if a request batch has previously been started using beginRequestBatch()
|
|
and not yet stopped using endRequestBatch().
|
|
|
|
\sa beginRequestBatch(), endRequestBatch()
|
|
*/
|
|
|
|
/*!
|
|
\fn uint QPlatformSharedGraphicsCache::textureIdForBuffer(void *bufferId)
|
|
|
|
Returns an OpenGL texture ID corresponding to the buffer \a bufferId, which has previously
|
|
been passed through signals itemsAvailable() or itemsUpdated(). The relevant OpenGL context
|
|
should be current when calling this function.
|
|
|
|
\sa eglImageForBuffer(), sizeOfBuffer()
|
|
*/
|
|
|
|
/*!
|
|
\fn void *QPlatformSharedGraphicsCache::eglImageForBuffer(void *bufferId)
|
|
|
|
Returns an EGLImageKHR image corresponding to the buffer \a bufferId.
|
|
|
|
\sa textureIdForBuffer(), sizeOfBuffer()
|
|
*/
|
|
|
|
/*!
|
|
\fn void QPlatformSharedGraphicsCache::referenceBuffer(void *bufferId)
|
|
|
|
Registers a reference to the buffer \a bufferId.
|
|
|
|
\sa dereferenceBuffer()
|
|
*/
|
|
|
|
/*!
|
|
\fn bool QPlatformSharedGraphicsCache::dereferenceBuffer(void *bufferId)
|
|
|
|
Removed a previously registered reference to the buffer \a bufferId. Returns \c true if there
|
|
are still more references to the buffer in question, or false if this was the last reference
|
|
(in which case the buffer may have been deleted in the cache.)
|
|
|
|
\sa dereferenceBuffer()
|
|
*/
|
|
|
|
/*!
|
|
\fn QSize QPlatformSharedGraphicsCache::sizeOfBuffer(void *bufferId)
|
|
|
|
Returns the size of the buffer \a bufferId.
|
|
|
|
\sa textureIdForBuffer(), eglImageForBuffer()
|
|
*/
|
|
|
|
QT_END_NAMESPACE
|