-
Notifications
You must be signed in to change notification settings - Fork 548
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve Documentation #942
Comments
If you can, please make this description more concrete, possibly by listing areas/types that need the documentation extended and updated. |
I'm currently working on |
I believe |
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! |
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):
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. |
@Razican Hello, and thanks for chiming in!
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!
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.
Sounds more like a tutorial, to be honest. We got plenty of examples.
Because no one bothered to add more.
When using gfx_app::launch_gl3::<App<_, _>>(wb); Otherwise, you pick a appropriate
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.
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. |
Hello kvark, 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.
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 :-). |
Lowering the priority since this issue is about pre-ll, which we are aiming to deprecate at some point. |
I believe we got some documentation now. If anything is missing, please file PRs/issues. |
942: Fix clippy warnings about using if-let over match r=kvark a=lberrymage The specific lint triggered was [clippy::single_match](https://rust-lang.github.io/rust-clippy/master/index.html#single_match). **Description** Details found in the link above **Testing** N/A Co-authored-by: lberrymage <mageelog@gmail.com>
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:
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.Slice
: Documentation is outdated.Factory
The text was updated successfully, but these errors were encountered: