@animech-public/playcanvas
Version:
PlayCanvas WebGL game engine
503 lines (502 loc) • 16.9 kB
TypeScript
/**
* A scene is graphical representation of an environment. It manages the scene hierarchy, all
* graphical objects, lights, and scene-wide properties.
*
* @category Graphics
*/
export class Scene extends EventHandler {
/**
* Fired when the layer composition is set. Use this event to add callbacks or advanced
* properties to your layers. The handler is passed the old and the new
* {@link LayerComposition}.
*
* @event
* @example
* app.scene.on('set:layers', (oldComp, newComp) => {
* const list = newComp.layerList;
* for (let i = 0; i < list.length; i++) {
* const layer = list[i];
* switch (layer.name) {
* case 'MyLayer':
* layer.onEnable = myOnEnableFunction;
* layer.onDisable = myOnDisableFunction;
* break;
* case 'MyOtherLayer':
* layer.shaderPass = myShaderPass;
* break;
* }
* }
* });
*/
static EVENT_SETLAYERS: string;
/**
* Fired when the skybox is set. The handler is passed the {@link Texture} that is the
* previously used skybox cubemap texture. The new skybox cubemap texture is in the
* {@link Scene#skybox} property.
*
* @event
* @example
* app.scene.on('set:skybox', (oldSkybox) => {
* console.log(`Skybox changed from ${oldSkybox.name} to ${app.scene.skybox.name}`);
* });
*/
static EVENT_SETSKYBOX: string;
/**
* Create a new Scene instance.
*
* @param {import('../platform/graphics/graphics-device.js').GraphicsDevice} graphicsDevice -
* The graphics device used to manage this scene.
* @ignore
*/
constructor(graphicsDevice: import("../platform/graphics/graphics-device.js").GraphicsDevice);
/**
* If enabled, the ambient lighting will be baked into lightmaps. This will be either the
* {@link Scene#skybox} if set up, otherwise {@link Scene#ambientLight}. Defaults to false.
*
* @type {boolean}
*/
ambientBake: boolean;
/**
* If {@link Scene#ambientBake} is true, this specifies the brightness of ambient occlusion.
* Typical range is -1 to 1. Defaults to 0, representing no change to brightness.
*
* @type {number}
*/
ambientBakeOcclusionBrightness: number;
/**
* If {@link Scene#ambientBake} is true, this specifies the contrast of ambient occlusion.
* Typical range is -1 to 1. Defaults to 0, representing no change to contrast.
*
* @type {number}
*/
ambientBakeOcclusionContrast: number;
/**
* The color of the scene's ambient light. Defaults to black (0, 0, 0).
*
* @type {Color}
*/
ambientLight: Color;
/**
* The luminosity of the scene's ambient light in lux (lm/m^2). Used if physicalUnits is true. Defaults to 0.
*
* @type {number}
*/
ambientLuminance: number;
/**
* The exposure value tweaks the overall brightness of the scene. Ignored if physicalUnits is true. Defaults to 1.
*
* @type {number}
*/
exposure: number;
/**
* The color of the fog (if enabled). Defaults to black (0, 0, 0).
*
* @type {Color}
*/
fogColor: Color;
/**
* The density of the fog (if enabled). This property is only valid if the fog property is set
* to {@link FOG_EXP} or {@link FOG_EXP2}. Defaults to 0.
*
* @type {number}
*/
fogDensity: number;
/**
* The distance from the viewpoint where linear fog reaches its maximum. This property is only
* valid if the fog property is set to {@link FOG_LINEAR}. Defaults to 1000.
*
* @type {number}
*/
fogEnd: number;
/**
* The distance from the viewpoint where linear fog begins. This property is only valid if the
* fog property is set to {@link FOG_LINEAR}. Defaults to 1.
*
* @type {number}
*/
fogStart: number;
/**
* The lightmap resolution multiplier. Defaults to 1.
*
* @type {number}
*/
lightmapSizeMultiplier: number;
/**
* The maximum lightmap resolution. Defaults to 2048.
*
* @type {number}
*/
lightmapMaxResolution: number;
/**
* The lightmap baking mode. Can be:
*
* - {@link BAKE_COLOR}: single color lightmap
* - {@link BAKE_COLORDIR}: single color lightmap + dominant light direction (used for bump or
* specular). Only lights with bakeDir=true will be used for generating the dominant light
* direction.
*
* Defaults to {@link BAKE_COLORDIR}.
*
* @type {number}
*/
lightmapMode: number;
/**
* Enables bilateral filter on runtime baked color lightmaps, which removes the noise and
* banding while preserving the edges. Defaults to false. Note that the filtering takes place
* in the image space of the lightmap, and it does not filter across lightmap UV space seams,
* often making the seams more visible. It's important to balance the strength of the filter
* with number of samples used for lightmap baking to limit the visible artifacts.
*
* @type {boolean}
*/
lightmapFilterEnabled: boolean;
/**
* Enables HDR lightmaps. This can result in smoother lightmaps especially when many samples
* are used. Defaults to false.
*
* @type {boolean}
*/
lightmapHDR: boolean;
/**
* The root entity of the scene, which is usually the only child to the {@link Application}
* root entity.
*
* @type {import('../framework/entity.js').Entity}
*/
root: import("../framework/entity.js").Entity;
/**
* Use physically based units for cameras and lights. When used, the exposure value is ignored.
*
* @type {boolean}
*/
physicalUnits: boolean;
/**
* Environment lighting atlas
*
* @type {import('../platform/graphics/texture.js').Texture|null}
* @private
*/
private _envAtlas;
/**
* The skybox cubemap as set by user (gets used when skyboxMip === 0)
*
* @type {import('../platform/graphics/texture.js').Texture|null}
* @private
*/
private _skyboxCubeMap;
device: import("../platform/graphics/graphics-device.js").GraphicsDevice;
_gravity: Vec3;
/**
* @type {import('./composition/layer-composition.js').LayerComposition}
* @private
*/
private _layers;
_fog: string;
_gammaCorrection: number;
_toneMapping: number;
/**
* Array of 6 prefiltered lighting data cubemaps.
*
* @type {import('../platform/graphics/texture.js').Texture[]}
* @private
*/
private _prefilteredCubemaps;
_internalEnvAtlas: any;
_skyboxIntensity: number;
_skyboxLuminance: number;
_skyboxMip: number;
_skyboxRotationShaderInclude: boolean;
_skyboxRotation: Quat;
_skyboxRotationMat3: Mat3;
_skyboxRotationMat4: Mat4;
_ambientBakeNumSamples: number;
_ambientBakeSpherePart: number;
_lightmapFilterRange: number;
_lightmapFilterSmoothness: number;
_clusteredLightingEnabled: boolean;
_lightingParams: LightingParams;
updateShaders: boolean;
_sky: Sky;
_stats: {
meshInstances: number;
lights: number;
dynamicLights: number;
bakedLights: number;
updateShadersTime: number;
};
_shaderVersion: number;
immediate: Immediate;
/**
* Gets the default layer used by the immediate drawing functions.
*
* @type {import('./layer.js').Layer}
* @ignore
*/
get defaultDrawLayer(): import("./layer.js").Layer;
/**
* Sets the number of samples used to bake the ambient light into the lightmap. Note that
* {@link Scene#ambientBake} must be true for this to have an effect. Defaults to 1. Maximum
* value is 255.
*
* @type {number}
*/
set ambientBakeNumSamples(value: number);
/**
* Gets the number of samples used to bake the ambient light into the lightmap.
*
* @type {number}
*/
get ambientBakeNumSamples(): number;
/**
* Sets the part of the sphere which represents the source of ambient light. Note that
* {@link Scene#ambientBake} must be true for this to have an effect. The valid range is 0..1,
* representing a part of the sphere from top to the bottom. A value of 0.5 represents the
* upper hemisphere. A value of 1 represents a full sphere. Defaults to 0.4, which is a smaller
* upper hemisphere as this requires fewer samples to bake.
*
* @type {number}
*/
set ambientBakeSpherePart(value: number);
/**
* Gets the part of the sphere which represents the source of ambient light.
*
* @type {number}
*/
get ambientBakeSpherePart(): number;
/**
* Sets whether clustered lighting is enabled. Set to false before the first frame is rendered
* to use non-clustered lighting. Defaults to true.
*
* @type {boolean}
*/
set clusteredLightingEnabled(value: boolean);
/**
* Gets whether clustered lighting is enabled.
*
* @type {boolean}
*/
get clusteredLightingEnabled(): boolean;
/**
* Sets the environment lighting atlas.
*
* @type {import('../platform/graphics/texture.js').Texture}
*/
set envAtlas(value: import("../platform/graphics/texture.js").Texture);
/**
* Gets the environment lighting atlas.
*
* @type {import('../platform/graphics/texture.js').Texture}
*/
get envAtlas(): import("../platform/graphics/texture.js").Texture;
/**
* Sets the type of fog used by the scene. Can be:
*
* - {@link FOG_NONE}
* - {@link FOG_LINEAR}
* - {@link FOG_EXP}
* - {@link FOG_EXP2}
*
* Defaults to {@link FOG_NONE}.
*
* @type {string}
*/
set fog(type: string);
/**
* Gets the type of fog used by the scene.
*
* @type {string}
*/
get fog(): string;
/**
* Sets the gamma correction to apply when rendering the scene. Can be:
*
* - {@link GAMMA_NONE}
* - {@link GAMMA_SRGB}
*
* Defaults to {@link GAMMA_SRGB}.
*
* @type {number}
*/
set gammaCorrection(value: number);
/**
* Gets the gamma correction to apply when rendering the scene.
*
* @type {number}
*/
get gammaCorrection(): number;
/**
* Sets the {@link LayerComposition} that defines rendering order of this scene.
*
* @type {import('./composition/layer-composition.js').LayerComposition}
*/
set layers(layers: import("./composition/layer-composition.js").LayerComposition);
/**
* Gets the {@link LayerComposition} that defines rendering order of this scene.
*
* @type {import('./composition/layer-composition.js').LayerComposition}
*/
get layers(): import("./composition/layer-composition.js").LayerComposition;
get sky(): Sky;
/**
* Gets the {@link LightingParams} that define lighting parameters.
*
* @type {LightingParams}
*/
get lighting(): LightingParams;
/**
* Sets the range parameter of the bilateral filter. It's used when {@link Scene#lightmapFilterEnabled}
* is enabled. Larger value applies more widespread blur. This needs to be a positive non-zero
* value. Defaults to 10.
*
* @type {number}
*/
set lightmapFilterRange(value: number);
/**
* Gets the range parameter of the bilateral filter.
*
* @type {number}
*/
get lightmapFilterRange(): number;
/**
* Sets the spatial parameter of the bilateral filter. It's used when {@link Scene#lightmapFilterEnabled}
* is enabled. Larger value blurs less similar colors. This needs to be a positive non-zero
* value. Defaults to 0.2.
*
* @type {number}
*/
set lightmapFilterSmoothness(value: number);
/**
* Gets the spatial parameter of the bilateral filter.
*
* @type {number}
*/
get lightmapFilterSmoothness(): number;
/**
* Sets the 6 prefiltered cubemaps acting as the source of image-based lighting.
*
* @type {import('../platform/graphics/texture.js').Texture[]}
*/
set prefilteredCubemaps(value: import("../platform/graphics/texture.js").Texture[]);
/**
* Gets the 6 prefiltered cubemaps acting as the source of image-based lighting.
*
* @type {import('../platform/graphics/texture.js').Texture[]}
*/
get prefilteredCubemaps(): import("../platform/graphics/texture.js").Texture[];
/**
* Sets the base cubemap texture used as the scene's skybox when skyboxMip is 0. Defaults to null.
*
* @type {import('../platform/graphics/texture.js').Texture}
*/
set skybox(value: import("../platform/graphics/texture.js").Texture);
/**
* Gets the base cubemap texture used as the scene's skybox when skyboxMip is 0.
*
* @type {import('../platform/graphics/texture.js').Texture}
*/
get skybox(): import("../platform/graphics/texture.js").Texture;
/**
* Sets the multiplier for skybox intensity. Defaults to 1. Unused if physical units are used.
*
* @type {number}
*/
set skyboxIntensity(value: number);
/**
* Gets the multiplier for skybox intensity.
*
* @type {number}
*/
get skyboxIntensity(): number;
/**
* Sets the luminance (in lm/m^2) of the skybox. Defaults to 0. Only used if physical units are used.
*
* @type {number}
*/
set skyboxLuminance(value: number);
/**
* Gets the luminance (in lm/m^2) of the skybox.
*
* @type {number}
*/
get skyboxLuminance(): number;
/**
* Sets the mip level of the skybox to be displayed. Only valid for prefiltered cubemap skyboxes.
* Defaults to 0 (base level).
*
* @type {number}
*/
set skyboxMip(value: number);
/**
* Gets the mip level of the skybox to be displayed.
*
* @type {number}
*/
get skyboxMip(): number;
/**
* Sets the rotation of the skybox to be displayed. Defaults to {@link Quat.IDENTITY}.
*
* @type {Quat}
*/
set skyboxRotation(value: Quat);
/**
* Gets the rotation of the skybox to be displayed.
*
* @type {Quat}
*/
get skyboxRotation(): Quat;
/**
* Sets the tonemapping transform to apply when writing fragments to the frame buffer. Can be:
*
* - {@link TONEMAP_LINEAR}
* - {@link TONEMAP_FILMIC}
* - {@link TONEMAP_HEJL}
* - {@link TONEMAP_ACES}
* - {@link TONEMAP_ACES2}
* - {@link TONEMAP_NEUTRAL}
*
* Defaults to {@link TONEMAP_LINEAR}.
*
* @type {number}
*/
set toneMapping(value: number);
/**
* Gets the tonemapping transform to apply when writing fragments to the frame buffer.
*
* @type {number}
*/
get toneMapping(): number;
destroy(): void;
drawLine(start: any, end: any, color?: Color, depthTest?: boolean, layer?: import("./layer.js").Layer): void;
drawLines(positions: any, colors: any, depthTest?: boolean, layer?: import("./layer.js").Layer): void;
drawLineArrays(positions: any, colors: any, depthTest?: boolean, layer?: import("./layer.js").Layer): void;
applySettings(settings: any): void;
_getSkyboxTex(): import("../platform/graphics/texture.js").Texture;
_updateSkyMesh(): void;
_resetSkyMesh(): void;
/**
* Sets the cubemap for the scene skybox.
*
* @param {import('../platform/graphics/texture.js').Texture[]} [cubemaps] - An array of
* cubemaps corresponding to the skybox at different mip levels. If undefined, scene will
* remove skybox. Cubemap array should be of size 7, with the first element (index 0)
* corresponding to the base cubemap (mip level 0) with original resolution. Each remaining
* element (index 1-6) corresponds to a fixed prefiltered resolution (128x128, 64x64, 32x32,
* 16x16, 8x8, 4x4).
*/
setSkybox(cubemaps?: import("../platform/graphics/texture.js").Texture[]): void;
/**
* Gets the lightmap pixel format.
*
* @type {number}
*/
get lightmapPixelFormat(): number;
}
import { EventHandler } from '../core/event-handler.js';
import { Color } from '../core/math/color.js';
import { Vec3 } from '../core/math/vec3.js';
import { Quat } from '../core/math/quat.js';
import { Mat3 } from '../core/math/mat3.js';
import { Mat4 } from '../core/math/mat4.js';
import { LightingParams } from './lighting/lighting-params.js';
import { Sky } from './skybox/sky.js';
import { Immediate } from './immediate/immediate.js';