@@ -75,7 +75,7 @@ screen sizes.
7575.. note ::
7676
7777 On this page, *window * refers to the screen area allotted to your game
78- by the system, while *viewport * refers to the root object (accessible
78+ by the system, while *viewport * refers to the root object (accessible
7979 from ``get_tree().root ``) which the game controls to fill this screen area.
8080 This viewport is a :ref: `Window <class_Window >` instance. Recall from the
8181 :ref: `introduction <doc_viewports >` that *all * Window objects are viewports.
@@ -481,18 +481,34 @@ Non-game application
481481hiDPI support
482482-------------
483483
484- By default, Godot projects aren't considered DPI-aware by the operating system.
485- This is done to improve performance on low-end systems, since the operating
486- system's DPI fallback scaling will be faster than letting the application scale
487- itself (even when using the ``viewport `` stretch mode).
488-
489- However, the OS-provided DPI fallback scaling doesn't play well with fullscreen
490- mode. If you want crisp visuals on hiDPI displays or if project uses fullscreen,
491- it's recommended to enable **Display > Window > Dpi > Allow Hidpi ** in the
492- Project Settings.
493-
494- **Allow Hidpi ** is only effective on Windows and macOS. It's ignored on all
495- other platforms.
484+ By default, Godot projects are considered DPI-aware by the operating system.
485+ This is controlled by the **Display > Window > Dpi > Allow Hidpi ** project setting,
486+ which should be left enabled whenever possible. Disabling DPI awareness can break
487+ fullscreen behavior on Windows.
488+
489+ Since Godot projects are DPI-aware, they may appear at a very small window size
490+ when launching on an hiDPI display (proportionally to the screen resolution).
491+ For a game, the most common way to work around this issue is to make them
492+ fullscreen by default. Alternatively, you could set the window size in an
493+ :ref: `autoload <doc_singletons_autoload >`'s ``_ready() `` function according to
494+ the screen size.
495+
496+ To ensure 2D elements don't appear too small on hiDPI displays:
497+
498+ - For games, use the ``canvas_items `` or ``viewport `` stretch modes so that 2D
499+ elements are automatically resized according to the current window size.
500+ - For non-game applications, use the ``disabled `` stretch mode and set the
501+ stretch scale to a value corresponding to the display scale factor in an
502+ :ref: `autoload <doc_singletons_autoload >`'s ``_ready() `` function.
503+ The display scale factor is set in the operating system's settings and can be queried
504+ using :ref: `screen_get_scale<class_DisplayServer_method_screen_get_scale> `. This
505+ method is currently only implemented on macOS. On other operating systems, you
506+ will need to implement a method to guess the display scale factor based on the
507+ screen resolution (with a setting to let the user override this if needed). This
508+ is the approach currently used by the Godot editor.
509+
510+ The **Allow Hidpi ** setting is only effective on Windows and macOS. It's ignored
511+ on all other platforms.
496512
497513.. note ::
498514
0 commit comments