composite method

void composite({ required Buffer target, required List<LayeredBuffer> layers, })

Flattens layers onto target in descending Z-index order (topmost first).

Uses a bit-packed Uint32List occlusion map to prevent redundant writes and supports early exit if all destination cells are covered by opaque cells.

Implementation

void composite({
  required Buffer target,
  required List<LayeredBuffer> layers,
}) {
  Tracer.record(_traceCompositeId, Phase.begin, TraceCategory.compositor);
  try {
    if (layers.isEmpty) return;

    // Stable sort in descending order (highest zIndex first)
    final sortedLayers = List<LayeredBuffer>.from(layers);
    final originalIndices = {
      for (var i = 0; i < layers.length; i++) layers[i]: i,
    };
    sortedLayers.sort((a, b) {
      final cmp = b.zIndex.compareTo(a.zIndex);
      if (cmp != 0) return cmp;
      return originalIndices[b]!.compareTo(originalIndices[a]!);
    });

    _poolIndex = 0;
    _compositeRecursive(target, sortedLayers, 0);
  } finally {
    Tracer.record(_traceCompositeId, Phase.end, TraceCategory.compositor);
  }
}