AdvancedReadonlyadaptora reference to the adaptor that interfaces with WebGL / WebGP
Readonlydefaultthe default clear color for render targets
Readonlyona runner that lets systems know if the active render target has changed. Eg the Stencil System needs to know so it can manage the stencil buffer
Readonlyprojectionthe projection matrix that is used by the shaders based on the active render target and the viewport
A boolean that lets the dev know if the current render pass is rendering to the screen. Used by some plugins
the current active render target
When rendering of a scene begins, this is where the root render surface is stored
This is the root viewport for the render pass
Readonlyviewportthe current viewport that the gpu is using
The effective front-face orientation of the current bind — true when a front-facing triangle
ends up wound the opposite way on the surface (so the winding/cull has been inverted to compensate).
This is the requested flipY combined with the backend's inherent orientation, not the raw request:
frontFaceInverted = flipY XOR (isWebGL && !isRoot)
WebGL's non-root FBOs carry an inherent Y-flip vs the root (the classic render-texture flip), so the
same requested flipY lands with the opposite winding depending on isRoot. WebGPU has no such
inherent flip, so there it is simply flipY. This is exactly the winding inversion each backend bakes
at bind (GlStateSystem / PipelineSystem), exposed so consumers (e.g. 3D pipelines) can
read the resolved orientation instead of re-deriving it from flipY, isRoot, and a backend check of
their own.
It is per-bind, not per-target: flipY is set on every bind/renderStart while isRoot is fixed on
the target, so this recomputes from whatever the last bind resolved.
whether the current bind's front face is inverted
the current array layer being rendered to (for array-backed targets)
the current mip level being rendered to (for texture subresources)
the current active render surface that the render target is created from
Binding a render surface! This is the main function of the render target system. It will take the RenderSurface (which can be a texture, canvas, or render target) and bind it to the renderer. Once bound all draw calls will be rendered to the render surface.
If a frame is not provided and the render surface is a Texture, the frame of the texture will be used.
IDEMPOTENT BIND:
Binding is "smart" — the viewport/projection math is always recomputed, but the underlying render pass is
only torn down and re-begun when something that actually requires it changes. If you bind the render target
that the currently open pass is already on (same mipLevel/layer) and request no clear
(clear is false / CLEAR.NONE), the live pass is reused and only the viewport is updated. This makes
drawing N things into one target at N viewports a single pass with N setViewport calls, and makes a
redundant same-target bind/pop essentially free. Any clear (even a partial one like CLEAR.DEPTH), a
different target, or a different mipLevel/layer forces a real begin. The MSAA resolve is never skipped:
it is deferred to the genuine pass end, which still happens before any target switch or read-back.
IMPORTANT:
frame is treated as base mip (mip 0) pixel space.mipLevel > 0, the viewport derived from frame is scaled by (2^{mipLevel}) and clamped to the
mip dimensions. This keeps "render the same region" semantics consistent across mip levels.renderSurface is a Texture, renderer.render({ container, target: texture, mipLevel }) will
render into
the underlying TextureSource (Pixi will create/use a RenderTarget for the source) using the
texture's frame to define the region (in mip 0 space).the bind options: see BindOptions
the render target that was bound
Binds a render surface using positional arguments.
the render surface to bind
Optionalclear: CLEAR_OR_BOOLthe clear mode to use. Can be true or a CLEAR number 'COLOR | DEPTH | STENCIL' 0b111
OptionalclearColor: RgbaArraythe color to clear to
Optionalframe: Rectanglethe frame to render to
OptionalmipLevel: numberthe mip level to render to
Optionallayer: numberthe layer (or slice) of the render surface to render to
OptionalflipY: booleanopt-in Y-orientation toggle
the render target that was bound
Optionaltarget: RenderSurfaceOptionalclearColor: RgbaArrayCopies the depth attachment from one render target to another. Both source and destination must have a depthStencilAttachment.
Important Note: When using the copied depth buffer in a subsequent render pass,
you must ensure you do not clear the depth buffer again. If you need to clear the color
buffer of the destination render target, use clear: CLEAR.COLOR to preserve the copied depth data.
the render surface (render target, depth texture, or canvas) to copy depth from
the depth/stencil texture to copy depth to
the origin of the copy
the x origin of the copy
the y origin of the copy
the size of the copy
the height of the copy
the width of the copy
the destination origin (top left to paste from!)
the x origin of the paste
the y origin of the paste
renderer.renderTarget.copyDepthTexture(
sourceRT, destRT, { x: 0, y: 0 }, { width: 200, height: 200 }, { x: 0, y: 0 }
);
// In the subsequent render pass, clear ONLY the color buffer!
renderer.render({
target: destRT,
container: myMesh,
clear: CLEAR.COLOR, // Preserves the copied depth
clearColor: [0, 0, 0, 1]
});
Copies a render surface to another texture.
NOTE: for sourceRenderSurfaceTexture, The render target must be something that is written too by the renderer
The following is not valid:
the render surface (render target, texture, or canvas) to copy from
the texture to copy to
the origin of the copy
the x origin of the copy
the y origin of the copy
the size of the copy
the height of the copy
the width of the copy
the destination origin (top left to paste from!)
the x origin of the paste
the y origin of the paste
const canvas = document.createElement('canvas')
canvas.width = 200;
canvas.height = 200;
const ctx = canvas2.getContext('2d')!
ctx.fillStyle = 'red'
ctx.fillRect(0, 0, 200, 200);
const texture = RenderTexture.create({
width: 200,
height: 200,
})
const renderTarget = renderer.renderTarget.getRenderTarget(canvas2);
renderer.renderTarget.copyToTexture(renderTarget,texture, {x:0,y:0},{width:200,height:200},{x:0,y:0});
The best way to copy a canvas is to create a texture from it. Then render with that.
Parsing in a RenderTarget canvas context (with a 2d context)
nukes the render target system
ensures that we have a depth stencil buffer available to render to This is used by the mask system to make sure we have a stencil buffer.
called when dev wants to finish a render pass
Captures the current binding as a BindOptions that can be passed back to
RenderTargetSystem.bind to restore it. The capture replays non-destructively:
its clear is CLEAR.NONE, so restoring never wipes the target.
const saved = renderer.renderTarget.getBindState();
renderer.renderTarget.bind({ target: scratchTexture, clear: true });
// ... draw ...
renderer.renderTarget.bind(saved);
// or compose: the saved binding, but into mip 1
renderer.renderTarget.bind({ ...saved, mipLevel: 1 });
The capture is a snapshot owned by the caller — later binds cannot change it — and holds
target and frame as they were passed, so a Texture bound without an explicit frame
replays through its frame fallback. It stays valid for as long as its target does.
Pass out to reuse one object across captures; every field of it is overwritten.
Optionalout: BindOptionsan optional object to write the bind state into; allocated when omitted
the captured bind state (out when provided)
Gets the render target from the provide render surface. Eg if its a texture, it will return the render target for the texture. If its a render target, it will return the same render target.
the render surface to get the render target for
the render target for the render surface
Pops the current render target and restores the previous binding.
the render target that was restored
Push a render surface to the renderer. This will bind the render surface to the renderer
and store the binding on a stack, so pop() can restore the previous binding.
the bind options: see BindOptions
the render target that was bound
Push a render surface using positional arguments.
the render surface to push
Optionalclear: boolean | CLEARthe clear mode to use. Can be true or a CLEAR number 'COLOR | DEPTH | STENCIL' 0b111
OptionalclearColor: RgbaArraythe color to clear to
Optionalframe: Rectanglethe frame to use when rendering to the render surface
OptionalmipLevel: numberthe mip level to render to
Optionallayer: numberthe layer of the render surface to render to
OptionalflipY: booleanopt-in Y-orientation toggle; stored on the stack so it is restored on pop
the render target that was bound
called when the renderer starts to render a scene: resets the bind stack and binds the root render surface
the BindOptions for the root binding
A system that manages render targets. A render target is essentially a place where the shaders can color in the pixels. The render target system is responsible for binding the render target to the renderer, and managing the viewport. Render targets can be pushed and popped.
To make it easier, you can also bind textures and canvases too. This will automatically create a render target for you. The render target itself is a lot more powerful than just a texture or canvas, as it can have multiple textures attached to it. It will also give ou fine grain control over the stencil buffer / depth texture.
Example