/**
 * Stable public entry point for the Surface Sampling product block.
 * @module three-blocks/surface-sampling
 */
import type { Matrix4, Mesh, Renderer, StorageBufferAttribute, StorageInstancedBufferAttribute, Vector3 } from 'three/webgpu';
import type { ComputeBVHSamplerSource } from './Compute/ComputeBVHSampler.js';
export type { ComputeBVHSamplerSource } from './Compute/ComputeBVHSampler.js';
/** Construction choices for repeatable static-mesh surface sampling. */
export interface ComputeMeshSurfaceSamplerOptions {
    /** Seed used to produce a repeatable distribution. */
    seed?: number | undefined;
    /** Whether interpolated vertex normals should orient the generated matrices. */
    useVertexNormals?: boolean | undefined;
}
/** Per-dispatch choices for static-mesh surface sampling. */
export interface ComputeMeshSurfaceSamplerComputeOptions {
    /** Recompute only this sample index; omit to recompute the complete output. */
    resampleIndex?: number | undefined;
    /** Resolve and return a WebGPU compute timestamp for this dispatch. */
    trackTimestamp?: boolean | undefined;
}
interface MeshSurfaceSamplerConstructor {
    /** Construct a stable static-mesh sampler with caller-owned mesh and renderer inputs. */
    new (mesh: Mesh, renderer: Renderer, count: number, options?: ComputeMeshSurfaceSamplerOptions): ComputeMeshSurfaceSampler;
    readonly prototype: ComputeMeshSurfaceSampler;
}
/**
 * Stable facade for sampling a static or skinned mesh surface into GPU instance
 * transforms. Construction validates the source geometry and allocates the
 * sampler-owned compute pipeline and output buffers; malformed triangle data,
 * missing skinning attributes, or an unusable renderer cause construction or
 * dispatch to throw. Call {@link ComputeMeshSurfaceSampler.compute} after pose
 * updates and before rendering consumers of {@link ComputeMeshSurfaceSampler.output}.
 * The output attributes remain owned by the sampler and must not be disposed
 * independently. Call {@link ComputeMeshSurfaceSampler.dispose} once the output
 * is no longer rendered; disposal is safe to repeat.
 */
export interface ComputeMeshSurfaceSampler {
    /** GPU instance matrices generated by the most recent compute dispatch. */
    readonly output: StorageInstancedBufferAttribute;
    /** World-space sampled normals, or `null` when normal output was not requested. */
    readonly outputNormal: StorageBufferAttribute | null;
    /**
     * Submit surface sampling after source pose changes and before rendering any
     * object that consumes the output. A resolved timestamp is returned only when
     * `trackTimestamp` is enabled.
     */
    compute(options?: ComputeMeshSurfaceSamplerComputeOptions): Promise<string | null | undefined>;
    /** Copy the current matrices from GPU storage into a caller-owned CPU snapshot. */
    readback(): Promise<Float32Array<ArrayBuffer>>;
    /** Release the compute pipeline and every GPU buffer owned by this sampler. */
    dispose(): void;
}
/** Runtime-identical constructor for the narrow stable surface-sampler facade. */
export declare const ComputeMeshSurfaceSampler: MeshSurfaceSamplerConstructor;
/** Required capacity and distribution choices for dynamic surface sampling. */
export interface ComputeMeshDynamicSurfaceSamplerOptions {
    /** WebGPU renderer used for compute submission and resource disposal. */
    renderer: Renderer;
    /** Maximum number of output samples. Must be a positive integer. */
    count: number;
    /** Seed used to produce a repeatable distribution. */
    seed?: number | undefined;
    /** Whether interpolated vertex normals should orient generated matrices. */
    useVertexNormals?: boolean | undefined;
}
/** Per-dispatch choices for dynamic surface sampling. */
export interface ComputeMeshDynamicSurfaceSamplerComputeOptions {
    /** Update only this output index; omit to update the complete output. */
    resampleIndex?: number | undefined;
}
/** Sampler-owned GPU outputs produced by dynamic surface sampling. */
export interface ComputeMeshDynamicSurfaceSamplerOutputs {
    /** Sampled world-space positions. */
    readonly position: StorageBufferAttribute;
    /** Sampled world-space normals. */
    readonly normal: StorageBufferAttribute;
    /** Sampled instance transforms. */
    readonly matrix: StorageInstancedBufferAttribute;
}
/** Caller-owned CPU snapshot returned by dynamic sampler readback. */
export interface ComputeMeshDynamicSurfaceSamplerReadback {
    /** Caller-owned snapshot of sampled positions. */
    readonly positions: Float32Array<ArrayBuffer>;
    /** Caller-owned snapshot of sampled normals. */
    readonly normals: Float32Array<ArrayBuffer>;
}
interface DynamicSurfaceSamplerConstructor {
    /** Construct a stable dynamic-mesh sampler and allocate its sampler-owned outputs. */
    new (mesh: Mesh, attributeName: string | undefined, options: ComputeMeshDynamicSurfaceSamplerOptions): ComputeMeshDynamicSurfaceSampler;
    readonly prototype: ComputeMeshDynamicSurfaceSampler;
}
/**
 * Stable facade for continuously sampling a deforming mesh near a world-space
 * region. Construction requires a WebGPU renderer, a positive sample count, and
 * a triangle position attribute; invalid inputs throw before usable outputs are
 * exposed. The sampler owns its compute nodes and output storage, while the
 * source mesh and renderer remain caller-owned. Set the region and source matrix
 * after animation updates, call {@link ComputeMeshDynamicSurfaceSampler.compute},
 * then render consumers of {@link ComputeMeshDynamicSurfaceSampler.outputs}.
 * Call {@link ComputeMeshDynamicSurfaceSampler.dispose} when finished; disposal
 * is safe to repeat, but using the sampler afterward is an error.
 */
