render method

Future<bool> render(
  1. Render3DScene scene,
  2. Render3DView view,
  3. GpuSurface surface, {
  4. int? frame,
})

Draws scene seen from view into a new frame of surface and presents it. Completes when the GPU has finished.

frame names the displayed frame the view is drawn in (an engine's frame number): views drawn in one displayed frame share it, so the intermediate targets they use are kept for RenderTargetPool.keepFrames displayed frames, not renders.

If recording fails, the frame is given back unpresented, what it held is let go of, and the error is rethrown.

Implementation

Future<bool> render(
  Render3DScene scene,
  Render3DView view,
  GpuSurface surface, {
  int? frame,
}) {
  final caps = device.caps;
  final hdr = caps.hdrRenderTarget;
  final width = math.max(1, view.width), height = math.max(1, view.height);
  if (surface.width != width || surface.height != height) {
    surface.resize(width, height);
  }

  device.beginFrame();
  _resetStats();
  _engineViewProjection.setProduct(view.projection, view.view);
  _frustum.setFromViewProjection(_engineViewProjection);
  ClipFixup.flipY(view.projection, _gpuProjection);
  _gpuViewProjection.setProduct(_gpuProjection, view.view);

  _collect(scene, view);
  _fitShadows(scene, view);
  final joints = skinning == SkinningMode.texture
      ? _packPalettes(scene)
      : null;

  GpuSurfaceFrame? target;
  GpuCommands? commands;
  try {
    final frameUniforms = device.frameData(
      _frameBlock(scene, view, toDisplay: !hdr, shadowed: _cascades > 0),
    );
    final lightUniforms = device.frameData(_lightsBlock(scene, view));
    target = surface.acquire();
    commands = device.commands();
    _record(
      commands,
      target,
      scene,
      view,
      joints,
      frameUniforms,
      lightUniforms,
      width,
      height,
    );
  } on Object {
    target?.discard();
    commands?.abandon();
    targets.endFrame(frame: frame);
    if (joints != null) _returnJoints(joints);
    rethrow;
  }

  final Future<bool> done;
  try {
    done = commands.submit(present: target);
  } finally {
    targets.endFrame(frame: frame);
  }
  _inFlight++;
  unawaited(
    done.then(
      (_) {
        _inFlight--;
        if (joints != null) _returnJoints(joints);
      },
      onError: (Object _) {
        _inFlight--;
      },
    ),
  );
  return done;
}