From c7bd56b7a28f7c95573b0a3eb7e2f1f40801294c Mon Sep 17 00:00:00 2001 From: Laszlo Agocs Date: Tue, 16 May 2023 14:51:27 +0200 Subject: Enhance Image docs about compressed formats Pick-to: 6.5 6.2 Fixes: QTBUG-113565 Change-Id: I6ccd0aa27a599c09a93a6c377b36697d9c60f25e Reviewed-by: Shawn Rutledge Reviewed-by: Eirik Aavitsland --- src/quick/items/qquickimage.cpp | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) 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 -- cgit v1.2.1