环境数据的原理在环境一章中介绍过。CLI接受一张hdr或sdr的全景图片,来生成微信小程序框架需要的环境数据,支持打包成二进制优化加载。
分类: XR-FRAME
真机调试
要使用真机调试来调试XR-FRAME,需要按照以下几个步骤:
- 确保工具是最新的
Nightly版本。 - 确定至少存在一个分包,空分包也可以。
- 在真机调试界面,左下角切换到真机调试2.0(如下图)。


然后便可以正常使用真机调试。
内置后处理资源
此处列出了微信小程序框架内置支持的后处理资源类型、参数和对应效果。
以下标题名即为后处理资源里的type属性。
blur
高斯模糊,效果好但是在radius较大时性能开销较高,快速近似方法见fastblur。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| radius | number | 5 | 模糊半径 |
示例,radius=64:

fastblur
也是高斯模糊,但是更快速的近似版本。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| radius | number | 5 | 模糊半径 |
时间稳定性高,但效果没有blur好,适用于需要不断变更radius的场景。
bloom
泛光,建议开启is-hdr使用。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| threshold | number | 0.5 | 阈值 |
| softThreshold | number | 0 | 软阈值 |
| radius | number | 20 | 半径 |
| intensity | number | 2 | 亮度 |
示例,radius=64,intensity=2,其他默认:

tone
色调映射,ACES曲线,一般配合hdr使用。
示例:

vignette
渐晕。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| center | number[] | [0.5,0.5] | 半径 |
| color | number[] | [0,0,0,1] | 颜色 |
| intensity | number | 1 | 亮度 |
| smoothness | number | 1 | 边缘柔化 |
| roundness | number | 1 | 圆度 |
| rounded | number | 0/1 | 强制为圆形 |
示例,color=[1,0,0,1],smoothness=2,其他默认:

fxaa
快速抗锯齿。
示例:

内置图集
框架内置了一些图集资源。
普通纹理
|名称|资源id|帧名|描述|
|—|—|—|
|数字|numbers|0~9|
|
Standard 标准物理光照渲染
Standard 材质基于标准的 PBR 进行实现。
PBR(Physically Based Rendering) 是指使用基于物理原理和微平面理论建模的着色/光照模型,以及使用从现实中测量的表面参数来准确表示真实世界材质的渲染理念。

使用 PBR 的优势
- 基于物理模型与数学推演带来的效果的
真实。 - 艺术导向性的、标准化的美术参数带来的
易用与效果一致。
xr-frame 使用 PBR 有以下两种方式
- 使用带光照材质的 glTF 资源,目前主流的各类
DCC工具(Digital Content Create) 都可以产出这种业界通用的格式。 - 使用内置的
standard创建材质,并设置所需的不同uniform来进行对应渲染。
创建 standard 材质进行渲染
使用 standard 材质进行渲染时,可以设置以下的 uniform 来决定渲染效果。
各系数的美术意义可以参考 创建PBR纹理实用指南。
基础色 (baseColor)
| uniforms | 类型 | 备注 | 默认值 |
|---|---|---|---|
| u_baseColorMap | texture | 颜色贴图,颜色空间为 SRGB | 默认未使用 |
| u_baseColorFactor | vec4 | 颜色因子,颜色空间为 SRGB | 1, 1, 1, 1 |
基础色表示物体的 表面颜色,PBR 中可以认为影响 电介质(非金属)漫反射 与 金属反射率值。
vec4 baseColor = vec4(1.0, 1.0, 1.0, 1.0);
// 若设定基础色贴图
baseColor *= SRGBtoLINEAR(u_baseColorMap);
// 若设定基础色因子,glTF情况下,传入LINEAR空间颜色,不进行颜色空间转化
baseColor *= SRGBtoLINEAR(u_baseColorFactor);
// 若设定顶点色
baseColor *= vec4(v_Color, 1.0);
基础色贴图:左侧为只有基础色效果;右侧为基础色贴图

