如何开发一个渲染组件

Renderable是引擎提供的渲染组件基类，这个类是一个抽象类，子类必须重载所有抽象方法（public和proteced），对于非抽象方法（public和protected）子类可以根据需求选择重载。

🌏 必须重载的方法

名称	类型	描述
raycast	public	射线拾取接口
_destroy	protected	销毁接口

🌏 可选择重载的方法

名称	类型	描述
setHighlight	public	设置是否高亮
setStencil	public	设置模板参数
_updateMatrixWorld	protected	更新渲染组件世界矩阵
_updateBounds	protected	更新渲染组件外包盒

此外，Renderable的 _object3D（protected）属性为渲染组件的根结点，渲染对象需要赋值给 _object3D 或挂接到 _object3D 下面。

赋值'_object3D'

import { Mesh } from 'three';

// 赋值'_object3D'
this._object3D = new Mesh( geometry, material );

挂接到'_object3D'下面

import { Group, Mesh } from 'three';

// 创建'Group'
this._object3D = new Group();

// 创建Mesh0
const mesh0 = new Mesh( geometry0, material0 );

// 创建Mesh1
const mesh1 = new Mesh( geometry1, material1 );

// 创建Mesh2
const mesh2 = new Mesh( geometry2, material2 );

// 将所有Mesh挂接到'_object3D'下面
this._object3D.add( mesh0 );
this._object3D.add( mesh1 );
this._object3D.add( mesh2 );

在扩展渲染组件时，我们通常需要做以下几步操作：

1️⃣ 构建渲染对象；

2️⃣ 将渲染对象赋值给'_object3D'或挂接到'_object3D'上；

3️⃣ 将'_object3D'添加到渲染场景中；

4️⃣ 更新渲染组件世界矩阵；

5️⃣ 更新渲染组件外包盒。

监听update、onCameraChanged、onResize事件

在某些情况下我们需要在渲染组件中监听 update（帧更新） 、 onCameraChanged（相机改变） 、 onResize（渲染视口尺寸改变） 事件，我们可以通过以下方式实现：

1️⃣ 首先，在渲染组件中定义事件回调函数

/**
 * 帧更新回调
 * 
 * @param {number} timeSinceLastFrame 距离上一帧更新的时长 （单位：毫秒）
 * @param {number} totalTime 总时长 (单位：毫秒)
 */ 
update( timeSinceLastFrame, totalTime ) {

    // TODO:帧更新响应

}

/**
 * 相机改变回调
 * 
 * @param {*} event 相机改变事件
 */ 
onCameraChanged( event ) {

    // TODO:相机改变事件响应

}

/**
 * 渲染窗口尺寸改变回调
 * 
 * @param {*} event 渲染窗口尺寸改变事件
 */ 
onResize( event ) {

    // TODO:渲染窗口尺寸改变事件响应

}

2️⃣ 其次，重载 _onEnable 和 _onDisable 方法，实现事件回调方法的添加和移除

/**
 * 重载_onEnable
 * 
 * @protected
 */ 
_onEnable() {

    // 调用基类方法
    super._onEnable();

    // 添加事件监听
    this.engine.componentManager.addUpdate( this );
    this.engine.componentManager.addOnCameraChanged( this );
    this.engine.componentManager.addOnResize( this );

}

/**
 * 重载_onDisable
 * 
 * @protected
 */
_onDisable() {

    // 调用基类方法
    super._onDisable();

    // 移除事件监听
    this.engine.componentManager.removeUpdate( this );
    this.engine.componentManager.removeOnCameraChanged( this );
    this.engine.componentManager.removeOnResize( this );    

}

提示

也可以通过脚本组件实现事件监听响应，详见教程"如何开发一个脚本组件"

下面的代码展示了如何扩展一个渲染组件并使用。首先，我们定义一个“地面”渲染组件类：

import { BufferGeometry, Color, Float32BufferAttribute, Mesh, MeshBasicMaterial, Vector3 } from 'three';
import { 
    
    AssetsManager, 
    Renderable, 
    applyColorCorrection, 
    defaultValue, 
    defined,
    extendQueryMask
    
} from '@tx3d/core'; 

/**
 * 地面渲染组件类
 */ 
class Groud extends Renderable {

    constructor( entity, parameters = {} ) {

        super( entity, parameters );

        // 渲染地面
        this._render( parameters );

    }

    // public functions

    /**
     * 设置地面颜色
     */
    set color( value ) {

        this._object3D.material.color.set( value );

    }

    /**
     * 射线查询
     */
    raycast( raycaster ) {

        // 判断是否可见
        if ( !this._object3D.visible ) {

            return null;

        }

        // 判断是否与外包盒相交
        if ( !raycaster.ray.intersectBox( this._bounds, new Vector3() ) ) {

            return null;

        }

        // Mesh相交判断
        const intersections = [];

        this._object3D.raycast( raycaster, intersections );

        // 判断是否拾取到
        if ( intersections.length > 0 ) {

            // 对结果进行排序
            intersections.sort( ( a, b ) =>  {

                return a.distance - b.distance;

            } );

            // 返回拾取结果
            return intersections[ 0 ];

        }

        return null;

    }

