Enhance Image docs about compressed formats

Pick-to: 6.5 6.2
Fixes: QTBUG-113565
Change-Id: I6ccd0aa27a599c09a93a6c377b36697d9c60f25e
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>
Reviewed-by: Eirik Aavitsland <eirik.aavitsland@qt.io>

1 files changed, 37 insertions, 0 deletions

diff --git a/src/quick/items/qquickimage.cpp b/src/quick/items/qquickimage.cpp
index 7101cf8719..9523b838f4 100644
--- a/src/quick/items/qquickimage.cpp
+++ b/src/quick/items/qquickimage.cpp
@@ -115,6 +115,43 @@ QQuickImagePrivate::QQuickImagePrivate()
     convert foo.png \( +clone -alpha Extract \) -channel RGB -compose Multiply -composite foo_pm.png
     \endcode
 
+    Do not confuse container formats, such as, \c KTX, and the format of the
+    actual texture data stored in the container file. For example, reading a
+    \c KTX file is supported on all platforms, independently of what GPU driver is
+    used at run time. However, this does not guarantee that the compressed
+    texture format, used by the data in the file, is supported at run time. For
+    example, if the KTX file contains compressed data with the format
+    \c{ETC2 RGBA8}, and the 3D graphics API implementation used at run time does not
+    support \c ETC2 compressed textures, the Image item will not display
+    anything.
+
+    \note Compressed texture format support is not under Qt's control, and it
+    is up to the application or device developer to ensure the compressed
+    texture data is provided in the appropriate format for the target
+    environment(s).
+
+    Do not assume that compressed format support is specific to a platform. It
+    may also be specific to the driver and 3D API implementation in use on that
+    particular platform. In practice, implementations of different 3D graphics
+    APIs (e.g., Vulkan and OpenGL) on the same platform (e.g., Windows) from
+    the same vendor for the same hardware may offer a different set of
+    compressed texture formats.
+
+    When targeting desktop environments (Windows, macOS, Linux) only, a general
+    recommendation is to consider using the \c{DXTn}/\c{BCn} formats since
+    these tend to have the widest support amongst the implementations of Direct
+    3D, Vulkan, OpenGL, and Metal on these platforms. In contrast, when
+    targeting mobile or embedded devices, the \c ETC2 or \c ASTC formats are
+    likely to be a better choice since these are typically the formats
+    supported by the OpenGL ES implementations on such hardware.
+
+    An application that intends to run across desktop, mobile, and embedded
+    hardware should plan and design its use of compressed textures carefully.
+    It is highly likely that relying on a single format is not going to be
+    sufficient, and therefore the application will likely need to branch based
+    on the platform to use compressed textures in a format appropriate there,
+    or perhaps to skip using compressed textures in some cases.
+
     \section1 Automatic Detection of File Extension
 
     If the \l source URL indicates a non-existing local file or resource, the