Merge branch 'master' of https://github.com/defold/doc

docs/zh/manuals/camera.md

@@ -5,17 +5,23 @@ brief: 本教程介绍了 Defold 摄像机组件的功能.
 
 # 摄像机
 
-Defold 的摄像机组件控制游戏世界的视口与映射. 摄像机组件定义了透视和平视的视口与映射矩阵用于渲染脚本进行渲染. 透视摄像机一般服务于 3D 游戏, 平视摄像机一般服务员 2D 游戏. 如果需要摄像机追随, 缩放, 震动之类的功能需要自己来实现 (可以参考下面的 [第三方摄像机解决方案](https://www.defold.com/manuals/camera/#第三方摄像机解决方案)).
+Defold 的摄像机组件控制游戏世界的视口与映射. 摄像机组件定义了透视和平视的视口与映射矩阵用于渲染脚本进行渲染.
+
+透视摄像机一般服务于 3D 游戏, 摄像机视口与物体透视基于视锥体, 摄像机到游戏物体的距离和视角.
+
+平视摄像机一般服务于 2D 游戏. 摄像机视口不是基于视锥体, 而是基于视立方体. 平视摄像机中的物体不因距离远近而缩放. 1000米远的物体和摄像机面前的物体是等大的.
+
+![projections](images/camera/projections.png)
 
 ## 创建摄像机
 
 要创建摄像机, 在游戏对象上 <kbd>右键点击</kbd> 选择 <kbd>Add Component ▸ Camera</kbd>. 或者先创建组件文件再链接到游戏对象上.
 
-![create camera component](images/camera/create.png){srcset="images/camera/[email protected] 2x"}
+![create camera component](images/camera/create.png)
 
 摄像机有以下属性用以建立 *视锥* (透视摄像机可用):
 
-![camera settings](images/camera/settings.png){srcset="images/camera/[email protected] 2x"}
+![camera settings](images/camera/settings.png)
 
 Id
 : 组件id
@@ -35,15 +41,22 @@ Far Z
 Auto Aspect Ratio
 : (**透视摄像机可用**) - 自动设置宽高比.
 
+Orthographic Projection
+: 切换摄像机为平视摄像机 (见下文).
+
+Orthographic Zoom
+: (**基于平视摄像机**) - 正交透视倍数 (> 1 = 放大, < 1 = 缩小).
+
+
 ## 使用摄像机
 
-通过发送 acquire_camera_focus 消息, 激活摄像机并填充视口同时向渲染脚本提供映射矩阵:
+通过发送 `acquire_camera_focus` 消息, 激活摄像机并填充视口同时向渲染脚本提供映射矩阵:
 
 ```lua
 msg.post("#camera", "acquire_camera_focus")
 ```
 
-被激活的摄像机, 会在每一帧向 "@render" 接口发送 `"set_view_projection"` 消息, 也就是说渲染脚本会接收此消息:
+被激活的摄像机, 会在每一帧向 "@render" 接口发送 `set_view_projection` 消息, 也就是说渲染脚本会接收此消息:
 
 ```lua
 -- builtins/render/default.render_script
@@ -57,6 +70,19 @@ end
 ```
 1. 这个消息中包含一个视口矩阵和一个映射矩阵.
 
+摄像机组件支持基于摄像机属性 *Orthographic Projection* 的, 使用透视或者平视透视矩阵的渲染脚本.
+
+::: 注意
+出于向后兼容性的原因，默认渲染脚本会忽略相机提供的透视，并始终使用平视透视. 关于渲染脚本, 视口和透视矩阵更多详情参见 [渲染教程](/manuals/render/#default-view-projection).
+:::
+
+可以用以下代码告诉渲染脚本使用摄像机提供的透视:
+
+```lua
+msg.post("@render:", "use_camera_projection")
+```
+
+
 ### 摄像机平移
 
 平移摄像机所在游戏对象就相当于平移摄像机. 摄像机会根据当前x和y坐标更新视口矩阵.
@@ -65,10 +91,10 @@ end
 
 延 z 轴移动透视摄像机所在游戏对象就相当于缩放摄像机. 摄像机会根据当前z坐标更新视口矩阵.
 
-对于平视摄像机只有将其映射类型设置为 `Fixed` 才可以进行视口缩放, 此时要向 "@render" 接口发送缩放等级进行视口缩放:
+可以通过设置平视摄像机的 *Orthographic Zoom* 属性来进行缩放:
 
-```Lua
-msg.post("@render:", "use_fixed_projection", { zoom = 2, near = -1, far = 1 })
+```lua
+go.set("#camera", "orthographic_zoom", 2)
 ```
 
 ### 摄像机跟随
@@ -81,7 +107,7 @@ msg.post("@render:", "use_fixed_projection", { zoom = 2, near = -1, far = 1 })
 
 ### 鼠标位置转换为世界坐标
 
-摄像机平移缩放后 on_input() 函数提供的鼠标位置就不再与世界坐标匹配了. 此时需要进行手动矫正. 默认渲染脚本里把鼠标/屏幕坐标转换为世界坐标的代码如下:
+摄像机平移缩放后 `on_input()` 函数提供的鼠标位置就不再与世界坐标匹配了. 此时需要进行手动矫正. 默认渲染脚本里把鼠标/屏幕坐标转换为世界坐标的代码如下:
 
 ::: 注意
 [本教程第三方摄像机解决方案部分](/manuals/camera/#第三方摄像机解决方案) 提供了坐标转换方法.
@@ -102,42 +128,28 @@ local function screen_to_world(x, y, z)
 end
 ```
 
-## 映射
 
-摄像机提供了用于透视映射的渲染脚本. 非常适合 3D 游戏. 对于 2D 游戏, 通常使用的是 *平视映射*. 这种摄像机的视口不是视锥, 而是方盒. 平视口没有近大远小. 同样大小的东西无论离摄像机远还是近映射出来都一样大.
+## 运行时控制
+可以通过一些消息和属性控制运行时的摄像机 (用法参考 [API 文档](/ref/camera/)).
 
-![projections](images/camera/projections.png){srcset="images/camera/[email protected] 2x"}
+摄像机的一些属性可以通过 `go.get()` 和 `go.set()` 控制:
 
-### 平视映射 (2D)
-平视映射的渲染脚本不采用摄像机发来的映射矩阵自己实现渲染算法. 默认提供三种适配方式: `Stretch`, `Fixed` 和 `Fixed Fit`. 可以通过发送消息设置适配方式:
-
-```lua
-msg.post("@render:", "use_fixed_fit_projection", { near = -1, far = 1 })
-```
+`fov`
+: 摄像机视野 (`number`).
 
-::: 注意
-消息里近远端裁剪平面深度还是需要的. 但是摄像机属性里的近远端裁剪平面设置只在透视摄像机里有效.
-:::
+`near_z`
+: 摄像机近端Z值 (`number`).
 
-::: 注意
-平时摄像机渲染视口的左下角对应摄像机所在游戏对象的位置.
-:::
-
-渲染脚本及适配方式详情请见 [渲染手册](/manuals/render/#默认视口映射).
-
-### 透视映射 (3D)
-透视映射渲染脚本采用摄像机发来的视口与映射矩阵信息实现渲染. 通过发送如下消息使渲染脚本使用来自摄像机的映射信息:
-
-```lua
-msg.post("@render:", "use_camera_projection")
-```
+`far_z`
+: 摄像机远端Z值 (`number`).
 
-渲染脚本详情请见 [渲染手册](/manuals/render/#透视映射).
+`orthographic_zoom`
+: 平视摄像机缩放 (`number`).
 
 
 ## 第三方摄像机解决方案
 
-有一些第三方库实现了诸如游戏对象跟随, 坐标转换等摄像机功能. 可以在 Defold 社区资源库找到:
+有一些第三方库实现了诸如游戏对象跟随, 屏幕抖动, 屏幕与世界坐标转换等摄像机功能. 可以在 Defold 社区资源库找到:
 
 - [Rendercam](https://defold.com/assets/rendercam/) (2D 和 3D) 由 Ross Grams 开发.
 - [Ortographic camera](https://defold.com/assets/orthographic/) (仅 2D) 由 Björn Ritzl 开发.

docs/zh/manuals/render.md

@@ -46,11 +46,7 @@ brief: 本教程介绍了 Defold 的渲染流程及其编程方法.
 
 ## 默认视口映射
 
-默认渲染脚本使用2D游戏常用的正交映射. 填充方式有三种: `Stretch` (默认), `Fixed Fit` 和 `Fixed`.
-
-做3D游戏的话, 可以使用摄像机组件提供的透视映射渲染方法.
-
-摄像机组件既可以设置为正交也可以设置为透视来改变视口矩阵 (简单地说就是游戏世界哪部分需要被渲染). 关于摄像机组件详情请见 [摄像机教程](/manuals/camera).
+默认渲染脚本使用2D游戏常用的平视透视. 填充方式有三种: `Stretch` (默认), `Fixed Fit` 和 `Fixed`. 除了默认渲染脚本使用的平时透视之外, 还可以使用摄像机组件提供的透视矩阵.
 
 ### Stretch
 
@@ -114,11 +110,9 @@ msg.post("@render:", "use_fixed_fit_projection", { near = -1, far = 1 })
 msg.post("@render:", "use_fixed_projection", { near = -1, far = 1, zoom = 2 })
 ```
 
-### 透视映射
-
-透视用来制作 3D 游戏, 游戏对象大小取决于与摄像机距离的远近.
+### 摄像机透视
 
-其命令脚本是:
+还可以使用 [摄像机组件](/manuals/camera)提供的透视矩阵. 用以下代码开启摄像机透视:
 
 ```lua
 msg.post("@render:", "use_camera_projection")