Improve shader function descriptions

[AshbyGeek]

Adds much detail to the documentation on built-in shader functions, copied from (with a few modifications) and linked to official GLSL documentation.

That documentation was moved into a separate file due to its verbosity, and organized into smaller sections following the organizational comments in https://github.com/godotengine/godot/blob/master/servers/rendering/shader_language.cpp.

Style tries to generally follow the styling used in class documentation, but differences between .gdshader and .gdscript meant some changes had to be made.

[AshbyGeek]

Pull request for issue #9310

[skyace65]

CC @clayjohn

[clayjohn]

That was unbelievably fast. I'm going to need a few days to review this. But I am very excited!

[AThousandShips]

This looks good, gonna go through it for style again but this was some that stuck out for now

[clayjohn]

Amazing work! This looks really good so far.

I think I just have two general comments:

1. I agree with Chaosus' comment earlier that, in most cases, functions with the same name should be grouped instead of duplicated. Especially for functions with really long descriptions.
2. I like how you kept the short description in the table. But I think it needs to be truly a short description. Some of the entries have the entire description copied in the table and that ends up making the table bloated in hard to navigate.

See DfDx for example

In these cases, the table actually has more information than the long description below.

[AshbyGeek]

Awesome! I'm glad you like it. I'm pushing hard to finish a project milestone this week, but I should be able to work on an update next week.

[AshbyGeek]

@tetrapod00 Any thoughts on the conversation @clayjohn and I were having about functions working on arrays piecewise?

[AshbyGeek]

Latest commit addresses concerns about component-wise functions and operators. It also improves some formatting and fixes some oddities with the navigation tree. Here's a bulleted list of what I changed:

• Use appropriate header so that the navigation tree will work correctly (accidentally used some subsubheaders I think)
• Make the classref-method styling apply to entries with multiple overloads
• Use a single table row for entries with multiple overloads
• 2nd column of each table disables text wrapping (had to add to static/custom.css) so that table rows with multiple entries will keep those entries aligned with their return types
• Fixed some function names in the descriptions that weren't bold
• Fixed a couple entries that failed to include the on-hover tooltip for vec_type
• Improve wording of note about operators being piece-wise and move it to underneath the actual operators
• Improve wording of note about functions being piece-wise

[AThousandShips]

Otherwise I think this looks good

[tetrapod00]

I see a lot of places where style can be improved in a minor way, like styling literals as code and with a decimal marker for floats (e.g. 0.0 instead of 0 or "0.0" for a float value of 0). I'll do a detail-oriented review on this (or a followup PR if we'd rather not block merging).

[tetrapod00]

I started on a nitpicky style review but I think it would be better as a followup PR - making all the required changes is annoying as suggestions.
It's a lot of stuff like:
"if x < -1" vs "if x is less than 0.0" vs "if x ≤ 0"
(e^x + e^-x)/2 vs "x=2\ :sup:y"
This stuff should be standardized, and I can do the work, but it will be annoying to do as a bunch of individual suggestions on the web UI.

IMO the style inconsistency is not bad enough to prevent merging as is.

[AshbyGeek]

Ok, fixed the couple things you already mentioned since I needed to fix my GLSL 4.0 mistake. I'm more than happy to let you fix the rest of the tedious formatting issues in another PR.

What does the merge process look like from here? We wait for ClayJohn or some such to come give a final approval and pull it in?

[tetrapod00]

Yeah, now you're waiting on another review from clayjohn or someone else with shader-specific knowledge to do a high-level review including whatever other style nitpicks come up in that review, then it should be merge-able. IMO this PR is already so much better than the current state of the function docs that this PR is merge-able as-is.

(Also I believe in most cases we would address the style consistency in this PR, not a followup, but it is really tedious work on a large PR, it's not blocking, and I'm volunteering to do it)

[clayjohn]

I keep meaning to do a deep review of this. But this is a huge chunk of work and I never have the time to do it in one sitting.

At this point I trust that the current state is way better than it was before. I also trust that the reviews from tetrapod and ATS would catch any glaring issues. Further Ashby has shown that they are working hard to make this as good as possible and I appreciate and respect his efforts.

I suggest we go ahead with merging this without me doing a super detailed review as I don't want to be the blocker for this any longer and I trust all the others involved in the process.

Great work everyone!

[tetrapod00]

I did an in-depth review. Overall this looks great. I found a few factual and copy-paste errors, and made a lot of minor style changes.

The changes are in a PR to the branch at AshbyGeek#1, which seemed to be the best way to make changes this big. Summary of changes:

• Standardized style.
• Fix a few factual and copy paste errors.
• Fix some formatting.
• Consistently use code blocks for literals.
• Use sentence case for all parameters.
• Avoid math symbols, prefer code-style >=.

[AshbyGeek]

Wowee, you weren't kidding about a lot of fiddly changes. You have a much better eye for detail and consistency in technical documentation than I do. My hat is off to you sir! I have already merged that pull request.

My only real question from looking at your pull request is really just a code style question:

You changed a bunch of instances of

.. rst-class:: classref-method

| |vec_type| **abs**\ (\ |vec_type| x)
| |vec_int_type| **abs**\ (\ |vec_int_type| x)

to the much more verbose

.. rst-class:: classref-method

|vec_type| **abs**\ (\ |vec_type| x)

.. rst-class:: classref-method

|vec_int_type| **abs**\ (\ |vec_int_type| x)

As far as I can tell the rendered HTML is the same. Am I mistaken?

Note, as I said above I've already merged your pull request. If you want to change these back, you can send me another pull request I guess, lol.

[tetrapod00]

The rendered HTML is not the same (tested on Windows 10, Firefox, 100% browser zoom). Before the changes, the function names are gray, but after the changes the function names are white, like the functions which appear on a single line with no overloads:
Before the changes, in 220fb2b:

After the changes, in 8972c45:

Compare to any function without overloads:

The version with white function names is correct.

(In 220fb2b, there were also a few unrelated formatting errors like the following, but those are not related to this difference.)

[tetrapod00]

With the style changes applied, this is good and mergable.

There are still many minor improvements that could be made, and I fully expect to find a factual error or two even after this is merged. But this is already much better than the current state of the shader function documentation. It's a good base for future improvements, which can be done in smaller chunks.

[AshbyGeek]

Why does yours render dark? Godot docs online use a light theme, which is also what I see on my computer.

Here's the code from commit 220fb2b:

.. rst-class:: classref-method

| |gvec4_type| **textureProjGrad**\ (\ |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy)
| |gvec4_type| **textureProjGrad**\ (\ |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy)
| |gvec4_type| **textureProjGrad**\ (\ |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy)

when compiled with Sphinx produces the following HTML on my computer:

<div class="classref-method line-block" id="shader-func-textureprojgrad">
    <div class="line">
        <abbr title="Any of: vec4, ivec4, uvec4">gvec4_type</abbr>
        <strong>textureProjGrad</strong>
        (<abbr title="Any of: sampler2D, isampler2D, uSampler2D">gsampler2D</abbr>
        s, vec3 p, vec2 dPdx, vec2 dPdy)
    </div>
    <div class="line">
        <abbr title="Any of: vec4, ivec4, uvec4">gvec4_type</abbr>
        <strong>textureProjGrad</strong>
        (<abbr title="Any of: sampler2D, isampler2D, uSampler2D">gsampler2D</abbr>
        s, vec4 p, vec2 dPdx, vec2 dPdy)
    </div>
    <div class="line">
        <abbr title="Any of: vec4, ivec4, uvec4">gvec4_type</abbr>
        <strong>textureProjGrad</strong>
        (<abbr title="Any of: sampler3D, isampler3D, uSampler3D">gsampler3D</abbr>
        s, vec4 p, vec3 dPdx, vec3 dPdy)
    </div>
</div>

which looks like this in Chrome v129.0.6668.101 (on Windows 10)

---

Here's code from commit 897nc452 (the merge commit)

.. _shader_func_textureProjGrad:

.. rst-class:: classref-method

|gvec4_type| **textureProjGrad**\ (\ |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy)

.. rst-class:: classref-method

|gvec4_type| **textureProjGrad**\ (\ |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy)

.. rst-class:: classref-method

|gvec4_type| **textureProjGrad**\ (\ |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy)

which produces the following html

<p class="classref-method" id="shader-func-textureprojgrad">
    <abbr title="Any of: vec4, ivec4, uvec4">gvec4_type</abbr>
    <strong>textureProjGrad</strong>
    (<abbr title="Any of: sampler2D, isampler2D, uSampler2D">gsampler2D</abbr>
    s, vec3 p, vec2 dPdx, vec2 dPdy)
</p>
<p class="classref-method">
    <abbr title="Any of: vec4, ivec4, uvec4">gvec4_type</abbr>
    <strong>textureProjGrad</strong>
    (<abbr title="Any of: sampler2D, isampler2D, uSampler2D">gsampler2D</abbr>
    s, vec4 p, vec2 dPdx, vec2 dPdy)
</p>
<p class="classref-method">
    <abbr title="Any of: vec4, ivec4, uvec4">gvec4_type</abbr>
    <strong>textureProjGrad</strong>
    (<abbr title="Any of: sampler3D, isampler3D, uSampler3D">gsampler3D</abbr>
    s, vec4 p, vec3 dPdx, vec3 dPdy)