    /**
     * 帧更新回调
     * 
     * @param {number} timeSinceLastFrame 距离上一帧更新的时长 （单位：毫秒）
     * @param {number} totalTime 总时长 (单位：毫秒)
     */ 
    update( timeSinceLastFrame, totalTime ) {

        // TODO:帧更新响应

    }

    /**
     * 相机改变回调
     * 
     * @param {*} event 相机改变事件
     */ 
    onCameraChanged( event ) {

        // TODO:相机改变事件响应

    }

    /**
     * 渲染窗口尺寸改变回调
     * 
     * @param {*} event 渲染窗口尺寸改变事件
     */ 
    onResize( event ) {

        // TODO:渲染窗口尺寸改变事件响应

    }    

    // private functions

    /**
     * 渲染地面
     * 
     * @private
     */
    _render( parameters ) {

        // 设置查询遮罩值
        this.queryMask = defaultValue( parameters.queryMask, extendQueryMask( 'Ground') );

        // 准备Geometry数据
        const geometry = this._prepareGeometry( parameters );

        // 准备Material数据
        const material = this._prepareMaterial( parameters );

        // 创建Mesh并赋值给'_object3D'
        this._object3D = new Mesh( geometry, material );
        this._object3D.name = 'Ground'; // 设置名称（自定义动画时会用到）
        this._object3D.renderOrder = this._renderOrder; // 设置渲染顺序，必不可少

        // 添加到渲染场景
        this.entity.transform.addObject3D( this._object3D );

        // 更新世界矩阵
        this._updateMatrixWorld();

        // 更新世界外包盒
        this._updateBounds();

    }

    /**
     * 准备Geometry数据
     * 
     * @private
     */ 
    _prepareGeometry( parameters ) {

        // 地面长度
        const length = defaultValue( parameters.length, 1024 );

        // 地面宽度
        const width = defaultValue( parameters.width, 1024 );

        // 顶点位置数组
        const positions = [

            -0.5 * width, 0.0, -0.5 * length,
            0.5 * width, 0.0, -0.5 * length,
            0.5 * width, 0.0, 0.5 * length,
            -0.5 * width, 0.0, 0.5 * length

        ];

        // 顶点纹理坐标数组
        const uvs = [
           
            0.0, 1.0,
            1.0, 1.0,
            1.0, 0.0,
            0.0, 0.0           
           
        ];

        // 索引数组
        const indices = [ 0, 2, 1, 0, 3, 2 ];

        // 构建Geometry
        const geometry = new BufferGeometry();
        geometry.setAttribute( 'position', new Float32BufferAttribute( positions, 3 ) );
        geometry.setAttribute( 'uv', new Float32BufferAttribute( uvs, 2 ) );
        geometry.setIndex( indices );
        
        return geometry;

    }

    /**
     * 准备Material
     * 
     * @private
     */ 
    _prepareMaterial( parameters ) {

        // 创建材质
        const material = new MeshBasicMaterial( { color: new Color( defaultValue( parameters.color, '#ffffff' ) ) } );

        // 设置纹理
        if ( defined( parameters.map ) ) {

            AssetsManager.loadTextureAsset( parameters.map ).then( ( textureAsset ) => {

                // 校正纹理
                applyColorCorrection( textureAsset.texture );

                // 更新材质纹理
                material.map = textureAsset.texture;

                // 标识材质需要更新
                material.needsUpdate = true;

                // 记录纹理资源（用于释放）
                material.userData.textureAsset = textureAsset;

            } );

        }

        return material;

    }

    // protected functions

    /**
     * 重载_onEnable
     * 
     * @protected
     */ 
    _onEnable() {

        // 调用基类方法
        super._onEnable();

        // 添加事件监听
        this.engine.componentManager.addUpdate( this );
        this.engine.componentManager.addOnCameraChanged( this );
        this.engine.componentManager.addOnResize( this );

    }

    /**
     * 重载_onDisable
     * 
     * @protected
     */
    _onDisable() {

        // 调用基类方法
        super._onDisable();

        // 移除事件监听
        this.engine.componentManager.removeUpdate( this );
        this.engine.componentManager.removeOnCameraChanged( this );
        this.engine.componentManager.removeOnResize( this );    

    }    

    /**
     * 销毁渲染组件
     * 
     * @protected
     */
    _destroy() {

        // 释放Geometry
        this._object3D.geometry.dispose();

        // 释放纹理资源
        if ( defined( this._object3D.material.userData.textureAsset ) ) {

            this._object3D.material.userData.textureAsset.dispose();

        }

        // 释放材质
        this._object3D.material.dispose();

    }

}

然后，在场景中使用扩展的“地面”渲染组件，渲染一个地面：

// 首先创建一个空实体
const entity = engine.createEntity();

// 接下来添加“地面”渲染组件
const ground = entity.addComponent( Ground, {

    length: 2048,                       // 地面长度
    width: 2048,                        // 地面宽度
    map: 'assets/textures/floor.jpg'    // 地面纹理

} );