src/declarative/qml/qdeclarativeimageprovider.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 QtDeclarative 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 "qdeclarativeimageprovider.h"
  43
  44 QT_BEGIN_NAMESPACE
  45
  46 class QDeclarativeImageProviderPrivate
  47 {
  48 public:
  49     QDeclarativeImageProvider::ImageType type;
  50 };
  51
  52 /*!
  53     \class QDeclarativeTextureFactory
  54     \since 5.0
  55     \brief The QDeclarativeTextureFactory class provides an interface for loading custom textures from QML.
  56
  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.
  59
  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.
  62  */
  63
  64 QDeclarativeTextureFactory::QDeclarativeTextureFactory()
  65 {
  66 }
  67
  68 QDeclarativeTextureFactory::~QDeclarativeTextureFactory()
  69 {
  70 }
  71
  72
  73
  74 /*!
  75     \fn QSGTexture *QDeclarativeTextureFactory::createTexture() const
  76
  77     This function is called on the scene graph rendering thread to create a QSGTexture
  78     instance from the factory.
  79
  80     QML will internally cache the returned texture as needed. Each call to this
  81     function should return a unique instance.
  82
  83     The OpenGL context used for rendering is bound when this function is called.
  84  */
  85
  86 /*!
  87     \fn QSize QDeclarativeTextureFactory::textureSize() const
  88
  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.
  91  */
  92
  93
  94 /*!
  95     \class QDeclarativeImageProvider
  96     \since 4.7
  97     \brief The QDeclarativeImageProvider class provides an interface for supporting pixmaps and threaded image requests in QML.
  98
  99     QDeclarativeImageProvider is used to provide advanced image loading features
 100     in QML applications. It allows images in QML to be:
 101
 102     \list
 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}
 105     \endlist
 106
 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:
 110
 111     \qml
 112     Image { source: "image://myimageprovider/image.png" }
 113     \endqml
 114
 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().
 119
 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").
 124     \qml
 125     Image { source: "image://MyImageProvider/Image.png" }
 126     \endqml
 127
 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.
 130
 131     \section2 An example
 132
 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:
 136
 137     \snippet examples/declarative/cppextensions/imageprovider/imageprovider-example.qml 0
 138
 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.
 143
 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:
 147
 148     \snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 0
 149     \codeline
 150     \snippet examples/declarative/cppextensions/imageprovider/imageprovider.cpp 1
 151
 152     To make this provider accessible to QML, it is registered with the QML engine
 153     with a "colors" identifier:
 154
 155     \code
 156     int main(int argc, char *argv[])
 157     {
 158         ...
 159
 160         QDeclarativeEngine engine;
 161         engine->addImageProvider(QLatin1String("colors"), new ColorPixmapProvider);
 162
 163         ...
 164     }
 165     \endcode
 166
 167     Now the images can be successfully loaded in QML:
 168
 169     \image imageprovider.png
 170
 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.
 175
 176
 177     \section2 Asynchronous image loading
 178
 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.
 186
 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
 191     synchronously.
 192
 193
 194     \section2 Image caching
 195
 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.
 203
 204     \sa QDeclarativeEngine::addImageProvider()
 205 */
 206
 207 /*!
 208     \enum QDeclarativeImageProvider::ImageType
 209
 210     Defines the type of image supported by this image provider.
 211
 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
 218 */
 219
 220 /*!
 221     Creates an image provider that will provide images of the given \a type.
 222 */
 223 QDeclarativeImageProvider::QDeclarativeImageProvider(ImageType type)
 224     : d(new QDeclarativeImageProviderPrivate)
 225 {
 226     d->type = type;
 227 }
 228
 229 /*!
 230     Destroys the QDeclarativeImageProvider
 231
 232     \note The destructor of your derived class need to be thread safe.
 233 */
 234 QDeclarativeImageProvider::~QDeclarativeImageProvider()
 235 {
 236     delete d;
 237 }
 238
 239 /*!
 240     Returns the image type supported by this provider.
 241 */
 242 QDeclarativeImageProvider::ImageType QDeclarativeImageProvider::imageType() const
 243 {
 244     return d->type;
 245 }
 246
 247 /*!
 248     Implement this method to return the image with \a id. The default
 249     implementation returns an empty image.
 250
 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".
 254
 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.
 258
 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.
 262
 263     \note this method may be called by multiple threads, so ensure the
 264     implementation of this method is reentrant.
 265 */
 266 QImage QDeclarativeImageProvider::requestImage(const QString &id, QSize *size, const QSize& requestedSize)
 267 {
 268     Q_UNUSED(id);
 269     Q_UNUSED(size);
 270     Q_UNUSED(requestedSize);
 271     if (d->type == Image)
 272         qWarning("ImageProvider supports Image type but has not implemented requestImage()");
 273     return QImage();
 274 }
 275
 276 /*!
 277     Implement this method to return the pixmap with \a id. The default
 278     implementation returns an empty pixmap.
 279
 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".
 283
 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.
 287
 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.
 291 */
 292 QPixmap QDeclarativeImageProvider::requestPixmap(const QString &id, QSize *size, const QSize& requestedSize)
 293 {
 294     Q_UNUSED(id);
 295     Q_UNUSED(size);
 296     Q_UNUSED(requestedSize);
 297     if (d->type == Pixmap)
 298         qWarning("ImageProvider supports Pixmap type but has not implemented requestPixmap()");
 299     return QPixmap();
 300 }
 301
 302
 303 /*!
 304     Implement this method to return the texture with \a id. The default
 305     implementation returns 0.
 306
 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".
 310
 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.
 314
 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.
 318
 319     \note this method may be called by multiple threads, so ensure the
 320     implementation of this method is reentrant.
 321 */
 322
 323 QDeclarativeTextureFactory *QDeclarativeImageProvider::requestTexture(const QString &id, QSize *size, const QSize &requestedSize)
 324 {
 325     Q_UNUSED(id);
 326     Q_UNUSED(size);
 327     Q_UNUSED(requestedSize);
 328     if (d->type == Texture)
 329         qWarning("ImageProvider supports Texture type but has not implemented requestTexture()");
 330     return 0;
 331 }
 332
 333 QT_END_NAMESPACE
 334