export interface ComputeMeshDynamicSurfaceSampler {
    /** Set the world-space center of the region considered for sampling. */
    setCenter(x: number, y: number, z: number): this;
    /** Set the non-negative world-space sampling radius. */
    setRadius(radius: number): this;
    /** Copy the source mesh world matrix used by the next compute dispatch. */
    setObjectMatrix(matrix: Matrix4): this;
    /** Sampler-owned GPU outputs; consumers may bind but must not dispose them. */
    readonly outputs: ComputeMeshDynamicSurfaceSamplerOutputs;
    /**
     * Submit sampling after geometry, animation, region, and matrix updates and
     * before rendering consumers of the output buffers.
     */
    compute(options?: ComputeMeshDynamicSurfaceSamplerComputeOptions): void;
    /** Copy positions and normals into caller-owned CPU diagnostic snapshots. */
    readback(): Promise<ComputeMeshDynamicSurfaceSamplerReadback>;
    /** Read the most recently tracked survivor count as an immutable scalar snapshot. */
    readSurvivorCountAsync(): Promise<number>;
    /** Immediately rebuild cached face data after source positions change. */
    rebuildFaceDataAsync(): Promise<void>;
    /** Schedule uploaded CPU geometry changes for the next compute dispatch. */
    markGeometryDirty(): this;
    /** Rebuild face data on every dispatch when the source geometry changes on GPU. */
    setDynamicGeometry(enabled?: boolean): this;
    /** Enable the survivor counter only while the diagnostic count is needed. */
    setTrackSurvivors(enabled?: boolean): this;
    /** Release compute nodes and sampler-owned GPU storage; safe to call repeatedly. */
    dispose(): void;
}
/** Runtime-identical constructor for the narrow dynamic-sampler facade. */
export declare const ComputeMeshDynamicSurfaceSampler: DynamicSurfaceSamplerConstructor;
/** Distribution strategy accepted by SDF-volume sampling. */
export type ComputeBVHSamplerStrategy = 'uniform' | 'surface' | 'custom';
/** Construction choices for SDF-volume rejection sampling. */
export interface ComputeBVHSamplerOptions {
    /** Sampling distribution. Unsupported strategies may yield no accepted samples. */
    strategy?: ComputeBVHSamplerStrategy | undefined;
    /** Signed-distance acceptance threshold. */
    sdfThreshold?: number | undefined;
    /** Seed used to produce a repeatable distribution. */
    seed?: number | undefined;
    /** Maximum rejection attempts for each output sample. */
    maxAttempts?: number | undefined;
    /** Relative surface weighting for surface-biased sampling. */
    surfaceWeight?: number | undefined;
    /** Whether accepted transforms should align to the SDF gradient. */
    alignToNormal?: boolean | undefined;
    /** Scale written into each accepted instance transform. */
    scale?: Vector3 | undefined;
}
/** Per-dispatch choices for SDF-volume rejection sampling. */
export interface ComputeBVHSamplerComputeOptions {
    /** Override the signed-distance threshold for this and later dispatches. */
    sdfThreshold?: number | undefined;
    /** Log sampling bounds and threshold diagnostics for this dispatch. */
    debug?: boolean | undefined;
}
interface BVHSamplerConstructor {
    /** Construct a stable SDF-volume sampler from a caller-owned source and renderer. */
    new (sdfGenerator: ComputeBVHSamplerSource, renderer: Renderer, count: number, options?: ComputeBVHSamplerOptions): ComputeBVHSampler;
    readonly prototype: ComputeBVHSampler;
}
/**
 * Stable facade for rejection-sampling an SDF volume into GPU positions and
 * instance transforms. Construction requires a {@link ComputeBVHSamplerSource}
 * with a generated SDF texture, WebGPU renderer, and usable output capacity;
 * missing SDF resources make kernel construction fail. The source and renderer
 * remain caller-owned, while the sampler creates its output attributes. Call {@link ComputeBVHSampler.compute}
 * after SDF or transform updates and before rendering output consumers. The
 * current engine leaves output-attribute backend cleanup to their renderer and
 * garbage-collection lifecycle; detach every consumer before dropping the sampler.
 */
export interface ComputeBVHSampler {
    /** Submit volume sampling after SDF updates and before dependent rendering. */
    compute(options?: ComputeBVHSamplerComputeOptions): void;
    /** Replace the caller-owned SDF source and rebuild the kernel when its texture changes. */
    updateSDF(sdfGenerator: ComputeBVHSamplerSource): void;
    /** Sampler-owned GPU instance matrices from the most recent dispatch. */
    readonly output: StorageInstancedBufferAttribute;
    /** Sampler-owned GPU positions from the most recent dispatch. */
    readonly positionsBuffer: StorageInstancedBufferAttribute;
    /** Copy current instance matrices into a caller-owned CPU snapshot. */
    readback(): Promise<Float32Array>;
    /** Copy current positions into a caller-owned CPU snapshot. */
    readbackPositions(): Promise<Float32Array>;
    /** Calculate the percentage of non-zero samples in a CPU position snapshot. */
    calculateValidRate(positions: Float32Array): number;
    /** End supported use after outputs are detached; this call is currently idempotent. */
    dispose(): void;
}
/** Runtime-identical constructor for the narrow SDF-volume sampler facade. */
export declare const ComputeBVHSampler: BVHSamplerConstructor;