金属度粗糙度 (metallic rougness)
| uniforms | 类型 | 备注 | 默认值 |
|---|---|---|---|
| u_metallicRoughnessMap | texture | 金属粗糙度贴图,g 部分为粗糙度,b 部分为金属度 | 默认未使用 |
| u_metallicMap | texture | 金属度贴图,未使用金属粗糙度贴图时才生效 | 默认未使用 |
| u_roughnessMap | texture | 粗糙度度贴图,未使用金属粗糙度贴图时才生效 | 默认未使用 |
| u_metallicRoughnessValues | vec2 | 金属粗糙度因子,第一位为金属度,第二位为粗糙度 | 0, 1 |
| u_ior | float | 折射率,默认值可以认为类似塑料折射率 | 1.5 |
金属度 表示 哪些区域是粗金属(0=电介质,1=金属),影响 电介质模型 与 金属模型 的 线性混合。
粗糙度 表示 表面粗糙度,控制 漫反射和镜面反射。
IOR 表示 折射率,控制材质的 F0,即0度角入射的菲涅尔反射值。
float metallic = u_metallicRoughnessValues.b; // 默认值 0.0,glTF 为 1.0
float roughness = u_metallicRoughnessValues.g; // 默认值 1.0
// 若设定金属度粗糙度贴图
metallic *= metallicRoughnessMap.b;
roughness *= metallicRoughnessMap.g;
// F0
f0 = min( pow2( ( u_ior - 1.0 ) / ( u_ior + 1.0 ) ) * specularColorFactor;
金属度粗糙度:左上角为金属度效果图,左下角为粗糙度效果图,数值0为黑色,数值1为白色;右侧为金属粗糙度贴图,g 部分为粗糙度,b 部分为金属度。

法线 (Normal)
| uniforms | 类型 | 备注 | 默认值 |
|---|---|---|---|
| u_normalMap | texture | 法线贴图 | 默认未使用 |
| u_normalScale | float | 法线贴图缩放,需使用法线贴图才生效 | 1 |
法线 可以认为是 垂直于顶点表面 的(单位)向量。于顶点数据中传入,用于 PBR 中光照相关的各类运算。
法线贴图 可以理解为一种高度贴图,用于模仿表面细节。贴图中的每个像素,代表切线空间中,将法线处理为真实法线的偏差处理。
使用法线贴图的情况下,需要传入顶点Tangent才能生效。
float normal = vNormal;
// 如果使用法线贴图,需要保证存在 vNormal 与 vTangent 以算出vTBN
mat3 vTBN = mat3( tangent, bitangent, normal );
normal = normalize( vTBN * normalMap );
法线:左侧图片为世界空间中法线效果,右侧为法线贴图。

自发光 (Emissive)
| uniforms | 类型 | 备注 | 默认值 |
|---|---|---|---|
| u_emissiveMap | texture | 自发光贴图,颜色空间为 SRGB | 默认未使用 |
| u_emissiveFactor | vec3 | 自发光贴图因子,颜色空间为 LINEAR | 0, 0, 0 |
自发光 表示了材质作为光源向外发送的颜色信息,颜色空间为 SRGB。
vec4 emissiveColor = u_emissiveFactor;
// 若设定自发光贴图
vec4 emissiveColor *= SRGBtoLINEAR(u_emissiveMap);
自发光:左侧图片为只有自发光的效果,右侧图片为自发光贴图。

环境光遮蔽 (Ambient occlusion)
| uniforms | 类型 | 备注 | 默认值 |
|---|---|---|---|
| u_occlusionMap | texture | 环境光遮蔽贴图 | 默认未使用 |
| u_occlusionStrength | float | 环境光遮蔽贴图强度,需使用遮蔽贴图才生效 | 1 |
环境光遮蔽 指表面某点能获得多少环境中的光。该贴图只影响漫反射分配,不影响高光反射分配。
// 若设定遮蔽贴图
float ao = u_occlusionMap;
// 若设定遮蔽贴图 与 遮蔽因子
ao *= u_occlusionStrength;
环境光遮蔽:左侧图片为默认PBR渲染效果,右侧图片为环境光遮挡显示效果,0为完全遮蔽,1为完全不遮蔽。

透明剔除 (alphaCutoff)
| uniforms | 类型 | 备注 | 默认值 |
|---|---|---|---|
| u_alphaCutoff | float | 透明剔除阈值,当 baseColor 的 alpha 小于 u_alphaCutoff 时,不进行绘制,alphaMode 为 MASK 的情况下才生效 | 0.5 |
透明剔除 用于进行透明度剔除。当alphaMode 为 MASK 的情况下,会不渲染 baseColor 的 alpha 小于 u_alphaCutoff 的像素。
如需使用透明剔除,需手动设置宏 WX_USE_ALPHA_CUTOFF或设置渲染状态使用。
透明剔除:左侧图片为开启alphaCutoff效果,右侧图片为未使用alphaCutoff效果。

清漆效果 (clearcoat)
| uniforms | 类型 | 备注 | 默认值 |
|---|---|---|---|
| u_clearcoatFactor | float | 清漆强度 | 0 |
| u_clearcoatRoughnessFactor | float | 清漆粗糙度 | 0 |
清漆效果 可以认为是往物体表面添加透明涂层。
如需使用清漆效果,需手动设置宏 WX_USE_CLEARCOAT。
清漆强度:左侧图片为使用clearcoat效果,右侧图片为未使用clearcoat效果

高光反射与光泽度 (specularGlossiness)
| uniforms | 类型 | 备注 | 默认值 |
|---|---|---|---|
| u_specularFactor | vec3 | 高光反射因子 | 1, 1, 1 |
| u_glossinessFactor | float | 光泽度 | 1.0 |
| u_specularGlossinessMap | texture | 高光光泽贴图,其中rgb部分是高光反射,a部分为光泽度 | 默认未使用 |
高光反射与光泽度 是 PBR 的另外一种渲染流程,相对于金属度粗糙度流程,该流程可以在高光反射贴图中控制F0。其中 光泽度 相当于(1 – 粗糙度)。
漫反射部分 的 diffuse 因子与贴图可以直接使用 基础色 basecolor 相关参数。
如需使用高光反射与光泽度流程,需手动设置宏 WX_USE_SPECULARGLOSSINESS。
高光反射与光泽度:左侧为使用高光反射与光泽度流程模型的渲染效果;右上为diffuse贴图(baseColorMap);右下为specularGlossiness贴图,其中rgb部分为高光反射,a部分为光泽度。

standard 参数定义
- 基础色相关 basecolor
- 金属度粗糙度相关 metallic rougness ior
- 法线相关 normal
- 自发光相关 emissive
- 环境光遮蔽相关 ambient occlusion
- 透明剔除相关 alphacutoff
- 清漆效果相关 clearcoat
- 高光反射与光泽度相关 specular glossiness
- 透射 transmission (TODO)
- 体积渲染 volume (TODO)
standard 宏定义
| 宏 | 说明 | 类型 |
|---|---|---|
| WX_MANUAL_LINEAR_BASECOLORFACTOR | 基础色因子是否使用 Linear空间 | bool |
| WX_USE_BASECOLORMAP | 是否使用基础色贴图,使用u_baseColorMap后会自动设为true | bool |
| WX_USE_METALROUGHNESSMAP | 是否使用金属粗糙度贴图,使用u_metallicRoughnessMap后会自动设为true | bool |
| WX_USE_EMISSIVEMAP | 是否使用自发光贴图,使用u_emissiveMap后会自动设为true | bool |
| WX_USE_OCCLUSIONMAP | 是否使用遮挡贴图,使用u_occlusionMap后会自动设为true | bool |
| WX_USE_COLOR_0 | 是否使用第一位顶点色 | bool |
| WX_USE_ALPHA_CUTOFF | 是否使用透明剔除 | bool |
| WX_USE_CLEARCOAT | 是否使用清漆效果 | bool |
| WX_USE_SPECULARGLOSSINESS | 是否使用高光反射与光泽度渲染流程 | bool |
| WX_USE_SPECULARGLOSSINESSMAP | 是否使用高光反射与光泽度渲染贴图,使用u_specularGlossinessMap后会自动设为true | bool |
standard 默认渲染状态
"renderStates": {
cullOn: true,
blendOn: false,
depthWrite: true,
cullFace: Kanata.ECullMode.BACK
}
具体渲染状态细节可以参考 材质支持渲染状态列表。
使用glTF渲染
参照 glTF 文档使用。
使用Mesh渲染
<xr-assets>
<!-- 加载外部环境配置 -->
<xr-asset-load type="env-data" asset-id="env1" src="/assets/env-hdr/data.bin" />
<!-- 加载外部贴图 -->
<xr-asset-load type="texture" asset-id="gold-albedo" src="/assets/material/gold/albedo.png" />
<xr-asset-load type="texture" asset-id="gold-metallic" src="/assets/material/gold/metallic.png" />
<xr-asset-load type="texture" asset-id="gold-roughness" src="/assets/material/gold/roughness.png" />
<xr-asset-load type="texture" asset-id="gold-ao" src="/assets/material/gold/ao.png" />
<!-- 加载standard材质 -->
<xr-asset-material asset-id="standard-mat" effect="standard" />
</xr-assets>
<!--
设置环境数据,配置对应的IBL(漫反射与镜面反射)
使用外部配置
env1
使用内置配置
xr-frame-team-workspace-day
xr-frame-team-workspace-day2
xr-frame-team-workspace-night
-->
<xr-env env-data="env1"/>
<!--
添加 圆体
使用 standard-mat 材质
设置 金属度因子为1,粗糙度因子为1
设置 不同类型的贴图
设置 渲染状态 cullOn 为 false
...
-->
<xr-mesh
node-id="mesh-sphere" geometry="sphere"
material="standard-mat"
uniforms="
u_metallicRoughnessValues: 1 1,
u_baseColorMap: gold-albedo,
u_metallicMap: gold-metallic,
u_roughnessMap: gold-roughness
"
states="cullOn: false"
></xr-mesh>
glTF Resource from SketchFab by @re1monsen @theblueturtle_ @Bastien Genbrugge @Willy Decarpentrie @Martin Trafas
Simple 无光照渲染
Simple 材质基于最基本的 无光照 情况进行实现。
使用该材质渲染的物体,不受任何光源影响,渲染性能最高。

simple 参数定义
| 名称 | 类型 | 备注 | 默认值 |
|---|---|---|---|
| u_baseColorMap | texture | 颜色贴图,颜色空间为 SRGB | 默认未使用 |
| u_baseColorFactor | vec4 | 颜色因子,颜色空间为 SRGB | 1, 1, 1, 1 |
simple 宏定义
| 宏 | 说明 | 类型 |
|---|---|---|
| WX_USE_BASECOLORMAP | 是否使用基础色贴图,使用u_baseColorMap后会自动设为true | bool |
使用glTF渲染
参照 glTF 文档使用 Unlit 材质资源即可。
使用Mesh渲染
<!-- 加载simple材质 -->
<xr-asset-material asset-id="simple-mat" effect="simple" />
<!--
添加 圆体
默认使用 simple 材质
设置 颜色因子为 红色
-->
<xr-mesh
node-id="mesh-sphere" geometry="sphere"
material="simple-mat"
uniforms="
u_baseColorFactor: 1 0 0 1
"
></xr-mesh>
内置效果和定义
框架内置了一些效果资源。
内置效果
目前除去内部效果之外,暴露给开发者会使用的效果有两个:
- 简单无光照效果 simple
- 标准物理渲染效果 standard
在内置的之外,开发者还可能会自定义效果,这里就可能会用到一些内置的uniforms、宏和着色器方法,我们将其列举如下:
内置Uniforms和宏
框架内置了一些uniforms和宏,便于开发者使用,它们分为以下几个大类:
基础
| 类型 | 宏 | 说明 |
|---|---|---|
| 是否为蒙皮网格 | WX_SKINNED | 布尔值 |
| 骨骼数量 | WX_BONE_NUM | 整数 |
| 是否使用骨骼数据纹理 | WX_USE_BONE_MATRIX_TEXTURE | 布尔值 |
| 类型 | uniforms | 说明 |
|---|---|---|
| 视图矩阵 | u_view | 4×4矩阵 |
| 投影矩阵 | u_projection | 4×4矩阵 |
| 世界矩阵 | u_world | 4×4矩阵 |
| 视图投影矩阵 | u_vp | 4×4矩阵 |
| 视图逆矩阵 | u_viewInverse | 4×4矩阵 |
| 游戏时间戳 | u_gameTime | 浮点数 |
| 骨骼偏移矩阵 | u_boneOffsetMatrix | 4×4矩阵数组(大小由宏决定) |
| 骨骼矩阵太大时,转换为的贴图 | u_boneMatrixTexture | 2D纹理 |
图元数据相关
图元数据相关的主要是创建几何数据时定义的那些attributes,由usage决定,每中usage对应唯一的宏,比如:
xrFrameSystem.EVertexLayoutUsage.NORMAL对应于WX_USE_NORMAL。
后处理相关
主要是要注意开了后处理时,前置的渲染流程需要保证输出是线性的,可能要视情况removeGamma:
vec3 removeGammaCorrection(vec3 color) {
return pow(color, vec3(2.2));
}
| 类型 | 宏 | 说明 |
|---|---|---|
| 是否开启了后处理 | WX_PP_ACTIVE | 布尔值 |
光照和阴影相关
可见灯光相关部分。
环境相关
可见环境相关部分。
内置着色器方法
@todo
内置纹理资源
微信小程序框架内置了一些纹理资源。
普通纹理
| 资源id | 描述 |
|---|---|
| white | 白色 |
| transparent | 白色透明 |
| black | 黑色 |
| red | 红色 |
| green | 绿色 |
| blue | 蓝色 |
| yellow | 黄色 |
| babyblue | 淡蓝色 |
| babygreen | 淡绿色 |
| babyred | 淡红色 |
| brdf-lut | ![]() |
| uv-debug | ![]() |
立方体纹理
| 资源id | 描述 |
|---|---|
| white | 白色 |
| transparent | 白色透明 |
| black | 黑色 |
| red | 红色 |
| green | 绿色 |
| blue | 蓝色 |
| yellow | 黄色 |
| babyblue | 淡蓝色 |
| babygreen | 淡绿色 |
| babyred | 淡红色 |
内置几何数据
我们提供了几个内置的几何数据,均拥有UV、法线和切线:
| 资源id | 描述 | 尺寸 |
|---|---|---|
| cube | 立方体 | 原点在中心,大小为1x1x1 |
| sphere | 球体 | 原点在中心,半径为1 |
| plane | 平面 | 原点在中心,一个xz平面,大小为1×1 |
| cylinder | 圆柱 | 原点在中心,半径为1,高度为2 |
内置 Geometry 使用缩放为1的 xr-mesh 的渲染效果

<!-- wxml 代码示例 -->
<!-- plane -->
<xr-mesh node-id="mesh-plane" position="1 0 1" rotation="0 0 0" scale="1 1 1" geometry="plane" uniforms="u_baseColorFactor:0.6 0.8 0.6 1"></xr-mesh>
<!-- cube -->
<xr-mesh node-id="mesh-cube" position="1 0 -1" scale="1 1 1" rotation="0 0 0" geometry="cube" uniforms="u_baseColorFactor:0.298 0.764 0.85 1, u_metallicRoughnessValues: 0.0 0.0"></xr-mesh>
<!-- sphere -->
<xr-mesh node-id="mesh-sphere" position="-1 0 -1" scale="1 1 1" geometry="sphere" uniforms="u_metallicRoughnessValues: 0 0"></xr-mesh>
<!-- cylinder -->
<xr-mesh node-id="mesh-cylinder" position="-1 0 1" scale="1 1 1" geometry="cylinder" uniforms="u_baseColorFactor:1 0.776 0.364 1, u_metallicRoughnessValues: 0.0 0.0"></xr-mesh>
内置环境数据
微信小程序框架内置了一些环境数据资源。
| 资源id | 描述 | 预览 |
|---|---|---|
| xr-frame-team-workspace-day | xr-frame团队工作地,白天 | ![]() |
| xr-frame-team-workspace-night | xr-frame团队工作地,夜晚 | ![]() |
| xr-frame-team-workspace-day2 | xr-frame团队工作地2,白天 | ![]() |
| gz-haixinsha | 广州海心沙,下午 | ![]() |





