Godot Documentation: Shader Reference

Repository

https://github.com/godotengine/godot-docs and https://github.com/godotengine/godot

Details

For this PR, I overhauled the shader reference found in the Godot docs.

I have taken the previous "Shading Language" document (which encapsulated all the information about shading in Godot in one long document), expanded on it greatly, and split it into 5 distinct documents. Each of which now contain extensive, more beginner-friendly information about writing shaders in Godot. The five documents are:

• Shaders (an introduction to shaders in Godot generally and from a high-level)
• Shading Language (substantially similar to the old document, but with updated and expanded information)
• Spatial shaders (information on Spatial shader specific variables and properties)
• CanvasItem shaders (information on CanvasItem shader specific variables and properties)
• Particle shaders (information on Particle shader specific variables and properties)

Three of the documents cover specific shader types (Spatial, CanvasItem, and Particles respectively). These documents have an explanation of the shader and how it is used as well as useful information that users often miss when writing them. For example, when users write particle shaders they are often surprised when the particle does not take on the color assigned in the particle shader. This happens because the Spatial or CanvasItem shader they are using to draw the particle is overriding the color. In order to fix it they need to set the color (or albedo) of the shader to the color passed in by the particle shader. This and other useful tidbits can now be found in the documents for each of the shader types.

Components

Shaders are a key part of computer graphics. They are special programs that run on the GPU that allow modern game engines to render thousands of objects on high resolution screens with no difficulty. Shaders are notoriously difficult for new programmers to grasp. While there is a very active shader community, they typically view shaders as something you learn "by getting your feet wet". Accordingly there are few resources on learning them.

By way of example, for those of you not well versed in GPU programming lingo, here is the opening paragraphs of the shader document (the one introducing users to shaders in general):

Shaders are unique programs that run on the GPU. They are used to specify how to take mesh data (vertex positions, colors, normals, etc.) and draw them to the screen. Shaders do not process information the same way a normal program does because they are optimized for running on the GPU. One consequence of this is that shaders do not retain their data after they run, they output a final color to the screen and then move on. Accordingly, there is no way of accessing the color output from the last run of the shader.

Godot uses a shader language very similar to GLSL but with added functionality and slightly less flexibility. The reason for doing this is that Godot integrates built-in functionality to make writing complex shaders substantially easier. Godot wraps the user-written shader code in code of its own. This way Godot handles a lot of the low-level stuff that the user doesn’t need to worry about, and it is able to parse your shader code and use it to affect the rendering pipeline. For more advanced shaders you can turn this functionality off using a render_mode.

Links

http://docs.godotengine.org/en/latest/tutorials/shading/shading_reference/index.html
All five files under this index are new

Bonus PRs

https://github.com/godotengine/godot-docs/pull/2105
https://github.com/godotengine/godot-docs/pull/2104
These are smaller PRs that happened to get pulled at the same time. They represent the size of typical contributions

GitHub Proof of Authorship

• GitHub Account: https://github.com/clayjohn
• Pull Request: https://github.com/godotengine/godot-docs/pull/2046