Description
Your Godot version:
4.3
Issue description:
Information about coordinate spaces is lacking in the shader pages. They are referred to by multiple names ("model space" = "local space"). They use names which may be unfamiliar to users coming from other renderers. The pages assume that you are already familiar with coordinate space from prior shader experience. Knowledge of how to transform between spaces is assumed.
I propose two things to solve this:
Brief documentation in Spatial, CanvasItem, etc pages
I am already working on this half in #9757.
Add a section about coordinate spaces to each shader documentation page. It will have a table of the various coordinate spaces, each with a paragraph long description of the coordinate space. The description will use as simple language as possible without being misleading. It will avoid technical terms if it does aid understanding. The range of each coordinate space will be documented, along with alternate names you may see ("local" or "object" for "model"; "camera" or "eye" for "view").
Below the table will be a section containing snippets on how to use coordinate spaces and convert between them, such as the common vec3 position_world = (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;.
The coordinate space section should be in the individual shader pages, not the shading reference page, because the spaces are different between CanvasItem and Spatial.
Each page needs a different level of attention:
- Spatial shaders will have a section with a table and some conversion snippets.
- CanvasItem shaders will have a section with a table and some conversion snippets. The language on the CanvasItem page may be aimed even more towards beginners, as 2D shaders are a good introduction. It's okay to assume a little more prior knowledge for 3D. CanvasItem can also link to this page.
- Particle shaders will link to the Spatial and CanvasItem sections, since Particle shaders can use both.
- Fog and Sky could either link to Spatial, copy the entire section, or only list the world spaces they use.
In-depth documentation in a new page
Once that section is complete, we may want to add a new page that describes the entire user-accessible shading pipeline, from vertex() to light(), and including the clip, NDC, and screen space operations that happen after your shader code runs. This page would be aimed at those looking to supplement their practical knowledge with precise technical knowledge of exactly how Godot renders a frame.
As an example of the difference between the two pages: the documentation on the shader pages will treat matrices as black boxes you can use to manipulate a position. The in-depth page may assume more matrix math knowledge, or go into detail about how a given matrix is constructed.
I have no current plans to write this page, if only because my knowledge is not deep enough.
URL to the documentation page (if already existing):
https://docs.godotengine.org/en/latest/tutorials/shaders/shader_reference/spatial_shader.html
https://docs.godotengine.org/en/latest/tutorials/shaders/shader_reference/canvas_item_shader.html
https://docs.godotengine.org/en/latest/tutorials/shaders/shader_reference/sky_shader.html
https://docs.godotengine.org/en/latest/tutorials/shaders/shader_reference/particle_shader.html
https://docs.godotengine.org/en/latest/tutorials/shaders/shader_reference/fog_shader.html