flutter3d
Showcase Changelog 62 packages API reference

A camera into a texture

since 1.0.0-rc.1 Scene and geometry

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 calls Scene.removeRenderTexture first.