Wgpu-rs: Create a git book

[kvark]

I believe https://book.amethyst.rs/stable/ sets up a great example.

We could have a nice description of what the API is, who is it for, what the components of the implementation are, and how to use them. In particular, these wiki pages can be moved into it entirely:

• https://github.com/gfx-rs/wgpu/wiki/Getting-Started
• https://github.com/gfx-rs/wgpu/wiki/Do's-and-Dont's
• https://github.com/gfx-rs/wgpu/wiki/Debugging-wgpu-Applications

[cormac-obrien]

I'd love to take a stab at this!

[cormac-obrien]

A few questions in terms of content:

1. Should we assume the readers are absolute beginners in graphics programming (i.e. go over winding order, backface culling, etc.) or that they have some experience and are just looking to learn a new API? (We could also do as the Amethyst book does and include a Concepts section up front for absolute beginners)
2. What external libraries should we choose as the "canonical" ones to use with wgpu? Particularly, what should we recommend for:
   
   
   
   • Linear algebra (cgmath, ultraviolet, or one of the other 1,000 linear algebra libs)?
   
   
   • Shader compilation (shaderc, glsl-to-spirv)?
   
   
3. Should we use the existing examples as the basis for the code parts of the book or would it be better to write different ones?

[kvark]

Thank you taking this on!

1. In general, yes. Priority should be focused on medium-experience developers, followed by inexperienced and well-experienced groups. Note that WebGPU spec also covers some of the info here, and we shouldn't try too hard to duplicate it (i.e. this can be a secondary goal).
2. great question!
   
   
   
   • math: ideally, we'd steer away from them, but I understand that some interaction is inevitable. If we have a single block where helper functions are defined, consider it up to you to choose what math it uses. If there are multiple places, we'd want to use different libraries.
   
   
   • shader: for now, let's just use glsl-to-spirv. In the future, we'll have WGSL shaders that are digested directly.
   
   
3. I think explaining the code of examples brings a lot of value, and it's easier to maintain.

[krooq]

I just want to link this bloody fantastic tutorial as well: https://sotrh.github.io/learn-wgpu
It was simple enough for me to follow and was up to date when I used it in early 2020.

Some 2c..
As an outside perspective, wgpu's technical offering is really second to none.
Where it lacks (although probably still the leader) is it's documentation and "marketing".
As a noob I'd really like to see a focus on improving the docs, tutorials and quality of examples over technical capabilities, I think this git book issue and the OpenGL support are really the only 2 things that turn people away at the moment.

[imoldfella]

Most tutorials leave the reader confused about threads and windows. Some of this is naturally confusing; you get an adapter from a window, a device from an adapter, and then you make a swap chain from the device for that window. But when you open a second window, what now? Same with a second thread. Hopefully we can save the new user some furious googling if we take the perspective that they will eventually want more than one window and more than one thread.

I don't think its yet a very important case, but a large number of machines also have more than one adapter, so bonus points to us if we can describe useful patterns for dealing with this, but I think its highly application specific. I think anything that's not a game will simply pick based on battery life or raw performance and only use one. Games of course will use both if they can get more fps. Maybe a simple example would be to do math on both adapters simultaneously.

[bzm3r]

@cormac-obrien What's your status on this issue? I'd be happy to run errands for you to help out.

[cormac-obrien]

@bzm3r There's been a significant amount of churn recently what with #478, so I took a break to allow that to settle. With 0.6 release coming up, I'm going to get back to work on it, but I'll let you know if I need any help!

[cormac-obrien]

I'm working on the section on shaders right now and hitting a bit of a snag. This will obviously be simplified quite a bit once WGSL is stable and wgpu consumes it directly, but until then, using glsl_to_spirv feels a bit...wonky? glsl_to_spirv::compile returns a File rather than a Vec<u32>, so an implementation is required to then read bytes from the resulting file, mapping every 4 bytes to a platform-endian (?) u32 with from_ne_bytes. This might be perfectionism on my part but this feels like a code smell.

Alternatives include:

• recommending a build.rs to precompile to SPIR-V and then using include_spirv!. This strikes me as the sort of complexity that we don't want to add to the build process—it makes sense in a large application, but I wouldn't want to have to set up this kind of scaffolding just to get a triangle on the screen.
• using shaderc, which doesn't seem like a good alternative as it also complicates the build process.
• using naga instead. I'm not sure how stable the current interface is, or how recent the crates.io release is, but the interface seems much nicer than glsl_to_spirv's and it doesn't require non-Rust deps. Is naga meant to be user-facing?

If we want to stick to the normal glsl_to_spirv method until WGSL is stabilized, I'm of course still happy to write the section that way.

[rukai]

afaik naga is not ready yet, and whatever we choose for now will be replaced by it eventually. I think the best compromise is to ask the user to manually run glslangValidator to compile the shader. (similar to the examples without the makefile) This will be easier to setup then shaderc and not as cursed as glsl_to_spirv.

If you do want to go the shaderc route I recommend this wrapper over shaderc instead https://github.com/Ralith/vk-shader-macros

[bzm3r]

piet-gpu used a build.ninja file to slightly smoothen glslangValidator usage: https://github.com/linebender/piet-gpu/blob/master/piet-gpu/shader/build.ninja