1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/
6 ** This file is part of the QtQml module of the Qt Toolkit.
8 ** $QT_BEGIN_LICENSE:LGPL$
9 ** GNU Lesser General Public License Usage
10 ** This file may be used under the terms of the GNU Lesser General Public
11 ** License version 2.1 as published by the Free Software Foundation and
12 ** appearing in the file LICENSE.LGPL included in the packaging of this
13 ** file. Please review the following information to ensure the GNU Lesser
14 ** General Public License version 2.1 requirements will be met:
15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
17 ** In addition, as a special exception, Nokia gives you certain additional
18 ** rights. These rights are described in the Nokia Qt LGPL Exception
19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
21 ** GNU General Public License Usage
22 ** Alternatively, this file may be used under the terms of the GNU General
23 ** Public License version 3.0 as published by the Free Software Foundation
24 ** and appearing in the file LICENSE.GPL included in the packaging of this
25 ** file. Please review the following information to ensure the GNU General
26 ** Public License version 3.0 requirements will be met:
27 ** http://www.gnu.org/copyleft/gpl.html.
30 ** Alternatively, this file may be used in accordance with the terms and
31 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qqmlimageprovider.h"
46 class QQmlImageProviderPrivate
49 QQmlImageProvider::ImageType type;
53 \class QQuickTextureFactory
55 \brief The QQuickTextureFactory class provides an interface for loading custom textures from QML.
58 The purpose of the texture factory is to provide a placeholder for a image
59 data that can be converted into an OpenGL texture.
61 Creating a texture directly is not possible as there is rarely an OpenGL context
62 available in the thread that is responsible for loading the image data.
65 QQuickTextureFactory::QQuickTextureFactory()
69 QQuickTextureFactory::~QQuickTextureFactory()
75 \fn QImage QQuickTextureFactory::image() const
77 Returns an image version of this texture.
79 The lifespan of the returned image is unknown, so the implementation should
80 return a self contained QImage, not make use of the QImage(uchar *, ...)
83 This function is not commonly used and is expected to be slow.
86 QImage QQuickTextureFactory::image() const
93 \fn QSGTexture *QQuickTextureFactory::createTexture() const
95 This function is called on the scene graph rendering thread to create a QSGTexture
96 instance from the factory.
98 QML will internally cache the returned texture as needed. Each call to this
99 function should return a unique instance.
101 The OpenGL context used for rendering is bound when this function is called.
105 \fn QSize QQuickTextureFactory::textureSize() const
107 Returns the size of the texture. This function will be called from arbitrary threads
108 and should not rely on an OpenGL context bound.
113 \class QQmlImageProvider
116 \brief The QQmlImageProvider class provides an interface for supporting pixmaps and threaded image requests in QML.
118 QQmlImageProvider is used to provide advanced image loading features
119 in QML applications. It allows images in QML to be:
122 \li Loaded using QPixmaps rather than actual image files
123 \li Loaded asynchronously in a separate thread, if imageType() is \l{QQmlImageProvider::ImageType}{ImageType::Image}
126 To specify that an image should be loaded by an image provider, use the
127 \b {"image:"} scheme for the URL source of the image, followed by the
128 identifiers of the image provider and the requested image. For example:
131 Image { source: "image://myimageprovider/image.png" }
134 This specifies that the image should be loaded by the image provider named
135 "myimageprovider", and the image to be loaded is named "image.png". The QML engine
136 invokes the appropriate image provider according to the providers that have
137 been registered through QQmlEngine::addImageProvider().
139 Note that the identifiers are case-insensitive, but the rest of the URL will be passed on with
140 preserved case. For example, the below snippet would still specify that the image is loaded by the
141 image provider named "myimageprovider", but it would request a different image than the above snippet
142 ("Image.png" instead of "image.png").
144 Image { source: "image://MyImageProvider/Image.png" }
147 If you want the rest of the URL to be case insensitive, you will have to take care
148 of that yourself inside your image provider.
152 Here are two images. Their \c source values indicate they should be loaded by
153 an image provider named "colors", and the images to be loaded are "yellow"
154 and "red", respectively:
156 \snippet examples/declarative/cppextensions/imageprovider/imageprovider-example.qml 0
158 When these images are loaded by QML, it looks for a matching image provider
159 and calls its requestImage() or requestPixmap() method (depending on its
160 imageType()) to load the image. The method is called with the \c id
161 parameter set to "yellow" for the first image, and "red" for the second.
163 Here is an image provider implementation that can load the images
164 requested by the above QML. This implementation dynamically
165 generates QPixmap images that are filled with the requested color:
167 \snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 0
169 \snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 1
171 To make this provider accessible to QML, it is registered with the QML engine
172 with a "colors" identifier:
175 int main(int argc, char *argv[])
180 engine->addImageProvider(QLatin1String("colors"), new ColorPixmapProvider);
186 Now the images can be successfully loaded in QML:
188 \image imageprovider.png
190 A complete example is available in Qt's
191 \l {declarative/cppextensions/imageprovider}{examples/declarative/cppextensions/imageprovider}
192 directory. Note the example registers the provider via a \l{QQmlExtensionPlugin}{plugin}
193 instead of registering it in the application \c main() function as shown above.
196 \section2 Asynchronous image loading
198 Image providers that support QImage loading automatically include support
199 for asychronous loading of images. To enable asynchronous loading for an
200 image source, set the \c asynchronous property to \c true for the relevant
201 \l Image, \l BorderImage or \l AnimatedImage object. When this is enabled,
202 the image request to the provider is run in a low priority thread,
203 allowing image loading to be executed in the background, and reducing the
204 performance impact on the user interface.
206 Asynchronous loading is not supported for image providers that provide
207 QPixmap rather than QImage values, as pixmaps can only be created in the
208 main thread. In this case, if \l {Image::}{asynchronous} is set to
209 \c true, the value is ignored and the image is loaded
213 \section2 Image caching
215 Images returned by a QQmlImageProvider are automatically cached,
216 similar to any image loaded by the QML engine. When an image with a
217 "image://" prefix is loaded from cache, requestImage() and requestPixmap()
218 will not be called for the relevant image provider. If an image should always
219 be fetched from the image provider, and should not be cached at all, set the
220 \c cache property to \c false for the relevant \l Image, \l BorderImage or
221 \l AnimatedImage object.
223 The QtQuick 1 version of this class is named QDeclarativeImageProvider.
225 \sa QQmlEngine::addImageProvider()
229 \enum QQmlImageProvider::ImageType
231 Defines the type of image supported by this image provider.
233 \value Image The Image Provider provides QImage images. The
234 requestImage() method will be called for all image requests.
235 \value Pixmap The Image Provider provides QPixmap images. The
236 requestPixmap() method will be called for all image requests.
237 \value Texture The Image Provider provides QSGTextureProvider based images.
238 The requestTexture() method will be called for all image requests. \omitvalue
242 Creates an image provider that will provide images of the given \a type.
244 QQmlImageProvider::QQmlImageProvider(ImageType type)
245 : d(new QQmlImageProviderPrivate)
251 Destroys the QQmlImageProvider
253 \note The destructor of your derived class need to be thread safe.
255 QQmlImageProvider::~QQmlImageProvider()
261 Returns the image type supported by this provider.
263 QQmlImageProvider::ImageType QQmlImageProvider::imageType() const
269 Implement this method to return the image with \a id. The default
270 implementation returns an empty image.
272 The \a id is the requested image source, with the "image:" scheme and
273 provider identifier removed. For example, if the image \l{Image::}{source}
274 was "image://myprovider/icons/home", the given \a id would be "icons/home".
276 The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
277 an Image element. If \a requestedSize is a valid size, the image
278 returned should be of that size.
280 In all cases, \a size must be set to the original size of the image. This
281 is used to set the \l {Item::}{width} and \l {Item::}{height} of the
282 relevant \l Image if these values have not been set explicitly.
284 \note this method may be called by multiple threads, so ensure the
285 implementation of this method is reentrant.
287 QImage QQmlImageProvider::requestImage(const QString &id, QSize *size, const QSize& requestedSize)
291 Q_UNUSED(requestedSize);
292 if (d->type == Image)
293 qWarning("ImageProvider supports Image type but has not implemented requestImage()");
298 Implement this method to return the pixmap with \a id. The default
299 implementation returns an empty pixmap.
301 The \a id is the requested image source, with the "image:" scheme and
302 provider identifier removed. For example, if the image \l{Image::}{source}
303 was "image://myprovider/icons/home", the given \a id would be "icons/home".
305 The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
306 an Image element. If \a requestedSize is a valid size, the image
307 returned should be of that size.
309 In all cases, \a size must be set to the original size of the image. This
310 is used to set the \l {Item::}{width} and \l {Item::}{height} of the
311 relevant \l Image if these values have not been set explicitly.
313 QPixmap QQmlImageProvider::requestPixmap(const QString &id, QSize *size, const QSize& requestedSize)
317 Q_UNUSED(requestedSize);
318 if (d->type == Pixmap)
319 qWarning("ImageProvider supports Pixmap type but has not implemented requestPixmap()");
325 Implement this method to return the texture with \a id. The default
326 implementation returns 0.
328 The \a id is the requested image source, with the "image:" scheme and
329 provider identifier removed. For example, if the image \l{Image::}{source}
330 was "image://myprovider/icons/home", the given \a id would be "icons/home".
332 The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
333 an Image element. If \a requestedSize is a valid size, the image
334 returned should be of that size.
336 In all cases, \a size must be set to the original size of the image. This
337 is used to set the \l {Item::}{width} and \l {Item::}{height} of the
338 relevant \l Image if these values have not been set explicitly.
340 \note this method may be called by multiple threads, so ensure the
341 implementation of this method is reentrant.
344 QQuickTextureFactory *QQmlImageProvider::requestTexture(const QString &id, QSize *size, const QSize &requestedSize)
348 Q_UNUSED(requestedSize);
349 if (d->type == Texture)
350 qWarning("ImageProvider supports Texture type but has not implemented requestTexture()");