playcanvas/build/playcanvas/src/platform/graphics/shader.d.ts

PlayCanvas WebGL game engine

/**
 * A shader is a program that is responsible for rendering graphical primitives on a device's
 * graphics processor. The shader is generated from a shader definition. This shader definition
 * specifies the code for processing vertices and fragments processed by the GPU. The language of
 * the code is GLSL (or more specifically ESSL, the OpenGL ES Shading Language). The shader
 * definition also describes how the PlayCanvas engine should map vertex buffer elements onto the
 * attributes specified in the vertex shader code.
 *
 * @category Graphics
 */
export class Shader {
    /**
     * Creates a new Shader instance.
     *
     * Consider {@link ShaderUtils#createShader} as a simpler and more powerful way to create
     * a shader.
     *
     * @param {GraphicsDevice} graphicsDevice - The graphics device used to manage this shader.
     * @param {object} definition - The shader definition from which to build the shader.
     * @param {string} [definition.name] - The name of the shader.
     * @param {Object<string, string>} [definition.attributes] - Object detailing the mapping of
     * vertex shader attribute names to semantics SEMANTIC_*. This enables the engine to match
     * vertex buffer data as inputs to the shader. When not specified, rendering without vertex
     * buffer is assumed.
     * @param {string[]} [definition.feedbackVaryings] - A list of shader output variable
     * names that will be captured when using transform feedback. This setting is only effective
     * if the useTransformFeedback property is enabled.
     * @param {string} [definition.vshader] - Vertex shader source (GLSL code). Optional when
     * compute shader is specified.
     * @param {string} [definition.fshader] - Fragment shader source (GLSL code). Optional when
     * useTransformFeedback or compute shader is specified.
     * @param {string} [definition.cshader] - Compute shader source (WGSL code). Only supported on
     * WebGPU platform.
     * @param {Map<string, string>} [definition.vincludes] - A map containing key-value pairs of
     * include names and their content. These are used for resolving #include directives in the
     * vertex shader source.
     * @param {Map<string, string>} [definition.fincludes] - A map containing key-value pairs
     * of include names and their content. These are used for resolving #include directives in the
     * fragment shader source.
     * @param {Map<string, string>} [definition.cincludes] - A map containing key-value pairs
     * of include names and their content. These are used for resolving #include directives in the
     * compute shader source.
     * @param {boolean} [definition.useTransformFeedback] - Specifies that this shader outputs
     * post-VS data to a buffer.
     * @param {string | string[]} [definition.fragmentOutputTypes] - Fragment shader output types,
     * which default to vec4. Passing a string will set the output type for all color attachments.
     * Passing an array will set the output type for each color attachment.
     * @param {string} [definition.shaderLanguage] - Specifies the shader language of vertex and
     * fragment shaders. Defaults to {@link SHADERLANGUAGE_GLSL}.
     * @example
     * // Create a shader that renders primitives with a solid red color
     *
     * // Vertex shader
     * const vshader = `
     * attribute vec3 aPosition;
     *
     * void main(void) {
     *     gl_Position = vec4(aPosition, 1.0);
     * }
     * `;
     *
     * // Fragment shader
     * const fshader = `
     * precision ${graphicsDevice.precision} float;
     *
     * void main(void) {
     *     gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0);
     * }
     * `;
     *
     * const shaderDefinition = {
     *     attributes: {
     *         aPosition: pc.SEMANTIC_POSITION
     *     },
     *     vshader,
     *     fshader
     * };
     *
     * const shader = new pc.Shader(graphicsDevice, shaderDefinition);
     */
    constructor(graphicsDevice: GraphicsDevice, definition: {
        name?: string;
        attributes?: {
            [x: string]: string;
        };
        feedbackVaryings?: string[];
        vshader?: string;
        fshader?: string;
        cshader?: string;
        vincludes?: Map<string, string>;
        fincludes?: Map<string, string>;
        cincludes?: Map<string, string>;
        useTransformFeedback?: boolean;
        fragmentOutputTypes?: string | string[];
        shaderLanguage?: string;
    });
    /**
     * Format of the uniform buffer for mesh bind group.
     *
     * @type {UniformBufferFormat}
     * @ignore
     */
    meshUniformBufferFormat: UniformBufferFormat;
    /**
     * Format of the bind group for the mesh bind group.
     *
     * @type {BindGroupFormat}
     * @ignore
     */
    meshBindGroupFormat: BindGroupFormat;
    /**
     * The attributes that this shader code uses. The location is the key, the value is the name.
     * These attributes are queried / extracted from the final shader.
     *
     * @type {Map<number, string>}
     * @ignore
     */
    attributes: Map<number, string>;
    id: number;
    device: GraphicsDevice;
    definition: {
        name?: string;
        attributes?: {
            [x: string]: string;
        };
        feedbackVaryings?: string[];
        vshader?: string;
        fshader?: string;
        cshader?: string;
        vincludes?: Map<string, string>;
        fincludes?: Map<string, string>;
        cincludes?: Map<string, string>;
        useTransformFeedback?: boolean;
        fragmentOutputTypes?: string | string[];
        shaderLanguage?: string;
    };
    name: string;
    vUnmodified: string;
    fUnmodified: string;
    failed: boolean;
    impl: any;
    /**
     * Initialize a shader back to its default state.
     *
     * @private
     */
    private init;
    ready: boolean;
    /** @ignore */
    get label(): string;
    /**
     * Frees resources associated with this shader.
     */
    destroy(): void;
    /**
     * Called when the WebGL context was lost. It releases all context related resources.
     *
     * @ignore
     */
    loseContext(): void;
    /** @ignore */
    restoreContext(): void;
}
import type { UniformBufferFormat } from './uniform-buffer-format.js';
import type { BindGroupFormat } from './bind-group-format.js';
import type { GraphicsDevice } from './graphics-device.js';