TX3D ENGINE

# Light组件

# 环境光

环境光（AmbientLight）会均匀的照亮场景中的所有物体。环境光不能用来投射阴影，因为它没有方向。

import { AmbientLight, Entity } from '@tx3d/core';

// 创建实体
const entity = engine.createEntity( { name: '环境光' } );

// 添加环境光组件
const ambientLight = entity.addComponent( AmbientLight, { 
    
    color: '#ffffff', // 颜色
    intensity: 0.25   // 强度
    
} );
1
2
3
4
5
6
7
8
9
10
11
12

提示

环境光组件初始化参数，详见“AmbientLightParameters”。

# 属性

🌏 color 颜色

// 获取颜色
const color = ambientLight.color;

// 设置环境光颜色
ambientLight.color = '#ff00aa';
1
2
3
4
5

🌏 intensity 强度

// 获取强度
const intensity = ambientLight.intensity;

// 设置环境光强度
ambientLight.intensity = 0.5;
1
2
3
4
5

# 半球光

半球光（HemisphereLight）直接放置在场景之上，光照颜色从天空光线颜色渐变到地面光线颜色。半球光不能投射阴影。

import { Entity, HemisphereLight } from '@tx3d/core';

// 创建实体
const entity = engine.createEntity( { name: '半球光' } );

// 添加半球光组件
const hemisphereLight = entity.addComponent( HemisphereLight, { 
    
    skyColor: '#ffffbb',    // 天空颜色
    groundColor: '#080820', // 地面颜色
    intensity: 0.5          // 强度 
    
} );
1
2
3
4
5
6
7
8
9
10
11
12
13

提示

半球光组件初始化参数，详见“HemisphereLightParameters”。

# 属性

🌏 skyColor 天空颜色

// 获取天空颜色
const skyColor = hemisphereLight.skyColor;

// 设置天空颜色
hemisphereLight.skyColor = '#00ffee';
1
2
3
4
5

🌏 groundColor 地面颜色

// 获取地面颜色
const groundColor = hemisphereLight.groundColor;

// 设置地面颜色
hemisphereLight.groundColor = '#aacc00';
1
2
3
4
5

🌏 intensity 强度

// 获取强度
const intensity = hemisphereLight.intensity;

// 设置强度
hemisphereLight.intensity = 0.75;
1
2
3
4
5

# 区域光

区域光（RectAreaLight）从一个矩形平面上均匀地发射光线。这种光源可以用来模拟像明亮的窗户或者条状灯光光源。区域光不能投射阴影，且只支持PBR材质。

注意

区域光默认沿着Z轴负向照射！

import { Entity, RectAreaLight } from '@tx3d/core';

// 创建实体
const entity = engine.createEntity( { name: '区域光' } );

// 添加一个区域光组件
const rectAreaLight = entity.addComponent( RectAreaLight, {

    color: '#ffffff',           // 颜色
    intensity: 0.5,             // 强度
    width: 8.0,                 // 宽度
    height: 6.0,                // 高度
    position: [ 0, 1.0, 2.0 ]   // 位置

} );
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

提示

区域光组件初始化参数，详见“RectAreaLightParameters”。

# 属性

🌏 color 颜色

// 获取颜色
const color = rectAreaLight.color;

// 设置颜色
rectAreaLight.color = '#ff00aa';
1
2
3
4
5

🌏 intensity 强度，单位：candela（坎德拉）

// 获取强度
const intensity = rectAreaLight.intensity;

// 设置强度
rectAreaLight.intensity = 0.75;
1
2
3
4
5

🌏 power 光通量，单位：lumen（流明）

// 获取光通量
const power = rectAreaLight.power;

// 设置光通量
rectAreaLight.power = 1.5;
1
2
3
4
5

🌏 watts 辐射通量，单位：watts（瓦）

// 获取辐射通量
const watts = rectAreaLight.watts;

// 设置辐射通量
rectAreaLight.watts = 20;
1
2
3
4
5

提示

辐射通量与光通量转换公式如下所示[1]：

power=watts∗683power = watts * 683

