场景

yisky大约 5 分钟基础知识文档场景

Scene 作为场景单元，负责组织管理实体树，SceneRenderer 场景渲染器，负责场景的具体渲染。

我们可以同时激活一个或多个场景，也可以通过控制逻辑动态切换激活的场景。不同场景的实体、组件之间是相互隔离，互不影响。

创建场景

创建场景

import { Scene } from '@fantasy3d/core';

// 创建场景
const scene = new Scene( engine );

提示

Scene 初始化参数详见 SceneOptions。

设置场景渲染器

import { SceneRenderer } from '@fantasy3d/core';

// 创建场景渲染器
const sceneRenderer = new SceneRenderer( engine );

// 为场景设置渲染器
scene.sceneRenderer = sceneRenderer;

重要

场景渲染器可以被多个场景共用，不要重复创建相同类型场景渲染器！除非不同场景使用不同类型渲染器。

import { SceneRenderer } from '@fantasy3d/core';
import { EffectRenderer } from '@fantasy3d/postprocessing';

// 创建默认场景渲染器
const sceneRenderer = new SceneRenderer( engine );
// 创建后处理场景渲染器
const effectRenderer = new EffectRenderer( engine );

// Scene1和Scene2使用相同的场景渲染器
scene1.sceneRenderer = sceneRenderer;
scene2.sceneRenderer = sceneRenderer;

// Scene3使用后处理场景渲染器
scene3.sceneRenderer = effectRenderer;

提示

Fantasy 3D 目前提供 SceneRenderer 和 EffectRenderer 两种类型场景渲染器。此外，我们也可以根据实际需求开发定制场景渲染器。

创建相机

import { Vector3, Vector4 } from 'three';

// 创建一个透视相机
const camera = scene.createPerspectiveCamera( {

  // 相机实体方位属性
  transform: {

    position: new Vector3( 0.0, 5.0, 5.0 ),
    lookAt: new Vector3( 0.0, 0.0, 0.0 )

  },

  // 相机属性
  camera: { 
    
    near: 0.1,                          // 近裁剪面距离
    far: 1000.0,                        // 远裁剪面距离
    viewport: new Vector3( 0, 0, 1, 1 ) // 相机单位化渲染视口范围，xy视口左上角坐标，zw视口宽高，且所有值均在[ 0~1 ]区间内
  
  }

} );

提示

一个场景可以拥有多个激活相机，可以通过 "viewport" 参数设置相机的渲染视口。

激活场景

// 激活场景
scene.isActive = true;

重要

一个场景只有被激活且至少存在一个激活相机才会被渲染！

场景属性

isActive - 场景是否激活，读写属性。
native - 获取 three.js 原生场景对象（Scene），只读属性。
rootEntity - 获取场景根实体，只读属性。

提示

场景创建时会自动创建根实体，之后可以使用根实体为场景添加其它实体。

import { Vector3 } from 'three';

// 获取场景根实体
const { rootEntity } = scene;

// 创建一个新实体
const entity = rootEntity.createChild( { transform: { position: new Vector3( 10.0, 0.0, 35.0 ) } } );

activeCameras - 获取场景激活的相机，只读属性。
background - 获取场景背景，只读属性。

提示

有关场景背景详细说明，详见场景背景。

environment - 获取场景环境，只读属性。

提示

有关场景环境详细说明，详见场景环境。

场景方法

createOrthographicCamera - 创建正交相机。

import { Vector3 } from 'three';

// 创建正交相机
const camera = scene.createOrthographicCamera( {

  transform: { position: new Vector3( 0.0, 10.0, 40.0 ) },
  camera: {

    near: 10.0,
    far: 150.0,
    frustum: 50.0

  }

} );

createPerspectiveCamera - 创建透视相机。

import { Vector3 } from 'three';

// 创建投射相机
const camera = scene.createPerspectiveCamera( {

  transform: {

    position: new Vector3( 0.0, 5.0, 5.0 ),
    lookAt: new Vector3( 0.0, 0.0, 0.0 )

  }

  camera: {

    near: 0.1,
    far: 500.0

  }

} );

setBackground - 设置场景背景。

设置纯色背景

import { BackgroundMode } from '@fantasy3d/core';

scene.setBackground( BackgroundMode.SolidColor, '#223344' );

设置纹理背景

import { BackgroundMode } from '@fantasy3d/core';

const textureOptions = {

  texture: './assets/textures/background.jpg',
  blurriness: 0.0,
  intensity: 1.0

}

scene.setBackground( BackgroundMode.Texture, textureOptions );

设置动态天空背景

import { BackgroundMode, SunMode } from '@fantasy3d/core';

const skyOptions = {

  sunMode: SunMode.HighQuality,
  sunSize: 0.04,
  sunSizeConvergence: 5.0,
  atmosphereThickness: 1.0,
  skyTint: '#bcbcbc',
  groundTint: '#a8a8a8',
  exposure: 1.3,
  sunLightColor: 'white',

}

scene.setBackground( BackgroundMode.Sky, skyOptions );

禁用场景背景

import { BackgroundMode } from '@fantasy3d/core';

// 禁用场景背景，使用渲染视口的背景
scene.setBackground( BackgroundMode.None );

提示

有关场景背景详细说明，详见场景背景。

render - 渲染场景。
dipose - 释放场景。

场景事件

on - 订阅事件。

import { EventType } from '@fantasy3d/core';

// 订阅“场景开始渲染”事件
scene.on( EventType.Before_Scene_Render, () => {

  // TODO:事件响应

} );

once - 订阅事件且仅响应一次。

import { EventType } from '@fantasy3d/core';

// 订阅一次“场景开始渲染”事件
scene.once( EventType.Before_Scene_Render, () => {

  // TODO:事件响应

} );

off - 取消事件订阅。

import { EventType } from '@fantasy3d/core';

// “场景开始渲染”事件订阅回调
const callback = () => {};

// 订阅“场景开始渲染”事件
scene.on( EventType.Before_Scene_Render, callback, { target: this } );

// 取消订阅“场景开始渲染”事件
scene.off( EventType.Before_Scene_Render, callback );

重要

“取消订阅”时如果不指定第二个参数，会取消该类型事件的所有订阅！

// 取消“场景开始渲染”事件的所有订阅
scene.off( EventType.Before_Scene_Render );

emit - 分发事件。

import { EventType } from '@fantasy3d/core';

// 分发“场景开始渲染”事件
scene.emit( { type: EventType.Before_Scene_Render } );

提示

通过Scene可订阅的内置事件类型及分发时机：

事件类型	事件说明
Before_Scene_Render	场景渲染之前分发，逐场景分发
Before_Camera_Frame_Capture	抓取相机帧缓冲区之前分发，逐相机分发
After_Camera_Frame_Capture	抓取相机帧缓冲区之后分发，逐相机分发
Before_Camera_Render	相机渲染之前分发，逐相机分发
After_Camera_Render	相机渲染之后分发，逐相机分发
After_Scene_Render	场景渲染之后分发，逐场景分发
Camera_Frustum_Changed	渲染相机视口发生改变时分发，逐相机分发
Camera_Changed	渲染相机位置、朝向、远近裁剪面等属性改变时分发，逐相机分发

场景

# 创建场景

# 场景属性

# 场景方法

# 场景事件

创建场景

场景属性

场景方法

场景事件