1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
|
/****************************************************************************
**
** Copyright (C) 2014 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the QtGui module of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL21$
** 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 Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/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 2.1 or version 3 as published by the Free
** Software Foundation and appearing in the file LICENSE.LGPLv21 and
** LICENSE.LGPLv3 included in the packaging of this file. Please review the
** following information to ensure the GNU Lesser General Public License
** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Digia gives you certain additional
** rights. These rights are described in the Digia Qt LGPL Exception
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
**
** $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 QVector<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 QVector<quint32> &itemIds, const QVector<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 QVector<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 QVector<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 vector \a itemIds 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 QVector<quint32> &itemIds, const QVector<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 vector. The
\a positionsInBuffer vector 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 QVector<quint32> &itemIds, const QVector<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 QVector<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
|