区域光光通量与强度转换公式如下所示：

power=π∗width∗height∗intensitypower = π * width * height * intensity

区域光强度与辐射通量转换公式如下所示：

intensity=watts∗683π∗width∗heightintensity = \frac{watts * 683}{π * width * height}

🌏 width 宽度

// 获取宽度
const width = rectAreaLight.width;

// 设置宽度
rectAreaLight.width = 8.0;
1
2
3
4
5

🌏 height 高度

// 获取高度
const height = rectAreaLight.height;

// 设置高度
rectAreaLight.height = 4.0;
1
2
3
4
5

🌏 poisition 位置（Local）

// 获取位置
const position = rectAreaLight.position;

// 设置位置
rectAreaLight.position = [ 0.0, 2.0, 0.0 ];
1
2
3
4
5

🌏 quaternion 旋转四元数（Local）

// 获取旋转四元数
const quaternion = rectAreaLight.quaternion;

// 设置旋转四元数
rectAreaLight.quaternion = [ 0.0, 0.0, 0.0, 1.0 ];
1
2
3
4
5

🌏 rotation 旋转量（Local）

// 获取旋转量
const rotation = rectAreaLight.rotation;

// 设置旋转量
rectAreaLight.rotation = [ 0.0, Math.PI * 0.15, 0.0 ];
1
2
3
4
5

🌏 helperVisible 辅助助手是否可见，只写。

// 显示辅助助手
rectAreaLight.helperVisible = true;
1
2

# 方向光

方向光（DirectionalLight）是从无限远沿着特定方向发射的光，方向光通常用来模拟太阳光的效果（注：由于three.js使用 “目标平行光”而非 “方向平行光”，因此创建时需要指定方向光的位置（position）和目标（target））。方向光可以投射阴影。

import { DirectionalLight, Entity } from '@tx3d/core';

// 创建实体
const entity = engine.createEntity( { name: '方向光' } );

// 添加一个方向光组件
const directionalLight = entity.addComponent( DirectionalLight, { 
    
    position: [ 100, 100, 100 ],    // 位置
    color: '#ffffff',               // 颜色 
    intensity: 1.0                  //强度 

} );
1
2
3
4
5
6
7
8
9
10
11
12
13

提示

方向光组件初始化参数，详见“DirectionalLightParameters”。

# 属性

🌏 color 颜色

// 获取颜色
const color = directionalLight.color;

// 设置颜色
directionalLight.color = '#ff00ff';
1
2
3
4
5

🌏 intensity 强度

// 获取强度
const intensity = directionalLight.intensity;

// 设置强度
directionalLight.intensity = 0.75;
1
2
3
4
5

🌏 position 位置（Local）

// 获取位置
const position = directionalLight.position;

// 设置位置
directionalLight.position = [ 0.0, 10.0, 0.0 ];
1
2
3
4
5

🌏 target 目标（Local）

// 获取目标
const target = directionalLight.target;

// 设置目标
directionalLight.target = [ 0.0, 0.0, -10.0 ];
1
2
3
4
5

🌏 helperVisible 辅助助手是否可见，只写。

// 显示辅助助手
directionalLight.helperVisible = true;
1
2

# 接口

🌏 translateTargetOnAxis 沿着本地坐标轴平移方向光目标点

// 目标点沿本地[ 1.0, 0.0, 0.0 ]平移50
directionalLight.translateTargetOnAxis( [ 1.0, 0.0, 0.0 ], 50.0 );
1
2

注意

平移坐标轴需要单位化！！！

# 点光源

点光（PointLight）是从一个点向各个方向发射的光源，常用于模拟灯光。点光源可以投射阴影。

import { Entity, PointLight } from '@tx3d/core';

// 创建实体
const entity = engine.createEntity( { name: '点光源' } );

// 添加一个点光源组件
const pointLight = entity.addComponent( PointLight, {

    color: '#eef2b0',           // 颜色
    intensity: 1.0,             // 强度   
    position: [ 0, 0.5, 0 ],    // 位置
    distance: 10,               // 光强衰减距离          
    decay: 1.0                  // 沿着光照距离的衰减量

} );
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

