Clarify the purpose of shader modules and their lifetime requirements (fixes #121)

Overv · Overv · commit d8784741bba8 · 2019-01-07T22:40:42.000+01:00
diff --git a/03_Drawing_a_triangle/02_Graphics_pipeline_basics/01_Shader_modules.md b/03_Drawing_a_triangle/02_Graphics_pipeline_basics/01_Shader_modules.md
@@ -241,8 +241,8 @@ We're now going to compile these into SPIR-V bytecode using the
 Create a `compile.bat` file with the following contents:
 
 ```bash
-C:/VulkanSDK/1.0.17.0/Bin32/glslangValidator.exe -V shader.vert
-C:/VulkanSDK/1.0.17.0/Bin32/glslangValidator.exe -V shader.frag
+C:/VulkanSDK/x.x.x.x/Bin32/glslangValidator.exe -V shader.vert
+C:/VulkanSDK/x.x.x.x/Bin32/glslangValidator.exe -V shader.frag
 pause
 ```
 
@@ -341,7 +341,7 @@ void createGraphicsPipeline() {
 ```
 
 Make sure that the shaders are loaded correctly by printing the size of the
-buffers and checking if they match the actual file size in bytes.
+buffers and checking if they match the actual file size in bytes. Note that the code doesn't need to be null terminated since it's binary code and we will later be explicit about its size.
 
 ## Creating shader modules
 
@@ -394,25 +394,18 @@ shader module:
 return shaderModule;
 ```
 
-The shader module objects are only required during the pipeline creation
-process, so instead of declaring them as class members, we'll make them local
-variables in the `createGraphicsPipeline` function:
+Shader modules are just a thin wrapper around the shader bytecode that we've previously loaded from a file and the functions defined in it. The compilation and linking of the SPIR-V bytecode to machine code for execution by the GPU doesn't happen until the graphics pipeline is created. That means that we're allowed to destroy the shader modules again as soon as pipeline creation is finished, which is why we'll make them local variables in the `createGraphicsPipeline` function instead of class members:
 
 ```c++
-VkShaderModule vertShaderModule;
-VkShaderModule fragShaderModule;
-```
-
-Call the helper function we created to load the shader modules:
+void createGraphicsPipeline() {
+    auto vertShaderCode = readFile("shaders/vert.spv");
+    auto fragShaderCode = readFile("shaders/frag.spv");
 
-```c++
-vertShaderModule = createShaderModule(vertShaderCode);
-fragShaderModule = createShaderModule(fragShaderCode);
+    VkShaderModule vertShaderModule = createShaderModule(vertShaderCode);
+    VkShaderModule fragShaderModule = createShaderModule(fragShaderCode);
 ```
 
-They should be cleaned up when the graphics pipeline has been created and
-`createGraphicsPipeline` returns, so make sure that they are deleted at the end
-of the function:
+The cleanup should then happen at the end of the function by adding two calls to `vkDestroyShaderModule`. ALl of the remaining code in this chapter will be inserted before these lines.
 
 ```c++
     ...
@@ -423,11 +416,7 @@ of the function:
 
 ## Shader stage creation
 
-The `VkShaderModule` object is just a dumb wrapper around the bytecode buffer.
-The shaders aren't linked to each other yet and they haven't even been given a
-purpose yet. Assigning a shader module to either the vertex or fragment shader
-stage in the pipeline happens through a `VkPipelineShaderStageCreateInfo`
-structure, which is part of the actual pipeline creation process.
+To actually use the shaders we'll need to assign them to a specific pipeline stage through `VkPipelineShaderStageCreateInfo` structures as part of the actual pipeline creation process.
 
 We'll start by filling in the structure for the vertex shader, again in the
 `createGraphicsPipeline` function.
@@ -448,7 +437,7 @@ vertShaderStageInfo.pName = "main";
 ```
 
 The next two members specify the shader module containing the code, and the
-function to invoke. That means that it's possible to combine multiple fragment
+function to invoke, known as the *entrypoint*. That means that it's possible to combine multiple fragment
 shaders into a single shader module and use different entry points to
 differentiate between their behaviors. In this case we'll stick to the standard
 `main`, however.
