threepipe/lib/materials/MaterialExtension.d.ts

A modern 3D viewer framework built on top of three.js, written in TypeScript, designed to make creating high-quality, modular, and extensible 3D experiences on the web simple and enjoyable.

import { IUniform, Object3D, WebGLProgramParametersWithUniforms, WebGLRenderer } from 'three';
import { IMaterial, IWebGLRenderer } from '../core';
import { UiObjectConfig } from 'uiconfig.js';
import { ValOrFunc } from 'ts-browser-helpers';
export type MaterialExtensionShader = WebGLProgramParametersWithUniforms;
/**
 * @deprecated use {@link MaterialExtensionShader} or {@link WebGLProgramParametersWithUniforms} instead
 */
export type Shader = WebGLProgramParametersWithUniforms;
/**
 * Material extension interface
 * This is used to extend a three.js material satisfying the IMaterial interface, with extra uniforms, defines, shader code, etc.
 */
export interface MaterialExtension {
    /**
     * Extra uniforms to copy to material
     */
    extraUniforms?: {
        [uniform: string]: ValOrFunc<IUniform>;
    };
    /**
     * Extra defines to copy to material
     * Note: boolean are converted to 0 and 1
     */
    extraDefines?: Record<string, ValOrFunc<number | string | undefined | boolean>>;
    /**
     * Custom callback to extend/modify/replace shader code and other shader properties
     * @param shader
     * @param material
     * @param renderer
     */
    shaderExtender?: (shader: MaterialExtensionShader, material: IMaterial, renderer: WebGLRenderer) => void;
    /**
     * Extra code to add to the top of the fragment shader
     * Value can be a string or a function that returns a string
     */
    parsFragmentSnippet?: string | ((renderer?: WebGLRenderer, material?: IMaterial) => string);
    /**
     * Extra code to add to the top of the vertex shader
     * Value can be a string or a function that returns a string
     */
    parsVertexSnippet?: string | ((renderer?: WebGLRenderer, material?: IMaterial) => string);
    /**
     * Custom cache key to use for this material extension.
     * A different cache key will cause the shader to be recompiled.
     * Check three.js docs for more info.
     * Value can be a string or a function that returns a string
     * This will only be checked if `material.needsUpdate` is `true`, not on every render.
     * Note: extension might never be registered if an empty string is returned.
     */
    computeCacheKey?: string | ((material: IMaterial) => string);
    /**
     * Custom callback to run code before the material is rendered
     * Executes from `material.onBeforeRender` for each material for each object it's rendered on.
     * @param object
     * @param material
     * @param renderer
     */
    onObjectRender?: (object: Object3D, material: IMaterial, renderer: IWebGLRenderer) => void;
    /**
     * Custom callback to run code after the material is rendered
     * Executes from `material.onAfterRender` for each material for each object it's rendered on.
     * @param object
     * @param material
     * @param renderer
     */
    onAfterRender?: (object: Object3D, material: IMaterial, renderer: IWebGLRenderer) => void;
    /**
     * Custom callback to run code when the material is updated. (when `materialUpdate` event is dispatched on the material)
     * @param material - material that was updated
     */
    onMaterialUpdate?: (material: IMaterial) => void;
    /**
     * Custom callback to run code when the material is added/applied to a mesh or any Object3D.
     * @param mesh - object/mesh applied to
     * @param material - material that was added
     */
    onAddToMesh?: (mesh: Object3D, material: IMaterial) => void;
    /**
     * Custom callback to run code when the material is removed from a mesh or any Object3D.
     * @param mesh
     * @param material
     */
    onRemoveFromMesh?: (mesh: Object3D, material: IMaterial) => void;
    /**
     * Custom callback to run code when this material extension is registered to a material.
     * @param material
     */
    onRegister?: (material: IMaterial) => void;
    /**
     * Custom callback to run code when this material extension is unregistered from a material.
     * @param material
     */
    onUnregister?: (material: IMaterial) => void;
    /**
     * Function to check if this material extension is compatible with the given material.
     * If not compatible, the material extension will not be added to the material.
     * This is only checked when the extension is registered.
     *
     * The extension is assumed to be compatible if this function is not defined
     * @param material
     */
    isCompatible?: (material: IMaterial) => boolean | undefined;
    /**
     * List of shader properties updaters to run on the material.
     *
     */
    updaters?: IShaderPropertiesUpdater[] | (() => IShaderPropertiesUpdater[]);
    /**
     * Function to return the UI config for this material extension.
     * This is called once when the material extension is registered.
     * @param material
     */
    getUiConfig?: (material: IMaterial, refreshUi?: UiObjectConfig['uiRefresh']) => UiObjectConfig | undefined;
    /**
     * Higher priority extensions are applied first. (or as they are added, depends on the type of extension)
     */
    priority?: number;
    updateVersion?: number;
    __setDirty?: () => void;
    uuid?: string;
    setDirty?: () => void;
}
export interface IShaderPropertiesUpdater {
    updateShaderProperties(material: {
        defines: Record<string, string | number | undefined>;
        uniforms: {
            [name: string]: IUniform;
        };
    }): void;
}
//# sourceMappingURL=../src/materials/MaterialExtension.d.ts.map