src/gui/kernel/qplatformsharedgraphicscache.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/legal
   5 **
   6 ** This file is part of the QtGui module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** Commercial License Usage
  10 ** Licensees holding valid commercial Qt licenses may use this file in
  11 ** accordance with the commercial license agreement provided with the
  12 ** Software or, alternatively, in accordance with the terms contained in
  13 ** a written agreement between you and Digia.  For licensing terms and
  14 ** conditions see http://qt.digia.com/licensing.  For further information
  15 ** use the contact form at http://qt.digia.com/contact-us.
  16 **
  17 ** GNU Lesser General Public License Usage
  18 ** Alternatively, this file may be used under the terms of the GNU Lesser
  19 ** General Public License version 2.1 as published by the Free Software
  20 ** Foundation and appearing in the file LICENSE.LGPL included in the
  21 ** packaging of this file.  Please review the following information to
  22 ** ensure the GNU Lesser General Public License version 2.1 requirements
  23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  24 **
  25 ** In addition, as a special exception, Digia gives you certain additional
  26 ** rights.  These rights are described in the Digia Qt LGPL Exception
  27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  28 **
  29 ** GNU General Public License Usage
  30 ** Alternatively, this file may be used under the terms of the GNU
  31 ** General Public License version 3.0 as published by the Free Software
  32 ** Foundation and appearing in the file LICENSE.GPL included in the
  33 ** packaging of this file.  Please review the following information to
  34 ** ensure the GNU General Public License version 3.0 requirements will be
  35 ** met: http://www.gnu.org/copyleft/gpl.html.
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qplatformsharedgraphicscache.h"
  43
  44 QT_BEGIN_NAMESPACE
  45
  46 /*!
  47     \class QPlatformSharedGraphicsCache
  48     \since 5.0
  49     \internal
  50     \preliminary
  51     \ingroup qpa
  52     \brief The QPlatformSharedGraphicsCache is an abstraction of a cross-process graphics cache.
  53
  54     If supported, it is possible to retrieve a QPlatformSharedGraphicsCache object from the
  55     platform integration. This is typically used to store graphical items which should be shared
  56     between several processes.
  57
  58     Items are requested from the cache by calling requestItems(). If the cache contains the
  59     requested items in the requested cache, the itemsAvailable() signal is emitted with the ID of
  60     the graphical buffer and each item's coordinates inside the buffer. Before requesting items
  61     from a cache, the user must call ensureCacheInitialized() to set the correct parameters for
  62     the cache.
  63
  64     If the cache does not yet contain the requested items, it will emit a similar itemsMissing()
  65     signal. The client can then call updateItems() with rasterizations of the items and they will be
  66     entered into the shared cache. As the items are rendered into the cache, itemsAvailable() signals
  67     will be emitted for each of the items which have previously been requested and which have not
  68     yet been reported as ready.
  69
  70     Using beginRequestBatch() and endRequestBatch(), it's possible to batch glyph requests, which
  71     could improve performance in cases where you have a sequence of requests pending, and you
  72     do not need the results during this sequence.
  73 */
  74
  75 /*!
  76     \enum QPlatformSharedGraphicsCache::BufferType
  77
  78     Defines how the type of buffer required to contain a cache.
  79
  80     \value OpenGLTexture The buffer will be allocated in graphics memory, and an OpenGL texture
  81                          for a buffer belonging to the cache can be requested using
  82                          textureIdForBuffer().
  83 */
  84
  85 /*!
  86     \enum QPlatformSharedGraphicsCache::PixelFormat
  87
  88     Defines the pixel format of a cache.
  89
  90     \value Alpha8 The cache will use 8 bits to represent the alpha value of each pixel. If an
  91                   OpenGL texture is created for a buffer belong to the cache, it will have the
  92                   pixel format GL_ALPHA.
  93 */
  94
  95 /*!
  96    \fn void QPlatformSharedGraphicsCache::ensureCacheInitialized(const QByteArray &cacheId, BufferType bufferType, PixelFormat pixelFormat)
  97
  98    Initializes a cache named \a cacheId if it has not yet been initialized. The \a bufferType and
  99    \a pixelFormat gives the format of the buffers that will be used to contain the items in the
 100    cache. If a cache with the same \a cacheId has previously been initialized, the call will be
 101    ignored. The cache will keep its previously set buffer type and pixel format.
 102 */
 103
 104 /*!
 105     \fn void QPlatformSharedGraphicsCache::requestItems(const QByteArray &cacheId, const QVector<quint32> &itemIds)
 106
 107     Requests all the items in \a itemIds from the cache with the name \a cacheId.
 108
 109     If any or all of the items are available in the cache, one or more itemsAvailable() signals will be
 110     emitted corresponding to the items. If the cache does not contain all of the items in question,
 111     then an itemsMissing() signal will be emitted corresponding to the missing items. The user
 112     is at this point expected to call insertItems() to insert the missing items into the cache. If
 113     the inserted items have previously been requested by the user, at which point an itemsAvailable()
 114     signal will be emitted corresponding to the items.
 115
 116     Before requesting items from a cache, the user must call ensureCacheInitialized() with the
 117     correct parameters for the cache.
 118 */
 119
 120 /*!
 121     \fn void QPlatformSharedGraphicsCache::insertItems(const QByteArray &cacheId, const QVector<quint32> &itemIds, const QVector<QImage> &items)
 122
 123     Inserts the items in \a itemIds into the cache named \a cacheId. The appearance of
 124     each item is stored in \a items. The format of the QImage objects is expected to match the
 125     pixel format of the cache as it was initialized in ensureCacheInitialized().
 126
 127     When the items have been successfully entered into the cache, one or more itemsAvailable() signals
 128     will be emitted for the items.
 129
 130     If the cache already contains the items, the behavior is implementation-specific. The
 131     implementation may choose to ignore the items or it may overwrite the existing instances in
 132     the cache. Either way, itemsAvailable() signals corresponding to the inserted items will be
 133     emitted.
 134 */
 135
 136 /*!
 137     \fn void QPlatformSharedGraphicsCache::releaseItems(const QByteArray &cacheId, const QVector<quint32> &itemIds)
 138
 139     Releases the reference to the items in \a itemIds from the cache named \a cacheId. This should
 140     only be called when all references to the items have been released by the user, and they are no
 141     longer needed.
 142 */
 143
 144 /*!
 145     \fn void QPlatformSharedGraphicsCache::itemsMissing(const QByteArray &cacheId, const QVector<quint32> &itemIds)
 146
 147     This signal is emitted when requestItems() has been called for one or more items in the
 148     cache named \a cacheId which are not yet available in the cache. The user is then expected to
 149     call insertItems() to update the cache with the respective items, at which point they will
 150     become available to all clients of the shared cache.
 151
 152     The vector \a itemIds contains the IDs of the items that need to be inserted into the cache.
 153
 154     \sa itemsAvailable(), insertItems(), requestItems()
 155 */
 156
 157 /*!
 158     \fn void QPlatformSharedGraphicsCache::itemsAvailable(const QByteArray &cacheId, void *bufferId, const QVector<quint32> &itemIds, const QVector<QPoint> &positionsInBuffer)
 159
 160     This signal can be emitted at any time when either requestItems() or insertItems() has been
 161     called by the application for one or more items in the cache named \a cacheId, as long as
 162     releaseItems() has not subsequently been called for the same items. It instructs the application
 163     on where to find the items that have been entered into the cache. When the application receives
 164     a buffer, it is expected to reference it using referenceBuffer() on it if it keeps a reference
 165     to the buffer.
 166
 167     The \a bufferId is an ID for the buffer that contains the items. The \a bufferId can be
 168     converted to a format usable by the application depending on which format it was given at
 169     initialization. If it is a OpenGLTexture, its texture ID can be requested using the
 170     textureIdForBuffer() function. The dimensions of the buffer are given by \a bufferSize.
 171
 172     The items provided by the cache are identified in the \a itemIds vector. The
 173     \a positionsInBuffer vector contains the locations inside the buffer of each item. Each entry in
 174     \a positionsInBuffer corresponds to an item in \a itemIds.
 175
 176     The buffer and the items' locations within the buffer can be considered valid until an
 177     itemsInvalidated() signal has been emitted for the items, or until releaseItems() is called
 178     for the items.
 179
 180     \sa itemsMissing(), requestItems(), bufferType()
 181 */
 182
 183 /*!
 184     \fn void QPlatformSharedGraphicsCache::itemsUpdated(const QByteArray &cacheId, void *bufferId, const QVector<quint32> &itemIds, const QVector<QPoint> &positionsInBuffer)
 185
 186     This signal is similar in usage to the itemsAvailable() signal, but will be emitted when
 187     the location of a previously requested or inserted item has been updated. The application
 188     must update its data for the respective items and release any references to old buffers held
 189     by the items.
 190
 191     If the application no longer holds any references to previously referenced items in a given
 192     cache, it should call releaseItems() for these items, at which point it will no longer receive
 193     any itemsUpdated() signal for these items.
 194
 195     \sa requestItems(), insertItems(), itemsAvailable()
 196 */
 197
 198 /*!
 199     \fn void QPlatformSharedGraphicsCache::itemsInvalidated(const QByteArray &cacheId, const QVector<quint32> &itemIds)
 200
 201     This signal is emitted when the items given by \a itemIds in the cache named \a cacheId have
 202     been removed from the cache and the previously reported information about them is considered
 203     invalid. It will only be emitted for items for which a buffer has previously been identified
 204     through the itemsAvailable() signal (either as response to a requestItems() call or an
 205     insertItems() call.)
 206
 207     The application is expected to throw away information about the items in the \a itemIds array
 208     and drop any references it might have to the memory held by the buffer. If the items are still
 209     required by the application, it can re-commit them to the cache using the insertItems() function.
 210
 211     If the application no longer holds any references to previously referenced items in a given
 212     cache, it should call releaseItems() for these items, at which point it will no longer receive
 213     any itemsInvalidated() signal for these items.
 214 */
 215
 216 /*!
 217     \fn void QPlatformSharedGraphicsCache::beginRequestBatch()
 218
 219     This is a hint to the cache that a burst of requests is pending. In some implementations, this
 220     will improve performance, as the cache can focus on handling the requests and wait with the
 221     results until it is done. It should typically be called prior to a sequence of calls to
 222     requestItems() and releaseItems().
 223
 224     Any call to beginRequestBatch() must be followed at some point by a call to endRequestBatch().
 225     Failing to do this may lead to the results of requests never being emitted.
 226
 227     \note beginRequestBatch() and endRequestBatch() have no stacking logic. Calling
 228     beginRequestBatch() twice in a row has no effect, and the single existing batch will be ended
 229     by the earliest call to endRequestBatch().
 230
 231     \sa endRequestBatch(), requestBatchStarted()
 232 */
 233
 234 /*!
 235     \fn void QPlatformSharedGraphicsCache::endRequestBatch()
 236
 237     Signals to the cache that the request sequence which has previously been commenced using
 238     beginRequestBatch() has now finished.
 239
 240     \sa beginRequestBatch(), requestBatchStarted()
 241 */
 242
 243 /*!
 244    \fn bool QPlatformSharedGraphicsCache::requestBatchStarted() const
 245
 246    Returns true if a request batch has previously been started using beginRequestBatch()
 247    and not yet stopped using endRequestBatch().
 248
 249    \sa beginRequestBatch(), endRequestBatch()
 250 */
 251
 252 /*!
 253     \fn uint QPlatformSharedGraphicsCache::textureIdForBuffer(void *bufferId)
 254
 255     Returns an OpenGL texture ID corresponding to the buffer \a bufferId, which has previously
 256     been passed through signals itemsAvailable() or itemsUpdated(). The relevant OpenGL context
 257     should be current when calling this function.
 258
 259     \sa eglImageForBuffer(), sizeOfBuffer()
 260 */
 261
 262 /*!
 263     \fn void *QPlatformSharedGraphicsCache::eglImageForBuffer(void *bufferId)
 264
 265     Returns an EGLImageKHR image corresponding to the buffer \a bufferId.
 266
 267     \sa textureIdForBuffer(), sizeOfBuffer()
 268 */
 269
 270 /*!
 271     \fn void QPlatformSharedGraphicsCache::referenceBuffer(void *bufferId)
 272
 273     Registers a reference to the buffer \a bufferId.
 274
 275     \sa dereferenceBuffer()
 276 */
 277
 278 /*!
 279     \fn bool QPlatformSharedGraphicsCache::dereferenceBuffer(void *bufferId)
 280
 281     Removed a previously registered reference to the buffer \a bufferId. Returns true if there
 282     are still more references to the buffer in question, or false if this was the last reference
 283     (in which case the buffer may have been deleted in the cache.)
 284
 285     \sa dereferenceBuffer()
 286 */
 287
 288 /*!
 289     \fn QSize QPlatformSharedGraphicsCache::sizeOfBuffer(void *bufferId)
 290
 291     Returns the size of the buffer \a bufferId.
 292
 293     \sa textureIdForBuffer(), eglImageForBuffer()
 294 */
 295
 296 QT_END_NAMESPACE