src/quick/util/qquickimageprovider.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtQml module of the Qt Toolkit.
   7 **
   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.
  16 **
  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.
  20 **
  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.
  28 **
  29 ** Other Usage
  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.
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 #include "qquickimageprovider.h"
  43
  44 QT_BEGIN_NAMESPACE
  45
  46 class QQuickImageProviderPrivate
  47 {
  48 public:
  49     QQuickImageProvider::ImageType type;
  50 };
  51
  52 /*!
  53     \class QQuickTextureFactory
  54     \since 5.0
  55     \brief The QQuickTextureFactory class provides an interface for loading custom textures from QML.
  56     \inmodule QtQml
  57
  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.
  60
  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.
  63  */
  64
  65 QQuickTextureFactory::QQuickTextureFactory()
  66 {
  67 }
  68
  69 QQuickTextureFactory::~QQuickTextureFactory()
  70 {
  71 }
  72
  73
  74 /*!
  75     \fn QImage QQuickTextureFactory::image() const
  76
  77     Returns an image version of this texture.
  78
  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 *, ...)
  81     constructor.
  82
  83     This function is not commonly used and is expected to be slow.
  84  */
  85
  86 QImage QQuickTextureFactory::image() const
  87 {
  88     return QImage();
  89 }
  90
  91
  92 /*!
  93     \fn QSGTexture *QQuickTextureFactory::createTexture() const
  94
  95     This function is called on the scene graph rendering thread to create a QSGTexture
  96     instance from the factory.
  97
  98     QML will internally cache the returned texture as needed. Each call to this
  99     function should return a unique instance.
 100
 101     The OpenGL context used for rendering is bound when this function is called.
 102  */
 103
 104 /*!
 105     \fn QSize QQuickTextureFactory::textureSize() const
 106
 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.
 109  */
 110
 111
 112 /*!
 113     \class QQuickImageProvider
 114     \since 5.0
 115     \inmodule QtQuick
 116     \brief The QQuickImageProvider class provides an interface for supporting pixmaps and threaded image requests in QML.
 117
 118     QQuickImageProvider is used to provide advanced image loading features
 119     in QML applications. It allows images in QML to be:
 120
 121     \list
 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}
 124     \endlist
 125
 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:
 129
 130     \qml
 131     Image { source: "image://myimageprovider/image.png" }
 132     \endqml
 133
 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().
 138
 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").
 143     \qml
 144     Image { source: "image://MyImageProvider/Image.png" }
 145     \endqml
 146
 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.
 149
 150     \section2 An example
 151
 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:
 155
 156     \snippet examples/declarative/cppextensions/imageprovider/imageprovider-example.qml 0
 157
 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.
 162
 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:
 166
 167     \snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 0
 168     \codeline
 169     \snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 1
 170
 171     To make this provider accessible to QML, it is registered with the QML engine
 172     with a "colors" identifier:
 173
 174     \code
 175     int main(int argc, char *argv[])
 176     {
 177         ...
 178
 179         QQmlEngine engine;
 180         engine->addImageProvider(QLatin1String("colors"), new ColorPixmapProvider);
 181
 182         ...
 183     }
 184     \endcode
 185
 186     Now the images can be successfully loaded in QML:
 187
 188     \image imageprovider.png
 189
 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.
 194
 195
 196     \section2 Asynchronous image loading
 197
 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.
 205
 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
 210     synchronously.
 211
 212
 213     \section2 Image caching
 214
 215     Images returned by a QQuickImageProvider 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.
 222
 223     The QtQuick 1 version of this class is named QDeclarativeImageProvider.
 224
 225     \sa QQmlEngine::addImageProvider()
 226 */
 227
 228 /*!
 229     Creates an image provider that will provide images of the given \a type.
 230 */
 231 QQuickImageProvider::QQuickImageProvider(ImageType type)
 232     : d(new QQuickImageProviderPrivate)
 233 {
 234     d->type = type;
 235 }
 236
 237 /*!
 238     Destroys the QQuickImageProvider
 239
 240     \note The destructor of your derived class need to be thread safe.
 241 */
 242 QQuickImageProvider::~QQuickImageProvider()
 243 {
 244     delete d;
 245 }
 246
 247 /*!
 248     Returns the image type supported by this provider.
 249 */
 250 QQuickImageProvider::ImageType QQuickImageProvider::imageType() const
 251 {
 252     return d->type;
 253 }
 254
 255 /*!
 256     Implement this method to return the image with \a id. The default
 257     implementation returns an empty image.
 258
 259     The \a id is the requested image source, with the "image:" scheme and
 260     provider identifier removed. For example, if the image \l{Image::}{source}
 261     was "image://myprovider/icons/home", the given \a id would be "icons/home".
 262
 263     The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
 264     an Image element. If \a requestedSize is a valid size, the image
 265     returned should be of that size.
 266
 267     In all cases, \a size must be set to the original size of the image. This
 268     is used to set the \l {Item::}{width} and \l {Item::}{height} of the
 269     relevant \l Image if these values have not been set explicitly.
 270
 271     \note this method may be called by multiple threads, so ensure the
 272     implementation of this method is reentrant.
 273 */
 274 QImage QQuickImageProvider::requestImage(const QString &id, QSize *size, const QSize& requestedSize)
 275 {
 276     Q_UNUSED(id);
 277     Q_UNUSED(size);
 278     Q_UNUSED(requestedSize);
 279     if (d->type == Image)
 280         qWarning("ImageProvider supports Image type but has not implemented requestImage()");
 281     return QImage();
 282 }
 283
 284 /*!
 285     Implement this method to return the pixmap with \a id. The default
 286     implementation returns an empty pixmap.
 287
 288     The \a id is the requested image source, with the "image:" scheme and
 289     provider identifier removed. For example, if the image \l{Image::}{source}
 290     was "image://myprovider/icons/home", the given \a id would be "icons/home".
 291
 292     The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
 293     an Image element. If \a requestedSize is a valid size, the image
 294     returned should be of that size.
 295
 296     In all cases, \a size must be set to the original size of the image. This
 297     is used to set the \l {Item::}{width} and \l {Item::}{height} of the
 298     relevant \l Image if these values have not been set explicitly.
 299 */
 300 QPixmap QQuickImageProvider::requestPixmap(const QString &id, QSize *size, const QSize& requestedSize)
 301 {
 302     Q_UNUSED(id);
 303     Q_UNUSED(size);
 304     Q_UNUSED(requestedSize);
 305     if (d->type == Pixmap)
 306         qWarning("ImageProvider supports Pixmap type but has not implemented requestPixmap()");
 307     return QPixmap();
 308 }
 309
 310
 311 /*!
 312     Implement this method to return the texture with \a id. The default
 313     implementation returns 0.
 314
 315     The \a id is the requested image source, with the "image:" scheme and
 316     provider identifier removed. For example, if the image \l{Image::}{source}
 317     was "image://myprovider/icons/home", the given \a id would be "icons/home".
 318
 319     The \a requestedSize corresponds to the \l {Image::sourceSize} requested by
 320     an Image element. If \a requestedSize is a valid size, the image
 321     returned should be of that size.
 322
 323     In all cases, \a size must be set to the original size of the image. This
 324     is used to set the \l {Item::}{width} and \l {Item::}{height} of the
 325     relevant \l Image if these values have not been set explicitly.
 326
 327     \note this method may be called by multiple threads, so ensure the
 328     implementation of this method is reentrant.
 329 */
 330
 331 QQuickTextureFactory *QQuickImageProvider::requestTexture(const QString &id, QSize *size, const QSize &requestedSize)
 332 {
 333     Q_UNUSED(id);
 334     Q_UNUSED(size);
 335     Q_UNUSED(requestedSize);
 336     if (d->type == Texture)
 337         qWarning("ImageProvider supports Texture type but has not implemented requestTexture()");
 338     return 0;
 339 }
 340
 341 QT_END_NAMESPACE
 342