summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorEirik Aavitsland <eirik.aavitsland@qt.io>2018-02-28 15:35:36 +0100
committerEirik Aavitsland <eirik.aavitsland@qt.io>2018-04-13 13:17:23 +0000
commit539d724890aec3f00eadb39aeae973670e664ec6 (patch)
treea09183d56e5445d8be9a9c5699985b02936020f6
parent191413704be811c31d5f9d8b5916681ee6c54ddf (diff)
Doc: Describe new 5.11 features in Image elementv5.11.0-beta4
Add user documentation of the compressed texture file support and the file extension auto detection. Change-Id: Icfae8574dd3acba30e8275ccd6ff3438fa037868 Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>
-rw-r--r--src/quick/doc/snippets/qml/image-ext.qml68
-rw-r--r--src/quick/items/qquickimage.cpp46
-rw-r--r--tests/auto/quick/examples/tst_examples.cpp1
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