GPUTraceTemporalIndex

Overview

GPUTraceTemporalIndex converts immutable per-batch trace summaries into stable, source-ordered candidate lists for the current viewport and semantic zoom level. It is exported from @luma.gl/experimental/gpu-trace because time intervals, span duration, and trace renderer groups are domain concepts; its scan and stable compaction stages reuse generic GPU scheduling primitives.

GitHub

Scroll page · Ctrl/⌘ + scroll to interact

The live viewer feeds the same candidate output to exact spans, density aggregation, labels, dependencies, and picking. This prevents independent viewport tests from disagreeing or visibly flickering as the view changes.

At a glance

Question	Answer
Problem	Select stable source-ordered trace candidates for a viewport and semantic zoom level.
Reads / writes	Reads persistent per-batch time/lane summaries; writes bounded candidate batches, counts, and diagnostics.
Ownership	Public inputs and outputs are caller-owned; scratch storage is graph-owned transient memory.
Output contract	Capacity is fixed at compilation; counts and diagnostics report incomplete or overflowed output.
Expected work	Queries the chosen hierarchy level, then scans and stably compacts candidate ranges.
Chunks	Publishes candidates in canonical batch/source order.
Conditions / budgets	Index construction can be resumable; unchanged viewport generations reuse cached candidates.
Neighborhood	trace summaries + viewport → GPUTraceTemporalIndex → spans, labels, dependencies, picking, analytics.

CostChosen level and overlapping partitions, not total canonical span count.

Common mistakeDo not bin in moving screen coordinates; stable trace-time boundaries prevent pan flicker.

Usage

import {
  GPUTraceTemporalIndex,
  GPUTraceTemporalIndexBuilder
} from '@luma.gl/experimental/gpu-trace';

new GPUTraceTemporalIndexBuilder({
  id: 'timeline-index-builder',
  batches: packedBatchRecords,
  batchCount,
  batchLayout,
  hierarchy: packedHierarchyRecords,
  hierarchyLayout,
  levels,
  partitionBatchCount: 256,
  dirtyPartitions,
  validationErrors
}).addToGraph(graph);

new GPUTraceTemporalIndex({
  id: 'timeline-index',
  batches: {
    minimumTimes,
    maximumTimes,
    groupIds,
    minimumLanes,
    maximumLanes
  },
  hierarchy: {
    minimumTimes: nodeMinimumTimes,
    maximumTimes: nodeMaximumTimes,
    groupIds: nodeGroupIds,
    firstBatchIndices,
    batchCounts,
    minimumLanes: nodeMinimumLanes,
    maximumLanes: nodeMaximumLanes,
    levels
  },
  query: {
    timeWindow,
    laneWindow,
    enabledGroups,
    level
  },
  output: {
    candidates,
    candidateCount
  }
}).addToGraph(graph);

timeWindow is a packed three-element float32 view containing minimum time, maximum time, and guard padding. laneWindow contains the minimum and exclusive maximum visible lane. enabledGroups is one 32-bit renderer-group mask. level selects one persistent hierarchy level using a small GPU-resident control word. Hierarchy nodes own bounded, contiguous leaf ranges and never cross renderer-group boundaries.

Matching time-and-lane hierarchy nodes expand into source-ordered leaf batches in candidates. Without a hierarchy, every intersecting leaf is queried directly. Every interactive consumer reads this one conservative publication and applies its row-level policy: exact shaders retain visible or sufficiently wide spans, density omits those retained rows, representative search chooses one span per lane/pixel cell, and labels, dependencies, and picking use the same canonical batch IDs. Coarse false positives cost bounded shader work but cannot make an offscreen row visible.

Execution contract

• Batch summaries and outputs may be interleaved graph views but must use aligned scalar words.
• Candidate order always follows source batch order, independent of workgroup scheduling.
• GPUTraceTemporalIndexBuilder rebuilds every hierarchy resolution for dirty source partitions, then clears their dirty words. Clean partitions retain their persistent summaries.
• Hierarchy levels are persistent summaries; viewport changes select a level without rebuilding graph topology or index storage.
• Validation bit 1 reports an invalid leaf range, bit 2 a range crossing its declared source partition, and bit 4 a hierarchy node crossing a renderer-group boundary.
• Coarse nodes may conservatively include offscreen leaves, but they cannot omit an intersecting leaf represented by their interval and group bounds.
• The query buffer may change between encodings without recompiling graph topology.
• The contributor performs no submission or readback and keeps candidate counts GPU-resident.
• Wide-span exceptions are selected from the shared conservative batches by the exact row shader.