flutter3d
Showcase Changelog 62 packages API reference

Planar reflections

since 1.0.0-rc.1 Light and environment

Screen-space reflections can only show what is already on the screen, and a reflection probe is a picture of the room taken from one point, which slides across a large floor. A flat mirror, a polished floor or a still pool can do better, because a flat surface reflects exactly what a camera mirrored in its plane would see.

That is what this page does. Each frame the scene is drawn a second time through the view's camera mirrored in the floor's plane, and that picture is laid over the floor. The near plane of the mirrored camera is moved onto the floor, so nothing below the floor is reflected up through it.

Step 1: The floor #

A dark, smooth floor. It keeps its own material: it is lit, shadowed and textured as any floor would be, and the reflection goes on top.

// A dark polished floor: the surface the reflection is laid over. It keeps
// its own material, lit and shadowed as any floor is.
final MeshNode floor = MeshNode(
  DeviceMesh.upload(
    context.device,
    const PlaneShape(width: 14, depth: 14).build(),
  ),
  RenderMaterial(
    name: 'polished floor',
    baseColor: LinearColor.fromSrgb(0.08, 0.08, 0.09, 1.0),
    roughness: 0.2,
  ),
  name: 'floor',
);

Step 2: Something to reflect #

A red ball, a gold metal block and a tall blue post. The post is the easiest to follow in the reflection as you orbit.

// Something to see in it: a red ball, a gold block and a tall blue post.
scene
  ..add(
    MeshNode(
      DeviceMesh.upload(
        context.device,
        SphereShape(radius: 0.8, segments: 32, rings: 16).build(),
      ),
      RenderMaterial(
        name: 'red',
        baseColor: LinearColor.fromSrgb(0.8, 0.12, 0.1, 1.0),
      ),
      name: 'ball',
    )..setPosition(-1.2, 0.8, 0.4),
  )
  ..add(
    MeshNode(
      DeviceMesh.upload(
        context.device,
        CuboidShape(size: Vector3(1.0, 1.0, 1.0)).build(),
      ),
      RenderMaterial(
        name: 'gold',
        baseColor: LinearColor.fromSrgb(1.0, 0.75, 0.3, 1.0),
        metallic: 1.0,
        roughness: 0.3,
      ),
      name: 'block',
    )..setPosition(1.3, 0.5, -0.3),
  )
  ..add(
    MeshNode(
      DeviceMesh.upload(
        context.device,
        CuboidShape(size: Vector3(0.4, 3.0, 0.4)).build(),
      ),
      RenderMaterial(
        name: 'blue',
        baseColor: LinearColor.fromSrgb(0.15, 0.3, 0.8, 1.0),
      ),
      name: 'post',
    )..setPosition(0.2, 1.5, -2.0),
  );

Step 3: The reflector #

A PlanarReflectorNode is the plane: it passes through the node's origin, with its local +Y as the side the reflection is seen from. A camera below the floor sees no reflection, as one under a pool sees none. surfaces are the meshes that lie in the plane, here the floor. They are left out of the reflection themselves, since they stand where the mirrored camera's clip would cut them in half.

reflectance is how much is reflected looking straight down at the plane: one for a mirror, which reflects everything at every angle, and about 0.02 for water, which reflects little looking down and nearly everything at a grazing angle. resolution is the size of the reflection's picture as a fraction of the view's, half by default, which is a quarter of the pixels.

// The plane is the node's own: through its origin, seen from its +Y. The
// floor lies in it, so the floor is the surface the picture goes on.
_mirror = PlanarReflectorNode(
  surfaces: <MeshNode>[floor],
  reflectance: reflectance,
  resolution: resolution,
  name: 'mirror',
);
scene.add(_mirror);

Step 4: Switch it on #

RenderSettings.planarReflections is off by default. With it off, the reflector costs nothing. With it on, a pass called planar reflections runs before the scene and draws the mirrored picture for every view that sees the plane's front.

Switch Planar reflections off and on. Drag Reflectance down towards 0.02 and orbit to a low angle: the floor reflects little from above and nearly everything near the horizon, as water does. Raise it to one for a mirror. Lower Resolution and the reflection softens.

planarReflections: PlanarReflectionSettings(enabled: reflections),

Step 5: What the frame should show #

With the switch on, the pass runs and the mirrored camera draws the three objects that stand above the floor. With it off, the pass does not run.

// On, the mirrored camera draws the scene before the scene pass does: the
// three objects, not the floor, which stands in the plane.
final FramePass? pass = frame.passes
    .where((FramePass p) => p.name == 'planar reflections')
    .firstOrNull;
if (!reflections) {
  if (pass != null) throw StateError('off should not run the pass');
  return;
}
if (pass == null) {
  throw StateError('the reflection was not drawn: ${frame.skipped}');
}
if (pass.drawCalls < 3) {
  throw StateError(
    'the mirrored camera drew ${pass.drawCalls} meshes; three stand '
    'above the floor',
  );
}

Note. A reflection costs a second picture of the scene per view, drawn with the frame's lights, shadows and sky. Nothing inside it is reflected again, and particles and other contributors do not reach it.