</p>

and looks like this in Chrome v129.0.6668.101 (on Windows 10)

---

I would guess from the inclusion of the "|" in your last image and the fact that you have a dark theme, that there's some configuration difference between your sphinx compiler and mine or maybe you've set a custom theme for your Godot docs? 🤷

As I've said, the code change here really isn't a show stopper for me, I just find my previous syntax easier to read.

[tetrapod00]

The docs was dark mode due to my Firefox configuration. I switched Firefox to light mode.

Now this reStructuredText source from commit 220fb2b:

.. _shader_func_textureProjGrad:

.. rst-class:: classref-method

| |gvec4_type| **textureProjGrad**\ (\ |gsampler2D| s, vec3 p, vec2 dPdx, vec2 dPdy)
| |gvec4_type| **textureProjGrad**\ (\ |gsampler2D| s, vec4 p, vec2 dPdx, vec2 dPdy)
| |gvec4_type| **textureProjGrad**\ (\ |gsampler3D| s, vec4 p, vec3 dPdx, vec3 dPdy)

Produces this HTML:

<div class="classref-method line-block" id="shader-func-textureprojgrad">
<div class="line"><abbr title="Any of: vec4, ivec4, uvec4">gvec4_type</abbr> <strong>textureProjGrad</strong>(<abbr title="Any of: sampler2D, isampler2D, uSampler2D">gsampler2D</abbr> s, vec3 p, vec2 dPdx, vec2 dPdy)</div>
<div class="line"><abbr title="Any of: vec4, ivec4, uvec4">gvec4_type</abbr> <strong>textureProjGrad</strong>(<abbr title="Any of: sampler2D, isampler2D, uSampler2D">gsampler2D</abbr> s, vec4 p, vec2 dPdx, vec2 dPdy)</div>
<div class="line"><abbr title="Any of: vec4, ivec4, uvec4">gvec4_type</abbr> <strong>textureProjGrad</strong>(<abbr title="Any of: sampler3D, isampler3D, uSampler3D">gsampler3D</abbr> s, vec4 p, vec3 dPdx, vec3 dPdy)</div>
</div>

Formatted similar to yours, it is identical to the one you posted. There is no difference in the compiled HTML:

<div class="classref-method line-block" id="shader-func-textureprojgrad">
    <div class="line">
        <abbr title="Any of: vec4, ivec4, uvec4">gvec4_type</abbr>
        <strong>textureProjGrad</strong>
        (<abbr title="Any of: sampler2D, isampler2D, uSampler2D">gsampler2D</abbr>
        s, vec3 p, vec2 dPdx, vec2 dPdy)
    </div>
    <div class="line">
        <abbr title="Any of: vec4, ivec4, uvec4">gvec4_type</abbr>
        <strong>textureProjGrad</strong>
        (<abbr title="Any of: sampler2D, isampler2D, uSampler2D">gsampler2D</abbr>
        s, vec4 p, vec2 dPdx, vec2 dPdy)
    </div>
    <div class="line">
        <abbr title="Any of: vec4, ivec4, uvec4">gvec4_type</abbr>
        <strong>textureProjGrad</strong>
        (<abbr title="Any of: sampler3D, isampler3D, uSampler3D">gsampler3D</abbr>
        s, vec4 p, vec3 dPdx, vec3 dPdy)
    </div>
</div>

That HTML looks like this in Firefox 131.0.3 (64-bit), Windows 10:

Now it looks fine but some style is still not applied, still. Compared to another function, the compact style still doesn't produce the gray text for the rest of the function (the difference is fairly subtle).

On Edge Version 130.0.2849.46, it's the same:

On Chrome Version 130.0.6723.70, I can't find a way to force light mode (the main docs site is also forced dark mode). But the difference in font style persists:

Since the HTML is identical, this is certainly some difference in configuration between your computer and mine. The more compact style (from 220fb2b) is probably the better choice in the abstract. The more verbose style (from 8972c45) does seem to render more consistently, with this tiny amount of testing.

Note that if we switch back to the compact style, there are some unrelated formatting errors that were in 220fb2b. The stray | is one of those formatting errors. It's not directly related to the question of which style to use.

With just the two of us testing, I'm inclined to keep the current verbose style (that is, the current state of this PR) and investigate again after this is merged.

[AshbyGeek]

Sounds like a plan to me. And honestly, don't even feel like additional investigation is really necessary. More consistent/better results should be a higher priority than code style.

[tetrapod00]

This closes #5594 and #9310.