A camera into a texture
Open the live demo · Read the source · View on GitHub
A security monitor, a portal, a minimap: each is a picture of the scene,
taken by a camera that is not the one you are looking through, and shown on a
surface in the scene. RenderTexture is that picture. The scene draws it
before its own meshes in the same frame, so the monitor shows what the room
looks like now, not one frame ago.
Step 1: A second camera #
An ordinary CameraNode with its own projection, added to the scene like any
other node so it can be moved and aimed. The aspect comes from the texture it
draws into.
// An ordinary camera, put in the scene like any node, with a projection
// of its own. The texture sets its aspect.
_watcher = CameraNode(name: 'watcher')
..projection = const PerspectiveProjection(
fieldOfView: math.pi / 4,
near: 0.1,
far: 50.0,
)
..setPosition(-3.0, 1.6, 2.4)
..lookAt(Vector3(-0.9, 0.4, 0.0));
scene.add(_watcher);
Step 2: A texture for it to draw into #
RenderTexture.create makes a texture of the given size on the device and
ties it to the camera. The picture is drawn with the frame's lights, shadows
and sky, and no post-processing chain runs on it. Particles and splats are
not in it either. clearColor shows where nothing was drawn.
The texture holds sRGB bytes, the way a picture loaded from a file does. That means it goes into a material's albedo or emissive slot exactly as an image would.
_picture = CameraView.texture(
context.device,
camera: _watcher,
width: 160,
height: 120,
clearColor: LinearColor.fromSrgb(0.35, 0.45, 0.6, 1.0),
);
Step 3: Show it on a screen #
The screen is an unlit plane, so it shows the picture as the camera took it.
A lit plane would light the picture again, like a printed photograph in the
room. A PlaneShape stood up has its v running down, the way a picture's rows
do, so the picture comes out the right way up. The sides of a CuboidShape
run v upward and would show it upside down.
// An unlit plane shows the picture exactly as the camera took it. A
// plane stood up has v running down it, the way a picture's rows do.
final MeshNode screen = MeshNode(
DeviceMesh.upload(
context.device,
const PlaneShape(width: 1.6, depth: 1.2).build(),
),
RenderMaterial(
name: 'screen',
lighting: LightingModel.unlit,
albedo: _picture.texture,
),
name: 'screen',
)..setPosition(1.4, 1.3, -0.6);
screen.setRotation(
Quaternion.axisAngle(Vector3(0.0, 1.0, 0.0), -0.4) *
Quaternion.axisAngle(Vector3(1.0, 0.0, 0.0), math.pi / 2),
);
final MeshNode stand = _slab(
context,
'stand',
Vector3(0.12, 0.7, 0.12),
Vector3(1.4, 0.35, -0.6),
Vector4(0.2, 0.2, 0.22, 1.0),
);
scene
..add(screen)
..add(stand);
Step 4: Leave the screen out and add the texture #
excluded lists meshes the camera does not draw. Without it, the monitor
would hold its own back in the picture. Scene.addRenderTexture is what has
the texture drawn each frame, in a render textures pass before the scene's
own.
// The monitor is left out of its own picture, and the texture joins the
// scene, which draws it before the frame's own meshes.
_picture.excluded.addAll(<MeshNode>[screen, stand]);
scene.addTextureView(_picture);
Step 5: Every frame, or only when asked #
refreshEveryFrame is on by default. Off, the texture is drawn once, and
again only after invalidate. A portrait of a room where nothing moves is
one picture, not sixty a second. Switch Every frame off and the blue block
on the screen stops turning while the one in the room keeps going. Take the
picture again calls invalidate, and the next frame takes one new picture.
// Every frame, or once and then only when asked: a picture of a room
// nobody changes does not need taking sixty times a second.
_picture.settings = _picture.settings.copyWith(
refreshEveryFrame: everyFrame,
);
if (_retakeAsked) {
_retakeAsked = false;
_picture.invalidate();
}
Step 6: What the page checks #
The frame ran the render textures pass, and the texture holds a picture
instead of whatever its allocation held before.
// The pass that draws the scene's textures ran, and the texture holds a
// picture rather than whatever its allocation held.
final PassSkip? skipped = frame.skipReasonOf('render textures');
if (skipped != null) {
throw StateError('the render textures pass was skipped: $skipped');
}
if (!frame.passes.any((FramePass p) => p.name == 'render textures')) {
throw StateError('the render textures pass did not run');
}
if (!_picture.isDrawn) {
throw StateError('the camera never drew into its texture');
}
Note. The texture belongs to whoever made it. When the page is left it is given back with
Renderer.releaseTextureAfterFrame, and a game that switches a monitor off callsScene.removeRenderTexturefirst.