From afbfe7683f139d71b037fc5a7248ad031935de9a Mon Sep 17 00:00:00 2001 From: Almar Klein Date: Wed, 5 Nov 2025 11:43:14 +0100 Subject: [PATCH 1/3] Add docs on physical-size, logical-size and pixel-ratio to guide --- docs/start.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/docs/start.rst b/docs/start.rst index a2817d7..b98e674 100644 --- a/docs/start.rst +++ b/docs/start.rst @@ -70,6 +70,56 @@ Rendering with wgpu: # ... wgpu code +Physical, logical size, and pixel-ratio +--------------------------------------- + +The context has properties for the logical size, physical size, and the +pixel-ratio. + +* The physical size represent the actual number of "harware pixels" of the canvas surface. +* The logical size represents the size in "virtual pixels", which is used to scale elements like text, points, line thickness etc. +* The pixel-ratio represents the factor between the physical size and the logical size. + +On regular screens, the physical size and logical size are often equal: + +.. code-block:: + + +----+----+----+----+ + | | | | | Physical pixels + +----+----+----+----+ + +----+----+ + | | | Logical pixels, pixel-ratio 1.0 + +----+----+ + +On HiDPI / Retina displays, there are many more pixels, but they are much smaller. To prevent things like text to become tiny, +the logical pixels are made larger, i.e. pixel-ratio is increased (by the operating system), usually by a factor 2: + +.. code-block:: + + +--+--+--+--+ + | | | | | Physical pixels + +--+--+--+--+ + +-----+-----+ + | | | Logical pixels, pixel-ratio 2.0 + +-----+-----+ + +Other operating system may increase the pixel-ratio as a global zoom factor, to increase the size of elements such as text in all applications. +This means that the pixel-ratio can indeed be fractional: + +.. code-block:: + + +----+----+----+----+ + | | | | | Physical pixels + +----+----+----+----+ + +-----+-----+ + | | | Logical pixels, pixel-ratio ± 1.2 + +-----+-----+ + +Side note: on MacOS with a Retina display, the pixel-ratio is fixed to 2.0. (The OS level +zooming is implemented by rendering the whole screen to an offscreen buffer with +a different size than the physical screen, and then up/down-scaling that to the +screen.) + .. _async: From 33fc3a6d2086a80bc474f5f53dfc8a2c10e9c6d5 Mon Sep 17 00:00:00 2001 From: Almar Klein Date: Wed, 5 Nov 2025 11:45:21 +0100 Subject: [PATCH 2/3] typo --- docs/start.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/start.rst b/docs/start.rst index b98e674..05db32e 100644 --- a/docs/start.rst +++ b/docs/start.rst @@ -70,8 +70,8 @@ Rendering with wgpu: # ... wgpu code -Physical, logical size, and pixel-ratio ---------------------------------------- +Physical size, logical size, and pixel-ratio +-------------------------------------------- The context has properties for the logical size, physical size, and the pixel-ratio. From 04ab4569aab08f9081e74d488bd631e9eb740349 Mon Sep 17 00:00:00 2001 From: Almar Klein Date: Wed, 5 Nov 2025 16:01:25 +0100 Subject: [PATCH 3/3] Update docs/start.rst --- docs/start.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/start.rst b/docs/start.rst index 05db32e..a395746 100644 --- a/docs/start.rst +++ b/docs/start.rst @@ -115,7 +115,7 @@ This means that the pixel-ratio can indeed be fractional: | | | Logical pixels, pixel-ratio ± 1.2 +-----+-----+ -Side note: on MacOS with a Retina display, the pixel-ratio is fixed to 2.0. (The OS level +Side note: on MacOS, the pixel-ratio is fixed to either 1.0 or 2.0, usually the latter on a Retina display with reasonable resolution settings. (The OS level zooming is implemented by rendering the whole screen to an offscreen buffer with a different size than the physical screen, and then up/down-scaling that to the screen.)