@luma.gl/core

import { type TypedArray } from '@math.gl/types'; import { type Device } from "../device.js"; import { type TextureFormat, type TextureMemoryLayout, type TextureFormatInfo } from "../../shadertypes/texture-types/texture-formats.js"; import { type ExternalImage } from "../../shadertypes/image-types/image-types.js"; import { type TextureView, type TextureViewProps } from "./texture-view.js"; import { Resource, type ResourceProps } from "./resource.js"; import { Sampler, type SamplerProps } from "./sampler.js"; import { Buffer } from "./buffer.js"; /** Options for Texture.copyExternalImage */ export type CopyExternalImageOptions = { /** Image */ image: ExternalImage; /** Copy from image x offset (default 0) */ sourceX?: number; /** Copy from image y offset (default 0) */ sourceY?: number; /** Copy area width (default 1) */ width?: number; /** Copy area height (default 1) */ height?: number; /** Copy depth, number of layers/depth slices(default 1) */ depth?: number; /** Start copying into offset x (default 0) */ x?: number; /** Start copying into offset y (default 0) */ y?: number; /** Start copying into layer / depth slice z (default 0) */ z?: number; /** Which mip-level to copy into (default 0) */ mipLevel?: number; /** When copying into depth stencil textures (default 'all') */ aspect?: 'all' | 'stencil-only' | 'depth-only'; /** Specific color space of image data */ colorSpace?: 'srgb'; /** load as premultiplied alpha */ premultipliedAlpha?: boolean; /** Whether to flip the image vertically */ flipY?: boolean; }; /** Options for copyImageData */ export type CopyImageDataOptions = { /** Data to copy (array of bytes) */ data: ArrayBuffer | SharedArrayBuffer | ArrayBufferView; /** Offset into the data (in addition to any offset built-in to the ArrayBufferView) */ byteOffset?: number; /** The stride, in bytes, between successive texel rows in the CPU source data. Tightly packed uploads can omit this. */ bytesPerRow?: number; /** Number of rows that make up one image when uploading multiple layers or depth slices from CPU memory. */ rowsPerImage?: number; /** Width to copy */ width?: number; /** Height to copy */ height?: number; /** Copy depth or number of layers */ depthOrArrayLayers?: number; /** @deprecated Use `depthOrArrayLayers` */ depth?: number; /** Start copying into offset x (default 0) */ x?: number; /** Start copying into offset y (default 0) */ y?: number; /** Start copying from depth layer z (default 0) */ z?: number; /** Which mip-level to copy into (default 0) */ mipLevel?: number; /** When copying into depth stencil textures (default 'all') */ aspect?: 'all' | 'stencil-only' | 'depth-only'; }; export type TextureReadOptions = { /** Start reading from offset x (default 0) */ x?: number; /** Start reading from offset y (default 0) */ y?: number; /** Start reading from layer / depth slice z (default 0) */ z?: number; /** Width of the region to read. Defaults to the mip width. */ width?: number; /** Height of the region to read. Defaults to the mip height. */ height?: number; /** Number of array layers or depth slices to read. Defaults to 1. */ depthOrArrayLayers?: number; /** Which mip-level to read from (default 0) */ mipLevel?: number; /** When reading from depth stencil textures (default 'all') */ aspect?: 'all' | 'stencil-only' | 'depth-only'; }; export type TextureWriteOptions = { /** Offset into the source data or buffer, in bytes. */ byteOffset?: number; /** The stride, in bytes, between successive texel rows in the source data or buffer. */ bytesPerRow?: number; /** The number of rows that make up one image when writing multiple layers or slices. */ rowsPerImage?: number; /** Start writing into offset x (default 0) */ x?: number; /** Start writing into offset y (default 0) */ y?: number; /** Start writing into layer / depth slice z (default 0) */ z?: number; /** Width of the region to write. Defaults to the mip width. */ width?: number; /** Height of the region to write. Defaults to the mip height. */ height?: number; /** Number of array layers or depth slices to write. Defaults to 1, or the full mip depth for 3D textures. */ depthOrArrayLayers?: number; /** Which mip-level to write into (default 0) */ mipLevel?: number; /** When writing into depth stencil textures (default 'all') */ aspect?: 'all' | 'stencil-only' | 'depth-only'; }; /** Texture properties */ export type TextureProps = ResourceProps & { /** @deprecated Use DynamicTexture to create textures with data. */ data?: ExternalImage | TypedArray | null; /** Dimension of this texture. Defaults to '2d' */ dimension?: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d'; /** The format (bit layout) of the textures pixel data */ format?: TextureFormat; /** Width in texels */ width: number; /** Width in texels */ height: number; /** Number of depth layers */ depth?: number; /** How this texture will be used. Defaults to TEXTURE | COPY_DST | RENDER_ATTACHMENT */ usage?: number; /** How many mip levels */ mipLevels?: number; /** Multi sampling */ samples?: number; /** Sampler (or SamplerProps) for the default sampler for this texture. Used if no sampler provided. Note that other samplers can still be used. */ sampler?: Sampler | SamplerProps; /** Props for the default TextureView for this texture. Note that other views can still be created and used. */ view?: TextureViewProps; }; /** * Abstract Texture interface * Texture Object * https://gpuweb.github.io/gpuweb/#gputexture */ export declare abstract class Texture extends Resource<TextureProps> { /** The texture can be bound for use as a sampled texture in a shader */ static SAMPLE: number; /** The texture can be bound for use as a storage texture in a shader */ static STORAGE: number; /** The texture can be used as a color or depth/stencil attachment in a render pass */ static RENDER: number; /** The texture can be used as the source of a copy operation */ static COPY_SRC: number; /** he texture can be used as the destination of a copy or write operation */ static COPY_DST: number; /** @deprecated Use Texture.SAMPLE */ static TEXTURE: number; /** @deprecated Use Texture.RENDER */ static RENDER_ATTACHMENT: number; /** dimension of this texture */ readonly dimension: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d'; /** base dimension of this texture */ readonly baseDimension: '1d' | '2d' | '3d'; /** format of this texture */ readonly format: TextureFormat; /** width in pixels of this texture */ readonly width: number; /** height in pixels of this texture */ readonly height: number; /** depth of this texture */ readonly depth: number; /** mip levels in this texture */ readonly mipLevels: number; /** sample count */ readonly samples: number; /** Rows are multiples of this length, padded with extra bytes if needed */ readonly byteAlignment: number; /** Default sampler for this texture */ abstract sampler: Sampler; /** Default view for this texture */ abstract view: TextureView; /** The ready promise is always resolved. It is provided for type compatibility with DynamicTexture. */ readonly ready: Promise<Texture>; /** isReady is always true. It is provided for type compatibility with DynamicTexture. */ readonly isReady: boolean; /** "Time" of last update. Monotonically increasing timestamp. TODO move to DynamicTexture? */ updateTimestamp: number; get [Symbol.toStringTag](): string; toString(): string; /** Do not use directly. Create with device.createTexture() */ constructor(device: Device, props: TextureProps, backendProps?: { byteAlignment?: number; }); /** * Create a new texture with the same parameters and optionally a different size * @note Textures are immutable and cannot be resized after creation, but we can create a similar texture with the same parameters but a new size. * @note Does not copy contents of the texture */ clone(size?: { width: number; height: number; }): Texture; /** Set sampler props associated with this texture */ setSampler(sampler: Sampler | SamplerProps): void; /** Create a texture view for this texture */ abstract createView(props: TextureViewProps): TextureView; /** Copy an image (e.g an ImageBitmap) into the texture */ abstract copyExternalImage(options: CopyExternalImageOptions): { width: number; height: number; }; /** * Copy raw image data (bytes) into the texture. * * @note Deprecated compatibility wrapper over {@link writeData}. * @note Uses the same layout defaults and alignment rules as {@link writeData}. * @note Tightly packed CPU uploads can omit `bytesPerRow` and `rowsPerImage`. * @note If the CPU source rows are padded, pass explicit `bytesPerRow` and `rowsPerImage`. * @deprecated Use writeData() */ copyImageData(options: CopyImageDataOptions): void; /** * Calculates the memory layout of the texture, required when reading and writing data. * @return the backend-aligned linear layout, in particular bytesPerRow which includes any required padding for buffer copy/read paths */ computeMemoryLayout(options_?: TextureReadOptions): TextureMemoryLayout; /** * Read the contents of a texture into a GPU Buffer. * @returns A Buffer containing the texture data. * * @note The memory layout of the texture data is determined by the texture format and dimensions. * @note The application can call Texture.computeMemoryLayout() to compute the backend-aligned layout. * @note The application can call Buffer.readAsync() to read the returned buffer on the CPU. * @note The destination buffer must be supplied by the caller and must be large enough for the requested region. * @note On WebGPU this corresponds to a texture-to-buffer copy and uses buffer-copy alignment rules. * @note On WebGL, luma.gl emulates the same logical readback behavior. */ readBuffer(options?: TextureReadOptions, buffer?: Buffer): Buffer; /** * Reads data from a texture into an ArrayBuffer. * @returns An ArrayBuffer containing the texture data. * * @note The memory layout of the texture data is determined by the texture format and dimensions. * @note The application can call Texture.computeMemoryLayout() to compute the layout. * @deprecated Use Texture.readBuffer() with an explicit destination buffer, or DynamicTexture.readAsync() for convenience readback. */ readDataAsync(options?: TextureReadOptions): Promise<ArrayBuffer>; /** * Writes a GPU Buffer into a texture. * * @param buffer - Source GPU buffer. * @param options - Destination subresource, extent, and source layout options. * @note The memory layout of the texture data is determined by the texture format and dimensions. * @note The application can call Texture.computeMemoryLayout() to compute the backend-aligned layout. * @note On WebGPU this corresponds to a buffer-to-texture copy and uses buffer-copy alignment rules. * @note On WebGL, luma.gl emulates the same destination and layout semantics. */ writeBuffer(buffer: Buffer, options?: TextureWriteOptions): void; /** * Writes an array buffer into a texture. * * @param data - Source texel data. * @param options - Destination subresource, extent, and source layout options. * @note If `bytesPerRow` and `rowsPerImage` are omitted, luma.gl computes a tightly packed CPU-memory layout for the requested region. * @note On WebGPU this corresponds to `GPUQueue.writeTexture()` and does not implicitly pad rows to 256 bytes. * @note On WebGL, padded CPU data is supported via the same `bytesPerRow` and `rowsPerImage` options. */ writeData(data: ArrayBuffer | SharedArrayBuffer | ArrayBufferView, options?: TextureWriteOptions): void; /** * WebGL can read data synchronously. * @note While it is convenient, the performance penalty is very significant */ readDataSyncWebGL(options?: TextureReadOptions): ArrayBuffer | ArrayBufferView; /** Generate mipmaps (WebGL only) */ generateMipmapsWebGL(): void; /** Ensure we have integer coordinates */ protected static normalizeProps(device: Device, props: TextureProps): TextureProps; /** Initialize texture with supplied props */ _initializeData(data: TextureProps['data']): void; _normalizeCopyImageDataOptions(options_: CopyImageDataOptions): Required<CopyImageDataOptions>; _normalizeCopyExternalImageOptions(options_: CopyExternalImageOptions): Required<CopyExternalImageOptions>; _normalizeTextureReadOptions(options_: TextureReadOptions): Required<TextureReadOptions>; /** * Normalizes a texture read request and validates the color-only readback contract used by the * current texture read APIs. Supported dimensions are `2d`, `cube`, `cube-array`, * `2d-array`, and `3d`. * * @throws if the texture format, aspect, or dimension is not supported by the first-pass * color-read implementation. */ protected _getSupportedColorReadOptions(options_: TextureReadOptions): Required<TextureReadOptions>; /** Validates that a read request targets the full color aspect of the texture. */ protected _validateColorReadAspect(options: Required<TextureReadOptions>): void; /** Validates that a read request targets an uncompressed color-renderable texture format. */ protected _validateColorReadFormat(formatInfo: TextureFormatInfo): void; _normalizeTextureWriteOptions(options_: TextureWriteOptions): Required<TextureWriteOptions>; protected _getMipLevelSize(mipLevel: number): Required<Pick<TextureReadOptions, 'width' | 'height' | 'depthOrArrayLayers'>>; protected getAllocatedByteLength(): number; protected static _omitUndefined<T extends object>(options: T): Partial<T>; static defaultProps: Required<TextureProps>; protected static defaultCopyDataOptions: Required<CopyImageDataOptions>; /** Default options */ protected static defaultCopyExternalImageOptions: Required<CopyExternalImageOptions>; protected static defaultTextureReadOptions: Required<TextureReadOptions>; protected static defaultTextureWriteOptions: Required<TextureWriteOptions>; } //# sourceMappingURL=texture.d.ts.map