真机调试

要使用真机调试来调试XR-FRAME,需要按照以下几个步骤:

  1. 确保工具是最新的Nightly版本。
  2. 确定至少存在一个分包空分包也可以
  3. 在真机调试界面,左下角切换到真机调试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

快速抗锯齿。

示例:

Standard 标准物理光照渲染

Standard 材质基于标准的 PBR 进行实现。

PBR(Physically Based Rendering) 是指使用基于物理原理和微平面理论建模的着色/光照模型,以及使用从现实中测量的表面参数来准确表示真实世界材质的渲染理念。

end

使用 PBR 的优势

  • 基于物理模型与数学推演带来的效果的 真实
  • 艺术导向性的、标准化的美术参数带来的 易用效果一致

xr-frame 使用 PBR 有以下两种方式

  1. 使用带光照材质的 glTF 资源,目前主流的各类 DCC工具 (Digital Content Create) 都可以产出这种业界通用的格式。
  2. 使用内置的 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);

基础色贴图:左侧为只有基础色效果;右侧为基础色贴图 baseColor

金属度粗糙度 (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 部分为金属度。 metallic

法线 (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 );

法线:左侧图片为世界空间中法线效果,右侧为法线贴图。 normal

自发光 (Emissive)

uniforms 类型 备注 默认值
u_emissiveMap texture 自发光贴图,颜色空间为 SRGB 默认未使用
u_emissiveFactor vec3 自发光贴图因子,颜色空间为 LINEAR 0, 0, 0

自发光 表示了材质作为光源向外发送的颜色信息,颜色空间为 SRGB

vec4 emissiveColor = u_emissiveFactor;
// 若设定自发光贴图
vec4 emissiveColor *= SRGBtoLINEAR(u_emissiveMap);

自发光:左侧图片为只有自发光的效果,右侧图片为自发光贴图。 emissive

环境光遮蔽 (Ambient occlusion)

uniforms 类型 备注 默认值
u_occlusionMap texture 环境光遮蔽贴图 默认未使用
u_occlusionStrength float 环境光遮蔽贴图强度,需使用遮蔽贴图才生效 1

环境光遮蔽 指表面某点能获得多少环境中的光。该贴图只影响漫反射分配,不影响高光反射分配。

// 若设定遮蔽贴图
float ao = u_occlusionMap;
// 若设定遮蔽贴图 与 遮蔽因子
ao *= u_occlusionStrength;

环境光遮蔽:左侧图片为默认PBR渲染效果,右侧图片为环境光遮挡显示效果,0为完全遮蔽,1为完全不遮蔽。 ao

透明剔除 (alphaCutoff)

uniforms 类型 备注 默认值
u_alphaCutoff float 透明剔除阈值,当 baseColor 的 alpha 小于 u_alphaCutoff 时,不进行绘制,alphaModeMASK 的情况下才生效 0.5

透明剔除 用于进行透明度剔除。当alphaModeMASK 的情况下,会不渲染 baseColor 的 alpha 小于 u_alphaCutoff 的像素。

如需使用透明剔除,需手动设置宏 WX_USE_ALPHA_CUTOFF或设置渲染状态使用。

透明剔除:左侧图片为开启alphaCutoff效果,右侧图片为未使用alphaCutoff效果。 alphacutoff

清漆效果 (clearcoat)

uniforms 类型 备注 默认值
u_clearcoatFactor float 清漆强度 0
u_clearcoatRoughnessFactor float 清漆粗糙度 0

清漆效果 可以认为是往物体表面添加透明涂层。

如需使用清漆效果,需手动设置宏 WX_USE_CLEARCOAT

清漆强度:左侧图片为使用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部分为光泽度。 specularGlossiness

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

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>

内置效果和定义

框架内置了一些效果资源。

内置效果

目前除去内部效果之外,暴露给开发者会使用的效果有两个:

  1. 简单无光照效果 simple
  2. 标准物理渲染效果 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 的渲染效果

geometry

<!-- 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 广州海心沙,下午