fromCommands static method

Future<PdfRetainedScene> fromCommands(PdfPage page, List<PdfRenderCommand> commands, { PdfPageRenderPlan plan = const PdfPageRenderPlan(), bool includeImages = true, bool retainDecodedPixels = false, PdfSceneBuildTiming? timing, double? maxImagePixelRatio, })

Builds a scene from an already-recorded commands buffer (e.g. one a PdfRenderWorker shipped back), decoding its images once. The buffer must have been recorded for page under plan. Set includeImages to false for a deliberate vector-only progressive buffer; image draws then stay transparent until a complete scene replaces it.

timing, when non-null, receives the duration of the decode pass - the perf log's way of splitting the render 'build' phase into image decode vs the canvas-call construction that follows. Null (the default) measures nothing.

maxImagePixelRatio caps each image decode to display resolution (decodeImages). This is the path that pays for a JPEG the worker shipped un-decoded (it cannot run the platform codec); the cap keeps that UI-thread decode at display size instead of the image's full native resolution.

Implementation

static Future<PdfRetainedScene> fromCommands(
  PdfPage page,
  List<PdfRenderCommand> commands, {
  PdfPageRenderPlan plan = const PdfPageRenderPlan(),
  bool includeImages = true,
  bool retainDecodedPixels = false,
  PdfSceneBuildTiming? timing,
  double? maxImagePixelRatio,
}) async {
  Map<Object, ui.Image> images = const <Object, ui.Image>{};
  final requests = <PdfImageRequest>[];
  if (includeImages) {
    PdfPageRenderer.collectImageRequests(commands, requests);
    // The clock exists only when a caller asked for the split; an ordinary
    // render never pays for it.
    final clock = timing == null ? null : (Stopwatch()..start());
    images = await decodeImages(page.document.cos, requests,
        cache: PdfImageCache.instance,
        maxImagePixelRatio: maxImagePixelRatio,
        imageDecodeHeadroom: 1);
    if (!retainDecodedPixels) {
      _releaseDecodedImagePixels(requests, images);
    }
    if (clock != null) {
      timing!.decodeMs = clock.elapsedMicroseconds / 1000.0;
    }
  }
  final retainedRequests = !retainDecodedPixels
      ? null
      : <PdfImageRequest>[
          for (final request in requests)
            if (request.decoded != null &&
                images.containsKey(pdfImageKey(request)))
              request,
        ];
  return PdfRetainedScene._(
    page,
    plan,
    commands,
    images,
    retainedRequests,
  );
}