Variants and animation pointers: the source

since 0.8.0 Formats and I/O
Open the live demo · Read the guide · View on GitHub
Regions the guide quotes: materials (line 33), variants (line 59), clip (line 76), roundtrip (line 108), bind (line 153), play (line 166), select (line 175), tick (line 182), check (line 212).
1/// A model that changes its look by name, and a clip that animates a material
2/// and a light, both written into a GLB and read back.
3///
4/// Quoted by `variants_and_pointers.md` and shown whole in the Source tab.
5library;

7import 'dart:typed_data';

9import 'package:flutter3d/flutter3d.dart';
10import 'package:flutter3d_showcase/src/demo/demo.dart';
11import 'package:vector_math/vector_math.dart';

13final class VariantsAndPointersDemo extends ShowcaseDemo {
/// 0 is the default look, then one option for each of the file's variants.
int variant = 1;

late final GltfAsset _readBack;
late final ModelAsset _asset;
late final ModelInstance _instance;
late final AnimationPlayer _player;
late final LightNode _sun;

@override
void configureView(DemoContext context) {
  context.orbit
    ..distance = 4.5
    ..pitch = 0.35
    ..yaw = 0.6;
}

@override
Future<void> prepare(DemoContext context) async {
  // Five materials. The body wears the first and the ball the second
  // unless a variant says otherwise; the other three are only ever worn
  // through a variant.
  final List<SurfaceMaterial> materials = <SurfaceMaterial>[
    SurfaceMaterial(name: 'red paint', baseColor: Vector4(0.6, 0.2, 0.15, 1)),
    SurfaceMaterial(
      name: 'cream',
      baseColor: Vector4(0.6, 0.55, 0.45, 1),
      roughness: 0.6,
    ),
    SurfaceMaterial(
      name: 'teal paint',
      baseColor: Vector4(0.12, 0.45, 0.42, 1),
    ),
    SurfaceMaterial(
      name: 'graphite',
      baseColor: Vector4(0.2, 0.2, 0.22, 1),
      roughness: 0.35,
    ),
    SurfaceMaterial(
      name: 'chalk',
      baseColor: Vector4(0.55, 0.55, 0.55, 1),
      roughness: 0.8,
    ),
  ];

  // `variantMaterials` maps a variant, by its index in `variants`, to the
  // material the surface wears in it. The body changes in both variants;
  // the ball only in "graphite".
  final List<ModelSurface> surfaces = <ModelSurface>[
    ModelSurface(
      mesh: CuboidShape(size: Vector3(1.2, 0.8, 0.8)).build(),
      materialIndex: 0,
      variantMaterials: const <int, int>{0: 2, 1: 3},
    ),
    ModelSurface(
      mesh: SphereShape(radius: 0.4, segments: 32, rings: 16).build(),
      materialIndex: 1,
      variantMaterials: const <int, int>{1: 4},
    ),
  ];
  const List<String> variants = <String>['teal', 'graphite'];

  // Two pointer tracks and no node track. One warms the ball's material
  // (index 1) from cream to amber and back; the other dims the file's
  // light (index 0) from 110 lux to 45 and back. Colour keys are linear,
  // as glTF keeps them; the first is the cream above.
  AnimationTrack track(AnimationPointer pointer, List<double> values) =>
      AnimationTrack(
        nodeIndex: -1,
        path: AnimationPath.pointer,
        interpolation: AnimationInterpolation.linear,
        times: Float32List.fromList(<double>[0.0, 1.5, 3.0]),
        values: Float32List.fromList(values),
        componentCount: pointer.property.componentCount,
        pointer: pointer,
      );
  final AnimationClip evening = AnimationClip(
    name: 'evening',
    tracks: <AnimationTrack>[
      track(
        AnimationPointer.of(AnimationPointerProperty.baseColor, 1),
        <double>[
          0.319, 0.262, 0.171, 1, //
          0.32, 0.09, 0.02, 1, //
          0.319, 0.262, 0.171, 1,
        ],
      ),
      track(
        AnimationPointer.of(AnimationPointerProperty.lightIntensity, 0),
        <double>[110, 45, 110],
      ),
    ],
  );

  final PlainModelDocument document = PlainModelDocument(
    surfaces: surfaces,
    materials: materials,
    lights: <ModelLight>[
      ModelLight(type: ModelLightType.directional, intensity: 110),
    ],
    nodes: <ModelNode>[
      ModelNode(
        name: 'body',
        surfaces: <int>[0],
        translation: Vector3(0, 0.4, 0),
      ),
      ModelNode(
        name: 'ball',
        surfaces: <int>[1],
        translation: Vector3(0, 1.2, 0),
      ),
      ModelNode(name: 'sun', lightIndex: 0),
    ],
    variants: variants,
    animations: <AnimationClip>[evening],
  );
  final Uint8List bytes = GltfWriter(document).writeGlb();
  _readBack = await GltfLoader().load(bytes);
  _asset = await ModelAsset.fromDocument(_readBack, device: context.device);
}

@override
Scene build(DemoContext context) {
  final Scene scene = Scene()
    ..add(
      MeshNode(
        DeviceMesh.upload(
          context.device,
          const PlaneShape(width: 8, depth: 8).build(),
        ),
        Material(
          name: 'floor',
          baseColor: Vector4(0.45, 0.45, 0.45, 1.0),
          roughness: 0.9,
        ),
        name: 'floor',
      ),
    );

  // Instantiating creates no lights, so the page places its own sun and
  // hands it to the instance as the file's light 0. The intensity track
  // reaches it through `pointerTargets`; the material tracks reach the
  // asset's materials the same way, by their index in the file.
  _instance = _asset.instantiate(scene);
  final ModelLight light = _readBack.lights.single;
  _sun = LightNode(
    name: 'sun',
    color: light.color,
    intensity: Photometric.fromLux(light.intensity),
  )..setLocalForward(Vector3(-0.5, -0.8, -0.4));
  _instance.bindLight(0, _sun);

  // The page opens halfway through the clip, where both tracks are
  // furthest from what the file says, and plays on from there.
  _player = _instance.player!
    ..play(0)
    ..seek(1.5);
  _wear(variant);
  return scene..add(_sun);
}

void _wear(int option) {
  variant = option;
  _instance.selectVariant(option == 0 ? null : _asset.variants[option - 1]);
}

@override
void update(DemoContext context, double dt) {
  _player.update(dt);
}

@override
List<DemoControl> controls(DemoContext context) => <DemoControl>[
  ChoiceControl(
    'Variant',
    options: <String>['Default', ..._asset.variants],
    index: () => variant,
    onChanged: _wear,
  ),
  ToggleControl(
    'Play clip',
    value: () => _player.isPlaying,
    onChanged: (bool v) => v ? _player.play() : _player.pause(),
  ),
  SliderControl(
    'Time',
    min: 0,
    max: _player.duration,
    value: () => _player.time,
    onChanged: (double v) => _player
      ..pause()
      ..seek(v),
    format: (double v) => '${v.toStringAsFixed(2)} s',
  ),
];

@override
void verify(Scene scene, FrameResult frame) {
  // One mesh node a surface, in the order the nodes are walked: the body,
  // then the ball. Each must point at the material the file gives it in
  // the variant being worn, and that material is the asset's own.
  final int worn = _instance.variant == null
      ? -1
      : _asset.variants.indexOf(_instance.variant!);
  for (var i = 0; i < _readBack.surfaces.length; i++) {
    final ModelSurface surface = _readBack.surfaces[i];
    final int expected =
        surface.variantMaterials[worn] ?? surface.materialIndex!;
    if (!identical(
      _instance.meshes[i].material,
      _asset.materials[expected],
    )) {
      throw StateError(
        'surface $i is not wearing material $expected, which '
        '${_instance.variant ?? 'the default look'} gives it',
      );
    }
  }

  // The clip is past its first key, so both tracks have moved their
  // targets away from what the file says.
  final Vector4 authored = _readBack.materials[1].baseColor;
  final Vector4 now = _asset.materials[1]!.baseColor;
  if ((now.xyz - authored.xyz).length < 0.05) {
    throw StateError("the colour track did not move the ball's material");
  }
  final double fileSun = Photometric.fromLux(_readBack.lights[0].intensity);
  if ((_sun.intensity - fileSun).abs() < 0.1) {
    throw StateError('the intensity track did not move the sun');
  }
  if (frame.drawCalls < 1) {
    throw StateError('the model was not drawn');
  }
}
248}