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