1 /****************************************************************************
3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: http://www.qt-project.org/
7 ** This file is part of the QtDeclarative module of the Qt Toolkit.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
42 #include "qdeclarativeimageprovider.h"
46 class QDeclarativeImageProviderPrivate
49 QDeclarativeImageProvider::ImageType type;
53 \class QDeclarativeTextureFactory
55 \brief The QDeclarativeTextureFactory class provides an interface for loading custom textures from QML.
57 The purpose of the texture factory is to provide a placeholder for a image
58 data that can be converted into an OpenGL texture.
60 Creating a texture directly is not possible as there is rarely an OpenGL context
61 available in the thread that is responsible for loading the image data.
64 QDeclarativeTextureFactory::QDeclarativeTextureFactory()
68 QDeclarativeTextureFactory::~QDeclarativeTextureFactory()
75 \fn QSGTexture *QDeclarativeTextureFactory::createTexture() const
77 This function is called on the scene graph rendering thread to create a QSGTexture
78 instance from the factory.
80 QML will internally cache the returned texture as needed. Each call to this
81 function should return a unique instance.
83 The OpenGL context used for rendering is bound when this function is called.
87 \fn QSize QDeclarativeTextureFactory::textureSize() const
89 Returns the size of the texture. This function will be called from arbitrary threads
90 and should not rely on an OpenGL context bound.
95 \class QDeclarativeImageProvider
97 \brief The QDeclarativeImageProvider class provides an interface for supporting pixmaps and threaded image requests in QML.
99 QDeclarativeImageProvider is used to provide advanced image loading features
100 in QML applications. It allows images in QML to be:
103 \o Loaded using QPixmaps rather than actual image files
104 \o Loaded asynchronously in a separate thread, if imageType() is \l{QDeclarativeImageProvider::ImageType}{ImageType::Image}
107 To specify that an image should be loaded by an image provider, use the
108 \bold {"image:"} scheme for the URL source of the image, followed by the
109 identifiers of the image provider and the requested image. For example:
112 Image { source: "image://myimageprovider/image.png" }
115 This specifies that the image should be loaded by the image provider named
116 "myimageprovider", and the image to be loaded is named "image.png". The QML engine
117 invokes the appropriate image provider according to the providers that have
118 been registered through QDeclarativeEngine::addImageProvider().
120 Note that the identifiers are case-insensitive, but the rest of the URL will be passed on with
121 preserved case. For example, the below snippet would still specify that the image is loaded by the
122 image provider named "myimageprovider", but it would request a different image than the above snippet
123 ("Image.png" instead of "image.png").
125 Image { source: "image://MyImageProvider/Image.png" }
128 If you want the rest of the URL to be case insensitive, you will have to take care
129 of that yourself inside your image provider.
133 Here are two images. Their \c source values indicate they should be loaded by
134 an image provider named "colors", and the images to be loaded are "yellow"
135 and "red", respectively:
137 \snippet examples/declarative/cppextensions/imageprovider/imageprovider-example.qml 0
139 When these images are loaded by QML, it looks for a matching image provider
140 and calls its requestImage() or requestPixmap() method (depending on its
141 imageType()) to load the image. The method is called with the \c id
142 parameter set to "yellow" for the first image, and "red" for the second.
144 Here is an image provider implementation that can load the images
145 requested by the above QML. This implementation dynamically
146 generates QPixmap images that are filled with the requested color:
148 \snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 0
150 \snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 1
152 To make this provider accessible to QML, it is registered with the QML engine
153 with a "colors" identifier:
156 int main(int argc, char *argv[])
160 QDeclarativeEngine engine;
161 engine->addImageProvider(QLatin1String("colors"), new ColorPixmapProvider);
167 Now the images can be successfully loaded in QML:
169 \image imageprovider.png
171 A complete example is available in Qt's
172 \l {declarative/cppextensions/imageprovider}{examples/declarative/cppextensions/imageprovider}
173 directory. Note the example registers the provider via a \l{QDeclarativeExtensionPlugin}{plugin}
174 instead of registering it in the application \c main() function as shown above.
177 \section2 Asynchronous image loading
179 Image providers that support QImage loading automatically include support
180 for asychronous loading of images. To enable asynchronous loading for an
181 image source, set the \c asynchronous property to \c true for the relevant
182 \l Image, \l BorderImage or \l AnimatedImage object. When this is enabled,
183 the image request to the provider is run in a low priority thread,
184 allowing image loading to be executed in the background, and reducing the
185 performance impact on the user interface.
187 Asynchronous loading is not supported for image providers that provide
188 QPixmap rather than QImage values, as pixmaps can only be created in the
189 main thread. In this case, if \l {Image::}{asynchronous} is set to
190 \c true, the value is ignored and the image is loaded
194 \section2 Image caching
196 Images returned by a QDeclarativeImageProvider are automatically cached,
197 similar to any image loaded by the QML engine. When an image with a
198 "image://" prefix is loaded from cache, requestImage() and requestPixmap()
199 will not be called for the relevant image provider. If an image should always
200 be fetched from the image provider, and should not be cached at all, set the
201 \c cache property to \c false for the relevant \l Image, \l BorderImage or
202 \l AnimatedImage object.
204 \sa QDeclarativeEngine::addImageProvider()
208 \enum QDeclarativeImageProvider::ImageType
210 Defines the type of image supported by this image provider.
212 \value Image The Image Provider provides QImage images. The
213 requestImage() method will be called for all image requests.
214 \value Pixmap The Image Provider provides QPixmap images. The
215 requestPixmap() method will be called for all image requests.
216 \value Texture The Image Provider provides QSGTextureProvider based images.
217 The requestTexture() method will be called for all image requests. \omitvalue
221 Creates an image provider that will provide images of the given \a type.
223 QDeclarativeImageProvider::QDeclarativeImageProvider(ImageType type)
224 : d(new QDeclarativeImageProviderPrivate)
230 Destroys the QDeclarativeImageProvider
232 \note The destructor of your derived class need to be thread safe.
234 QDeclarativeImageProvider::~QDeclarativeImageProvider()
240 Returns the image type supported by this provider.
242 QDeclarativeImageProvider::ImageType QDeclarativeImageProvider::imageType() const
248 Implement this method to return the image with \a id. The default
249 implementation returns an empty image.
251 The \a id is the requested image source, with the "image:" scheme and
252 provider identifier removed. For example, if the image \l{Image::}{source}
253 was "image://myprovider/icons/home", the given \a id would be "icons/home".
255 The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
256 an Image element. If \a requestedSize is a valid size, the image
257 returned should be of that size.
259 In all cases, \a size must be set to the original size of the image. This
260 is used to set the \l {Item::}{width} and \l {Item::}{height} of the
261 relevant \l Image if these values have not been set explicitly.
263 \note this method may be called by multiple threads, so ensure the
264 implementation of this method is reentrant.
266 QImage QDeclarativeImageProvider::requestImage(const QString &id, QSize *size, const QSize& requestedSize)
270 Q_UNUSED(requestedSize);
271 if (d->type == Image)
272 qWarning("ImageProvider supports Image type but has not implemented requestImage()");
277 Implement this method to return the pixmap with \a id. The default
278 implementation returns an empty pixmap.
280 The \a id is the requested image source, with the "image:" scheme and
281 provider identifier removed. For example, if the image \l{Image::}{source}
282 was "image://myprovider/icons/home", the given \a id would be "icons/home".
284 The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
285 an Image element. If \a requestedSize is a valid size, the image
286 returned should be of that size.
288 In all cases, \a size must be set to the original size of the image. This
289 is used to set the \l {Item::}{width} and \l {Item::}{height} of the
290 relevant \l Image if these values have not been set explicitly.
292 QPixmap QDeclarativeImageProvider::requestPixmap(const QString &id, QSize *size, const QSize& requestedSize)
296 Q_UNUSED(requestedSize);
297 if (d->type == Pixmap)
298 qWarning("ImageProvider supports Pixmap type but has not implemented requestPixmap()");
304 Implement this method to return the texture with \a id. The default
305 implementation returns 0.
307 The \a id is the requested image source, with the "image:" scheme and
308 provider identifier removed. For example, if the image \l{Image::}{source}
309 was "image://myprovider/icons/home", the given \a id would be "icons/home".
311 The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
312 an Image element. If \a requestedSize is a valid size, the image
313 returned should be of that size.
315 In all cases, \a size must be set to the original size of the image. This
316 is used to set the \l {Item::}{width} and \l {Item::}{height} of the
317 relevant \l Image if these values have not been set explicitly.
319 \note this method may be called by multiple threads, so ensure the
320 implementation of this method is reentrant.
323 QDeclarativeTextureFactory *QDeclarativeImageProvider::requestTexture(const QString &id, QSize *size, const QSize &requestedSize)
327 Q_UNUSED(requestedSize);
328 if (d->type == Texture)
329 qWarning("ImageProvider supports Texture type but has not implemented requestTexture()");