summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLaszlo Agocs <laszlo.agocs@qt.io>2019-10-20 18:06:07 +0200
committerLaszlo Agocs <laszlo.agocs@qt.io>2019-10-21 09:28:33 +0200
commit5288c8dae34ae3a3883f12c8fabeb717e1c5a263 (patch)
tree207d5642613bc56529dc3b7e186ec32f35d4aece
parentd71dbe3e9322430dceed9cb2d3f957fbac2ab715 (diff)
rhi: Enhance swapchain size query docs
Inspired by a recent Qt Quick fix. Make sure we make it clear that QRhi-based rendering code should base output size calculations (e.g. for setViewport() and similar) on the pixel size reported from QRhiSwapChain, instead of going to the QWindow. Change-Id: I2fc22972162ccc6307ac07ceb7766c746d5f562a Reviewed-by: Paul Olav Tvete <paul.tvete@qt.io>
-rw-r--r--src/gui/rhi/qrhi.cpp26
1 files changed, 24 insertions, 2 deletions
diff --git a/src/gui/rhi/qrhi.cpp b/src/gui/rhi/qrhi.cpp
index dabad35688..8ef98d2e42 100644
--- a/src/gui/rhi/qrhi.cpp
+++ b/src/gui/rhi/qrhi.cpp
@@ -3518,14 +3518,36 @@ QRhiResource::Type QRhiSwapChain::resourceType() const
\c{currentPixelSize() != surfacePixelSize()} then the swapchain needs to be
resized.
+ \note Typical rendering logic will call this function to get the output
+ size when starting to prepare a new frame, and base dependent calculations
+ (such as, the viewport) on the size returned from this function.
+
+ While in many cases the value is the same as \c{QWindow::size() *
+ QWindow::devicePixelRatio()}, relying on the QWindow-reported size is not
+ guaranteed to be correct on all platforms and graphics API implementations.
+ Using this function is therefore strongly recommended whenever there is a
+ need to identify the dimensions, in pixels, of the output layer or surface.
+
+ This also has the added benefit of avoiding potential data races when QRhi
+ is used on a dedicated rendering thread, because the need to call QWindow
+ functions, that may then access data updated on the main thread, is
+ avoided.
+
\sa surfacePixelSize()
*/
/*!
\fn QSize QRhiSwapChain::surfacePixelSize()
- \return The size of the window's associated surface or layer. Do not assume
- this is the same as QWindow::size() * QWindow::devicePixelRatio().
+ \return The size of the window's associated surface or layer.
+
+ \warning Do not assume this is the same as \c{QWindow::size() *
+ QWindow::devicePixelRatio()}. With some graphics APIs and windowing system
+ interfaces (for example, Vulkan) there is a theoretical possibility for a
+ surface to assume a size different from the associated window. To support
+ these cases, rendering logic must always base size-derived calculations
+ (such as, viewports) on the size reported from QRhiSwapChain, and never on
+ the size queried from QWindow.
\note Can also be called before buildOrResize(), if at least window() is
already set) This in combination with currentPixelSize() allows to detect