@oeave/bakery3 0.0.0-stage → 0.2.0

package/dist/bake/index.d.ts

@@ -0,0 +1,369 @@
+export { B as BakeSimplifyInput, P as PrepareBakeSettings } from '../prepare-BtjY4G3q.js';
+import { Mesh, Object3D, Texture, Scene } from 'three';
+import { j as BakeBundle } from '../bake-DZ-CJR6f.js';
+export { r as BAKE_TEXTURE_SIZES, a as BakeQuality, i as BakeSettings, e as BakeSpec, B as BakeTextureSize, s as MAX_BAKE_OBJECTS, t as MAX_BAKE_TEXELS } from '../bake-DZ-CJR6f.js';
+import '../animation-B1h0Ryvj.js';
+
+/**
+ * Which of your meshes can take a lightmap, and, for the ones that cannot,
+ * why and what to do about it.
+ *
+ * The SDK decides this, not the render worker: the worker sees a GLB, which
+ * has already flattened a `MeshPhysicalNodeMaterial` into something plausible
+ * and lost the fact that it was transmissive. The SDK is looking at the live
+ * material. So `bake.include` leaves the browser explicit and authoritative,
+ * and every mesh that did not make the list carries a `reason` the panel can
+ * show in place: never a silent skip.
+ *
+ * Two different verdicts live here:
+ *
+ *   `bakeable: false`: a lightmap cannot be applied to this at all. The
+ *     checkbox is disabled and the reason says why.
+ *   `defaultInclude: false`: it would work, but baking it is probably not
+ *     what you meant (glass, a hidden variant, something you opted out of).
+ *     The checkbox is off and you can turn it on.
+ */
+
+/** A refusal, per object, with the same fields as `BakeSkip` and
+ *  `PreflightIssue`, so a reason from here and one from the render worker
+ *  read identically in the panel. */
+type BakeCandidateReason = {
+    code: string;
+    message: string;
+    why?: string;
+    fix?: string;
+};
+type BakeCandidate = {
+    /** The id this object travels under: `userData.bakery3Id` or its uuid. */
+    objectId: string;
+    object: Mesh;
+    /** For humans: the three name, falling back to the graph path. */
+    name: string;
+    /** Where in the scene graph it lives, for a tooltip. */
+    path: string;
+    /** Can a lightmap be applied to this mesh at all? */
+    bakeable: boolean;
+    /** Present whenever there is something to say: on a refusal and on a
+     *  bakeable object that is off by default. */
+    reason?: BakeCandidateReason;
+    /** Whether the checkbox starts ticked. Always false when `!bakeable`. */
+    defaultInclude: boolean;
+};
+/**
+ * Every mesh in the scene, classified.
+ *
+ * Excluded objects (helpers, gizmos, `userData.bakery3.exclude`) are not
+ * listed at all: they never reach the renderer, so there is nothing to
+ * explain. Everything else appears, including the things that cannot be
+ * baked, because a list that quietly omits the instanced chairs is exactly
+ * the list that makes a developer think the bake covered them.
+ */
+declare function bakeCandidates(options: {
+    scene: Object3D;
+}): BakeCandidate[];
+
+/**
+ * How a lightmap is combined with the lights that are still running.
+ *
+ * three adds a lightmap to everything else that lights a surface, which is
+ * right when only the bounce was baked and wrong here: a Bakery3 lightmap is
+ * the whole diffuse answer (direct light, bounce, ambient and the
+ * environment's diffuse) in one texture, so adding it to a scene whose lamps
+ * are still on counts everything twice. Muting the lights
+ * (`session.muteLights`) fixes the diffuse and breaks the specular: the
+ * highlight a lamp puts on a glossy floor is not in a lightmap, and an
+ * environment map cannot be muted without losing its reflections.
+ *
+ * So this module leaves every light on and changes what the diffuse lobe
+ * listens to: the lightmap alone. Specular keeps hearing the lamps and the
+ * environment map, which is the closest a rasterizer gets to the traced
+ * frame, with the lights exactly as you left them.
+ *
+ * Two renderers, one material. WebGLRenderer compiles GLSL from chunks, and
+ * `onBeforeCompile` inserts a few lines after the chunk that samples the
+ * lightmap: direct diffuse is discarded and the indirect irradiance is
+ * replaced by the lightmap's, routed through a physical material's
+ * energy-conserving path so a metal stays dark. WebGPURenderer (and its WebGL
+ * backend) builds node materials, and converts a classic material by copying
+ * its own properties across, which is what lets `setupLightMap` and
+ * `setupLightingModel`, assigned here as own properties, arrive on the node
+ * side and wrap the lighting model the same way. Nothing is imported from the
+ * node system, so an app that never touches WebGPU never downloads it.
+ *
+ * Reversible, like everything else in the bake: each hook records the
+ * property descriptor it replaced (your own `onBeforeCompile`, or nothing)
+ * and `off()` puts it back. Your own `onBeforeCompile` keeps running first,
+ * and your cache key is folded into ours, so two materials that differed
+ * before still compile to two programs after.
+ */
+
+/**
+ * `'replace'`: the lightmap is the diffuse lighting, and lamps, ambient and
+ * the environment contribute specular only. The default, because it is what
+ * makes a baked scene match its traced still.
+ *
+ * `'add'`: three's stock behavior, the lightmap added on top of whatever else
+ * lights the surface. For a bake that deliberately contains only part of the
+ * lighting.
+ */
+type BakeShading = 'replace' | 'add';
+
+/**
+ * Putting the lightmaps on, and taking them off again.
+ *
+ * A bake is applied to your live meshes, in a running application, next to
+ * your r3f component graph and event handlers. That is only acceptable if it
+ * is exactly reversible, so nothing here mutates anything without first
+ * recording the reference or the value it replaced, and every mutation is a
+ * pair (`on`/`off`) over that record. `off()` restores references, not
+ * equivalents: the same `BufferAttribute` object, the same `Material` object,
+ * the same `lightMapIntensity` number. That pairing is also what makes
+ * hold-to-compare instant: it is `off()` then `on()` on a patch that is
+ * already built, so it flips within a frame.
+ *
+ * Three cases decide whether your geometry is touched:
+ *
+ * 1. `uv: { values }` and nobody else uses this geometry: the second UV set
+ *    is written straight onto the existing geometry as `uv1`. Your
+ *    `BufferGeometry` object survives, which matters in r3f, where a swapped
+ *    geometry is a prop React does not know changed.
+ * 2. `uv: { topology }`: the unwrap split vertices, so a new geometry is
+ *    built by gathering every original attribute (custom ones included)
+ *    through `vertexSource`, and the mesh points at it. The original is kept,
+ *    untouched, for revert.
+ * 3. The geometry is shared by another mesh that needs a different unwrap:
+ *    the same rebuild, per mesh, because one geometry cannot hold two
+ *    `uv1`s. Shared geometry whose sharers all got the same unwrap (25
+ *    spheres from one `SphereGeometry`) is written once, in place.
+ *
+ * Materials follow the same logic: a material used by one mesh is mutated in
+ * place (its `lightMap` and `lightMapIntensity` saved first); one shared with
+ * another mesh is cloned, because two objects have two lightmaps and one
+ * material holds one.
+ */
+
+/** A per-object refusal, with the same fields as the render worker's
+ *  `BakeSkip`, so a skip that happened here and one that happened on the
+ *  worker render the same way in the panel. */
+type BakeApplySkip = {
+    objectId: string;
+    name?: string;
+    code: string;
+    message: string;
+    why?: string;
+    fix?: string;
+};
+
+/**
+ * A lightmap URI becomes a `THREE.Texture`, with the settings that make it
+ * land the right way up on the right UV set.
+ *
+ * Orientation is a contract, not a guess: the render worker encodes the flip
+ * at bake time, so the pixels and the UV values it ships are already correct
+ * for `EXRLoader`'s defaults. This module changes nothing: `flipY = false` on
+ * both the EXR and the PNG path, so an LDR fallback lands identically to the
+ * HDR one.
+ *
+ * The bake's unwrap is a second UV set (your own `uv` still maps your
+ * albedo). In three the second set is the `uv1` attribute, and
+ * `texture.channel = 1` is how a map selects it, under WebGLRenderer and
+ * WebGPURenderer alike.
+ *
+ * No mipmaps: a lightmap atlas is islands separated by a dilation margin, and
+ * mipping it averages across island boundaries, which shows as light leaking
+ * round the silhouette of every object at distance. Linear filtering with no
+ * mips is the right trade for a map that is already low-frequency.
+ */
+
+type BakeTextureSource = {
+    /** Already resolved against the bundle's own location. */
+    url: string;
+    format: 'exr' | 'png';
+    /** For error messages: which object's lightmap this is. */
+    objectId: string;
+    size: number;
+    /** What the texture is for. A lightmap (the default) is configured by
+     *  `configureLightmap`; the reflection probe by `configureProbe`. A factory
+     *  of your own may ignore this: the session applies the probe's mapping
+     *  itself either way. */
+    role?: 'lightmap' | 'probe' | 'color' | 'normal' | 'billboard' | 'shadow';
+};
+/**
+ * How a lightmap URI becomes a texture.
+ *
+ * Injectable for two reasons: a test wants a `DataTexture` and no
+ * network, and an application that already has a loading manager, a CDN
+ * rewrite or an auth header wants its own fetch in the loop.
+ */
+type BakeTextureFactory = (source: BakeTextureSource) => Promise<Texture>;
+/**
+ * Apply the settings above to a texture from any source.
+ *
+ * Exported because a caller supplying their own `BakeTextureFactory` still
+ * wants the channel, the color space and the filtering to be the ones the
+ * bake was authored against: those are part of the format, not of the
+ * loader.
+ */
+declare function configureLightmap(texture: Texture, format: 'exr' | 'png'): Texture;
+
+/**
+ * A bake session: generations of lighting you can step through, over one
+ * live scene.
+ *
+ * The session is the thing a panel binds to. It owns three pieces of state
+ * and nothing else: which bundles it knows about, which one is currently
+ * applied (`-1` means "your scene, untouched"), and whether the realtime
+ * lights are muted. Everything visible follows from those.
+ *
+ * Generations do not stack: `apply(i)` reverts to live first, every time.
+ * Applying generation 2 over generation 1 would leave generation 1's cloned
+ * materials and rebuilt geometries in the scene under generation 2's
+ * textures, and the second revert would restore the first bake rather than
+ * your scene.
+ *
+ * Generations are evicted: twelve objects at 2048² of half-float RGBA is
+ * around 400 MB of VRAM per generation, so only the applied generation and
+ * the most recent few keep their textures. The rest are disposed and
+ * reloaded on demand.
+ */
+
+type BakeGeneration = {
+    /** Stable index into `session.generations`; generations are append-only. */
+    index: number;
+    /** What the stepper shows: `1024 · standard` unless the host names it. */
+    label: string;
+    bundle: BakeBundle;
+    baseUrl?: string;
+    /** When `addGeneration` was called, for "2m ago". */
+    createdAt: number;
+    /** True while this generation's textures are resident. */
+    loaded: boolean;
+};
+/**
+ * What one `apply()` actually managed to do.
+ *
+ * Reported rather than thrown, because a generation that no longer perfectly
+ * matches the scene is the normal case the moment you edit anything, and
+ * "applied 10 of 12, here are the other two" is more useful than either a
+ * failure or a lie.
+ */
+type BakeApplyReport = {
+    /** The generation this report is about, or -1 for your scene untouched. */
+    generation: number;
+    /** objectIds whose lightmap landed. */
+    applied: string[];
+    /** Baked objects with nothing in the scene answering to their id. */
+    unmatched: string[];
+    /** Bakeable meshes in the scene this generation has no lightmap for. */
+    unbaked: string[];
+    /** Objects the apply refused, each with a reason and a fix. */
+    skipped: BakeApplySkip[];
+    /** objectIds that received the bake's reflection probe as `envMap`: the
+     *  meshes the bake did not light (the product, the glass beside it). */
+    probed: string[];
+    /** Stand-ins that went into the scene, by their place in the request. */
+    standIns: number[];
+    /** objectIds out of sight because a stand-in took their place. */
+    replaced: string[];
+    /** Whether the bake's shadow plane is in the scene. */
+    shadow: boolean;
+    /**
+     * The prebaked preset room applied under this generation, and how many of
+     * its surfaces found a mesh. A bake in `room: 'preset'` mode covers only
+     * the product; this is where the rest of the light came from.
+     */
+    room?: {
+        name: string;
+        lighting: string;
+        applied: number;
+        unmatched: number;
+    };
+    /** Why the prebaked room is not on: it was wanted and did not load. The
+     *  product's own lightmaps applied regardless. */
+    roomError?: string;
+    /** Why the bundle's probe is on nothing: it was wanted and did not load.
+     *  The lightmaps applied regardless: a probe costs the product its
+     *  reflections of the room and nothing else. */
+    probeError?: string;
+};
+type BakeSessionOptions = {
+    scene: Scene | Object3D;
+    /**
+     * Where the preset library lives, for a bundle that stands its objects in
+     * a prebaked room (`BakeBundle.room`). Defaults to the CDN the SDK ships
+     * with; a test points it somewhere else.
+     */
+    presetBaseUrl?: string;
+    /**
+     * How a lightmap uri becomes a texture. Defaults to EXRLoader/TextureLoader
+     * with the channel, color space and filtering the format requires.
+     * Injected by tests, and by applications that need their own fetch.
+     */
+    textureFactory?: BakeTextureFactory;
+    /** `lightMapIntensity` to write. Default 1: the bake is already in the
+     *  scene's own light units. */
+    intensity?: number;
+    /**
+     * How the lightmap meets the lights that keep running. `'replace'` (the
+     * default) makes it the only diffuse lighting while lamps and the
+     * environment still supply specular, the combination that matches the
+     * traced still. `'add'` is three's stock behavior, for a bake that
+     * deliberately holds only part of the light. See shading.ts.
+     */
+    shading?: BakeShading;
+    /**
+     * Put the bake's reflection probe on the objects it did not light, as
+     * `envMap`, so a product kept live in a baked room reflects that room
+     * rather than the scene's own environment. Default `true`; `false` leaves
+     * every material's environment as you set it. See probe.ts.
+     */
+    probe?: boolean;
+    /** How many generations keep their textures. Default 3. */
+    residentGenerations?: number;
+};
+type BakeSession = {
+    readonly generations: readonly BakeGeneration[];
+    /** Index of the applied generation, or -1 when none is (see `revert()`). */
+    readonly current: number;
+    /** The last apply's report, for the panel's "what didn't match" line. */
+    readonly lastReport: BakeApplyReport | null;
+    /** True while `compare(true)` is showing the live scene under an applied
+     *  generation: the applied state is still there, just switched off. */
+    readonly comparing: boolean;
+    readonly lightsMuted: boolean;
+    /** Whether an applied bake puts its reflection probe on the objects it did
+     *  not light. The `probe` option, until `setProbe` changes it. */
+    readonly probe: boolean;
+    /** Which meshes could be baked, and why the others could not. */
+    candidates(): BakeCandidate[];
+    /** Remember a bundle. Textures are not fetched until it is applied. */
+    addGeneration(bundle: BakeBundle, options?: {
+        baseUrl?: string;
+        label?: string;
+    }): number;
+    /** Revert to live, then apply generation `index`. `revert()` goes back to live. */
+    apply(index: number): Promise<BakeApplyReport>;
+    /** Back to your scene, exactly. */
+    revert(): void;
+    /** Hold-to-compare: `true` shows live, `false` puts the bake back. Neither
+     *  loses the applied patch, so both are instant and lossless. */
+    compare(showLive: boolean): void;
+    /**
+     * The reflection probe on or off. With a generation applied this re-applies
+     * it, so the change shows at once and the report says which objects carry
+     * the probe; turning it on for the first time fetches the file.
+     */
+    setProbe(on: boolean): Promise<BakeApplyReport>;
+    /**
+     * Realtime lights to zero and back. Under the default `'replace'` shading
+     * the lamps only add specular, so this shows the bake's diffuse on its own;
+     * under `'add'` it is what stops the lamps being counted twice.
+     */
+    muteLights(on: boolean): void;
+    on(event: 'change', listener: (session: BakeSession) => void): () => void;
+    /** Revert, drop every texture, restore the lights. */
+    dispose(): void;
+};
+declare function createBakeSession(options: BakeSessionOptions): BakeSession;
+
+export { type BakeApplyReport, type BakeApplySkip, BakeBundle, type BakeCandidate, type BakeCandidateReason, type BakeGeneration, type BakeSession, type BakeSessionOptions, type BakeShading, type BakeTextureFactory, type BakeTextureSource, bakeCandidates, configureLightmap, createBakeSession };

package/dist/bake/index.js

@@ -0,0 +1,9 @@
+export { configureLightmap, createBakeSession } from '../chunk-KNUAOILG.js';
+export { bakeCandidates } from '../chunk-JFYUDERE.js';
+import '../chunk-4E5VV4QY.js';
+export { BAKE_TEXTURE_SIZES, MAX_BAKE_OBJECTS, MAX_BAKE_TEXELS } from '../chunk-APWUCEEB.js';
+import '../chunk-6NYR73Y7.js';
+import '../chunk-LAKXC4WR.js';
+import '../chunk-3G5QL4F4.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/bake/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}