gpu-atlas 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,398 @@
+export declare interface AdapterIdentity {
+    vendor: string;
+    architecture: string;
+    device: string;
+    description: string;
+    /** A software adapter — every performance number means something else entirely */
+    isFallbackAdapter: boolean;
+    /** The powerPreference passed to requestAdapter */
+    powerPreference: GPUPowerPreference | 'default';
+}
+
+export declare interface AtlasProfile {
+    schema: number;
+    capturedAt: string;
+    /**
+     * Stable hash grouping the same device + browser combination. 32 hex
+     * characters — wide enough that collisions stay negligible across a large
+     * collection of profiles, which an 8-character hash was not.
+     */
+    fingerprint: string;
+    environment: EnvironmentInfo;
+    adapter: AdapterIdentity | null;
+    declared: DeclaredCapabilities | null;
+    verified: VerifiedCapabilities | null;
+    benchmarks: BenchmarkResults | null;
+    discrepancies: Discrepancy[];
+    /** Why WebGPU could not be used at all, when that is the case */
+    unavailable?: string;
+    /** Total time the probe took */
+    elapsedMs: number;
+}
+
+export declare interface BenchDiff {
+    id: string;
+    description: string;
+    unit: string;
+    /** fingerprint -> throughput, null when the benchmark did not produce one */
+    values: Record<string, number | null>;
+    fastest: string | null;
+    slowest: string | null;
+    /** fastest / slowest */
+    ratio: number | null;
+    /**
+     * Devices whose measurement should not be trusted for this benchmark, either
+     * because it sat on the quantization floor or because it was too unstable.
+     * A ratio computed against these is not meaningful.
+     */
+    unreliable: string[];
+}
+
+/** Look up a benchmark result by id */
+export declare function benchmark(profile: AtlasProfile, id: string): BenchResult | null;
+
+export declare interface BenchmarkResults {
+    results: BenchResult[];
+    /** Whether timestamp-query was usable */
+    timestampQuery: boolean;
+    /**
+     * Measured granularity of the GPU timer, in nanoseconds. Browsers round
+     * timestamps into coarse buckets as a Spectre mitigation and the bucket size
+     * differs per browser and device, so it is measured rather than assumed.
+     */
+    timerResolutionNs: number | null;
+    /**
+     * Measured granularity of performance.now(), in milliseconds. Safari rounds
+     * to 1ms, which bounds how precisely the wall-clock benchmarks can be read.
+     */
+    wallClockResolutionMs: number | null;
+    /** Wall-clock time the whole benchmark suite took */
+    totalMs: number;
+}
+
+export declare interface BenchResult {
+    id: string;
+    description: string;
+    /** Representative value (median), in ms */
+    medianMs: number;
+    /** Lowest sample — a noise-free floor */
+    minMs: number;
+    /** Coefficient of variation. High means this number should not be trusted */
+    variation: number;
+    /** Throughput in the unit this benchmark defines (draws/s, MPixel/s, ...) */
+    throughput?: number;
+    throughputUnit?: string;
+    /** Whether this came from GPU timestamps or the wall clock */
+    timing: 'timestamp-query' | 'wall-clock';
+    samples: number;
+    /** How many unit workloads were run per sample after auto-scaling */
+    repetitions: number;
+    /**
+     * Measured duration expressed in timer resolution units. Low values mean the
+     * number is riding on the quantization floor and carries little information,
+     * which is the one case where a variation of 0 must not be read as stability.
+     */
+    ticks?: number;
+    /** The measurement sits too close to the timer resolution to be trusted */
+    quantized?: boolean;
+    failed?: string;
+}
+
+/** Only the problems that will actually break code */
+export declare function breakingIssues(profile: AtlasProfile): Discrepancy[];
+
+export declare function compareProfiles(profiles: AtlasProfile[]): Comparison;
+
+export declare interface Comparison {
+    devices: DeviceRef[];
+    /** Features present on some devices but not others */
+    features: FeatureDiff[];
+    /** Features every compared device has */
+    sharedFeatures: string[];
+    formats: FormatDiff[];
+    limits: LimitDiff[];
+    benchmarks: BenchDiff[];
+    /** Profiles that could not be compared, and why */
+    excluded: Array<{
+        index: number;
+        reason: string;
+    }>;
+}
+
+export declare interface DeclaredCapabilities {
+    features: string[];
+    limits: Record<string, number>;
+    /** navigator.gpu.getPreferredCanvasFormat() */
+    preferredCanvasFormat: string;
+}
+
+export declare function describeDevice(p: AtlasProfile): string;
+
+export declare interface DeviceRef {
+    fingerprint: string;
+    /** Human-readable identity, e.g. "qualcomm adreno-7xx / Samsung Internet 30" */
+    label: string;
+    mobile: boolean;
+    /** Index into the input array, for callers that need to get back to it */
+    index: number;
+    /** Schema version the profile was captured under */
+    schema: number;
+    /**
+     * The profile predates the schema that made measurement trustworthiness
+     * explicit, so its benchmark numbers are reported but never treated as
+     * reliable. Capability data from such profiles is still comparable.
+     */
+    staleBenchmarks: boolean;
+}
+
+export declare interface Discrepancy {
+    kind: DiscrepancyKind;
+    /** Where it occurred — a format name, limit name, or shader case id */
+    subject: string;
+    detail: string;
+    /** 'breaking' means code relying on the declaration will fail on this device */
+    severity: 'breaking' | 'degraded' | 'note';
+}
+
+export declare type DiscrepancyKind = 'format-declared-not-usable' | 'format-usable-not-declared' | 'limit-not-honored' | 'shader-compile-failure' | 'shader-pipeline-failure' | 'performance-cliff';
+
+export declare interface EnvironmentInfo {
+    /** From UA-CH when available */
+    platform?: string;
+    /** 'Chrome' | 'Firefox' | 'Safari' | 'Edge' | 'unknown' */
+    browser: string;
+    browserVersion: string;
+    /** Prefers the UA-CH mobile hint, falls back to UA sniffing */
+    mobile: boolean;
+    deviceMemoryGB?: number;
+    hardwareConcurrency?: number;
+    devicePixelRatio: number;
+}
+
+export declare interface FeatureDiff {
+    feature: string;
+    supportedBy: string[];
+    missingFrom: string[];
+}
+
+export declare function findMeta(format: string): FormatMeta | undefined;
+
+/**
+ * Render a comparison as plain text. Useful for dropping into an issue, a
+ * README, or a terminal without building a table by hand.
+ */
+export declare function formatComparison(c: Comparison, options?: FormatOptions): string;
+
+/** A texture capability that is not uniform across the compared devices */
+export declare interface FormatDiff {
+    format: string;
+    capability: 'creatable' | 'sampleable' | 'renderable' | 'blendable' | 'storageWritable' | 'multisample4x';
+    supportedBy: string[];
+    missingFrom: string[];
+}
+
+export declare type FormatKind = 'color' | 'depth' | 'compressed';
+
+export declare interface FormatMeta {
+    format: string;
+    kind: FormatKind;
+    /** Texel type of the WGSL texture */
+    texel: 'f32' | 'u32' | 'i32';
+    /** Whether a filtering sampler may be attached (decides bindGroupLayout sampleType) */
+    filterable: boolean;
+    /** The device feature this format requires */
+    requiresFeature?: string;
+    /** Block size for compressed formats — createTexture must be a multiple of it */
+    block?: [number, number];
+    hasDepth?: boolean;
+    hasStencil?: boolean;
+    /** What the spec says to expect */
+    expect: {
+        renderable: boolean;
+        blendable: boolean;
+        storage: boolean;
+    };
+}
+
+export declare interface FormatOptions {
+    /**
+     * Rows to print per section before summarising the rest. Sections are sorted
+     * worst-first, so the truncated tail is the least interesting part — but a
+     * hundred devices would otherwise produce thousands of lines.
+     */
+    limit?: number;
+}
+
+export declare const FORMATS: FormatMeta[];
+
+/** Whether a texture format actually works for each usage */
+export declare interface FormatSupport {
+    format: string;
+    /** The device feature this format requires, if any */
+    requiresFeature?: string;
+    /** Whether that feature appears in declared.features */
+    featureDeclared: boolean;
+    /** createTexture succeeds */
+    creatable: boolean;
+    /** Readable from a shader via TEXTURE_BINDING */
+    sampleable: boolean;
+    /** A render pass actually runs against it via RENDER_ATTACHMENT */
+    renderable: boolean;
+    /** Blending works when used as a render target */
+    blendable: boolean;
+    /** Writable from a compute shader via STORAGE_BINDING */
+    storageWritable: boolean;
+    /** Works as a 4x MSAA render target */
+    multisample4x: boolean;
+    /** Errors captured at each stage, for diagnosis */
+    errors: ProbeError[];
+}
+
+/** Whether WebGPU could not be used at all */
+export declare function isUnavailable(profile: AtlasProfile): boolean;
+
+export declare interface LimitDiff {
+    limit: string;
+    /** fingerprint -> value actually achieved */
+    values: Record<string, number>;
+    min: number;
+    max: number;
+    /** max / min — how far apart the devices are */
+    ratio: number;
+}
+
+/** Whether a declared limit can actually be used up to its stated value */
+export declare interface LimitProbe {
+    limit: string;
+    declared: number;
+    /** Highest value that actually allocated, found by bisection */
+    achieved: number;
+    /** achieved < declared means the declaration was not honored */
+    honored: boolean;
+    error?: ProbeError;
+}
+
+/**
+ * Below this, benchmark numbers cannot be trusted for comparison: version 1
+ * profiles carry no quantization information, and their overdraw benchmarks
+ * were architecture-dependent.
+ */
+export declare const MIN_COMPARABLE_BENCHMARK_SCHEMA = 2;
+
+/**
+ * Pick the first candidate this device actually supports.
+ * The result is measured rather than declared, so whatever comes back works.
+ */
+export declare function pickFormat(profile: AtlasProfile, candidates: string[], usage?: 'render' | 'sample' | 'storage'): string | null;
+
+export declare function probe(options?: ProbeOptions): Promise<AtlasProfile>;
+
+declare interface ProbeError {
+    kind: ProbeErrorKind;
+    message: string;
+    stage?: ProbeStage;
+}
+
+/**
+ * Why something failed. `validation` and `out-of-memory` come straight from
+ * WebGPU error scopes; `exception` means the call threw synchronously, which is
+ * what browsers do for a format they do not recognise at all.
+ */
+declare type ProbeErrorKind = 'validation' | 'out-of-memory' | 'internal' | 'exception' | 'queue' | 'scope-unavailable';
+
+export declare interface ProbeOptions {
+    /** Which GPU to ask for. On laptops this decides which chip you get */
+    powerPreference?: GPUPowerPreference;
+    /** Run benchmarks. false leaves only capability verification, which is fast */
+    benchmark?: boolean;
+    /** Samples per benchmark. More is more accurate and slower. Clamped to 1-99 */
+    benchSamples?: number;
+    /** Progress callback */
+    onProgress?: (stage: string, ratio: number) => void;
+    /** Verify only these texture formats (default: the full built-in list) */
+    formats?: string[];
+}
+
+/** Which check was running when an error surfaced */
+declare type ProbeStage = 'create' | 'sample' | 'render' | 'blend' | 'storage' | 'msaa4x' | 'limit';
+
+/** Formats verified to work as render targets on this device */
+export declare function renderableFormats(profile: AtlasProfile): string[];
+
+/** Formats verified to be readable from a shader */
+export declare function sampleableFormats(profile: AtlasProfile): string[];
+
+/**
+ * Profile schema version.
+ *
+ * Collecting profiles is the point of this project, so a profile has to say
+ * honestly what shape it is. Bump this whenever a field is added, removed, or
+ * changes meaning, and record why below — consumers compare against it to know
+ * which fields they can rely on.
+ *
+ * 4 — EnvironmentInfo.userAgent removed.
+ *     Browser, version, platform and mobile are already parsed into their own
+ *     fields, so the raw string was duplicate data — and a fingerprinting
+ *     vector. A project that asks people to share profiles should not ship
+ *     identifying information it does not use.
+ *
+ * 3 — Errors became structured, and fingerprints got wider.
+ *     Wall-clock benchmarks also changed: they now scale to 60 ticks of the
+ *     measured performance.now() granularity and drop their extreme samples,
+ *     so those figures shift by a few percent against version 2. GPU-timed
+ *     benchmarks are unaffected, which is why version 2 profiles remain
+ *     comparable rather than being cut off.
+ *     ~ FormatSupport.errors and LimitProbe.error are now ProbeError objects
+ *       rather than preformatted strings, so a consumer can branch on why
+ *       something failed without matching on message text.
+ *     ~ AtlasProfile.fingerprint is a 32-character hash instead of 8. The old
+ *       32-bit value collided at a rate that mattered once profiles were being
+ *       collected in bulk.
+ *
+ * 2 — Measurement trustworthiness became explicit.
+ *     + BenchResult.repetitions   how far auto-scaling pushed each benchmark
+ *     + BenchResult.ticks         duration in timer-resolution units
+ *     + BenchResult.quantized     sitting on the quantization floor
+ *     + BenchmarkResults.timerResolutionNs      measured GPU timer granularity
+ *     + BenchmarkResults.wallClockResolutionMs  measured performance.now() granularity
+ *     + ShaderCase.skipped        previously inferred from message text
+ *     Benchmarks also changed: the overdraw ones now blend additively, so their
+ *     numbers are not comparable with version 1 readings taken on tile-based
+ *     deferred GPUs, where the unblended version measured almost nothing.
+ *
+ * 1 — Initial schema.
+ */
+export declare const SCHEMA_VERSION = 4;
+
+/** Result of one WGSL compilation case */
+export declare interface ShaderCase {
+    id: string;
+    /** What this case is probing for */
+    description: string;
+    /** Skipped because a required feature is missing */
+    skipped: boolean;
+    compiled: boolean;
+    /** Compiling can succeed while pipeline creation still fails — it happens */
+    pipelineCreated: boolean;
+    /** Warnings and errors from getCompilationInfo() */
+    messages: ShaderMessage[];
+    /** Compile time in ms. Identifies devices with slow shader compilation */
+    compileMs: number;
+}
+
+export declare interface ShaderMessage {
+    type: 'error' | 'warning' | 'info';
+    message: string;
+    lineNum: number;
+}
+
+export declare interface VerifiedCapabilities {
+    formats: FormatSupport[];
+    shaders: ShaderCase[];
+    limits: LimitProbe[];
+    /** The device died partway through — everything after that is meaningless */
+    deviceLost: boolean;
+    deviceLostReason?: string;
+}
+
+export { }

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "gpu-atlas",
+  "version": "0.1.0",
+  "description": "What WebGPU actually does on this device — verified by creating the resources and running the passes, not by reading declared limits.",
+  "keywords": [
+    "webgpu",
+    "gpu",
+    "capabilities",
+    "benchmark",
+    "compatibility",
+    "graphics",
+    "rendering"
+  ],
+  "license": "MIT",
+  "author": "ahnminjae08043-glitch (https://github.com/ahnminjae08043-glitch)",
+  "homepage": "https://ahnminjae08043-glitch.github.io/gpu-atlas/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ahnminjae08043-glitch/gpu-atlas.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ahnminjae08043-glitch/gpu-atlas/issues"
+  },
+  "type": "module",
+  "main": "./dist/gpu-atlas.js",
+  "module": "./dist/gpu-atlas.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/gpu-atlas.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "npm run typecheck && npm test && vite build",
+    "build:demo": "vite build --mode demo",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-basic-ssl": "^2.3.0",
+    "@webgpu/types": "^0.1.60",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.5",
+    "vite-plugin-dts": "^4.4.0",
+    "vitest": "^4.1.11"
+  }
+}