decodeBanded static method

Future<void> decodeBanded({ required String filePath, required int pageIndex, required int bandHeight, required int maxBytesPerChunk, required int workerCount, required void onBand(TiffBand band), void setUpIsolate()?, })

Decodes page pageIndex of the file at filePath in horizontal bands, spread across up to workerCount isolates — each opens its own handle on filePath (a decoded TiffImage and its underlying file handle can't cross an isolate boundary, so there's no way to share one already-open document across workers). onBand is called back on the caller's isolate once per decoded band, so it can do arbitrary work per band — write a file, accumulate into a buffer, feed a progress counter — without that work itself needing to be isolate-safe. Bands from different workers can interleave, so don't assume they arrive in increasing TiffBand y order across the whole page (they do arrive in order within any one worker's own share of it).

bandHeight is the height of each delivered TiffBand — independent of the taller, tile/strip-aligned chunk actually decoded per call (see TiffChunkPlan); one chunk decode gets sliced into bandHeight-tall pieces before delivery, so a caller that wants a tight per-band memory footprint doesn't have to give up the tile-alignment that avoids redundant redecoding.

maxBytesPerChunk bounds one worker's one in-flight chunk decode (see TiffChunkPlan.forBudget) — it is not divided by workerCount here, since up to workerCount chunks can be in flight at once. If you need the aggregate peak (workerCount * maxBytesPerChunk, roughly) bounded by some total budget, pick workerCount via TiffChunkPlan.recommendedWorkerCount against that budget and this same maxBytesPerChunk — deliberately not done automatically here, since shrinking maxBytesPerChunk to fit more workers instead reintroduces the redundant-redecode problem TiffChunkPlan exists to avoid (see its doc comment).

If the source uses a codec that needs a plugged-in decoder (JPEG, Compression 6/7 — see package:tiff/tiff_image_adapter.dart), pass setUpIsolate as a static or top-level function reference (not a closure capturing local state, which can't cross an isolate boundary) that wires it up — e.g. TiffImageAdapter.enableJpegSupport — called once in every worker isolate before that worker decodes anything.

Throws a TiffException (wrapping whatever error message a worker reported) if any worker's decode fails; the remaining workers are killed rather than left to keep running.

Implementation

static Future<void> decodeBanded({
  required String filePath,
  required int pageIndex,
  required int bandHeight,
  required int maxBytesPerChunk,
  required int workerCount,
  required void Function(TiffBand band) onBand,
  void Function()? setUpIsolate,
}) async {
  if (bandHeight <= 0) {
    throw ArgumentError.value(bandHeight, 'bandHeight', 'must be > 0');
  }
  if (workerCount <= 0) {
    throw ArgumentError.value(workerCount, 'workerCount', 'must be > 0');
  }

  final metadataSource = FileByteSource.open(File(filePath));
  final int width;
  final List<(int, int)> chunks;
  try {
    final document = TiffDecoder.decodeSource(metadataSource);
    if (pageIndex < 0 || pageIndex >= document.images.length) {
      throw ArgumentError.value(
        pageIndex,
        'pageIndex',
        'out of range (page count: ${document.images.length})',
      );
    }
    final metadata = document.images[pageIndex].metadata;
    width = metadata.width;
    chunks = TiffChunkPlan.forBudget(
      metadata,
      maxBytesPerChunk: maxBytesPerChunk,
    ).chunks;
  } finally {
    metadataSource.close();
  }
  if (chunks.isEmpty) return;

  final effectiveWorkerCount = workerCount < chunks.length
      ? workerCount
      : chunks.length;
  final chunksByWorker = List.generate(
    effectiveWorkerCount,
    (_) => <(int, int)>[],
  );
  for (var i = 0; i < chunks.length; i++) {
    chunksByWorker[i % effectiveWorkerCount].add(chunks[i]);
  }

  final receivePort = ReceivePort();
  final isolates = <Isolate>[];
  String? workerError;
  try {
    for (final assigned in chunksByWorker) {
      isolates.add(
        await Isolate.spawn(_bandWorkerEntry, (
          receivePort.sendPort,
          filePath,
          pageIndex,
          width,
          bandHeight,
          assigned,
          setUpIsolate,
        )),
      );
    }

    var finishedWorkers = 0;
    await for (final message in receivePort) {
      if (message is (int, int, Uint8List)) {
        final (y, height, rgba) = message;
        onBand((y: y, height: height, rgba: rgba));
      } else if (message == true) {
        finishedWorkers++;
        if (finishedWorkers == effectiveWorkerCount) break;
      } else {
        workerError = message as String;
        break;
      }
    }
  } finally {
    for (final isolate in isolates) {
      isolate.kill(priority: Isolate.immediate);
    }
    receivePort.close();
  }
  if (workerError != null) throw TiffException(workerError);
}