Accueil / npm / three@0.186.1 / src / core / RenderTarget.js
RenderTarget.js
import { EventDispatcher } from './EventDispatcher.js';
import { Texture } from '../textures/Texture.js';
import { LinearFilter } from '../constants.js';
import { Vector4 } from '../math/Vector4.js';
import { TextureSource } from '../textures/TextureSource.js';
/**
* A render target is a buffer where the video card draws pixels for a scene
* that is being rendered in the background. It is used in different effects,
* such as applying postprocessing to a rendered image before displaying it
* on the screen.
*
* @augments EventDispatcher
*/
class RenderTarget extends EventDispatcher {
/**
* Render target options.
*
* @typedef {Object} RenderTarget~Options
* @property {boolean} [generateMipmaps=false] - Whether to generate mipmaps or not.
* @property {number} [magFilter=LinearFilter] - The mag filter.
* @property {number} [minFilter=LinearFilter] - The min filter.
* @property {number} [format=RGBAFormat] - The texture format.
* @property {number} [type=UnsignedByteType] - The texture type.
* @property {?string} [internalFormat=null] - The texture's internal format.
* @property {number} [wrapS=ClampToEdgeWrapping] - The texture's uv wrapping mode.
* @property {number} [wrapT=ClampToEdgeWrapping] - The texture's uv wrapping mode.
* @property {number} [anisotropy=1] - The texture's anisotropy value.
* @property {string} [colorSpace=NoColorSpace] - The texture's color space.
* @property {boolean} [depthBuffer=true] - Whether to allocate a depth buffer or not.
* @property {boolean} [stencilBuffer=false] - Whether to allocate a stencil buffer or not.
* @property {boolean} [resolveColorBuffer=true] - Whether to resolve the color buffer or not. Only relevant for multisampled render targets.
* @property {boolean} [resolveDepthBuffer=true] - Whether to resolve the depth buffer or not. Only relevant for multisampled render targets.
* @property {boolean} [resolveStencilBuffer=true] - Whether to resolve the stencil buffer or not. Only relevant for multisampled render targets.
* @property {boolean} [storeMultisampledColorBuffer=true] - Whether to store the multisampled color buffer or not. Setting to `false` saves memory bandwidth when the multisampled data are not needed after a render pass.
* @property {boolean} [storeMultisampledDepthBuffer=true] - Whether to store the multisampled depth buffer or not. Setting to `false` saves memory bandwidth when the multisampled data are not needed after a render pass.
* @property {boolean} [storeMultisampledStencilBuffer=true] - Whether to store the multisampled stencil buffer or not. Setting to `false` saves memory bandwidth when the multisampled data are not needed after a render pass.
* @property {?Texture} [depthTexture=null] - Reference to a depth texture.
* @property {number} [samples=0] - The MSAA samples count.
* @property {number} [count=1] - Defines the number of color attachments . Must be at least `1`.
* @property {number} [depth=1] - The texture depth.
* @property {boolean} [multiview=false] - Whether this target is used for multiview rendering (WebGL OVR_multiview2 extension).
* @property {boolean} [useArrayDepthTexture=false] - Whether to create the depth texture as an array texture for per-layer depth testing. This is separate from multiview so layered render targets can use array depth without the multiview extension.
*/
/**
* Constructs a new render target.
*
* @param {number} [width=1] - The width of the render target.
* @param {number} [height=1] - The height of the render target.
* @param {RenderTarget~Options} [options] - The configuration object.
*/
constructor( width = 1, height = 1, options = {} ) {
super();
options = Object.assign( {
generateMipmaps: false,
internalFormat: null,
minFilter: LinearFilter,
depthBuffer: true,
stencilBuffer: false,
resolveColorBuffer: true,
resolveDepthBuffer: true,
resolveStencilBuffer: true,
storeMultisampledColorBuffer: true,
storeMultisampledDepthBuffer: true,
storeMultisampledStencilBuffer: true,
depthTexture: null,
samples: 0,
count: 1,
depth: 1,
multiview: false,
useArrayDepthTexture: false
}, options );
/**
* This flag can be used for type testing.
*
* @type {boolean}
* @readonly
* @default true
*/
this.isRenderTarget = true;
/**
* The width of the render target.
*
* @type {number}
* @default 1
*/
this.width = width;
/**
* The height of the render target.
*
* @type {number}
* @default 1
*/
this.height = height;
/**
* The depth of the render target.
*
* @type {number}
* @default 1
*/
this.depth = options.depth;
/**
* A rectangular area inside the render target's viewport. Fragments that are
* outside the area will be discarded.
*
* @type {Vector4}
* @default (0,0,width,height)
*/
this.scissor = new Vector4( 0, 0, width, height );
/**
* Indicates whether the scissor test should be enabled when rendering into
* this render target or not.
*
* @type {boolean}
* @default false
*/
this.scissorTest = false;
/**
* A rectangular area representing the render target's viewport.
*
* @type {Vector4}
* @default (0,0,width,height)
*/
this.viewport = new Vector4( 0, 0, width, height );
/**
* An array of textures. Each color attachment is represented as a separate texture.
* Has at least a single entry for the default color attachment.
*
* @type {Array<Texture>}
*/
this.textures = [];
const image = { width: width, height: height, depth: options.depth };
const texture = new Texture( image );
const count = options.count;
for ( let i = 0; i < count; i ++ ) {
this.textures[ i ] = texture.clone();
this.textures[ i ].isRenderTargetTexture = true;
this.textures[ i ].renderTarget = this;
}
this._setTextureOptions( options );
/**
* Whether to allocate a depth buffer or not.
*
* @type {boolean}
* @default true
*/
this.depthBuffer = options.depthBuffer;
/**
* Whether to allocate a stencil buffer or not.
*
* @type {boolean}
* @default false
*/
this.stencilBuffer = options.stencilBuffer;
/**
* Whether to resolve the color buffer or not. When set to `false`, the color
* attachments do not receive the resolved (single-sampled) output of a render
* pass and the render target's textures are left untouched. The rendered
* content is then only accessible within the render pass itself.
*
* Only relevant for multisampled render targets.
*
* @type {boolean}
* @default true
*/
this.resolveColorBuffer = options.resolveColorBuffer;
/**
* Whether to resolve the depth buffer or not. When set to `false`, the depth
* texture does not receive the resolved depth output of a render pass which
* saves memory bandwidth. Use this setting when the depth data of a render
* pass are not required afterwards.
*
* Only relevant for multisampled render targets in WebGL. WebGPU does not
* support depth resolves; sampling the depth texture of a multisampled render
* target accesses the multisampled data directly, see
* {@link RenderTarget#storeMultisampledDepthBuffer}.
*
* @type {boolean}
* @default true
*/
this.resolveDepthBuffer = options.resolveDepthBuffer;
/**
* Whether to resolve the stencil buffer or not. Analogous to
* {@link RenderTarget#resolveDepthBuffer} but for the stencil aspect.
*
* @type {boolean}
* @default true
*/
this.resolveStencilBuffer = options.resolveStencilBuffer;
/**
* Whether to store the multisampled color buffer or not. When set to `false`,
* the multisampled data are discarded at the end of a render pass, right after
* they have been resolved. This saves memory bandwidth, especially on tile-based
* GPUs, and is the recommended setting for render targets that are fully redrawn
* each frame and whose output is only accessed via the resolved textures (e.g.
* scene passes in post-processing chains).
*
* Must be kept `true` when the multisampled data are needed after the render
* pass ends, e.g. when rendering into the target without clearing or when the
* scene contains transmissive objects which require a mid-pass framebuffer copy.
*
* @type {boolean}
* @default true
*/
this.storeMultisampledColorBuffer = options.storeMultisampledColorBuffer;
/**
* Whether to store the multisampled depth buffer or not. When set to `false`,
* the multisampled depth data are discarded at the end of a render pass which
* saves memory bandwidth.
*
* Must be kept `true` in WebGPU when the depth texture of a multisampled render
* target is sampled (e.g. by depth-based post-processing effects) since depth
* is read directly from the multisampled data.
*
* @type {boolean}
* @default true
*/
this.storeMultisampledDepthBuffer = options.storeMultisampledDepthBuffer;
/**
* Whether to store the multisampled stencil buffer or not. Analogous to
* {@link RenderTarget#storeMultisampledDepthBuffer} but for the stencil aspect.
*
* @type {boolean}
* @default true
*/
this.storeMultisampledStencilBuffer = options.storeMultisampledStencilBuffer;
this._depthTexture = null;
this.depthTexture = options.depthTexture;
/**
* The number of MSAA samples.
*
* A value of `0` disables MSAA.
*
* @type {number}
* @default 0
*/
this.samples = options.samples;
/**
* Whether to this target is used in multiview rendering.
*
* @type {boolean}
* @default false
*/
this.multiview = options.multiview;
/**
* Whether to create the depth texture as an array texture for per-layer depth testing.
* This is separate from multiview so layered render targets can use array depth without
* the multiview extension.
*
* @type {boolean}
* @default false
*/
this.useArrayDepthTexture = options.useArrayDepthTexture;
}
_setTextureOptions( options = {} ) {
const values = {
minFilter: LinearFilter,
generateMipmaps: false,
flipY: false,
internalFormat: null
};
if ( options.mapping !== undefined ) values.mapping = options.mapping;
if ( options.wrapS !== undefined ) values.wrapS = options.wrapS;
if ( options.wrapT !== undefined ) values.wrapT = options.wrapT;
if ( options.wrapR !== undefined ) values.wrapR = options.wrapR;
if ( options.magFilter !== undefined ) values.magFilter = options.magFilter;
if ( options.minFilter !== undefined ) values.minFilter = options.minFilter;
if ( options.format !== undefined ) values.format = options.format;
if ( options.type !== undefined ) values.type = options.type;
if ( options.anisotropy !== undefined ) values.anisotropy = options.anisotropy;
if ( options.colorSpace !== undefined ) values.colorSpace = options.colorSpace;
if ( options.flipY !== undefined ) values.flipY = options.flipY;
if ( options.generateMipmaps !== undefined ) values.generateMipmaps = options.generateMipmaps;
if ( options.internalFormat !== undefined ) values.internalFormat = options.internalFormat;
for ( let i = 0; i < this.textures.length; i ++ ) {
const texture = this.textures[ i ];
texture.setValues( values );
}
}
/**
* The texture representing the default color attachment.
*
* @type {Texture}
*/
get texture() {
return this.textures[ 0 ];
}
set texture( value ) {
this.textures[ 0 ] = value;
}
set depthTexture( current ) {
if ( this._depthTexture !== null && this._depthTexture.renderTarget === this ) this._depthTexture.renderTarget = null;
if ( current !== null && current.renderTarget === null ) current.renderTarget = this;
this._depthTexture = current;
}
/**
* Instead of saving the depth in a renderbuffer, a texture
* can be used instead which is useful for further processing
* e.g. in context of post-processing.
*
* @type {?DepthTexture}
* @default null
*/
get depthTexture() {
return this._depthTexture;
}
/**
* Sets the size of this render target.
*
* @param {number} width - The width.
* @param {number} height - The height.
* @param {number} [depth=1] - The depth.
*/
setSize( width, height, depth = 1 ) {
if ( this.width !== width || this.height !== height || this.depth !== depth ) {
this.width = width;
this.height = height;
this.depth = depth;
for ( let i = 0, il = this.textures.length; i < il; i ++ ) {
this.textures[ i ].image.width = width;
this.textures[ i ].image.height = height;
this.textures[ i ].image.depth = depth;
if ( this.textures[ i ].isData3DTexture !== true ) { // Fix for #31693
// TODO: Reconsider setting isArrayTexture flag here and in the ctor of Texture.
// Maybe a method `isArrayTexture()` or just a getter could replace a flag since
// both are evaluated on each call?
this.textures[ i ].isArrayTexture = this.textures[ i ].image.depth > 1;
}
}
this.dispose();
}
this.viewport.set( 0, 0, width, height );
this.scissor.set( 0, 0, width, height );
}
/**
* Returns a new render target with copied values from this instance.
*
* @return {RenderTarget} A clone of this instance.
*/
clone() {
return new this.constructor().copy( this );
}
/**
* Copies the settings of the given render target. This is a structural copy so
* no resources are shared between render targets after the copy. That includes
* all MRT textures and the depth texture.
*
* @param {RenderTarget} source - The render target to copy.
* @return {RenderTarget} A reference to this instance.
*/
copy( source ) {
this.width = source.width;
this.height = source.height;
this.depth = source.depth;
this.scissor.copy( source.scissor );
this.scissorTest = source.scissorTest;
this.viewport.copy( source.viewport );
this.textures.length = 0;
for ( let i = 0, il = source.textures.length; i < il; i ++ ) {
this.textures[ i ] = source.textures[ i ].clone();
this.textures[ i ].isRenderTargetTexture = true;
this.textures[ i ].renderTarget = this;
// ensure image object is not shared, see #20328
const image = Object.assign( {}, source.textures[ i ].image );
this.textures[ i ].source = new TextureSource( image );
}
this.depthBuffer = source.depthBuffer;
this.stencilBuffer = source.stencilBuffer;
this.resolveColorBuffer = source.resolveColorBuffer;
this.resolveDepthBuffer = source.resolveDepthBuffer;
this.resolveStencilBuffer = source.resolveStencilBuffer;
this.storeMultisampledColorBuffer = source.storeMultisampledColorBuffer;
this.storeMultisampledDepthBuffer = source.storeMultisampledDepthBuffer;
this.storeMultisampledStencilBuffer = source.storeMultisampledStencilBuffer;
if ( source.depthTexture !== null ) {
if ( source.depthTexture.renderTarget === source ) {
const depthTexture = source.depthTexture.clone();
depthTexture.renderTarget = null;
this.depthTexture = depthTexture;
} else {
this.depthTexture = source.depthTexture;
}
}
this.samples = source.samples;
this.multiview = source.multiview;
this.useArrayDepthTexture = source.useArrayDepthTexture;
return this;
}
/**
* Frees the GPU-related resources allocated by this instance. Call this
* method whenever this instance is no longer used in your app.
*
* @fires RenderTarget#dispose
*/
dispose() {
this.dispatchEvent( { type: 'dispose' } );
}
}
export { RenderTarget };