v5.11.0-beta4

3 files changed, 113 insertions, 2 deletions

diff --git a/src/quick/doc/snippets/qml/image-ext.qml b/src/quick/doc/snippets/qml/image-ext.qml
new file mode 100644
index 0000000000..5e95f2b4cf
--- /dev/null
+++ b/src/quick/doc/snippets/qml/image-ext.qml
@@ -0,0 +1,68 @@
+/****************************************************************************
+**
+** Copyright (C) 2018 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:BSD$
+** 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 The Qt Company. For licensing terms
+** and conditions see https://www.qt.io/terms-conditions. For further
+** information use the contact form at https://www.qt.io/contact-us.
+**
+** BSD License Usage
+** Alternatively, you may use this file under the terms of the BSD license
+** as follows:
+**
+** "Redistribution and use in source and binary forms, with or without
+** modification, are permitted provided that the following conditions are
+** met:
+**   * Redistributions of source code must retain the above copyright
+**     notice, this list of conditions and the following disclaimer.
+**   * Redistributions in binary form must reproduce the above copyright
+**     notice, this list of conditions and the following disclaimer in
+**     the documentation and/or other materials provided with the
+**     distribution.
+**   * Neither the name of The Qt Company Ltd nor the names of its
+**     contributors may be used to endorse or promote products derived
+**     from this software without specific prior written permission.
+**
+**
+** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+//! [ext]
+// Assuming the "pics" directory contains the following files:
+//   dog.jpg
+//   cat.png
+//   cat.pkm
+
+Image {
+    source: "pics/cat.png"     // loads cat.png
+}
+
+Image {
+    source: "pics/dog"         // loads dog.jpg
+}
+
+Image {
+    source: "pics/cat"         // normally loads cat.pkm, but if no OpenGL, loads cat.png instead.
+}
+//! [ext]
diff --git a/src/quick/items/qquickimage.cpp b/src/quick/items/qquickimage.cpp
index dc2cd17b4e..db5cfd2526 100644
--- a/src/quick/items/qquickimage.cpp
+++ b/src/quick/items/qquickimage.cpp
@@ -135,6 +135,48 @@ QQuickImagePrivate::QQuickImagePrivate()
 
     \clearfloat
 
+    \section1 OpenGL Texture Files
+
+    When the default OpenGL \l{Qt Quick Scene Graph}{scene graph} backend is in
+    use, images can also be supplied in compressed texture files. The content
+    must be a simple RGB(A) format 2D texture. Supported compression schemes
+    are only limited by the underlying OpenGL driver and GPU. The following
+    container file formats are supported:
+
+    \list
+    \li \c PKM (since Qt 5.10)
+    \li \c KTX (since Qt 5.11)
+    \endlist
+
+    \note Semi-transparent original images require alpha pre-multiplication
+    prior to texture compression in order to be correctly displayed in Qt
+    Quick. This can be done with the following ImageMagick command
+    line:
+    \badcode
+    convert MYORIGIMAGE \( +clone -alpha Extract \) -channel RGB -compose Multiply -composite MYPMIMAGE
+    \endcode
+
+    \section1 Automatic Detection of File Extension
+
+    If the \l source URL indicates a non-existing local file or resource, the
+    Image element attempts to auto-detect the file extension. If an existing
+    file can be found by appending any of the supported image file extensions
+    to the \l source URL, then that file will be loaded.
+
+    If the OpenGL \l{Qt Quick Scene Graph}{scene graph} backend is in use, the
+    file search the attempts the OpenGL texture file extensions first. If the
+    search is unsuccessful, it attempts to search with the file extensions for
+    the \l{QImageReader::supportedImageFormats()}{conventional image file
+    types}. For example:
+
+    \snippet qml/image-ext.qml ext
+
+    This functionality facilitates deploying different image asset file types
+    on different target platforms. This can be useful in order to tune
+    application performance and adapt to different graphics hardware.
+
+    This functionality was introduced in Qt 5.11.
+
     \section1 Performance
 
     By default, locally available images are loaded immediately, and the user interface
@@ -154,7 +196,7 @@ QQuickImagePrivate::QQuickImagePrivate()
     size bounded via the \l sourceSize property. This is especially important for content
     that is loaded from external sources or provided by the user.
 
-    \sa {Qt Quick Examples - Image Elements}, QQuickImageProvider
+    \sa {Qt Quick Examples - Image Elements}, QQuickImageProvider, QImageReader::setAutoDetectImageFormat()
 */
 
 QQuickImage::QQuickImage(QQuickItem *parent)
@@ -461,7 +503,7 @@ qreal QQuickImage::paintedHeight() const
 
     The URL may be absolute, or relative to the URL of the component.
 
-    \sa QQuickImageProvider
+    \sa QQuickImageProvider {OpenGL Texture Files} {Automatic Detection of File Extension}
 */
 
 /*!
diff --git a/tests/auto/quick/examples/tst_examples.cpp b/tests/auto/quick/examples/tst_examples.cpp
index 716651ec0c..eee8dfcf26 100644
--- a/tests/auto/quick/examples/tst_examples.cpp
+++ b/tests/auto/quick/examples/tst_examples.cpp
@@ -86,6 +86,7 @@ tst_examples::tst_examples()
     excludedDirs << "snippets/qml/visualdatamodel_rootindex";
     excludedDirs << "snippets/qml/qtbinding";
     excludedDirs << "snippets/qml/imports";
+    excludedFiles << "snippets/qml/image-ext.qml";
     excludedFiles << "examples/quick/shapes/content/main.qml"; // relies on resources
     excludedFiles << "examples/quick/shapes/content/interactive.qml"; // relies on resources