内置着色器 uniform

PlayCanvas 在前向通道渲染网格时提供以下数值 uniform。可直接在 ShaderMaterial 和自定义材质代码块中使用，无需对这些名称调用 Material.setParameter()。自行设置值参见着色器参数。

相机值对应当前渲染的相机或 XR 视图。此列表描述前向渲染，不应假定阴影、拾取、计算或独立后处理通道也填充相同输入。

可用 uniform

顶点和片元着色器均可读取。按下表类型声明所需名称，WGSL 中通过 uniform. 前缀访问。

Uniform	GLSL 类型	WGSL 类型	值
matrix_view	mat4	mat4x4f	将世界空间位置变换到视图空间。
matrix_viewInverse	mat4	mat4x4f	matrix_view 的逆矩阵，将视图空间位置变换到世界空间。
matrix_view3	mat3	mat3x3f	matrix_view 左上角 3×3 部分，只变换方向，不含平移。
matrix_projection	mat4	mat4x4f	将视图空间位置变换到裁剪空间，包含渲染器投影调整，例如抖动、目标 Y 翻转和图形后端深度约定。
matrix_viewProjection	mat4	mat4x4f	matrix_projection * matrix_view，将世界空间位置变换到裁剪空间。
view_position	vec3	vec3f	世界空间相机位置，XR 中为当前眼睛位置。
camera_params	vec4	vec4f	相机裁剪平面和投影类型：1 / farClip、farClip、nearClip，以及正交相机为 1、透视相机为 0。可用于线性化深度。
screen_size	vec4	vec4f	画布绘制缓冲区的宽、高及其倒数，单位为实际像素而非 CSS 尺寸。
viewport_size	vec4	vec4f	相机视口的像素宽、高及其倒数，考虑目标、camera.rect 和 XR 眼视口，不含视口原点。
view_index	uint	u32	当前 XR 视图从零开始的索引，可选择逐视图数据，例如深度纹理数组层。

投影矩阵是实际渲染版本，可能与应用在抖动或后端调整之前计算的矩阵不同。在着色器中投影世界位置时，应优先使用 matrix_viewProjection。

matrix_model 和 matrix_normal 是逐网格输入，与上述相机和场景值分开。要支持蒙皮、变形和实例化变换，使用顶点着色器代码块。

场景深度和颜色纹理 uSceneDepthMap 与 uSceneColorMap，参见深度图层。

声明与读取 uniform

例如，将世界空间方向转换到视图空间：

GLSL

uniform mat3 matrix_view3;

vec3 directionToView(vec3 worldDirection) {
    return matrix_view3 * worldDirection;
}

WGSL

uniform matrix_view3: mat3x3f;

fn directionToView(worldDirection: vec3f) -> vec3f {
    return uniform.matrix_view3 * worldDirection;
}

完整声明规则参见 GLSL 特性和 WGSL 反射。

屏幕尺寸与视口尺寸

两个尺寸 uniform 均采用 [width, height, 1 / width, 1 / height] 布局，但描述区域不同：

• screen_size 始终描述画布绘制缓冲区，渲染到更小的离屏目标不会改变它。
• viewport_size 描述相机在当前目标中的视口，会随离屏目标、局部相机矩形和 XR 眼视口改变。

例如 1920×1080 画布中，相机填满 960×540 目标时，screen_size.xy 为 (1920, 1080)，viewport_size.xy 为 (960, 540)。如果相机只占目标宽度一半，后者为 (480, 540)。

不要将 screen_size 用作通用纹理尺寸。对局部视口归一化帧缓冲坐标时，还需考虑视口原点，而这两个 uniform 均不提供原点。