Improved camera and render manuals

Improved instructions on how to change projection

docs/en/manuals/camera.md

@@ -7,7 +7,7 @@ brief: This manual describes the functionality of the Defold camera component.
 
 A camera in Defold is a component that changes the viewport and projection of the game world. Out of the box, Defold ships with a built in render script that renders the game with no need of a camera component but you can easily replace the built in script with one that renders the game to your liking.
 
-The camera component defines a bare bones perspective camera that provides a view and projection matrix to the render script. If you need advanced features like chasing, zooming, shake etc you will need to implement it. There are a few library camera solutions that implements common camera features. They are available from the Defold community assets portal:
+The camera component defines a bare bones perspective or orthographic camera that provides a view and projection matrix to the render script. If you need advanced features like chasing, zooming, shake etc you will need to implement it. There are a few library camera solutions that implements common camera features. They are available from the Defold community assets portal:
 
 - [Rendercam](https://www.defold.com/community/projects/84064/) by Ross Grams.
 - [Ortographic camera](https://www.defold.com/community/projects/76573/) by Björn Ritzl.
@@ -26,10 +26,10 @@ Id
 : The id of the component
 
 Aspect Ratio
-: The ratio between the frustum width and height. 1.0 means that you assume a quadratic view. 1.33 is good for a 4:3 view like 1024x768. 1.78 is good for a 16:9 view. This setting is ignored if *Auto Aspect Ratio* is set.
+: (**Perspective camera only**) - The ratio between the frustum width and height. 1.0 means that you assume a quadratic view. 1.33 is good for a 4:3 view like 1024x768. 1.78 is good for a 16:9 view. This setting is ignored if *Auto Aspect Ratio* is set.
 
 Fov
-: The *vertical* camera field of view expressed in _radians_. The wider the field of view, the more the camera will see. Note that the current default value (45) is misleading. For a 45 degree field of view, change the value to 0.785 ($\pi / 4$).
+: (**Perspective camera only**) - The *vertical* camera field of view expressed in _radians_. The wider the field of view, the more the camera will see. Note that the current default value (45) is misleading. For a 45 degree field of view, change the value to 0.785 ($\pi / 4$).
 
 Near Z
 : The Z-value of the near clipping plane.
@@ -38,7 +38,7 @@ Far Z
 : The Z-value of the far clipping plane.
 
 Auto Aspect Ratio
-: Set this to let the camera automatically calculate the aspect ratio.
+: (**Perspective camera only**) - Set this to let the camera automatically calculate the aspect ratio.
 
 ## Using the camera
 
@@ -53,13 +53,6 @@ Each frame, the camera component that currently has camera focus will send a `"s
 ```lua
 -- example.render_script
 --
-function update(self)
-    ...
-    render.set_view(self.view)
-    render.set_projection(self.projection)
-    ...
-end
-
 function on_message(self, message_id, message)
     if message_id == hash("set_view_projection") then
         self.view = message.view                    -- [1]
@@ -71,10 +64,11 @@ end
 
 ## Projections
 
-The camera component currently supplies the render script with a perspective projection. This is well suited for 3D games. For 2D games, it is often desirable to render the scene with *orthographic projection*. This means that the view of the camera is no longer dictated by a frustum, but by a box. Orthographic projection is unrealistic in that it does not alter the size of objects based on their distance. An object 1000 units away will render at the same size as an object right in front of the camera.
+The camera component supplies the render script with a perspective projection. This is well suited for 3D games. For 2D games, it is often desirable to render the scene with *orthographic projection*. This means that the view of the camera is no longer dictated by a frustum, but by a box. Orthographic projection is unrealistic in that it does not alter the size of objects based on their distance. An object 1000 units away will render at the same size as an object right in front of the camera.
 
 ![projections](images/camera/projections.png){srcset="images/camera/[email protected] 2x"}
 
+### Orthographic projection
 To use orthographic projection you can ignore the projection matrix sent by the camera component and instead provide one yourself in the render script, just like the default renderscript does:
 
 ```lua
@@ -98,3 +92,42 @@ end
 ```
 1. Set up an orthographic projection based on the width and height of the game window. The center of view is the camera's position. Note that the default render script sets the lower left corner of the view at the camera's position.
 2. Only care about camera view since the projection is done separately.
+
+The default render script is initially set up to use the view matrix provided by the camera and a stretch projection. You can change the orthographic projection type by sending a message to the render script:
+
+```lua
+msg.post("@render:", "use_fixed_fit_projection", { near = -1, far = 1 })
+```
+
+Learn more about the render script and how to change which type of orthographic projection to use in the [Render manual](/manuals/render).
+
+### Perspective projection
+To use perspective projection you must use both the view and projection provided by the camera:
+
+```lua
+-- example_perspective.render_script
+--
+function update(self)
+    ...
+    render.set_view(self.view)                      -- [1]
+    render.set_projection(self.projection)
+    ...
+end
+
+function on_message(self, message_id, message)
+    if message_id == hash("set_view_projection") then
+        self.view = message.view                    -- [2]
+        self.projection = message.projection
+    end
+end
+```
+1. Use both the view and projection matrix provided by the camera
+2. The message posted from the camera component includes a view matrix and a projection matrix.
+
+The default render script is initially set up to use an orthographic projection. You can change to the render script to use the perspective projection provided by a camera by sending a message to the render script:
+
+```lua
+msg.post("@render:", "use_camera_projection")
+```
+
+Learn more about the render script in the [Render manual](/manuals/render).

docs/en/manuals/render.md

@@ -25,11 +25,15 @@ To set up a custom renderer:
 
 3. Change the *Render* property (under *bootstrap*) in the "game.project" settings file to refer to your copy of the "default.render" file.
 
-### Default view projection
+## Default view projection
 
-The default render script provides a number of different projections for drawing your game content, with the default being a stretch projection. The other projections provided in the default render script are fixed fit and fixed projections.
+The default render script is configured to use an orthographic projection suitable for 2D games. It provides three different orthographic projections: `Stretch` (default), `Fixed Fit` and `Fixed`.
 
-#### Stretch projection
+You can also use a perspective projection suitable for 3D games, as provided by a camera component.
+
+The camera component can be used for both orthographic and perspective projections to change the view matrix (basically which part of the game world that is rendered). Learn more about the camera component in the [Camera manual](/manuals/camera).
+
+### Stretch projection
 
 The stretch projection will always draw an area of your game that is equal to the dimensions set in "game.project", even when the window is resized. If the aspect ratio changes it will result in game content being stretched either vertically or horizontally:
 
@@ -44,12 +48,10 @@ The stretch projection will always draw an area of your game that is equal to th
 The stretch projection is the default projection but if you have changed from it and need to switch back you do it by sending a message to the render script:
 
 ```lua
-function init(self)
-    msg.post("@render:", "use_stretch_projection", { near = -1, far = 1 })
-end
+msg.post("@render:", "use_stretch_projection", { near = -1, far = 1 })
 ```
 
-#### Fixed fit projection
+### Fixed fit projection
 
 Just like the stretch projection the fixed fit projection will always show an area of the game that is equal to the dimensions set in "game.project", but if the window is resized and the aspect ratio changes the game content will retain the original aspect ratio and additional game content will be show vertically or horizontally:
 
@@ -68,12 +70,10 @@ Just like the stretch projection the fixed fit projection will always show an ar
 You enable the fixed fit projection by sending a message to the render script:
 
 ```lua
-function init(self)
-    msg.post("@render:", "use_fixed_fit_projection", { near = -1, far = 1 })
-end
+msg.post("@render:", "use_fixed_fit_projection", { near = -1, far = 1 })
 ```
 
-#### Fixed projection
+### Fixed projection
 
 The fixed projection will retain the original aspect ratio and render your game content with a fixed zoom level. This means that it if the zoom level is set to something other than 100% it will show more or less than the area of the game defined by the dimensions in "game.project":
 
@@ -92,11 +92,20 @@ The fixed projection will retain the original aspect ratio and render your game
 You enable the fixed projection by sending a message to the render script:
 
 ```lua
-function init(self)
-    msg.post("@render:", "use_fixed_projection", { near = -1, far = 1, zoom = 2 })
-end
+msg.post("@render:", "use_fixed_projection", { near = -1, far = 1, zoom = 2 })
 ```
 
+### Perspective projection
+
+The perspective projection is suitable for 3D games where game objects are rendered with a perspective and where the size of objects vary depending on the distance from an imagined eye/camera position.
+
+You enable the perspective projection provided from a camera component by sending a message to the render script:
+
+```lua
+msg.post("@render:", "use_camera_projection")
+```
+
+
 ## Render predicates
 
 To be able to control the draw order of objects, you create render _predicates_. A predicate declares what should be drawn based on a selection of material _tags_.