flutter3d
Showcase Changelog 62 packages API reference

Decals

since 1.0.0-rc.1 Scene and geometry

A scorch on a floor, a puddle, a sign painted on a wall: none of these needs polygons of its own. A DecalNode is a box. Whatever geometry stands inside it takes the decal's colour, and the box itself is never drawn.

The decal changes the colour of the surface, not the light falling on it. The renderer reads back how much light each pixel got and lays the decal's colour under that same light, so a decal in a shadow stays in the shadow. In this scene the crate's shadow falls across the blue patch and darkens it like the floor around it.

Step 1: A room with something to paint on #

A floor, a wall, a crate on the floor and a sun that casts shadows. Nothing here knows about decals.

final Scene scene = Scene()
  ..ambientColor = LinearColor(0.55, 0.6, 0.7)
  ..ambientIntensity = 0.35 * LightNode.legacyUnit
  ..add(
    _slab(
      context,
      'floor',
      Vector3(6.0, 0.1, 6.0),
      Vector3(0.0, -0.05, 0.0),
      Vector4(0.8, 0.8, 0.78, 1.0),
    ),
  )
  ..add(
    _slab(
      context,
      'wall',
      Vector3(6.0, 3.0, 0.1),
      Vector3(0.0, 1.5, -2.0),
      Vector4(0.82, 0.8, 0.76, 1.0),
    ),
  )
  ..add(
    // A crate standing in the stain's box: its top takes the stain, and
    // its sides only as far as the angle limit lets them.
    _slab(
      context,
      'crate',
      Vector3(0.6, 0.6, 0.6),
      Vector3(0.5, 0.3, 0.4),
      Vector4(0.7, 0.62, 0.5, 1.0),
    ),
  )
  ..add(
    LightNode(
      name: 'sun',
      intensity: 2.0 * LightNode.legacyUnit,
      castsShadow: true,
    )..setLocalForward(Vector3(-0.4, -0.8, -0.35)),
  );

Step 2: Lay two decals on the floor #

The box is the node's unit cube, from minus a half to a half on each axis. So the node's scale sets the decal's size: x and z for the picture, y for how deep it reaches. With no rotation the box lies flat and stamps down its own y axis, which is what a floor needs.

color is an sRGB tint, and its w is the opacity. There is no texture here, so each decal paints its tint alone, which is enough for a stain. A texture would be multiplied by the tint, and region picks one cell of an atlas.

The red stain's box is 1.4 m tall, so it reaches the top of the crate as well as the floor around it.

// With no rotation a decal's box lies flat and stamps down its own y
// axis: x and z are the size of the picture, y how deep it reaches.
_stain =
    DecalNode(
        name: 'stain',
        color: LinearColor.fromSrgb(0.85, 0.2, 0.1, opacity),
      )
      ..setPosition(0.3, 0.0, 0.3)
      ..setScale(2.0, 1.4, 2.0);
_puddle =
    DecalNode(
        name: 'puddle',
        color: LinearColor.fromSrgb(0.15, 0.3, 0.9, opacity),
      )
      ..setPosition(-0.6, 0.0, 0.6)
      ..setScale(1.8, 0.4, 1.4);
scene
  ..add(_stain)
  ..add(_puddle);

Step 3: Turn a box to face a wall #

To put a decal on a wall, rotate the box until its up points out of the wall. A quarter turn about x points it along +z, toward the camera, and the yellow sign lands on the wall.

// On a wall the box is turned until its up points out of the wall.
_sign =
    DecalNode(
        name: 'sign',
        color: LinearColor.fromSrgb(0.95, 0.8, 0.1, 1.0),
      )
      ..setPosition(-1.2, 1.6, -1.95)
      ..setScale(1.4, 0.3, 0.8);
_sign.setRotation(
  Quaternion.axisAngle(Vector3(1.0, 0.0, 0.0), math.pi / 2),
);
scene.add(_sign);

Step 4: Decide which decal is on top #

Where two decals overlap, the higher order is painted over the lower. When two decals have the same order, the one attached later goes on top. Switch Blue over red to swap them where the puddle crosses the stain.

// Where the two floor decals overlap, the higher order is painted over
// the lower one.
_puddle.order = blueOnTop ? 1 : 0;
_stain.order = blueOnTop ? 0 : 1;

Step 5: Keep a decal off the sides #

angleLimit is the angle from the box's up past which a surface takes none of the decal. The default is seventy-five degrees, so a stain on the floor stays off the walls around it instead of smearing down them. The crate's sides are at ninety degrees, so they stay clean. Drag Angle limit past 90° and the stain runs down them too. angleFade softens that edge, and depthFade softens the top and bottom of the box.

// The crate's sides turn ninety degrees from the stain's up: a limit
// under ninety keeps the stain off them, one past it paints them too.
_stain.angleLimit = angleLimitDegrees * math.pi / 180.0;

Step 6: Switch the pass on #

Decals are off by default. DecalSettings(enabled: true) turns on the pass that paints them. It runs between the opaque half of the scene and the transparent half, so glass in front of a decal is drawn over it. The pass needs three colour attachments and turns multisampling off for the frame, as everything that reads the surface buffer does. Switch Decals off and the room is bare again.

decals: DecalSettings(enabled: decals),

Step 7: What the page checks #

The scene holds the three decals, and the frame ran the decals pass instead of culling or skipping it.

// Three decals in the scene and the switch on: the pass that paints them
// has to have run, not been culled or skipped.
if (scene.decals.length != 3) {
  throw StateError('the scene holds ${scene.decals.length} decals, not 3');
}
final PassSkip? skipped = frame.skipReasonOf('decals');
if (skipped != null) {
  throw StateError('the decal pass was skipped: $skipped');
}
if (!frame.passes.any((FramePass p) => p.name == 'decals')) {
  throw StateError('the decal pass did not run');
}

Note. A decal paints the albedo only. It does not change a normal or a roughness, so a painted crack catches the light the way the wall under it does. Up to sixteen decals and four pictures go into one draw, and more are drawn in further batches.