Many documentation updates

Posted on January 23, 2022 by michalis

component_gallery example - TCastleLabel

component_gallery example - TCastleUserInterface

component_gallery example - TCastleRectangleControl

Documentation is the theme of recent news, as I work intensively on updating our manual 🙂

Added section about TCastleBehavior.
Improved X3D example to show building a mesh.
Update to user interface page is in progress, using an updated version of examples/component_gallery. It is not yet finished, but I feel it is already better.
Documentation about AAB (Android App Bundle) added, documentation about Android signing updated.
Logging docs updated.
Some outdated pages have been just removed, as they were outdated and described stuff of low importance (like TCastleOnScreenMenu, that is nowadays easier to do as just TCastleVerticalGroup with a number of buttons). Also the order of pages have been reworked, to put most important things at the top.

Notable Replies

chikega says:

Thank you for all the hard work, Michalis et al !
Arioch says:
back to the docs

chapter 4 at Designing a 2D world | Manual | Castle Game Engine

This is usually a good idea — this way the visible area remains the same, regardless of your viewport size, and even regardless of whether you use UI scaling (and with what reference size UI scaling works). To do this, just set Viewport.Camera.Orthographic.Width to a constant value, like 1600. You can also set Viewport.Camera.Orthographic.Height , but you don’t have to — the other viewport size (left as 0) will be calculated automatically based on current viewport control aspect ratio.

As a newb i got it all wrong, so i consider that paragraph ambiguos.

regardless of your viewport size

while it is typically a relatively minor concern for games (they usually run full-screen, unless the yhave a floating resizable “portal” windows, like OpenTTS), it was an issue for me, as i was designing a smi-desktop app, working in a usual window, free to any resizing.

So, what would happen if the user freelly resizes the app’s window?

set .Width to a constant value

and i did it

the other viewport size (left as 0) will be calculated automatically based on current viewport control aspect ratio.

and so i let it as zero, because i wanted CGE to respect my aspect ratio. I do not want CGE to ignore the aspect ratio, no!!!

I was not wanting my app “squeezed” by changing its hosting windows aspect ratio!
The bad side effcect was whe nuser was changing the window’s height not width - the elements quickly fallen out of view.

Test shows, though, that is was not the case. CGE would not “squeeze” my worls if i set BOTH .Width and .Height

Okay, common sense says there can be three strategies when fixing both Width and Height:
1. treat them as “minimum” hint, preserve aspect ratio, scale to match the lowest of the two
2. treat them as “maximum” hint, preserve aspect ratio, scale to match the largest of the two
3. treat them as exact order, mantain both Height and Width to be exactly as specified, ignore aspect ratio
Frankly, a newb can not be sure which of the strategies CGE implement, and the current wording suggests the last one! It seems to be documented inside https://castle-engine.io/apidoc-unstable/html/CastleCameras.TCastleOrthographic.html#Height - perhaps some text can be copied from there, so mere reading Designing a 2D world | Manual | Castle Game Engine would give immediately correct if shallow idea. And then newb to be suggested to look into .Width for more detailed description.
michalis says:

Arioch:

treat them as “minimum” hint, preserve aspect ratio, scale to match the lowest of the two

As you yourself point out, this is documented at TCastleOrthographic.Width : https://castle-engine.io/apidoc-unstable/html/CastleCameras.TCastleOrthographic.html#Width . The orthographic width and height are minimum values. So we will not distort / squeeze things, we will not disregard the actual aspect ratio of the viewport. Unless you set TCastleOrthographic.Stretch to true.

The manual page Designing a 2D world | Manual | Castle Game Engine is scheduled for rework anyway, there’s a clear warning there – this is not yet finished, it is supposed to show in more tutorial-like fashion the most useful workflow for designing 2D viewport.