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

source code of qtbase/src/gui/kernel/qplatformsharedgraphicscache.cpp