// generated by diplomat-tool
import type { NucleationError } from "./NucleationError.mjs"
import type { pointer, codepoint } from "./diplomat-runtime.d.ts";



/**
 * A set of colored blocks that color/gradient brushes snap their computed
 * colors to (nearest neighbor in Oklab space). Wraps an Arc'd
 * {@link crate::building::BlockPalette}; sharing one palette across many
 * brushes is cheap.
 */
export class Palette {
    /** @internal */
    get ffiValue(): pointer;
    /** @internal */
    constructor();


    /**
     * Every block blockpedia knows a color for (the default palette
     * brushes use when none is set).
     */
    static all(): Palette;

    /**
     * Only solid blocks: no transparency, gravity, tile entities, or
     * support requirements.
     */
    static solid(): Palette;

    /**
     * Conservative structural set (full building blocks).
     */
    static structural(): Palette;

    /**
     * Decorative set: allows stairs/slabs but no tile entities.
     */
    static decorative(): Palette;

    /**
     * The 16 concrete colors (excludes concrete powder).
     */
    static concrete(): Palette;

    /**
     * The 16 wool colors.
     */
    static wool(): Palette;

    /**
     * Terracotta colors (excludes glazed variants).
     */
    static terracotta(): Palette;

    /**
     * Genuinely gray blocks: opaque full cubes whose measured color
     * is near-neutral (low Oklab chroma) — judged from color data,
     * not names.
     */
    static grayscale(): Palette;

    /**
     * The planks family — a natural light→dark wood ramp.
     */
    static wood(): Palette;

    /**
     * A copy of this palette with ordered dithering enabled: brushes
     * snapping through it alternate between the two nearest blocks per
     * voxel (4x4 Bayer threshold, deterministic in position), which
     * reads as intermediate shades at a distance — the classic map-art
     * trick. Ramp and list queries are unaffected.
     */
    dithered(): Palette;

    /**
     * A copy of this palette ordered by perceptual lightness (Oklab L,
     * dark → light). Combined with `block_ids_json`, gives a
     * ready-to-index ramp: `ids[i]` for intensity `i / (len - 1)`.
     */
    sortedByLightness(): Palette;

    /**
     * JSON array of exactly `steps` DISTINCT block ids forming the
     * smoothest ramp this palette can make from (`r1`,`g1`,`b1`) to
     * (`r2`,`g2`,`b2`): targets are evenly spaced along the Oklab line
     * and blocks are chosen by a minimum-cost monotonic matching, so
     * off-hue blocks are penalized and no block repeats. Errors with
     * `InvalidArgument` when the palette has fewer than `steps` blocks,
     * `steps` is 0, or start equals end.
     */
    rampIdsJson(r1: number, g1: number, b1: number, r2: number, g2: number, b2: number, steps: number): string;

    /**
     * JSON array of exactly `steps` block ids sampling the color
     * gradient from (`r1`,`g1`,`b1`) to (`r2`,`g2`,`b2`) in Oklab
     * space, each step snapped to this palette's closest block. Built
     * for value→block lookups (heatmaps, fractals): index the returned
     * list by `intensity * (steps - 1)`. Entries may repeat on coarse
     * palettes; errors with `NotFound` on an empty palette.
     */
    gradientIdsJson(r1: number, g1: number, b1: number, r2: number, g2: number, b2: number, steps: number): string;

    /**
     * JSON array of exactly `steps` block ids sampling an Oklab gradient
     * whose endpoints are the measured texture colors of `start_block`
     * and `end_block`. Errors with `NotFound` when either id is unknown
     * or has no measured color, or when this palette is empty.
     */
    gradientIdsBetweenBlocksJson(startBlock: string, endBlock: string, steps: number): string;

    /**
     * Custom palette from a JSON array of block ids, e.g.
     * `["minecraft:stone", "minecraft:oak_planks"]`. Ids blockpedia has
     * no color for are silently skipped — check `len` afterwards.
     */
    static fromBlockIds(idsJson: string): Palette;

    /**
     * Number of blocks in the palette.
     */
    len(): number;

    /**
     * The palette's block ids as a JSON array string.
     */
    blockIdsJson(): string;

    /**
     * Position-aware dithered snap: the block for the given RGB at
     * voxel (x, y, z), alternating between the two nearest palette
     * blocks per position (4x4 Bayer) — the per-pixel entry point for
     * pixel art and image mapping. Deterministic. Errors with
     * `NotFound` on an empty palette.
     */
    closestBlockDithered(r: number, g: number, b: number, x: number, y: number, z: number): string;

    /**
     * The palette block whose color is closest (Oklab distance) to the
     * given RGB. Errors with `NotFound` on an empty palette.
     */
    closestBlock(r: number, g: number, b: number): string;
}