提示

点光源组件初始化参数，详见“PointLightParameters”。

# 属性

🌏 color 颜色

// 获取颜色
const color = pointLight.color;

// 设置颜色
pointLight.color = '#00ffaa';
1
2
3
4
5

🌏 intensity 强度，单位：candela（坎德拉）

// 获取强度
const intensity = pointLight.intensity;

// 设置强度
pointLight.intensity = 0.75;
1
2
3
4
5

🌏 power 光通量，单位：lumen（流明）

// 获取光通量
const power = pointLight.power;

// 设置光通量
pointLight.power = 1.5;
1
2
3
4
5

🌏 watts 辐射通量，单位：watts（瓦）

// 获取辐射通量
const watts = pointLight.watts;

// 设置辐射通量
pointLight.watts = 5.0;
1
2
3
4
5

提示

辐射通量与光通量转换公式如下所示[1:1]：

power=watts∗683power = watts * 683

点光源光通量与强度转换公式如下所示：

power=4∗π∗intensitypower = 4 * π * intensity

点光源强度与辐射通量转换公式如下所示：

intensity=watts∗6834∗πintensity = \frac{watts * 683}{4 * π}

🌏 position 位置（Local）

// 获取位置
const position = pointLight.position;

// 设置位置
pointLight.position = [ 0.0, 10.0, 0.0 ];
1
2
3
4
5

🌏 distance 衰减距离，当设置为0时，表示永不衰减。

// 获取衰减距离
const distance = pointLight.distance;

// 设置衰减距离
pointLight.distance = 10.0;
1
2
3
4
5

🌏 decay 沿着光照距离的衰减量，默认值为2。

// 获取衰减量
const decay = pointLight.decay;

// 设置衰减量
pointLight.decay = 2.0;
1
2
3
4
5

注意

在Physical渲染模式下，不要修改decay默认值！

🌏 helperVisible 辅助助手是否可见，只写。

// 显示辅助助手
pointLight.helperVisible = true;
1
2

# 聚光灯

聚光灯（SpotLight）的光线从一个点沿一个方向射出，随着光线照射的边远，光线圆锥体的尺寸逐渐增大。聚光灯可以投射阴影。

注意

聚光灯默认沿着Y轴负向照射！

import { Entity, SpotLight } from '@tx3d/core';

// 创建实体
const entity = engine.createEntity( { name: '聚光灯' } );

// 添加一个聚光灯组件
const spotLight = entity.addComponent( SpotLight, {

    color: '#ffe0d3',        // 灯颜色
    intensity: 1.0,          // 灯强度
    angle: Math.PI * 0.5,    // 角度（单位：弧度）
    distance: 200,           // 衰减距离
    decay: 1.0,              // 衰减，设置为1就可以了
    penumbra: 0,             // 0~1区间
    position: [ 0, 200, 0 ]  // 位置

} );
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

提示

聚光灯组件初始化参数，详见“SpotLightParameters”。

# 属性

🌏 color 颜色

// 获取颜色
const color = spotLight.color;

// 设置颜色
spotLight.color = '#ff00ff';
1
2
3
4
5

🌏 intensity 强度，单位：candela（坎德拉）

// 获取强度
const intensity = spotLight.intensity;

// 设置强度
spotLight.intensity = 1.0;
1
2
3
4
5

🌏 power 光通量，单位：lumen（流明）

// 获取光通量
const power = spotLight.power;

// 设置光通量
spotLight.power = 1.5;
1
2
3
4
5

🌏 watts 辐射通量，单位：watts（瓦）

// 获取辐射通量
const watts = spotLight.watts;

// 设置辐射通量
spotLight.watts = 5.0;
1
2
3
4
5

提示

辐射通量与光通量转换公式如下所示[1:2]：

power=watts∗683power = watts * 683

聚光灯光通量与强度转换公式如下所示：

power=π∗intensitypower = π * intensity

聚光灯强度与辐射通量转换公式如下所示：

