Gfx: Improve Documentation

[Binero]

There is very few documentation in gfx, and there are a lot of features not covered. This should be resolved.

There are a few areas that have been identified for needing work:

• [x] PipelineState: This area is not well defined.
• [ ] Textures: There is a lack of documentation on how to create and handle textures.
• [ ] Encoder: Specific commands could be and should be elaborated more.
• [x] Slice: Documentation is outdated.
• [ ] Inline Code Examples: We need quick and short examples that illustrate how to use different items.
• [ ] Back-end Front-end: It's not clear what types are part of the back-end, and what types are part of the front-end.
• [ ] Factory

[kvark]

If you can, please make this description more concrete, possibly by listing areas/types that need the documentation extended and updated.

[Binero]

I'm currently working on PipelineState. If other areas in need of documentation are identified, please do comment.

[Bastacyclop]

I believe Slice's instances field is in need of documentation.

[Binero]

I would like to note that I've taken a break from GFX. While I'll certainly come back and contribute more documentation and hopefully also deal with some other issues, this means that I won't be tracking this issue anymore.

Basically, feel free to fix and contribute to the remaining documentation!

[Razican]

As a newbie to graphics programming, I find it difficult to understand how GFX works. I've found many tutorials about OpenGL, for example, or even about Vulkan (even though they are mostly targeted for people with graphics knowledge). It would be great if documentation could be more newbie directed.

Things like macros not being documented is a bit troublesome. Also, examples with much more inline documentation could help. A simple example on "how to build a simple GFX app" would also be great. What do you need? a builder, an encoder, a pso, a vertex buffer, a main loop...

Some of the questions I had (and still have):

• Why are there only some GLSL versions in the gfx_app::shade::Source?
• How to use different backends? (I think this is done with features)
• How does the gfx_defines macro work? constants, pipelines, vertices...

Articles in the blog are great, but probably too close to implementation details. Also, since the API has changed a lot, the first blog post, for example, explaining the triangle drawing is very outdated.

I am probably pointing out many silly things here, or probably googleing the correct terms would give me better understanding of most of it, but I hope that you can get a feeling of how documentation could be improved for someone like me. I've also found out that #346 has some good points. For someone from outside, GFX looks really complex with a really steep learning curve.

[kvark]

@Razican Hello, and thanks for chiming in!

As a newbie to graphics programming, I find it difficult to understand how GFX works.

Yes, gfx-rs is not too obvious to newcomers, especially ones without prior graphics experience. The core developers has been focusing mostly on our strategic goals and general architecture. We have not reached the state yet where actively seeking new users makes sense... But we welcome any help to become more friendly!

Things like macros not being documented is a bit troublesome.

I think non-trivial macros are hard to document in general, and I wish we could get away nicely without them. Perhaps, now with Rust custom derives being stabilized, we can re-evaluate the macros and replace them with new derives. Effectively that means most of the current documentation for the macros will become outdated.

A simple example on "how to build a simple GFX app" would also be great.

Sounds more like a tutorial, to be honest. We got plenty of examples.

Why are there only some GLSL versions in the gfx_app::shade::Source?

Because no one bothered to add more. gfx_app has been created as a framework for the examples in the first place, so that's what drove gfx_app features.

How to use different backends? (I think this is done with features)

When using gfx_app, you just manually pick the appropriate launch function (some are hidden behind features), like with the shadow example:

gfx_app::launch_gl3::<App<_, _>>(wb);

Otherwise, you pick a appropriate gfx_window_* crate and go from there.

How does the gfx_defines macro work? constants, pipelines, vertices...

The big fat things are pipelines. Their definitions consist of components, which are defined and described in sub-modules of https://docs.rs/gfx/0.13.0/gfx/pso/index.html. You can get a basic idea from the examples, and then dive into the docs or source to get a better understanding of each component usage and limitations.

Articles in the blog are great, but probably too close to implementation details. Also, since the API has changed a lot, the first blog post, for example, explaining the triangle drawing is very outdated.

Yes, bog posts are a bad substitute for docs, and we are not trying to rely on them. The blog just happens to tell the development story, so it's more of a history material than the documentation.

[liquidnight2]

Hello kvark,
nice to see someone working on the 3D projects. I am a newbie (like Razican) and have spent several days now on rs-gfx, with no good outcome.

It seems that the documentation has not been written by a beginner. For starting with it, it is pretty confusing if on the first example a link is bad, and the code does not work at all.

I could offer a little help creating some documentation for beginners (maybe reworking the 1st chapter). And I am not experienced in rs-gfx, except my impression that it is currently difficult to use, especially the examples. The missing experience comes to a good use for writing a basic tutorial that does less likely omit several important topics at once.

We got plenty of examples.
They work inside that project ONLY, not outside. What you do there is not possible for beginners to re-create or even extract it.

I have drawn a simple sequence diagram for the triangle example which could be of use for other users. But dont know where to put that. So if you need help on documentation, i could help a little (maybe that alleviates the criticism here :-).

[kvark]

Lowering the priority since this issue is about pre-ll, which we are aiming to deprecate at some point.

[kvark]

I believe we got some documentation now. If anything is missing, please file PRs/issues.