Improve Description of gdshader SmoothStep and Mix functions

AshbyGeek commented 5 months ago

Your Godot version: 4.2.1

Issue description: Official documentation on these functions (really all shader functions) is very spartan. Basically its expected that you know other shading languages that provide similar functions (most of these functions seem to pass more or less straight through to GLSL). I'm new to shaders though and made some very poor assumptions about what smoothstep was.

"Hermite interpolate between a and b by c." made me assume it works like a lerp, but it doesn't. Finally found this page which explains how it actually works. The pertinent part is:

the returned value will be 0.0 if it is below a first limit and 1.0 if it is above a second limit. Between the limits, the value will be smoothly interpolated (using a Hermite smooth interpolation, which is why you might come across this name when smooth step is mentioned)

And now that I'm looking for similar documentation in other languages I found the gles docs entry.

While we're in the neighborhood, I'd like to add the word "lerp" to the description of the mix function so that people searching for a shader equivalent of lerp can find it easier.

If someone is feeling spunky, we could go through the full list and borrow wording from the glsl docs. I cannot do so because there is a high chance that there are differences that I'm unfamiliar with.

URL to the documentation page (if already existing): documentation page: https://docs.godotengine.org/en/stable/tutorials/shaders/shader_reference/shading_language.html#built-in-functions documentation source: https://github.com/godotengine/godot-docs/blob/4.2/tutorials/shaders/shader_reference/shading_language.rst

clayjohn commented 5 months ago

I think adding the full descriptions from the original GLSL docs is a good idea. The functions just pass through to the raw GLSL, so the official docs apply perfectly.

I started doing this years ago but its a lot of manual copy-pasting and other priorities got in the way https://github.com/godotengine/godot-docs/pull/5729

AshbyGeek commented 5 months ago

Oh, that's pretty sweet. If I do a bunch of copy-paste can I just pass you the file to put in your pull request?

AshbyGeek commented 5 months ago

Any complaints if the functions section is split into its own page? That page is rather ridiculously long and the new formatting will make it even worse.

clayjohn commented 5 months ago

Oh, that's pretty sweet. If I do a bunch of copy-paste can I just pass you the file to put in your pull request?

Sure!

Any complaints if the functions section is split into its own page? That page is rather ridiculously long and the new formatting will make it even worse.

Not from me. I think its definitely worth splitting up at this point