From c3c5895502f196e91dd3cea46f3d70ad9f905264 Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Sat, 21 Oct 2023 10:50:48 +0200 Subject: [PATCH] Document integer scaling support in Multiple resolutions This also adds more recommendations for base viewport sizes in pixel art games. --- ...olutions_pixel_art_fractional_scaling.webp | Bin 0 -> 610 bytes ...resolutions_pixel_art_integer_scaling.webp | Bin 0 -> 420 bytes tutorials/rendering/multiple_resolutions.rst | 68 +++++++++++++++--- 3 files changed, 59 insertions(+), 9 deletions(-) create mode 100644 tutorials/rendering/img/multiple_resolutions_pixel_art_fractional_scaling.webp create mode 100644 tutorials/rendering/img/multiple_resolutions_pixel_art_integer_scaling.webp diff --git a/tutorials/rendering/img/multiple_resolutions_pixel_art_fractional_scaling.webp b/tutorials/rendering/img/multiple_resolutions_pixel_art_fractional_scaling.webp new file mode 100644 index 0000000000000000000000000000000000000000..31324d3d1eddf05b63b6f057a7cbfea7b90c4391 GIT binary patch literal 610 zcmV-o0-gO*Nk&Fm0ssJ4MM6+kP&iCZ0ssInY{4D?HAsvkIc_9hWXw8uj-6Ng0W*z( zglOD5HM<7VwheasFQ7)=e+X{dNRpJ<-DFRftIyQzJm5jE=HRE}yJ|Z8P0YVZ zmt|bm3p2VRtDJX0A_B81T&3pF_rdjOO7 z<4sXWwouWD96#Ujh9Tyz0keQn4QAs~VK#SGxcXxO*^k-I@A^Aev$>37j`f!A7&g8` znbBCtRCtV`cdpWm`i`M@uF_Ep{uH=#eX;}|G#h`4ilj0(8~=*#uIkBH`Tv)CA1rEo z*^OOAWve&s<(iF4h1V|x=5_q{pS$FFy2+f|ubU-!K~88Q6&;uen!lOTB%VvEiN#DJ z70qO0+vyiC?$_NA>B-5og+_>@iHHRU&Ip4Q#u%`q1fyL8=XBk5 zvVbg?Dcj^1FYecWdRCfw3jOEy>nd4k45?iidUX|1@mx`jvWnQsDk5ZKJGWouBzk0} zskP#0v<_aVR2yv8e>$~aSAek4kv_XXK;(#l^hj`Szpe)9*)glf-0r&TeengF4VBuP?IC<;TNDJ*|b{bbjS)D^q;M)co-+cu7*Np3N9 zo$c*D5dWm5*WF(zcwJg&Km~_Mtxe;N83+mtZzIVFprTg0jRXZvW=&8~WRyoxl^;>)QR3d&6A-js^s8%lOAlAvJ7=(;XVeOD1s z)S98^lPX3TXzizl#@Ev|Cls6+NlMlA1V#Co#pdN|gzx}yd1jX&6d;*44{s#^@tIw7 z5}AUDLj6foKvBG9FQkKsYCV15v%B4iKmy|{e@$tv1L8yYGtfV6>B+lx9Tno6!c?wh z1~J7eAOGCXEefkmPEt5&S`{A^A}+3<6=j3>V)p%HRj=aC3K0;q{n!o85>AF?NVS`3 z0w?aE5E&UVw(54`). +.. _doc_multiple_resolutions_stretch_scale_mode: + +Stretch Scale Mode +^^^^^^^^^^^^^^^^^^ + +Since Godot 4.2, the **Stretch Scale Mode** setting allows you to constrain the +automatically determined scale factor (as well as the manually specified +**Stretch Scale** setting) to integer values. By default, this setting is set to +``fractional``, which allows any scale factor to be applied (including fractional +values such as ``2.5``). When set to ``integer``, the value is rounded down to +the nearest integer. For example, instead of using a scale factor of ``2.5``, it +would be rounded down to ``2.0``. This is useful to prevent distortion when +displaying pixel art. + +Compare this pixel art which is displayed with the ``viewport`` stretch mode, +with the stretch scale mode set to ``fractional``: + +.. figure:: img/multiple_resolutions_pixel_art_fractional_scaling.webp + :align: center + :alt: Fractional scaling example (incorrect pixel art appearance) + + Checkerboard doesn't look "even". Line widths in the logo and text varies wildly. + +This pixel art is also displayed with the ``viewport`` stretch mode, but the +stretch scale mode is set to ``integer`` this time: + +.. figure:: img/multiple_resolutions_pixel_art_integer_scaling.webp + :align: center + :alt: Integer scaling example (correct pixel art appearance) + + Checkerboard looks perfectly even. Line widths are consistent. + +For example, if your viewport base size is 640×360 and the window size is 1366×768: + +- When using ``fractional``, the viewport is displayed at a resolution of + 1366×768 (scale factor is roughly 2.133×). The entire window space is used. + Each pixel in the viewport corresponds to 2.133×2.133 pixels in the displayed + area. However, since displays can only display "whole" pixels, this will lead + to uneven pixel scaling which results in incorrect appearance of pixel art. +- When using ``integer``, the viewport is displayed at a resolution of 1280×720 + (scale factor is 2×). The remaining space is filled with black bars on all + four sides, so that each pixel in the viewport corresponds to 2×2 pixels in + the displayed area. + +This setting is effective with any stretch mode. However, when using the +``disabled`` stretch mode, it will only affect the **Stretch Scale** setting by +rounding it *down* to the nearest integer value. This can be used for 3D games +that have a pixel art UI, so that the visible area in the 3D viewport doesn't +reduce in size (which occurs when using ``canvas_items`` or ``viewport`` stretch +mode with the ``integer`` scale mode). + Common use case scenarios ------------------------- @@ -305,16 +356,20 @@ Desktop game **Pixel art:** -- Set the base window size to the viewport size you intend to use. Most pixel art games - use viewport sizes between 256×224 and 640×480. Higher viewport sizes will - require using higher resolution artwork, unless you intend to show more of the - game world at a given time. +- Set the base window size to the viewport size you intend to use. Most pixel + art games use viewport sizes between 256×224 and 640×480. 640×360 is a good + baseline, as it scales to 1280×720, 1920×1080, 2560×1440, and 3840×2160 without + any black bars when using integer scaling. Higher viewport sizes will require + using higher resolution artwork, unless you intend to show more of the game + world at a given time. - Set the stretch mode to ``viewport``. - Set the stretch aspect to ``keep`` to enforce a single aspect ratio (with black bars). As an alternative, you can set the stretch aspect to ``expand`` to support multiple aspect ratios. - If using the ``expand`` stretch aspect, Configure Control nodes' anchors to snap to the correct corners using the **Layout** menu. +- Set the stretch scale mode to ``integer``. This prevents uneven pixel scaling + from occurring, which makes pixel art not display as intended. .. note:: @@ -324,11 +379,6 @@ Desktop game viewport, you should use the ``canvas_items`` stretch mode instead of the ``viewport`` stretch mode. - Godot currently doesn't have a way to enforce integer scaling when using the - ``canvas_items`` or ``viewport`` stretch mode, which means pixel art may look bad if the - final window size is not a multiple of the base window size. - To fix this, use an add-on such as the `Integer Resolution Handler `__. - Mobile game in landscape mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^