1berry/qtbase
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

rhi: Enhance swapchain size query docs

Browse Source 
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>
This commit is contained in:
Laszlo Agocs 2019-10-20 18:06:07 +02:00
parent d71dbe3e93
commit 5288c8dae3
1 changed files with 24 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
src/gui/rhi/qrhi.cpp
View File

@ -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