Changed Perspective to Projection

Author: lwjglgamedev

bookcontents/chapter-07/chapter-07.md

@@ -367,36 +367,36 @@ After that we create a reference to the depth attachment (`VkAttachmentReference
 
 ## Scene changes
 
-If we are going to represent 3D scenes, we need to project from the 3D world into a 2D space (the screen). We will need to use a perspective projection matrix in order to avoid distortions and to represent far away objects smaller than closer ones. We will create a new class that will support its creation and update (due to windows resizing) named `Perspective`, which is defined like this:
+If we are going to represent 3D scenes, we need to project from the 3D world into a 2D space (the screen). We will need to use a perspective projection matrix in order to avoid distortions and to represent far away objects smaller than closer ones. We will create a new class that will support its creation and update (due to windows resizing) named `Projection`, which is defined like this:
 
 ```java
 package org.vulkanb.eng.scene;
 
 import org.joml.Matrix4f;
 import org.vulkanb.eng.EngineProperties;
 
-public class Perspective {
+public class Projection {
 
-    private Matrix4f perspectiveMatrix;
+    private Matrix4f projectionMatrix;
 
-    public Perspective() {
-        perspectiveMatrix = new Matrix4f();
+    public Projection() {
+        projectionMatrix = new Matrix4f();
     }
 
-    public Matrix4f getPerspectiveMatrix() {
-        return perspectiveMatrix;
+    public Matrix4f getProjectionMatrix() {
+        return projectionMatrix;
     }
 
     public void resize(int width, int height) {
         EngineProperties engProps = EngineProperties.getInstance();
-        perspectiveMatrix.identity();
-        perspectiveMatrix.perspective(engProps.getFov(), (float) width / (float) height,
+        projectionMatrix.identity();
+        projectionMatrix.perspective(engProps.getFov(), (float) width / (float) height,
                 engProps.getZNear(), engProps.getZFar(), true);
     }
 }
 ```
 
-We are using the [JOML](https://github.com/JOML-CI/JOML) library to create a `Matrix4f` which will hold the projection matrix. The `resize`should be called, at least once, to initialize the parameters of the matrix with the correct parameters (by invoking the `Matrix4f` `perspective`method). The `perspective` method receives the usual arguments, the field of view (in  radians), the aspect ratio and the near and far planes. You may have noticed that it receives an extra argument, which in JOML documentation is named `zZeroToOne`. We have already talked about that Vulkan uses a different coordinate System where y axis point downwards. Vulkan also defines a different range for z coordinates. The Normalized Device Coordinates (NDC), in OpenGL use the range [-1, 1] to represent screen coordinates and also for the z value. Anything outside that range is considered to be out of the field of view and will not be presented. In Vulkan, and also in Direct3D, the NDC range used for the z coordinates is [0, 1]. We need to set the `zZeroToOne` parameter to true to be compliant with Vulkan coordinates System.
+We are using the [JOML](https://github.com/JOML-CI/JOML) library to create a `Matrix4f` which will hold the projection matrix. The `resize`should be called, at least once, to initialize the parameters of the matrix with the correct parameters (by invoking the `Matrix4f` `Projection`method). The `Projection` method receives the usual arguments, the field of view (in  radians), the aspect ratio and the near and far planes. You may have noticed that it receives an extra argument, which in JOML documentation is named `zZeroToOne`. We have already talked about that Vulkan uses a different coordinate System where y axis point downwards. Vulkan also defines a different range for z coordinates. The Normalized Device Coordinates (NDC), in OpenGL use the range [-1, 1] to represent screen coordinates and also for the z value. Anything outside that range is considered to be out of the field of view and will not be presented. In Vulkan, and also in Direct3D, the NDC range used for the z coordinates is [0, 1]. We need to set the `zZeroToOne` parameter to true to be compliant with Vulkan coordinates System.
 
 The parameters of the perspective matrix can be configured in the `eng.properties` file, so we need to update the `EngineProperties` class:
 ```java
@@ -498,24 +498,24 @@ public class Entity {
 
 Each `Entity` shall have an identifier which should be unique. It is also linked to the mesh that will be used to render it through the `meshId` attribute. An `Entity` will have also a position, a rotation (modeled using a  quaternion) and a scale. With all that information we are able to construct a model matrix by calling the `updateModelMatrix` from the `Matrix4f` class. The `updateModelMatrix` should be called, each time the position, rotation or scale changes.
 
-Now we can setup the required infrastructure to put the `Perspective` and `Entity` classes into work. We will add this to an empty class which has been there since the beginning, the  `Scene` class. The class definition starts like this:
+Now we can setup the required infrastructure to put the `Projection` and `Entity` classes into work. We will add this to an empty class which has been there since the beginning, the  `Scene` class. The class definition starts like this:
 
 ```java
 public class Scene {
 
     private Map<String, List<Entity>> entitiesMap;
-    private Perspective perspective;
+    private Projection projection;
 
     public Scene(Window window) {
         entitiesMap = new HashMap<>();
-        perspective = new Perspective();
-        perspective.resize(window.getWidth(), window.getHeight());
+        projection = new Projection();
+        projection.resize(window.getWidth(), window.getHeight());
     }
     ...
 }
 ```
 
-The constructor receives the a `Window` instance and creates a `Map` of `List`s which will contain `Entity` instances. That map will organized the entities by its `meshId`. The constructor initializes that map and also creates an instance of the `Perspective` class, which will hold the perspective matrix. The next method will be used to add new entities:
+The constructor receives the a `Window` instance and creates a `Map` of `List`s which will contain `Entity` instances. That map will organized the entities by its `meshId`. The constructor initializes that map and also creates an instance of the `Projection` class, which will hold the perspective matrix. The next method will be used to add new entities:
 
 ```java
 public class Scene {
@@ -532,7 +532,7 @@ public class Scene {
 }
 ```
 
-As it can be seen, the entities are organized by their `meshId`. Those entities which share the same `meshId` will be placed inside a `List` associated to that identifier. This will allow us to organize the rendering later on in an efficient way. Although each entity has different parameters they will share the vertices, textures, etc. defined by the mesh. Organizing the rendering around mesh information will allow us to bind those common resources just once per mesh. The rest of the methods of the `Scene` class, are used to access the entities map, to get and remove specific entities (suing its identifier) and to get the perspective matrix.
+As it can be seen, the entities are organized by their `meshId`. Those entities which share the same `meshId` will be placed inside a `List` associated to that identifier. This will allow us to organize the rendering later on in an efficient way. Although each entity has different parameters they will share the vertices, textures, etc. defined by the mesh. Organizing the rendering around mesh information will allow us to bind those common resources just once per mesh. The rest of the methods of the `Scene` class, are used to access the entities map, to get and remove specific entities (suing its identifier) and to get the projection matrix.
 
 ```java
 public class Scene {
@@ -545,8 +545,8 @@ public class Scene {
         return entitiesMap;
     }
 
-    public Perspective getPerspective() {
-        return perspective;
+    public Projection getProjection() {
+        return projection;
     }
 
     public void removeAllEntities() {
@@ -689,7 +689,7 @@ public class Render {
         if (window.isResized() || this.swapChain.acquireNextImage()) {
             window.resetResized();
             resize(window);
-            scene.getPerspective().resize(window.getWidth(), window.getHeight());
+            scene.getProjection().resize(window.getWidth(), window.getHeight());
             swapChain.acquireNextImage();
         }
 
@@ -842,7 +842,7 @@ public class ForwardRenderActivity {
 
                 List<Entity> entities = scene.getEntitiesByMeshId(mesh.getId());
                 for (Entity entity : entities) {
-                    setPushConstants(cmdHandle, scene.getPerspective().getPerspectiveMatrix(), entity.getModelMatrix(),
+                    setPushConstants(cmdHandle, scene.getProjection().getProjectionMatrix(), entity.getModelMatrix(),
                             pushConstantBuffer);
                     vkCmdDrawIndexed(cmdHandle, mesh.getIndicesCount(), 1, 0, 0, 0);
                 }

bookcontents/chapter-08/chapter-08.md

@@ -1210,7 +1210,7 @@ public class ForwardRenderActivity {
     ...
     public ForwardRenderActivity(SwapChain swapChain, CommandPool commandPool, PipelineCache pipelineCache, Scene scene) {
         ...
-        VulkanUtils.copyMatrixToBuffer(projMatrixUniform, scene.getPerspective().getPerspectiveMatrix());
+        VulkanUtils.copyMatrixToBuffer(projMatrixUniform, scene.getProjection().getProjectionMatrix());
     }
     ...
 }
@@ -1323,7 +1323,7 @@ The `resize` method needs also to be modified to update the buffer that will bac
 public class ForwardRenderActivity {
     ...
     public void resize(SwapChain swapChain, Scene scene) {
-        VulkanUtils.copyMatrixToBuffer(projMatrixUniform, scene.getPerspective().getPerspectiveMatrix());
+        VulkanUtils.copyMatrixToBuffer(projMatrixUniform, scene.getProjection().getProjectionMatrix());
         ...
     }
     ...

bookcontents/chapter-09/chapter-09.md

@@ -665,7 +665,7 @@ public class ForwardRenderActivity {
 
 We will be using four descriptor sets now, the first one for the perspective projection matrix, the second one will be used for the view matrix, the third one for the texture sampler and, finally, the fourth one for the materials uniform. Therefore, we need to update the descriptor sets layouts that will be used in the pipeline. After that, we setup the number of descriptor sets we need according to their type:
 
-- We will use the `VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER` descriptor sets for the uniforms associated to the perspective projection matrix and the view matrix. We just need one descriptor set for the perspective uniform, since we will not be changing it while drawing a frame. However, the view matrix can be modified while rendering, so we will create separate descriptor sets (and also the associated buffers), one per swap chain image.
+- We will use the `VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER` descriptor sets for the uniforms associated to the perspective projection matrix and the view matrix. We just need one descriptor set for the projection uniform, since we will not be changing it while drawing a frame. However, the view matrix can be modified while rendering, so we will create separate descriptor sets (and also the associated buffers), one per swap chain image.
 - We will use the `VK_DESCRIPTOR_TYPE_COMBINED_IMAGE_SAMPLER` descriptor sets for the combined texture samplers. We will need as many descriptor sets as textures we will have. Here we are defining a new property to configure the maximum number of supported materials. As explained in the previous chapter, we don't need separate descriptor sets per swap chain image. Textures here are read only.
 - We will use the `VK_DESCRIPTOR_TYPE_UNIFORM_BUFFER_DYNAMIC` descriptor sets for the uniform associated to the material data. If we were not using dynamic uniform buffers, we would need at least one per material. We are using a single descriptor set to hold all the material data, since we will not be updating them while rendering.
 

bookcontents/chapter-10/chapter-10.md

@@ -338,7 +338,7 @@ public class GeometryRenderActivity {
         createDescriptorSets(numImages);
         createPipeline();
         createCommandBuffers(commandPool, numImages);
-        VulkanUtils.copyMatrixToBuffer(projMatrixUniform, scene.getPerspective().getPerspectiveMatrix());
+        VulkanUtils.copyMatrixToBuffer(projMatrixUniform, scene.getProjection().getProjectionMatrix());
     }
 
     public void cleanup() {
@@ -641,7 +641,7 @@ This method is almost identical than the one used in the `ForwardRenderActivity`
 public class GeometryRenderActivity {
     ...
     public void resize(SwapChain swapChain, Scene scene) {
-        VulkanUtils.copyMatrixToBuffer(projMatrixUniform, scene.getPerspective().getPerspectiveMatrix());
+        VulkanUtils.copyMatrixToBuffer(projMatrixUniform, scene.getProjection().getProjectionMatrix());
         this.swapChain = swapChain;
         geometryFrameBuffer.resize(swapChain);
     }

bookcontents/chapter-11/chapter-11.md

@@ -983,7 +983,7 @@ Finally, we need to add two new methods to update the inverse projection matrix
 public class LightingRenderActivity {
     ...
     private void updateInvProjMatrix(Scene scene) {
-        Matrix4f invProj = new Matrix4f(scene.getPerspective().getPerspectiveMatrix()).invert();
+        Matrix4f invProj = new Matrix4f(scene.getProjection().getProjectionMatrix()).invert();
         VulkanUtils.copyMatrixToBuffer(device, invProjBuffer, invProj);
     }
 

booksamples/chapter-07/src/main/java/org/vulkanb/eng/graph/ForwardRenderActivity.java

@@ -167,7 +167,7 @@ public void recordCommandBuffers(List<VulkanMesh> meshes, Scene scene) {
 
                 List<Entity> entities = scene.getEntitiesByMeshId(mesh.getId());
                 for (Entity entity : entities) {
-                    setPushConstants(cmdHandle, scene.getPerspective().getPerspectiveMatrix(), entity.getModelMatrix(),
+                    setPushConstants(cmdHandle, scene.getProjection().getProjectionMatrix(), entity.getModelMatrix(),
                             pushConstantBuffer);
                     vkCmdDrawIndexed(cmdHandle, mesh.getIndicesCount(), 1, 0, 0, 0);
                 }

booksamples/chapter-07/src/main/java/org/vulkanb/eng/graph/Render.java

@@ -69,7 +69,7 @@ public void render(Window window, Scene scene) {
         if (window.isResized() || swapChain.acquireNextImage()) {
             window.resetResized();
             resize(window);
-            scene.getPerspective().resize(window.getWidth(), window.getHeight());
+            scene.getProjection().resize(window.getWidth(), window.getHeight());
             swapChain.acquireNextImage();
         }
 

booksamples/chapter-07/src/main/java/org/vulkanb/eng/scene/Perspective.java

@@ -0,0 +1,24 @@
+package org.vulkanb.eng.scene;
+
+import org.joml.Matrix4f;
+import org.vulkanb.eng.EngineProperties;
+
+public class Projection {
+
+    private Matrix4f projectionMatrix;
+
+    public Projection() {
+        projectionMatrix = new Matrix4f();
+    }
+
+    public Matrix4f getProjectionMatrix() {
+        return projectionMatrix;
+    }
+
+    public void resize(int width, int height) {
+        EngineProperties engProps = EngineProperties.getInstance();
+        projectionMatrix.identity();
+        projectionMatrix.perspective(engProps.getFov(), (float) width / (float) height,
+                engProps.getZNear(), engProps.getZFar(), true);
+    }
+}

booksamples/chapter-07/src/main/java/org/vulkanb/eng/scene/Projection.java

@@ -7,12 +7,12 @@
 public class Scene {
 
     private Map<String, List<Entity>> entitiesMap;
-    private Perspective perspective;
+    private Projection projection;
 
     public Scene(Window window) {
         entitiesMap = new HashMap<>();
-        perspective = new Perspective();
-        perspective.resize(window.getWidth(), window.getHeight());
+        projection = new Projection();
+        projection.resize(window.getWidth(), window.getHeight());
     }
 
     public void addEntity(Entity entity) {
@@ -32,8 +32,8 @@ public Map<String, List<Entity>> getEntitiesMap() {
         return entitiesMap;
     }
 
-    public Perspective getPerspective() {
-        return perspective;
+    public Projection getProjection() {
+        return projection;
     }
 
     public void removeAllEntities() {