Improve shader function descriptions #9338
Conversation
|
Pull request for issue #9310 |
AThousandShips
changed the title
skyace65
added
enhancement
area:manual
|
CC @clayjohn |
|
That was unbelievably fast. I'm going to need a few days to review this. But I am very excited! |
|
|
||
| .. rst-class:: classref-method | ||
|
|
||
| ivec2 **textureSize** ( samplerCubeArray s, int lod ) |
There was a problem hiding this comment.
The following text is just a duplicated information, I think you should remove it, and instead add the overloads to header of first declaration eg:
ivec2 **textureSize** ( |gsampler2D| s, int lod )
ivec2 **textureSize** ( samplerCube s, int lod )
ivec3 **textureSize** ( |gsampler2DArray| s, int lod )
ivec3 **textureSize** ( |gsampler3D| s, int lod )
And do the same for other functions...
There was a problem hiding this comment.
There were a number of these kinds of functions, in a few of them the text was exactly the same, but a lot of them had minor differences. For instance, the atan function has significant behavioral differences between its two overloads.
I decided that the documentation would be slightly clearer if these were addressed individually and that consistency of layout/format (in this case meaning each overload gets its own documentation) was more important than concerns about repetition.
Admittedly, most of them are not-just the difference between int and uint or similarly small, but even some of these behave differently, such as packUnorm2x16 which has a different snippet of equivalent code for each overload.
There was a problem hiding this comment.
I think we can separate them in cases like atan where you need two different descriptions. But in cases like textureSize, it makes sense to group them together. You are right not to worry about repetition, but some cases (like all the texture* functions) the sheer amount of repetition makes the document harder to navigate
There was a problem hiding this comment.
Understood, I will add this to my todo list.
Co-authored-by: Yuri Rubinsky <[email protected]> Co-authored-by: A Thousand Ships <[email protected]>
There was a problem hiding this comment.
Amazing work! This looks really good so far.
I think I just have two general comments:
- 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.
- 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.
|
|
||
| vec_type atan( |vec_type| y_over_x) | ||
|
|
||
| Calculate the arctangent given a tangent value of ``y/x``. Note: becuase of |
There was a problem hiding this comment.
| Calculate the arctangent given a tangent value of ``y/x``. Note: becuase of | |
| Calculate the arctangent given a tangent value of ``y/x``. Note: because of |
|
|
||
| vec_type atanh( |vec_type| x) | ||
|
|
||
| Calculate the arctangent given a tangent value of ``y/x``. Note: becuase of |
There was a problem hiding this comment.
| Calculate the arctangent given a tangent value of ``y/x``. Note: becuase of | |
| Calculate the arctangent given a tangent value of ``y/x``. Note: because of |
| Built-in functions | ||
| ------------------ | ||
|
|
||
| A large number of built-in functions are supported, conforming to GLSL ES 3.0. | ||
| When vec_type (float), vec_int_type, vec_uint_type, vec_bool_type nomenclature | ||
| is used, it can be scalar or vector. |
There was a problem hiding this comment.
I think its worth keeping this section and only having one sentence that simply points to the new page. Users may have a hard time finding it otherwise
| .. note:: | ||
| Most operations on vectors (multiplication, division, etc) are performed component-wise. | ||
| For example, the operation ``vec2(3, 4) * vec2(10, 20)`` would result in ``vec2(3 * 10, 4 * 20)``. | ||
| or the operation ``min(vec2(3, 4), vec2(1, 8))`` would result in ``vec2(min(3, 1), min(4, 8))``. | ||
|
|
||
| The `GLSL Language Specification <http://www.opengl.org/registry/doc/GLSLangSpec.4.30.6.pdf>` says under section 5.10 Vector and Matrix Operations: | ||
|
|
||
| With a few exceptions, operations are component-wise. Usually, when an operator operates on a | ||
| vector or matrix, it is operating independently on each component of the vector or matrix, | ||
| in a component-wise fashion. [...] The exceptions are matrix multiplied by vector, | ||
| vector multiplied by matrix, and matrix multiplied by matrix. These do not operate component-wise, | ||
| but rather perform the correct linear algebraic multiply. |
There was a problem hiding this comment.
This is probably better suited in the section on data types rather than here.
There was a problem hiding this comment.
I disagree. Operating primarily component-wise isn't really a feature of these data types, it's a feature of the functions that operate on them. I could see an argument for putting it in both places (or maybe one has a short reminder with a link).
It would also make sense to me if you wanted to remove this from the header and include it in each applicable method. Cause chances are if someone needs this reminder its while they're looking at a specific function. They may or may not look at data types documentation or general comments first.
|
|
||
| .. note:: | ||
|
|
||
| Available only in the fragment shader |
There was a problem hiding this comment.
| Available only in the fragment shader | |
| Available only in the fragment shader | |
| Not available when using the GL_Compatibility rendering backend. |
The same note should be added for dFdyCoarse, dFdxFine, dFdyFine, fwidthFine, and fwidthCoarse
|
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. |
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.