@plasius/gpu-debug 0.2.4

package/dist/index.d.ts

@@ -0,0 +1,295 @@
+type GpuDebugQueueClass = "render" | "simulation" | "lighting" | "post-processing" | "voxel" | "transfer" | "custom";
+type GpuResourceCategory = "buffer" | "texture" | "bind-group" | "pipeline" | "custom";
+type GpuPipelinePhase = "simulation" | "secondary-simulation" | "scene-preparation" | "render";
+interface GpuVector3 {
+    x: number;
+    y?: number;
+    z?: number;
+}
+interface GpuDebugAdapterInfo {
+    label?: string;
+    vendor?: string;
+    architecture?: string;
+    driver?: string;
+    maxBufferSizeBytes?: number;
+    maxStorageBufferBindingSizeBytes?: number;
+    maxComputeInvocationsPerWorkgroup?: number;
+    maxComputeWorkgroupsPerDimension?: number;
+    memoryCapacityHintBytes?: number;
+    coreCountHint?: number;
+    metadata?: Readonly<Record<string, unknown>>;
+}
+interface GpuDebugSessionOptions {
+    enabled?: boolean;
+    adapter?: GpuDebugAdapterInfo;
+    maxRetainedDispatches?: number;
+    maxRetainedQueueSamples?: number;
+    maxRetainedReadyLaneSamples?: number;
+    maxRetainedDependencyUnlockSamples?: number;
+    maxRetainedPipelinePhaseSamples?: number;
+    maxRetainedWavefrontSamples?: number;
+    maxRetainedFrameSamples?: number;
+    maxTrackedAllocations?: number;
+}
+interface TrackedGpuAllocation {
+    id: string;
+    owner: string;
+    category: GpuResourceCategory;
+    sizeBytes: number;
+    label?: string;
+    signal?: AbortSignal;
+}
+interface GpuQueueSample {
+    owner: string;
+    queueClass: GpuDebugQueueClass;
+    depth: number;
+    capacity?: number;
+    frameId?: string;
+    signal?: AbortSignal;
+}
+interface GpuReadyLaneSample {
+    owner: string;
+    queueClass: GpuDebugQueueClass;
+    laneId: string;
+    priority?: number;
+    depth: number;
+    capacity?: number;
+    frameId?: string;
+    signal?: AbortSignal;
+}
+interface GpuDispatchSample {
+    id?: string;
+    owner: string;
+    queueClass: GpuDebugQueueClass;
+    jobType: string;
+    frameId?: string;
+    durationMs?: number;
+    workgroups: GpuVector3;
+    workgroupSize?: GpuVector3;
+    bytesRead?: number;
+    bytesWritten?: number;
+    signal?: AbortSignal;
+}
+interface GpuFrameSample {
+    frameId?: string;
+    frameTimeMs: number;
+    targetFrameTimeMs?: number;
+    gpuBusyMs?: number;
+    dropped?: boolean;
+    signal?: AbortSignal;
+}
+interface GpuDependencyUnlockSample {
+    owner: string;
+    queueClass: GpuDebugQueueClass;
+    sourceJobType: string;
+    unlockedJobType: string;
+    priority?: number;
+    unlockCount?: number;
+    frameId?: string;
+    signal?: AbortSignal;
+}
+interface GpuPipelinePhaseSample {
+    owner: string;
+    pipeline: GpuPipelinePhase;
+    stage: string;
+    frameId?: string;
+    durationMs?: number;
+    snapshotFrameId?: string;
+    snapshotAgeFrames?: number;
+    snapshotAgeMs?: number;
+    signal?: AbortSignal;
+}
+interface GpuWavefrontHitKindSample {
+    kind: string;
+    count: number;
+}
+interface GpuWavefrontTerminationSample {
+    reason: string;
+    count: number;
+}
+interface GpuWavefrontTelemetrySample {
+    owner: string;
+    queueClass: GpuDebugQueueClass;
+    frameId?: string;
+    bounceDepth: number;
+    activeRayCount: number;
+    queueCapacity?: number;
+    overflowCount?: number;
+    hitBufferCount?: number;
+    hitKinds?: readonly GpuWavefrontHitKindSample[];
+    terminationReasons?: readonly GpuWavefrontTerminationSample[];
+    signal?: AbortSignal;
+}
+interface GpuDebugMemorySnapshot {
+    totalTrackedBytes: number;
+    peakTrackedBytes: number;
+    allocationCount: number;
+    trackedUsageRatio?: number;
+    byOwner: readonly {
+        owner: string;
+        bytes: number;
+    }[];
+    byCategory: readonly {
+        category: GpuResourceCategory;
+        bytes: number;
+    }[];
+}
+interface GpuDebugDispatchSnapshot {
+    sampleCount: number;
+    totalDurationMs: number;
+    averageDurationMs?: number;
+    estimatedWorkgroups: number;
+    estimatedInvocations: number;
+    averageBytesRead?: number;
+    averageBytesWritten?: number;
+    busyRatio?: number;
+    byQueueClass: readonly {
+        queueClass: GpuDebugQueueClass;
+        dispatches: number;
+        totalDurationMs: number;
+        estimatedInvocations: number;
+    }[];
+}
+interface GpuDebugQueueSnapshot {
+    sampleCount: number;
+    averageDepth: number;
+    peakDepth: number;
+    peakUtilizationRatio?: number;
+    hottestQueues: readonly {
+        owner: string;
+        queueClass: GpuDebugQueueClass;
+        depth: number;
+        capacity?: number;
+        utilizationRatio?: number;
+    }[];
+}
+interface GpuDebugFrameSnapshot {
+    sampleCount: number;
+    latestFrameTimeMs?: number;
+    averageFrameTimeMs?: number;
+    averageTargetFrameTimeMs?: number;
+    droppedFrameRatio?: number;
+    averageGpuBusyMs?: number;
+}
+interface GpuDebugDagSnapshot {
+    readyLaneSampleCount: number;
+    averageReadyLaneDepth: number;
+    peakReadyLaneDepth: number;
+    peakReadyLaneUtilizationRatio?: number;
+    hottestReadyLanes: readonly {
+        owner: string;
+        queueClass: GpuDebugQueueClass;
+        laneId: string;
+        priority?: number;
+        depth: number;
+        capacity?: number;
+        utilizationRatio?: number;
+    }[];
+    dependencyUnlockSampleCount: number;
+    totalUnlockCount: number;
+    bySourceJobType: readonly {
+        owner: string;
+        queueClass: GpuDebugQueueClass;
+        sourceJobType: string;
+        unlockCount: number;
+    }[];
+    byUnlockedJobType: readonly {
+        owner: string;
+        queueClass: GpuDebugQueueClass;
+        unlockedJobType: string;
+        priority?: number;
+        unlockCount: number;
+    }[];
+}
+interface GpuDebugPipelineSnapshot {
+    sampleCount: number;
+    totalDurationMs: number;
+    averageDurationMs?: number;
+    averageSnapshotAgeMs?: number;
+    maxSnapshotAgeMs?: number;
+    maxSnapshotAgeFrames?: number;
+    byPipeline: readonly {
+        pipeline: GpuPipelinePhase;
+        sampleCount: number;
+        totalDurationMs: number;
+        averageDurationMs?: number;
+        averageSnapshotAgeMs?: number;
+        maxSnapshotAgeMs?: number;
+        maxSnapshotAgeFrames?: number;
+    }[];
+    hottestStages: readonly {
+        owner: string;
+        pipeline: GpuPipelinePhase;
+        stage: string;
+        frameId?: string;
+        durationMs?: number;
+        snapshotFrameId?: string;
+        snapshotAgeFrames?: number;
+        snapshotAgeMs?: number;
+    }[];
+}
+interface GpuDebugWavefrontSnapshot {
+    sampleCount: number;
+    averageActiveRayCount: number;
+    peakActiveRayCount: number;
+    peakQueueUtilizationRatio?: number;
+    maxBounceDepth?: number;
+    totalOverflowCount: number;
+    peakOverflowCount: number;
+    averageHitBufferCount?: number;
+    peakHitBufferCount?: number;
+    byBounceDepth: readonly {
+        bounceDepth: number;
+        sampleCount: number;
+        averageActiveRayCount: number;
+        peakActiveRayCount: number;
+        averageHitBufferCount?: number;
+        peakHitBufferCount?: number;
+        totalOverflowCount: number;
+    }[];
+    byTerminationReason: readonly {
+        reason: string;
+        count: number;
+    }[];
+    byHitKind: readonly {
+        kind: string;
+        count: number;
+    }[];
+}
+interface GpuDebugSnapshot {
+    enabled: boolean;
+    adapter: Readonly<GpuDebugAdapterInfo>;
+    memory: GpuDebugMemorySnapshot;
+    dispatch: GpuDebugDispatchSnapshot;
+    queues: GpuDebugQueueSnapshot;
+    frames: GpuDebugFrameSnapshot;
+    dag: GpuDebugDagSnapshot;
+    pipeline: GpuDebugPipelineSnapshot;
+    wavefront: GpuDebugWavefrontSnapshot;
+    limitations: readonly string[];
+}
+interface GpuDebugSession {
+    isEnabled(): boolean;
+    setEnabled(enabled: boolean): void;
+    trackAllocation(allocation: TrackedGpuAllocation): () => void;
+    releaseAllocation(id: string): boolean;
+    recordQueue(sample: GpuQueueSample): boolean;
+    recordReadyLane(sample: GpuReadyLaneSample): boolean;
+    recordDispatch(sample: GpuDispatchSample): boolean;
+    recordDependencyUnlock(sample: GpuDependencyUnlockSample): boolean;
+    recordPipelinePhase(sample: GpuPipelinePhaseSample): boolean;
+    recordWavefrontTelemetry(sample: GpuWavefrontTelemetrySample): boolean;
+    recordFrame(sample: GpuFrameSample): boolean;
+    getSnapshot(): GpuDebugSnapshot;
+    reset(): void;
+}
+
+declare function estimateDispatchInvocations(sample: GpuDispatchSample): number;
+declare function createGpuDebugSession(options?: GpuDebugSessionOptions): GpuDebugSession;
+declare function summarizeWavefrontTelemetry(snapshot: GpuDebugWavefrontSnapshot | undefined): readonly string[];
+
+declare const gpuDebugQueueClasses: readonly ("render" | "simulation" | "lighting" | "post-processing" | "voxel" | "transfer" | "custom")[];
+declare const gpuResourceCategories: readonly ("custom" | "buffer" | "texture" | "bind-group" | "pipeline")[];
+declare const gpuPipelinePhases: readonly ("render" | "simulation" | "secondary-simulation" | "scene-preparation")[];
+
+export { type GpuDebugAdapterInfo, type GpuDebugDagSnapshot, type GpuDebugDispatchSnapshot, type GpuDebugFrameSnapshot, type GpuDebugMemorySnapshot, type GpuDebugPipelineSnapshot, type GpuDebugQueueClass, type GpuDebugQueueSnapshot, type GpuDebugSession, type GpuDebugSessionOptions, type GpuDebugSnapshot, type GpuDebugWavefrontSnapshot, type GpuDependencyUnlockSample, type GpuDispatchSample, type GpuFrameSample, type GpuPipelinePhase, type GpuPipelinePhaseSample, type GpuQueueSample, type GpuReadyLaneSample, type GpuResourceCategory, type GpuVector3, type GpuWavefrontHitKindSample, type GpuWavefrontTelemetrySample, type GpuWavefrontTerminationSample, type TrackedGpuAllocation, createGpuDebugSession, estimateDispatchInvocations, gpuDebugQueueClasses, gpuPipelinePhases, gpuResourceCategories, summarizeWavefrontTelemetry };