@animech-public/playcanvas
Version:
PlayCanvas WebGL game engine
648 lines (647 loc) • 19.7 kB
TypeScript
/**
* The graphics device manages the underlying graphics context. It is responsible for submitting
* render state changes and graphics primitives to the hardware. A graphics device is tied to a
* specific canvas HTML element. It is valid to have more than one canvas element per page and
* create a new graphics device against each.
*
* @category Graphics
*/
export class GraphicsDevice extends EventHandler {
static EVENT_RESIZE: string;
constructor(canvas: any, options: any);
/**
* Fired when the canvas is resized. The handler is passed the new width and height as number
* parameters.
*
* @event
* @example
* graphicsDevice.on('resizecanvas', (width, height) => {
* console.log(`The canvas was resized to ${width}x${height}`);
* });
*/
/**
* The canvas DOM element that provides the underlying WebGL context used by the graphics device.
*
* @type {HTMLCanvasElement}
* @readonly
*/
readonly canvas: HTMLCanvasElement;
/**
* The render target representing the main back-buffer.
*
* @type {import('./render-target.js').RenderTarget|null}
* @ignore
*/
backBuffer: import("./render-target.js").RenderTarget | null;
/**
* The dimensions of the back buffer.
*
* @ignore
*/
backBufferSize: Vec2;
/**
* The pixel format of the back buffer. Typically PIXELFORMAT_RGBA8, PIXELFORMAT_BGRA8 or
* PIXELFORMAT_RGB8.
*
* @ignore
*/
backBufferFormat: any;
/**
* True if the back buffer should use anti-aliasing.
*
* @type {boolean}
*/
backBufferAntialias: boolean;
/**
* True if the deviceType is WebGPU
*
* @type {boolean}
* @readonly
*/
readonly isWebGPU: boolean;
/**
* True if the deviceType is WebGL1
*
* @type {boolean}
* @readonly
*/
readonly isWebGL1: boolean;
/**
* True if the deviceType is WebGL2
*
* @type {boolean}
* @readonly
*/
readonly isWebGL2: boolean;
/**
* The scope namespace for shader attributes and variables.
*
* @type {ScopeSpace}
* @readonly
*/
readonly scope: ScopeSpace;
/**
* The maximum number of supported bones using uniform buffers.
*
* @type {number}
* @readonly
*/
readonly boneLimit: number;
/**
* The maximum supported texture anisotropy setting.
*
* @type {number}
* @readonly
*/
readonly maxAnisotropy: number;
/**
* The maximum supported dimension of a cube map.
*
* @type {number}
* @readonly
*/
readonly maxCubeMapSize: number;
/**
* The maximum supported dimension of a texture.
*
* @type {number}
* @readonly
*/
readonly maxTextureSize: number;
/**
* The maximum supported dimension of a 3D texture (any axis).
*
* @type {number}
* @readonly
*/
readonly maxVolumeSize: number;
/**
* The maximum supported number of color buffers attached to a render target.
*
* @type {number}
* @readonly
*/
readonly maxColorAttachments: number;
/**
* The highest shader precision supported by this graphics device. Can be 'hiphp', 'mediump' or
* 'lowp'.
*
* @type {string}
* @readonly
*/
readonly precision: string;
/**
* The number of hardware anti-aliasing samples used by the frame buffer.
*
* @readonly
* @type {number}
*/
readonly samples: number;
/**
* True if the main framebuffer contains stencil attachment.
*
* @ignore
* @type {boolean}
*/
supportsStencil: boolean;
/**
* True if Multiple Render Targets feature is supported. This refers to the ability to render to
* multiple color textures with a single draw call.
*
* @readonly
* @type {boolean}
*/
readonly supportsMrt: boolean;
/**
* True if the device supports volume textures.
*
* @readonly
* @type {boolean}
*/
readonly supportsVolumeTextures: boolean;
/**
* True if the device supports compute shaders.
*
* @readonly
* @type {boolean}
*/
readonly supportsCompute: boolean;
/**
* True if the device can read from StorageTexture in the compute shader. By default, the
* storage texture can be only used with the write operation.
* When a shader uses this feature, it's recommended to use a `requires` directive to signal the
* potential for non-portability at the top of the WGSL shader code:
* ```javascript
* requires readonly_and_readwrite_storage_textures;
* ```
*
* @readonly
* @type {boolean}
*/
readonly supportsStorageTextureRead: boolean;
/**
* Currently active render target.
*
* @type {import('./render-target.js').RenderTarget|null}
* @ignore
*/
renderTarget: import("./render-target.js").RenderTarget | null;
/**
* Array of objects that need to be re-initialized after a context restore event
*
* @type {import('./shader.js').Shader[]}
* @ignore
*/
shaders: import("./shader.js").Shader[];
/**
* An array of currently created textures.
*
* @type {import('./texture.js').Texture[]}
* @ignore
*/
textures: import("./texture.js").Texture[];
/**
* A set of currently created render targets.
*
* @type {Set<import('./render-target.js').RenderTarget>}
* @ignore
*/
targets: Set<import("./render-target.js").RenderTarget>;
/**
* A version number that is incremented every frame. This is used to detect if some object were
* invalidated.
*
* @type {number}
* @ignore
*/
renderVersion: number;
/**
* Index of the currently active render pass.
*
* @type {number}
* @ignore
*/
renderPassIndex: number;
/** @type {boolean} */
insideRenderPass: boolean;
/**
* True if hardware instancing is supported.
*
* @type {boolean}
* @readonly
*/
readonly supportsInstancing: boolean;
/**
* True if the device supports uniform buffers.
*
* @type {boolean}
* @ignore
*/
supportsUniformBuffers: boolean;
/**
* True if 32-bit floating-point textures can be used as a frame buffer.
*
* @type {boolean}
* @readonly
*/
readonly textureFloatRenderable: boolean;
/**
* True if 16-bit floating-point textures can be used as a frame buffer.
*
* @type {boolean}
* @readonly
*/
readonly textureHalfFloatRenderable: boolean;
/**
* True if filtering can be applied when sampling float textures.
*
* @type {boolean}
* @readonly
*/
readonly textureFloatFilterable: boolean;
/**
* True if filtering can be applied when sampling 16-bit float textures.
*
* @type {boolean}
* @readonly
*/
readonly textureHalfFloatFilterable: boolean;
/**
* A vertex buffer representing a quad.
*
* @type {VertexBuffer}
* @ignore
*/
quadVertexBuffer: VertexBuffer;
/**
* An object representing current blend state
*
* @ignore
*/
blendState: BlendState;
/**
* The current depth state.
*
* @ignore
*/
depthState: DepthState;
/**
* True if stencil is enabled and stencilFront and stencilBack are used
*
* @ignore
*/
stencilEnabled: boolean;
/**
* The current front stencil parameters.
*
* @ignore
*/
stencilFront: StencilParameters;
/**
* The current back stencil parameters.
*
* @ignore
*/
stencilBack: StencilParameters;
/**
* The dynamic buffer manager.
*
* @type {import('./dynamic-buffers.js').DynamicBuffers}
* @ignore
*/
dynamicBuffers: import("./dynamic-buffers.js").DynamicBuffers;
/**
* The GPU profiler.
*
* @type {import('./gpu-profiler.js').GpuProfiler}
*/
gpuProfiler: import("./gpu-profiler.js").GpuProfiler;
defaultClearOptions: {
color: number[];
depth: number;
stencil: number;
flags: number;
};
/**
* The current client rect.
*
* @type {{ width: number, height: number }}
* @ignore
*/
clientRect: {
width: number;
height: number;
};
initOptions: any;
_maxPixelRatio: number;
buffers: any[];
_vram: {
texShadow: number;
texAsset: number;
texLightmap: number;
tex: number;
vb: number;
ib: number;
ub: number;
sb: number;
};
_shaderStats: {
vsCompiled: number;
fsCompiled: number;
linked: number;
materialShaders: number;
compileTime: number;
};
_drawCallsPerFrame: number;
_shaderSwitchesPerFrame: number;
_primsPerFrame: number[];
_renderTargetCreationTime: number;
textureBias: import("./scope-id.js").ScopeId;
/**
* Function that executes after the device has been created.
*/
postInit(): void;
/**
* Destroy the graphics device.
*/
destroy(): void;
onDestroyShader(shader: any): void;
postDestroy(): void;
/**
* Called when the device context was lost. It releases all context related resources.
*
* @ignore
*/
loseContext(): void;
contextLost: boolean;
/**
* Called when the device context is restored. It reinitializes all context related resources.
*
* @ignore
*/
restoreContext(): void;
toJSON(key: any): any;
initializeContextCaches(): void;
indexBuffer: import("./index-buffer.js").IndexBuffer;
vertexBuffers: any[];
shader: any;
shaderValid: any;
shaderAsyncCompile: boolean;
initializeRenderState(): void;
cullMode: number;
vx: number;
vy: number;
vw: number;
vh: number;
sx: number;
sy: number;
sw: number;
sh: number;
blendColor: Color;
/**
* Sets the specified stencil state. If both stencilFront and stencilBack are null, stencil
* operation is disabled.
*
* @param {StencilParameters} [stencilFront] - The front stencil parameters. Defaults to
* {@link StencilParameters.DEFAULT} if not specified.
* @param {StencilParameters} [stencilBack] - The back stencil parameters. Defaults to
* {@link StencilParameters.DEFAULT} if not specified.
*/
setStencilState(stencilFront?: StencilParameters, stencilBack?: StencilParameters): void;
/**
* Sets the specified blend state.
*
* @param {BlendState} blendState - New blend state.
*/
setBlendState(blendState: BlendState): void;
/**
* Sets the constant blend color and alpha values used with {@link BLENDMODE_CONSTANT} and
* {@link BLENDMODE_ONE_MINUS_CONSTANT} factors specified in {@link BlendState}. Defaults to
* [0, 0, 0, 0].
*
* @param {number} r - The value for red.
* @param {number} g - The value for green.
* @param {number} b - The value for blue.
* @param {number} a - The value for alpha.
*/
setBlendColor(r: number, g: number, b: number, a: number): void;
/**
* Sets the specified depth state.
*
* @param {DepthState} depthState - New depth state.
*/
setDepthState(depthState: DepthState): void;
/**
* Controls how triangles are culled based on their face direction. The default cull mode is
* {@link CULLFACE_BACK}.
*
* @param {number} cullMode - The cull mode to set. Can be:
*
* - {@link CULLFACE_NONE}
* - {@link CULLFACE_BACK}
* - {@link CULLFACE_FRONT}
*/
setCullMode(cullMode: number): void;
/**
* Sets the specified render target on the device. If null is passed as a parameter, the back
* buffer becomes the current target for all rendering operations.
*
* @param {import('./render-target.js').RenderTarget|null} renderTarget - The render target to
* activate.
* @example
* // Set a render target to receive all rendering output
* device.setRenderTarget(renderTarget);
*
* // Set the back buffer to receive all rendering output
* device.setRenderTarget(null);
*/
setRenderTarget(renderTarget: import("./render-target.js").RenderTarget | null): void;
/**
* Sets the current index buffer on the graphics device. On subsequent calls to
* {@link GraphicsDevice#draw}, the specified index buffer will be used to provide index data
* for any indexed primitives.
*
* @param {import('./index-buffer.js').IndexBuffer|null} indexBuffer - The index buffer to assign to
* the device.
*/
setIndexBuffer(indexBuffer: import("./index-buffer.js").IndexBuffer | null): void;
/**
* Sets the current vertex buffer on the graphics device. On subsequent calls to
* {@link GraphicsDevice#draw}, the specified vertex buffer(s) will be used to provide vertex
* data for any primitives.
*
* @param {import('./vertex-buffer.js').VertexBuffer} vertexBuffer - The vertex buffer to
* assign to the device.
*/
setVertexBuffer(vertexBuffer: import("./vertex-buffer.js").VertexBuffer): void;
/**
* Clears the vertex buffer set on the graphics device. This is called automatically by the
* renderer.
* @ignore
*/
clearVertexBuffer(): void;
/**
* Queries the currently set render target on the device.
*
* @returns {import('./render-target.js').RenderTarget} The current render target.
* @example
* // Get the current render target
* const renderTarget = device.getRenderTarget();
*/
getRenderTarget(): import("./render-target.js").RenderTarget;
/**
* Initialize render target before it can be used.
*
* @param {import('./render-target.js').RenderTarget} target - The render target to be
* initialized.
* @ignore
*/
initRenderTarget(target: import("./render-target.js").RenderTarget): void;
/**
* Reports whether a texture source is a canvas, image, video or ImageBitmap.
*
* @param {*} texture - Texture source data.
* @returns {boolean} True if the texture is a canvas, image, video or ImageBitmap and false
* otherwise.
* @ignore
*/
_isBrowserInterface(texture: any): boolean;
_isImageBrowserInterface(texture: any): boolean;
_isImageCanvasInterface(texture: any): boolean;
_isImageVideoInterface(texture: any): boolean;
/**
* Sets the width and height of the canvas, then fires the `resizecanvas` event. Note that the
* specified width and height values will be multiplied by the value of
* {@link GraphicsDevice#maxPixelRatio} to give the final resultant width and height for the
* canvas.
*
* @param {number} width - The new width of the canvas.
* @param {number} height - The new height of the canvas.
* @ignore
*/
resizeCanvas(width: number, height: number): void;
/**
* Sets the width and height of the canvas, then fires the `resizecanvas` event. Note that the
* value of {@link GraphicsDevice#maxPixelRatio} is ignored.
*
* @param {number} width - The new width of the canvas.
* @param {number} height - The new height of the canvas.
* @ignore
*/
setResolution(width: number, height: number): void;
updateClientRect(): void;
/**
* Width of the back buffer in pixels.
*
* @type {number}
*/
get width(): number;
/**
* Height of the back buffer in pixels.
*
* @type {number}
*/
get height(): number;
/**
* Sets whether the device is currently in fullscreen mode.
*
* @type {boolean}
*/
set fullscreen(fullscreen: boolean);
/**
* Gets whether the device is currently in fullscreen mode.
*
* @type {boolean}
*/
get fullscreen(): boolean;
/**
* Sets the maximum pixel ratio.
*
* @type {number}
*/
set maxPixelRatio(ratio: number);
/**
* Gets the maximum pixel ratio.
*
* @type {number}
*/
get maxPixelRatio(): number;
/**
* Gets the type of the device. Can be:
*
* - {@link DEVICETYPE_WEBGL1}
* - {@link DEVICETYPE_WEBGL2}
* - {@link DEVICETYPE_WEBGPU}
*
* @type {import('./constants.js').DEVICETYPE_WEBGL1 | import('./constants.js').DEVICETYPE_WEBGL2 | import('./constants.js').DEVICETYPE_WEBGPU}
*/
get deviceType(): string | string | string;
/**
* Queries the maximum number of bones that can be referenced by a shader. The shader
* generators (programlib) use this number to specify the matrix array size of the uniform
* 'matrix_pose[0]'. The value is calculated based on the number of available uniform vectors
* available after subtracting the number taken by a typical heavyweight shader. If a different
* number is required, it can be tuned via {@link GraphicsDevice#setBoneLimit}.
*
* @returns {number} The maximum number of bones that can be supported by the host hardware.
* @ignore
*/
getBoneLimit(): number;
/**
* Specifies the maximum number of bones that the device can support on the current hardware.
* This function allows the default calculated value based on available vector uniforms to be
* overridden.
*
* @param {number} maxBones - The maximum number of bones supported by the host hardware.
* @ignore
*/
setBoneLimit(maxBones: number): void;
startRenderPass(renderPass: any): void;
endRenderPass(renderPass: any): void;
startComputePass(): void;
endComputePass(): void;
/**
* Function which executes at the start of the frame. This should not be called manually, as
* it is handled by the AppBase instance.
*
* @ignore
*/
frameStart(): void;
/**
* Function which executes at the end of the frame. This should not be called manually, as it is
* handled by the AppBase instance.
*
* @ignore
*/
frameEnd(): void;
/**
* Dispatch multiple compute shaders inside a single compute shader pass.
*
* @param {Array<import('./compute.js').Compute>} computes - An array of compute shaders to
* dispatch.
*/
computeDispatch(computes: Array<import("./compute.js").Compute>): void;
/**
* Get a renderable HDR pixel format supported by the graphics device.
*
* @param {number[]} [formats] - An array of pixel formats to check for support. Can contain:
*
* - {@link PIXELFORMAT_111110F}
* - {@link PIXELFORMAT_RGBA16F}
* - {@link PIXELFORMAT_RGBA32F}
*
* @param {boolean} [filterable] - If true, the format also needs to be filterable. Defaults to
* true.
* @returns {number|undefined} The first supported renderable HDR format or undefined if none is
* supported.
*/
getRenderableHdrFormat(formats?: number[], filterable?: boolean): number | undefined;
}
import { EventHandler } from '../../core/event-handler.js';
import { Vec2 } from '../../core/math/vec2.js';
import { ScopeSpace } from './scope-space.js';
import { VertexBuffer } from './vertex-buffer.js';
import { BlendState } from './blend-state.js';
import { DepthState } from './depth-state.js';
import { StencilParameters } from './stencil-parameters.js';
import { Color } from '../../core/math/color.js';