import { LatLngBounds, type LatLngBoundsLike } from "../geo.js";
import type { Layer } from "../layer.js";
import type { Orihon } from "../map.js";
import { GridLayer, type GridLayerOptions, type ResolvedGridLayerOptions } from "./grid-layer.js";
export declare function modulo(value: number, divisor: number): number;
export interface TileCoordinates {
    x: number;
    y: number;
    z: number;
    s: string;
    r: string;
    retina: boolean;
}
export type TileTemplate = string | ((coordinates: TileCoordinates) => string);
/** Common redraw flag for raster URL/param updates. Prefer `{ redraw }` over polarity-inverted booleans. */
export type TileRedrawFlag = boolean | {
    redraw?: boolean;
};
export declare function shouldRedrawTiles(flag: TileRedrawFlag | undefined, defaultRedraw?: boolean): boolean;
export type RasterTileRendererKind = "dom" | "webgl" | "webgpu" | "none";
/**
 * Diagnostics every raster basemap reports. This is the supported way to observe tile
 * bookkeeping: the tile maps themselves are implementation detail and stay private.
 */
export interface RasterTileStats {
    /** Which raster implementation is running. */
    renderer: RasterTileRendererKind;
    /** Zoom the attached tiles were requested at; `null` before the first render. */
    tileZoom: number | null;
    /** Tiles attached for the active zoom. */
    active: number;
    /** Tiles kept from the previous zoom while the new level fills in. */
    retained: number;
    /** Tiles held for reuse without being drawn. */
    cached: number;
    /** Tile requests in flight. */
    loading: number;
}
/**
 * Shared public contract for DOM and GPU raster basemaps returned by `tileLayer()`.
 * Runtime may be `TileLayer` or `GPUTileLayer`; use `rendererKind` to discriminate.
 */
export interface RasterTileLayer extends Layer {
    readonly rendererKind: RasterTileRendererKind;
    getTileUrl(x: number, y: number, z: number): string;
    setUrl(template: TileTemplate, redraw?: TileRedrawFlag): this;
    setOpacity(opacity: number): this;
    redraw(): this;
    getStats(): RasterTileStats;
}
export interface TileLayerOptions extends GridLayerOptions {
    minZoom?: number;
    maxZoom?: number;
    maxNativeZoom?: number;
    tileSize?: number;
    buffer?: number;
    cacheSize?: number;
    maxRequests?: number;
    subdomains?: string | string[];
    crossOrigin?: string;
    referrerPolicy?: ReferrerPolicy | "";
    opacity?: number;
    errorTileUrl?: string;
    noWrap?: boolean;
    tms?: boolean;
    detectRetina?: boolean;
    bounds?: LatLngBoundsLike | null;
    /**
     * Which raster implementation to build. Defaults to `"dom"` in every tier, so the same
     * `tileLayer(url)` call builds the same renderer from `orihon/core`, `orihon/standard` and
     * `orihon`. GPU rasters are opt-in, and asking for one is a preference or a requirement
     * depending on how specific the request is:
     *
     * - `"dom"` — DOM `<img>` tiles.
     * - `"auto"` — a preference: WebGPU when `navigator.gpu` exists, then WebGL, then DOM.
     *   Degrades quietly when no GPU implementation is registered or supported.
     * - `"webgl"` / `"webgpu"` — a requirement: that implementation, or an
     *   `UnsupportedCapabilityError`. A silent DOM fallback would look like a GPU path in
     *   development and profile as a DOM path in production.
     *
     * A GPU implementation is registered by the Advanced `orihon` entry, or by importing
     * `orihon/webgpu` on top of Standard.
     */
    renderer?: "auto" | "dom" | "webgl" | "webgpu";
    /** GPU path: maximum new tile textures uploaded in one frame. */
    maxNewPerFrame?: number;
    /** GPU path: upper device-pixel-ratio used by the framebuffer. */
    maxDpr?: number;
}
interface ResolvedTileOptions extends ResolvedGridLayerOptions {
    pane: string;
    minZoom: number;
    maxZoom: number;
    maxNativeZoom?: number;
    tileSize: number;
    buffer: number;
    cacheSize: number;
    maxRequests: number;
    subdomains: string | string[];
    attribution: string;
    crossOrigin: string;
    referrerPolicy: ReferrerPolicy | "";
    opacity: number;
    zIndex: number;
    className: string;
    errorTileUrl: string;
    noWrap: boolean;
    tms: boolean;
    detectRetina: boolean;
    bounds: LatLngBounds | null;
}
/** Internal normalization shared by DOM and GPU raster tile implementations. */
export declare function normalizeTileBounds(value: unknown, errorMessage: string): LatLngBounds | null;
/** Shared raster payload: GPU backends do not provide a DOM image. */
export interface RasterTileEventDetail {
    x: number;
    y: number;
    z: number;
    url: string;
    tile?: HTMLImageElement;
}
export interface TileLayerEventMap {
    tileloadstart: RasterTileEventDetail;
    tileload: RasterTileEventDetail;
    tileerror: RasterTileEventDetail;
    tileabort: RasterTileEventDetail;
    load: {};
}
export declare class TileLayer<TEvents extends object = {}> extends GridLayer<ResolvedTileOptions, TileLayerEventMap & TEvents> implements RasterTileLayer {
    #private;
    /** URL template. Subclasses build their own request URLs from it; apps use `setUrl` / `getTileUrl`. */
    protected template: TileTemplate;
    readonly rendererKind: RasterTileRendererKind;
    constructor(template: TileTemplate, options?: TileLayerOptions);
    onAdd(map: Orihon): void;
    onRemove(): void;
    getTileUrl(x: number, y: number, z: number): string;
    setUrl(template: TileTemplate, redraw?: TileRedrawFlag): this;
    redraw(): this;
    getStats(): RasterTileStats;
    render(): void;
}
export declare function nativeTileZoom(maxNativeZoom: unknown, maxZoom: number): number;
export declare function tileLayer(template: TileTemplate, options?: TileLayerOptions): RasterTileLayer;
/**
 * Optional GPU raster basemap (Advanced tier).
 * Standard/Core keep DOM `<img>` tiles — register from `orihon` entry, not `orihon/core`.
 */
export type GPUTileFactory = (template: TileTemplate, options?: TileLayerOptions) => RasterTileLayer;
/** Advanced entry registers the unified WebGPU/WebGL raster implementation. */
export declare function registerGpuTileFactory(factory: GPUTileFactory | null): void;
export {};
//# sourceMappingURL=tile-layer.d.ts.map