flutter3d
Showcase Changelog 62 packages API reference

Lens effects

since 1.0.0-rc.1 Post-processing

Three things a real lens does to a picture, all of them settings on the composite or the glow. A very bright light throws ghosts and a ring across the frame. The glass bends the frame, outwards like a wide lens or inwards like a long one. And a colourist hands over a grade as a .cube file, which the engine reads as it is.

This page puts a lamp far brighter than the display in the top left of the post-processing stage and runs all three over it.

Step 1: A light bright enough to flare #

The flare is drawn from the glow, so only what blooms flares. The lamp is a small sphere with an emission forty times over the display's white, placed so that the line from it through the middle of the frame crosses the shapes on the floor. Nothing else in the scene is bright enough to throw a ghost.

// A lamp far brighter than the display can show, up and to the left, so
// its glow is strong enough to flare and its ghosts cross the middle.
final MeshNode lamp = MeshNode(
  DeviceMesh.upload(
    context.device,
    const SphereShape(radius: 0.25).build(),
  ),
  RenderMaterial(
    name: 'lamp',
    baseColor: LinearColor.fromSrgb(0.1, 0.1, 0.1, 1.0),
    emissive: LinearColor(1.0, 0.85, 0.6),
    emissiveStrength: 40.0 * RenderMaterial.defaultEmissiveStrength,
  ),
  name: 'lamp',
)..setPosition(-3.2, 2.8, -2.0);

Step 2: Turn on the flare and bend the frame #

BloomSettings.lensFlare takes a LensFlareSettings. With it enabled, the glow's bright spots are reflected through the middle of the frame as a row of ghosts, each with its colours pulled slightly apart at the rim, and a ring is drawn at haloRadius from the middle. halo is the ring's strength against the ghosts; nought draws none. A ghost is as soft as the glow it is drawn from, so this page asks for three bloom levels instead of five. With five, the ghosts spread into a wash across half the frame.

LookSettings.distortion bends the frame radially about its middle. Above nought is barrel, the corners held and the middle pushed out; below nought is pincushion. The bend is applied once in the composite, before anything is read, so the glow and the flare bend with the scene. The vignette, the grain and the dither do not move, because they belong to the film and not to the glass. Drag Distortion through nought to see it change direction.

final BloomSettings bloom = BloomSettings(
  // Three levels rather than five keep the glow, and so each ghost,
  // tight enough to read as a disc rather than a wash.
  levels: 3,
  lensFlare: LensFlareSettings(enabled: flare, halo: halo),
);
_look = LookSettings(distortion: distortion, lut: _strips[table]);

Step 3: Tables from a grading tool #

A .cube file is plain text: a size, then one line of three numbers per entry, red changing fastest. The warm table here is the smallest 3D table there is, the eight corners of the colour cube, and every colour between them is blended from those corners. The curve is a 1D table, one S curve applied to each channel on its own. Both are written inline, but a file read with rootBundle.loadString goes through the same call.

/// A warm grade as a `.cube` file: the eight corners of the colour cube,
/// red running fastest. Black is lifted a little towards blue, white is
/// pulled towards amber, and everything between is blended from the corners.
const String _warmCube = '''
TITLE "Warm highlights"
LUT_3D_SIZE 2
0.04 0.02 0.06
1.00 0.10 0.02
0.06 0.92 0.04
1.00 0.96 0.10
0.02 0.06 0.80
0.95 0.10 0.78
0.06 0.95 0.86
1.00 0.97 0.88
''';

/// A contrast curve as a 1D `.cube`: the same S on each channel, darker
/// shadows and brighter highlights with the middle left where it was.
const String _curveCube = '''
TITLE "S curve"
LUT_1D_SIZE 5
0.00 0.00 0.00
0.15 0.15 0.15
0.50 0.50 0.50
0.85 0.85 0.85
1.00 1.00 1.00
''';

CubeLut.parse reads the text and throws a FormatException naming the line when something is wrong with it. upload resamples whatever the file holds into the strip that LookSettings.lut grades through, and puts it on the device. Pick a table with Table.

_warm = CubeLut.parse(_warmCube);
_strips = <TextureHandle?>[
  null,
  _warm.upload(context.device),
  CubeLut.parse(_curveCube).upload(context.device),
];

Step 4: What the page checks #

The flare has to have run as a pass of its own. The warm table has to give back the file's own numbers at the white corner and turn a middle grey warmer than it went in, with more red than blue. The uploaded table has to have reached the device, and the composite, which bends the frame and reads the table, has to have run.

// The flare is a pass of its own, drawn from the glow.
if (flare && !passRan(frame, 'lens flare')) {
  throw StateError('the lens flare did not run: ${frame.skipped}');
}
// The table reads back what the file says at a corner, and a middle grey
// comes out of it warmer than it went in: more red than blue.
final RgbTriple(:r, :g, :b) = _warm.lookup(1.0, 1.0, 1.0);
// Held as 32-bit floats, so compared to within a millionth.
if ((r - 1.0).abs() > 1e-6 ||
    (g - 0.97).abs() > 1e-6 ||
    (b - 0.88).abs() > 1e-6) {
  throw StateError('white maps to ($r, $g, $b), not the file\'s corner');
}
final RgbTriple(r: gr, b: gb) = _warm.lookup(0.5, 0.5, 0.5);
if (gr <= gb + 0.05) {
  throw StateError('mid grey is not warmer: red $gr, blue $gb');
}
if (table != 0 && (_strips[table] == null || !_look.gradesThroughLut)) {
  throw StateError('the table did not reach the device');
}
// The composite bends the frame and reads the table.
if (!passRan(frame, 'composite')) {
  throw StateError('the composite pass is absent');
}

Note. The check reads the table and the pass list, not the pixels: the claim that the flare lands where the ghosts should is held by the lens-flare and lens-distortion reference images, recorded on all four backends. There is no anamorphic streak yet, and no starburst from an aperture texture. The table is applied after the picture is encoded for the display, so values outside nought and one are clamped before it reads them.