Improve Description of gdshader SmoothStep and Mix functions

[AshbyGeek]

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]

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 #5729

[AshbyGeek]

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]

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]

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

[AshbyGeek]

Here's a work in progress if you're interested in taking a peek. It includes the source and the html as saved by a web browser (That was the easiest way I could think of to make sure I got all any necessary extra files)

wip-shader-functions-html.zip

I wound up moving the built-in functions to their own file and also splitting them into categories (mostly following the comments in: https://github.com/godotengine/godot/blob/master/servers/rendering/shader_language.cpp)

I've also expanded a bit on the note about vec_type at the top.

[AshbyGeek]

My Regex-fu has gotten a serious workout, lol.

[skyace65]

Please don't put changes you want made to the documentation in issues. Please make a PR so we can properly look at it.

[AshbyGeek]

Sorry, didn't think it would be good to make a pull request while my code still has extremely obvious work-in-progress incompletions. I did finally make myself a fork for that eventual purpose though. Here's a link to my branch. Should I go ahead and make the pull request anyway?

[AshbyGeek]

Perhaps a better question is: how does godot-docs do design reviews? It would be nice if I could get one soon so that I know I'm on the right track for the remaining 100 some odd functions.

[AshbyGeek]

Found the draft pull request feature. Here's my PR as a draft: #9338

[AshbyGeek]

Ok, finished the copy paste its ready for review.