渲染组件
大约 5 分钟基础知识文档组件渲染组件
渲染组件用于数据渲染，它会依据不同的数据源显示相对应的渲染效果，例如，MeshRenderer、ModelRenderer等。在 Fantasy 3D 中所有渲染组件都必须继承自 Renderer。
渲染组件属性
提示
查询遮罩值（QueryMask）用于拾取查询过滤。
userData - 组件用户数据，读写属性。
position - 组件本地位置，读写属性。
scale - 组件本地缩放，读写属性。
rotation - 组件本地旋转量，读写属性。
quaternion - 组件本地旋转四元数，读写属性。
worldBounds - 组件世界外包范围，只读属性。
visible - 设置组件是否可见，只写属性。
renderOrder - 组件渲染顺序，读写属性。
提示
renderOrder 用于控制组件渲染顺序，值越小越靠前渲染，默认值为 Default。
// 通过 RenderOrder 枚举设置
renderer.renderOrder = RenderOrder.Default + 1;
// 使用数值设置
renderer.renderOrder = 51;
渲染组件方法
- getWorldPosition - 获取组件世界位置。
import { Vector3 } from 'three';
const worldPosition = renderer.getWorldPosition( new Vector3() );
- getWorldScale - 获取组件世界缩放。
import { Vector3 } from 'three';
const worldScale = renderer.getWorldScale( new Vector3() );
- getWorldDirection - 获取组件世界朝向。
import { Vector3 } from 'three';
const worldDirection = renderer.getWorldDirection( new Vector3() );
- getWorldQuaternion - 获取组件世界旋转四元数。
import { Quaternion } from 'three';
const worldQuaternion = renderer.getWorldQuaternion( new Quaternion() );
- setTransformation - 设置组件本地方位信息。
import { Euler, Vector3 } from 'three';
renderer.setTransformation( {
position: new Vector3( 0.0, 0.0, 20.0 ), // 本地位置
scale: new Vector3( 2.0, 2.0, 2.0 ), // 本地缩放
rotation: new Euler( 0.0, Math.PI * 0.5, 0.0 ) // 本地旋转
} );
- lookAt - 旋转组件使其朝向世界空间中的目标点。
import { Vector3 } from 'three';
renderer.lookAt( new Vector3( 0.0, 5.0, -3.0 ) );
- localToWorld - 将组件本地空间中的坐标转换到世界空间中。
import { Vector3 } from 'three';
const local = new Vector3( 0.0, 5.0, 3.0 );
const world = renderer.localToWorld( local );
- worldToLocal - 将组件世界空间中的坐标转换到本地空间中。
import { Vector3 } from 'three';
const world = new Vector3( 0.0, 5.0, 3.0 );
const local = renderer.worldToLocal( world );
- updateWorldMatrix - 手动更新组件世界矩阵。
提示
通常情况下我们不需要手动更新组件的世界矩阵，但当我们通过 three.js 原生 Object3D 对象更新方位属性时，更新后需要手动更新组件的世界矩阵。
// 获取组件 three.js 原生 Object3D 对象
const { object3D } = renderer;
// 通过原生 Object3D 对象更新方位信息
object3D.position.x += 10.0; // 沿X轴正向移动
object3D.rotation.y += 0.01; // 绕Y轴旋转
// 手动更新组件世界矩阵
renderer.updateWorldMatrix();
- update - 帧更新接口，逐帧调用。
提示
Renderer 中的 update 是一个空方法，子类需根据实际情况重载该方法。
- beforeCameraRender - 相机渲染前回调，逐相机调用。
提示
Renderer 中的 beforeCameraRender 是一个空方法，子类需根据实际情况重载该方法。
- afterCameraRender - 相机渲染后回调，逐相机调用。
提示
Renderer 中的 afterCameraRender 是一个空方法，子类需根据实际情况重载该方法。
- raycast - 射线查询。
重要
Renderer 中的 raycast 是一个抽象方法，子类必须重载实现！
- _destroy - 组件销毁接口，protected方法。
重要
- Renderer 中的 _destroy 是一个抽象方法，子类必须重载实现！
- _destroy 主要用于销毁渲染相关的Mesh、材质、纹理等资源。
渲染组件事件
重要
“取消订阅”时如果不指定第二个参数，会取消该类型事件的所有订阅！
- emit - 分发事件。
扩展渲染组件
Fantasy 3D允许开发人员扩展渲染组件以丰富实体渲染效果。在扩展渲染组件时需要注意以下几点：
// 赋值
this._object3D = new Mesh( geometry, material );
// 挂接
this._object3D = new Group();
this._object3D.add( new Mesh( geometry, material ) );
- 需要将 Renderer 的 _renderOrder 赋值给渲染对象。
// 新建Mesh
const mesh = new Mesh( geometry, material );
// 设置RenderOrder
mesh.renderOrder = this._renderOrder;
// 赋值
this._object3D = mesh;
提示
渲染组件完整扩展示例:
import { BoxGeometry, Intersection, Mesh, MeshLambertMaterial, Raycaster } from 'three';
import { Entity, Renderer, defined } from '@fantasy3d/core';
class CubeRenderer extends Renderer {
constructor( entity: Entity, parameters: any = {} ) {
super( entity, parameters );
// 初始化组件
this._initialize( parameters );
}
// public functions
/**
* 射线查询（必须重载）
*/
raycast( raycaster: Raycaster ): Intersection {
const { _object3D: object3D } = this;
if ( !defined( object3D ) || !object3D.visible ) {
return null;
}
const intersections = [];
object3D.raycast( raycaster, intersections );
if ( intersections.length > 0 ) {
intersections.sort( ( a, b ) => {
return a.distance - b.distance;
} );
return intersections[ 0 ];
}
return null;
}
// private functions
/**
* 初始化接口
*/
private _initialize( parameters: any ): void {
const { size = 1.0, color = '#ff0000' } = parameters;
// 创建Geometry
const geometry = new BoxGeometry( size, size, size );
// 创建材质
const material = new MeshLambertMaterial( { color } );
// 创建Mesh并赋值给"_object3D"
this._object3D = new Mesh( geometry, material );
// 设置RenderOrder
this._object3D.renderOrder = this._renderOrder;
}
// protected functions
/**
* 销毁接口（必须重载）
*/
protected _destroy(): void {
const { _object3D: object3D } = this;
const { geometry, material } = object3D as Mesh;
// 释放Geometry资源
geometry.dispose();
// 释放Material资源
material.dispose();
}
}