Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document the meaning of display/window/stretch/aspect #104254

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+6 −0
Open

Document the meaning of display/window/stretch/aspect #104254

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions doc/classes/ProjectSettings.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -916,6 +916,12 @@
[b]Note:[/b] By default, or when set to [code]0[/code], the initial window width is the [member display/window/size/viewport_width]. This setting is ignored on iOS, Android, and Web.
</member>
<member name="display/window/stretch/aspect" type="String" setter="" getter="" default="&quot;keep&quot;">
Defines if and how the aspect ratio of the root [Viewport] should be preserved when stretching is applied.
[b]"ignore"[/b]: Keep the width and height of the viewport. If the aspect ratio of the window or screen does not match that of the viewport, stretch the render to fill it.
[b]"keep"[/b]: Keep the width and height of the viewport. If the aspect ratio of the window or screen does not match that of the viewport, empty space is filled with black.
[b]"keep_width"[/b]: Keep the width of the viewport, but allow its height to expand. If the aspect ratio of the window or screen is greater, the game is shown centered with vertical black bars. If the aspect ratio is smaller, the viewport is expanded vertically downwards.
[b]"keep_height"[/b]: Keep the height of the viewport, but allow its width to expand. If the aspect ratio of the window or screen is smaller, the game is shown centered with horizontal black bars. If the aspect ratio is greater, the viewport is expanded horizontally to the right.
[b]"expand"[/b]: Allow the viewport to expand in either direction to fill the screen or window. If the aspect ratio of the window or screen is greater, the game is expanded horizontally to the right. If the aspect ratio is smaller, the viewport is expanded vertically downwards.
Comment on lines +919 to +924
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Defines if and how the aspect ratio of the root [Viewport] should be preserved when stretching is applied.
[b]"ignore"[/b]: Keep the width and height of the viewport. If the aspect ratio of the window or screen does not match that of the viewport, stretch the render to fill it.
[b]"keep"[/b]: Keep the width and height of the viewport. If the aspect ratio of the window or screen does not match that of the viewport, empty space is filled with black.
[b]"keep_width"[/b]: Keep the width of the viewport, but allow its height to expand. If the aspect ratio of the window or screen is greater, the game is shown centered with vertical black bars. If the aspect ratio is smaller, the viewport is expanded vertically downwards.
[b]"keep_height"[/b]: Keep the height of the viewport, but allow its width to expand. If the aspect ratio of the window or screen is smaller, the game is shown centered with horizontal black bars. If the aspect ratio is greater, the viewport is expanded horizontally to the right.
[b]"expand"[/b]: Allow the viewport to expand in either direction to fill the screen or window. If the aspect ratio of the window or screen is greater, the game is expanded horizontally to the right. If the aspect ratio is smaller, the viewport is expanded vertically downwards.
Defines if and how the aspect ratio of the root [Viewport] should be preserved when stretching is applied.
[b]"ignore"[/b]: Keep the width and height of the viewport. If the aspect ratio of the window or screen does not match that of the viewport, stretch the render to fill it.
[b]"keep"[/b]: Keep the width and height of the viewport. If the aspect ratio of the window or screen does not match that of the viewport, empty space is filled with black.
[b]"keep_width"[/b]: Keep the width of the viewport, but allow its height to expand. If the aspect ratio of the window or screen is wider, the game is shown centered with vertical black bars. If the aspect ratio is narrower, the viewport is expanded vertically downwards.
[b]"keep_height"[/b]: Keep the height of the viewport, but allow its width to expand. If the aspect ratio of the window or screen is narrower, the game is shown centered with horizontal black bars. If the aspect ratio is wider, the viewport is expanded horizontally to the right.
[b]"expand"[/b]: Allow the viewport to expand in either direction to fill the screen or window. If the aspect ratio of the window or screen is wider, the game is expanded horizontally to the right. If the aspect ratio is narrower, the viewport is expanded vertically downwards.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry to edit things after the review, so I propose it through the suggestions. After sleeping on it, I think it's probably better to use narrower (instead of smaller) and wider (instead of greater), as the meaning w.r.t. game screen/window shape is more intuitive.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No worries, though I'm not sure about the change; more intuitive, sure, but in the context of aspect ratios, comparisons would usually use words like smaller/greater, no? I'm not a native speaker so I wouldn't want to call the shots here, we might want to wait for a review from someone on the docs team.

Copy link
Author

@PGijsbers PGijsbers Mar 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wasn't sure either, which is why I initially used greater/smaller (since it's a ratio, it's at least correct). However, reading the wikipedia page they do use "wider/narrower" in this context:

but converted when the international standards group introduced a wider ratio of 5+1⁄3 to 3 (= 16:9).

and

which progressed to a wider 4:3

and

This aspect ratio is also wider than the popular 16:9

and

Notably one of the few popular display aspect ratios narrower than 4:3

So I'll leave it for your (and the docs team's) consideration.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know why I couldn't find it yesterday, but I found the proper documentation page for this now: https://docs.godotengine.org/en/stable/tutorials/rendering/multiple_resolutions.html#stretch-aspect

I can update the PR to include these descriptions instead, or is there a way to instead share the same source to reduce the risk of the doc pages and attribute documentation get out-of-sync? And/or can we link to this documentation directly? The animated gifs will be very useful.

</member>
<member name="display/window/stretch/mode" type="String" setter="" getter="" default="&quot;disabled&quot;">
Defines how the base size is stretched to fit the resolution of the window or screen.
Expand Down