Review chapter 22

handouts/src/22-shady-business.md

@@ -19,10 +19,10 @@ programming language you like to write the GPU-side code. All you need is a new
 compiler backend that emits SPIR-V instead of machine code.
 
 Sadly, compiler backends are big pieces of work, so Rust is not quite there yet.
-All we have today is [a promising prototype around called
+All we have today is [a promising prototype called
 `rust-gpu`](https://github.com/EmbarkStudios/rust-gpu). I hope to introduce it
-in a future edition of this course[^1], but what I read in its bugtracker, it
-felt a bit too experimental for this year's edition.
+in a future edition of this course[^1], but it felt a bit too experimental for
+this year's edition.
 
 Therefore, we will prefer the tried and true alternative of Khronos' standard
 GPU programming language: the OpenGL Shading Language, or GLSL for short.
@@ -54,19 +54,19 @@ To give some examples, in GLSL you can easily...
 - Allow the value of a compilation constant to be specified before the shader's
   SPIR-V is compiled into a device binary, to improve configurability and
   compiler optimizations.
-- A more extensive library of built-in functions than C could ever dream of.
+- Enjoy a more extensive library of built-in math functions than C could ever
+  dream of.
 - ...and many other things revolving around the high-speed drawing of textured
   triangles that we will not care much about in everyday numerical
   computing.[^4]
 
 As you can see, this opens quite a few interesting possibilities. And that's
 part of why `rust-gpu` is still experimental in spite of having been in
-development for quite a while. Making a new GPU programming language is actually
-not only a matter of adding a SPIR-V backend to the compiler (which is already
-quite a piece of work), it's also a matter of extending the source programming
-language (possibly via a library of functions implemented in SPIR-V "assembly")
-to expose all the GPU features that GPU-specific programming languages have been
-supporting forever.[^5]
+development for quite a while. Making a _good_ new GPU programming language is
+actually not only a matter of adding a SPIR-V backend to the compiler (which is
+already a large amount of work), it's also a matter of extending the source
+programming language and its standard library to expose all the GPU features
+that GPU-specific programming languages have been exposing forever.[^5]
 
 
 ## Our first GLSL Gray-Scott
@@ -127,9 +127,8 @@ There is a fair bit to unpack here:
 - `params` is a struct that lets us pass simulation parameters to the GPU code.
   Notice that unlike the CPU code, the GPU code does not know about some
   computation parameters at compile time, which puts it at a slight performance
-  disadvantage. By using specialization constants, we could reverse this
-  situation and let the GPU compiler know about **all** simulation parameters at
-  compile time using specialization constants.
+  disadvantage. By using specialization constants, we could reverse this and let
+  the GPU code know about **all** simulation parameters at compile time.
 - All variables introduced so far are `uniform`s, which means that all
   work-items (same thing as CUDA threads) in a given shader execution agree on
   their value. This greatly improves GPU code performance by letting the GPU
@@ -137,12 +136,12 @@ There is a fair bit to unpack here:
   computations, and is in fact mandatory for images and samplers.
 - To enable binding associated resources from the CPU side, each of these inputs
   and outputs is assigned a set and binding number. Here, we have made all
-  inputs and outputs part of set 0, and parameters part of set 1. Here the two
-  layer set->binding hierarchy lets us flip simulation inputs and outputs
-  without needing to rebind unchanging simulation parameters.
+  inputs and outputs part of set 0, and all parameters part of set 1. Thi 
+  set-binding hierarchy lets us flip simulation inputs/outputs in a single API
+  transaction, without needing to rebind unchanging parameters.
 - Finally, we specify the work-group size, which is Vulkan's equivalent of
   CUDA's thread-block size. For now, we hardcode it in the shader code, but
-  later we can make it runtime-configurable using specialization constants.
+  later we could make it runtime-configurable using specialization constants.
 
 ---
 
@@ -307,6 +306,8 @@ version of each type from the input GLSL code. All we need to do is to
 expose it so other code can use it:
 
 ```rust,ignore
+/// Simulation parameters, in a GPU-friendly layout
+///
 /// This syntax lets you re-export a type defined in another module as if you
 /// defined said type yourself
 pub use shader::Parameters;