Book-like guide: 'gfx-fundamentals'

[fu5ha]

Hello all,

So I think that one of the main things gfx is/has lacked is great documentation. I saw there was an issue somewhat along these lines of having a book but it was from a couple years ago I believe.

Of course, gfx is still in a pretty heavy flux period, but I get the impression that we're coming relatively along and close to the end, at least for ll/HAL. So, the purpose of this issue is that I would be interested in writing something like https://webgl2fundamentals.org/ or https://learnopengl.com/ for gfx and want to gather comments on if anyone else would like to help, things to keep in mind, ideas on structure or content, or whatever else.

So, let me know what y'all think :)

[kvark]

Somewhat relevant chat quote:

we need to talk about what there needs to be in the first place. I'd argue that a tutorial to HAL itself has a very limited target audience. It could be more useful to teach something like gfx-rs plus gfx-memory plus other things?... But those are not nearly well tested in terms of APIs and need even more time to stabilize. I guess we need to give it more time and see what works at higher levels and what not.

In other words, we do fully realize the lack of documentation at the moment. But it's not yet clear, at what abstraction level the documentation needs to be targeted. If we focus on the HAL itself, and most of the users end up working with higher-level abstraction, then the documentation is not going to be useful.

[fu5ha]

For sure, this is something I was thinking about as well. This may be overkill/not even possible depending on how the higher levels will work, but one idea I tossed around a little bit is that even if we do target a higher level, there could be a somewhat seamless "drop down" type thing where you could see the "equivalent" HAL code for whatever action you were doing using one of the higher level abstractions.

[nical]

So, let me know what y'all think :)

This would be great! For inspiration, see also glium's book/tutorial which I think is quite good.

If we focus on the HAL itself, and most of the users end up working with higher-level abstraction, then the documentation is not going to be useful.

There is only one way to know, though. If hal isn't properly documented, it's not going to help it get traction.

[icefoxen]

I have some work done on an introductory tutorial: https://wiki.alopex.li/LearningGfxHal but things seemed to be shifting too much for me to keep going on it. That may not be true anymore? I don't think I have time (or knowledge) to write a full book-level document though.

But it's not yet clear, at what abstraction level the documentation needs to be targeted. If we focus on the HAL itself, and most of the users end up working with higher-level abstraction, then the documentation is not going to be useful.

I think you're over-thinking this... documentation is always going to be useful to someone. ;-)

[fu5ha]

I don't think I have time (or knowledge) to write a full book-level document though.

Well, I don't think I currently have the knowledge of all pieces really either, but hopefully in writing it I will learn them and can get corrections from those who do :D

[parasyte]

documentation is always going to be useful to someone. ;-)

This is probably the most compelling reason to continually write about and document the lay-of-the-land. Even if it all changes over time, you still end up with contextual information that helps describe why certain architectural decisions were made. The historical account of how the project has evolved over time is always going to be useful for making decisions in the future. (The same kind of information can be mined from commit logs, but not quite as easy to consume.)

Personally, I would be interested in contributing some of the material. It will all be a learning experience for me, as well. But I have done the same kind of work for WebGL. It turned out to be very useful for myself and I was even able to turn it into a talk that I gave at a conference: https://youtu.be/W3rUwzjDMHE

Anyway, I'm still a bit in over my head with hal, but this is seriously a good excuse to start familiarizing myself.

[GabrielMajeri]

How about a book which introduces fundamental graphics programming concepts and terms, which https://webgl2fundamentals.org and https://learnopengl.com also do, but using wgpu-rs?

This would provide people with no graphics programming experience with enough context to understand the structures and functions of the gfx-hal API. And since wgpu-rs is much higher-level, it would be more attractive to beginners.

[grovesNL]

@GabrielMajeri did you see https://github.com/sotrh/learn-wgpu?

[GabrielMajeri]

@GabrielMajeri did you see sotrh/learn-wgpu?

Just took a quick look at it, looks like a good resource! And with more contributions it could be expaned to cover the whole graphics pipeline and all the relevant concepts.

My question is - does it solve this issue? Because if so, we'd just need to link to it in the README / on the website.

[grovesNL]

I'm not sure if it makes sense to direct people to learn-wgpu as a resource for learning gfx-hal itself, because wgpu-rs is meant to be a completely different API than gfx-hal (even though they share many similarities and graphics concepts). But I think it's a great resource to learn about wgpu-rs or graphics in general.

For learning gfx-hal there are a couple resources at the moment: https://github.com/mistodon/gfx-hal-tutorials and https://github.com/rust-tutorials/learn-gfx-hal Maybe we could link to those?