playcanvas/build/playcanvas/src/scene/shader-lib/shader-chunks.d.ts

Open-source WebGL/WebGPU 3D engine for the web

/**
 * A collection of GLSL and WGSL shader chunks, used to generate shaders.
 *
 * @category Graphics
 */
export class ShaderChunks {
    /**
     * Static map of chunk validations shared by all instances.
     *
     * @type {Map<string, ChunkValidation>}
     * @private
     */
    private static _validations;
    /**
     * Returns a shader chunks map for the given device and shader language.
     *
     * @param {GraphicsDevice} device - The graphics device.
     * @param {string} shaderLanguage - The shader language to use (GLSL or WGSL).
     * @returns {ShaderChunkMap} The shader chunks for the specified language.
     */
    static get(device: GraphicsDevice, shaderLanguage?: string): ShaderChunkMap;
    /**
     * Register a validation for a shader chunk. When the chunk is set, the validation will be
     * executed. This is useful for deprecation warnings or content validation.
     *
     * @param {string} name - The name of the shader chunk.
     * @param {ChunkValidation} options - Validation options.
     * @example
     * // Deprecate an existing chunk - only warn when overridden with non-default code
     * import { myChunksGLSL } from './glsl/collections/my-chunks-glsl.js';
     * import { myChunksWGSL } from './wgsl/collections/my-chunks-wgsl.js';
     *
     * ShaderChunks.registerValidation('myChunkVS', {
     *     message: 'myChunkVS is deprecated. Use newChunkVS instead.',
     *     defaultCodeGLSL: myChunksGLSL.myChunkVS,
     *     defaultCodeWGSL: myChunksWGSL.myChunkVS
     * });
     * @example
     * // Warn for a removed chunk - any attempt to use it triggers warning
     * ShaderChunks.registerValidation('removedChunkVS', {
     *     message: 'removedChunkVS has been removed. Use replacementChunkVS instead.'
     * });
     * @example
     * // Use callback for custom validation logic
     * ShaderChunks.registerValidation('myChunkVS', {
     *     callback: (name, code) => {
     *         if (code.includes('gl_FragColor')) {
     *             Debug.error(`Chunk ${name} uses deprecated gl_FragColor. Use pcFragColor instead.`);
     *         }
     *     }
     * });
     * @ignore
     */
    static registerValidation(name: string, options: ChunkValidation): void;
    /**
     * A map of shader chunks for GLSL.
     *
     * @type {ShaderChunkMap}
     * @ignore
     */
    glsl: ShaderChunkMap;
    /**
     * A map of shader chunks for WGSL.
     *
     * @type {ShaderChunkMap}
     * @ignore
     */
    wgsl: ShaderChunkMap;
    /**
     * Specifies the API version of the shader chunks.
     *
     * This should be a string containing the current engine major and minor version (e.g., '2.8'
     * for engine v2.8.1) and ensures compatibility with the current engine version. When providing
     * custom shader chunks, set this to the latest supported version. If a future engine release no
     * longer supports the specified version, a warning will be issued. In that case, update your
     * shader chunks to match the new format and set this to the latest version accordingly.
     */
    version: string;
    get useWGSL(): boolean;
    get key(): string;
    isDirty(): boolean;
    resetDirty(): void;
    /**
     * Copy the shader chunks.
     *
     * @param {ShaderChunks} source - The instance to copy.
     * @returns {ShaderChunks} The destination instance.
     * @ignore
     */
    copy(source: ShaderChunks): ShaderChunks;
}
import { ShaderChunkMap } from './shader-chunk-map.js';
import type { GraphicsDevice } from '../../platform/graphics/graphics-device.js';
import type { ChunkValidation } from './shader-chunk-map.js';