intensity=watts∗683πintensity = \frac{watts * 683}{π}

🌏 angle 光线散射角度，单位：弧度，最大值为Math.PI * 0.5。

// 获取角度
const angle = spotLight.angle;

// 设置角度
spotLight.angle = Math.PI * 0.15;
1
2
3
4
5

🌏 distance 衰减距离，当设置为0时，表示永不衰减。

// 获取衰减距离
const distance = spotLight.distance;

// 设置衰减距离
spotLight.distance = 100.0;
1
2
3
4
5

🌏 decay 沿着光线方向的衰减量，默认值为2。

// 获取衰减量
const decay = spotLight.decay;

// 设置衰减量
spotLight.decay = 2.0;
1
2
3
4
5

注意

在Physical渲染模式下，不要修改decay默认值！

🌏 penumbra 聚光锥的半影衰减百分比。在0和1之间的值。默认为0。

// 获取衰减百分比
const penumbra = spotLight.penumbra;

// 设置衰减百分比
spotLight.penumbra = 0.5;
1
2
3
4
5

🌏 position 位置

// 获取位置
const position = spotLight.position;

// 设置位置
spotLight.position = [ 0.0, 10.0, 0.0 ];
1
2
3
4
5

🌏 target 光线照射目标

// 获取目标
const target = spotLight.target;

// 设置目标
spotLight.target = [ 0.0, -10.0, 0.0 ];
1
2
3
4
5

🌏 helperVisible 辅助助手是否可见，只写。

// 显示辅助助手
spotLight.helperVisible = true;
1
2

# 灯光模式

Tx3d Engine目前提供Legacy和Physical两种灯光模式，在引擎创建时设置灯光模式，默认使用Physical灯光模式。

import { Engine } from '@tx3d/core';

// 创建引擎
const engine = new Engine( {

    sceneRenderer: {

        // 设置灯光模式，false -> Physical模式，true -> Legacy模式，默认false。
        useLegacyLights: false

    }

} );
1
2
3
4
5
6
7
8
9
10
11
12
13
  • Legacy模式

Legacy模式下，three.js内部会使用PI对光的强度（intensity）进行缩放，即所谓的艺术家友好光强缩放因子，这样更容易实现强度在1左右得到较好的照明。然而，Legacy模式下光的强度并不具有真实的物理含义，也无法使用国际单位（SI (opens new window)）进行描述。

  • Physical模式

Physical模式下，three.js内部不再对光的强度（intensity）进行缩放，强度具有真实的物理含义。

注意

three.js从 r155 版本开始将useLegacyLights的默认值由true调整为false（即默认使用Physical模式），并且最终会在 r165 版本中彻底删除Legacy模式只保留Physical模式，详见Updates to lighting in three.js r155 (opens new window)。Tx3d Engine核心包（@tx3d/core）从 3.14.0 版本开始也将useLegacyLights的默认值调整为false，如果仍想使用Legacy模式请在创建引擎时将useLegacyLights设置为ture。考虑three.js后续版本变更 强烈建议将useLegacyLights设置为false使用Physical模式！！！

# Legacy模式迁移到Physical模式

只需要将强度（intensity）乘以PI即可，如下所示：

const intensity = 0.75;

// Legacy模式
light.intensity = intensity;

// Physical模式
light.intensity = intensity * Math.PI;
1
2
3
4
5
6
7

  • 区域光（RectAreaLight）、点光源（PointLight）、聚光灯（SpotLight）

    • 区域光、点光源、聚光灯的强度（intensity）单位是candela（cd，坎德拉 (opens new window)），需要远远大于Legacy模式下的强度值，推荐通过辐射通量（watts）设置强度；

    • 不要修改点光源和聚光灯的decay默认值。

  1. 按现代光通量的定义，波长为555nm的1watts辐射通量，有683lumen的光通量。人眼对555nm波长的光最为敏感。

    1watts=683lumen1_{watts} = 683_{lumen}

    ↩︎ ↩︎ ↩︎
Last Updated: 8/14/2023, 10:10:14 AM

← Renderable组件 →