@three3d/effect

/** * ThreeJS的特效库 * * @remarks * ThreeJS 的一些特效 * * @packageDocumentation */ import { BufferGeometry } from 'three'; import { ColorRepresentation } from 'three'; import { ComputeCurveFrenetFramesOptions } from '@three3d/tools'; import { CreateLineConnectionOptions } from '@three3d/tools'; import { Curve } from 'three'; import { CurvePath } from 'three'; import type { FrenetFrames } from '@three3d/tools'; import type { IUniform } from 'three'; import { IVector3 } from '@three3d/tools'; import { LineConnectionType } from '@three3d/tools'; import type { Material } from 'three'; import type { Point_Length_FrenetFrames } from '@three3d/tools'; import type { SampleOptions } from '@three3d/tools'; import { Shader } from 'three'; import { Vector2 } from 'three'; import { Vector3 } from 'three'; import { WebGLRenderer } from 'three'; export declare function addUniformPropertiesOnMaterial<M extends Material, U extends Record<string, any>>(material: M, uniforms: U, shaderUniforms?: Record<string, IUniform<any>>): ModifiedMaterial<M, U>; export declare function addUniforms<U extends Record<string, any>>(shaderUniforms: Record<string, IUniform<any>>, uniforms: U): Record<string, IUniform<any>>; /** * 带状几何体 * @remarks * 可根据曲线、折线点来生成带状几何体； * 支持路径追加； * 支持设置起始长度 * 支持起始-终点颜色渐变 * 支持绘制的指定的长度区间 * 支持设置宽度 * 支持设置带状几何体起始位置处的向上方向 */ export declare class BandGeometry extends PathGeometry<BandGeometryOptions> { readonly isBandGeometry = true; static options: BandGeometryOptions; constructor(options?: BandGeometryOptions); /** * 起点处的向上的方向 { x: 0, y: 1, z: 0 } * @defaultValue */ get up(): IVector3; set up(value: IVector3); /** * 是否固定 up；保证up不变 * @defaultValue false */ get fixUp(): boolean; set fixUp(value: boolean); /** * 是否固定 up；保证up不变 * @defaultValue false */ get useU(): boolean; set useU(value: boolean); /** * uv的步长 * * @defaultValue 1 */ get uvStep(): number; set uvStep(value: number); /** * CurvePath 的绘制类型 * @defaultValue BandDrawType.blend */ get drawType(): PathDrawType; set drawType(value: PathDrawType); /** * 线的衔接类型 * @defaultValue LineConnectionType.round */ get connectionType(): LineConnectionType; set connectionType(value: LineConnectionType); /** * 圆形衔接角的长度步长 * @remarks * 与 smoothStepAngle 作用相同 * smoothStepAngle 的优先级高于 smoothStepLength */ get smoothStepLength(): number | undefined; set smoothStepLength(value: number | undefined); /** * 圆形衔接角的步长角 * @remarks * 与 smoothStepLength 作用相同 * smoothStepAngle 的优先级高于 smoothStepLength * @defaultValue LineConnectionType.round */ get smoothStepAngle(): number | undefined; set smoothStepAngle(value: number | undefined); append(pathItem: PathItem): void; updateGeometry(): void; /** * 几何体的数据 */ get geometryData(): { position: number[]; normal: number[]; uv: number[]; index: number[]; color: number[]; lineDistance: number[]; lengths: number[]; points: Vector3[]; tangents: Vector3[]; normals: Vector3[]; binormals: Vector3[]; } | null; /** * 未闭合的几何体的数据 */ get openedGeometryData(): BandGeometryData | null; frenetFrames: Point_Length_FrenetFrames | null; /** * 重围所有的 Attributes * @param attrs */ resetAttributes(attrs: BandGeometryData): void; /** * 获取顶点索引对应的分段索引 * @remarks * 分段指的是沿路径的方向上的分段 * @param vertexIndex * @returns */ getDivisionIndex(vertexIndex: number): number; /** * 设置绘制的长度范围 * @param startLength * @param endLength */ setDrawLength(startLength: number, endLength?: number | null): void; } export declare type BandGeometryData = ReturnType<typeof createCurveBandGeometryData>; /** * BandGeometry的选项 */ export declare interface BandGeometryOptions extends PathGeometryOptions, CreateLineConnectionOptions, Omit<ComputeCurveFrenetFramesOptions, "closed"> { /** * 起点处的向上的方向 { x: 0, y: 1, z: 0 } * @defaultValue */ up?: IVector3; /** * uv的步长 * * @defaultValue 1 */ uvStep?: number; /** * CurvePath 的绘制类型 * @defaultValue BandDrawType.blend */ drawType?: PathDrawType; /** * 被视为转角的最小角度 */ minCorner?: number; } /** * 连接两个 BandGeometryData * @param frontData * @param backData * @param options * @param lengthConnectType - 长度的连接类型 * @returns */ export declare function connectBandGeometryData(frontData: BandGeometryData, backData: BandGeometryData, options: CreateBandGeometryDataOptions, lengthConnectType?: LengthConnectType): { position: number[]; normal: number[]; uv: number[]; color: number[]; lineDistance: number[]; index: number[]; points: Vector3[]; lengths: number[]; length: number; tangents: Vector3[]; normals: Vector3[]; binormals: Vector3[]; }; export declare interface CreateBandGeometryDataOptions extends Omit<BandGeometryOptions, "startLength" | "up"> { /** * 起点处的向上的方向 */ up: Vector3; /** * 上一个点的索引 * @remarks * 索引从哪里开始 */ preIndex?: number; /** * 上一个顶点 */ prePoint?: Vector3 | null; /** * 上一个点的长度 */ preLength?: number; /** * 是否拼接以前的索引 */ connectPre?: boolean | null; } /** * 根据 pathData 创建混合方式的 BandGeometry 所需要的数据 * @param pathData * @param options * @param preGeoData * @returns */ export declare function createBlendBandGeometryData(pathData: PathData, options: CreateBandGeometryDataOptions, preGeoData?: BandGeometryData | null): { position: number[]; normal: number[]; uv: number[]; index: number[]; color: number[]; lineDistance: number[]; lengths: number[]; points: Vector3[]; tangents: Vector3[]; normals: Vector3[]; binormals: Vector3[]; }; /** * 根据曲线生成 BandGeometry 所需要的数据 * @param curve * @param options * @returns */ export declare function createCurveBandGeometryData(curve: Curve<Vector3>, options: CreateBandGeometryDataOptions): { position: number[]; normal: number[]; uv: number[]; index: number[]; color: number[]; lineDistance: number[]; lengths: number[]; points: Vector3[]; tangents: Vector3[]; normals: Vector3[]; binormals: Vector3[]; }; export declare function createCurveBandGeometryDataByFrenetFrames(frenetFrames: FrenetFramesOfCreateCurveBandGeometryData, options: CreateBandGeometryDataOptions): { position: number[]; normal: number[]; uv: number[]; index: number[]; color: number[]; lineDistance: number[]; lengths: number[]; points: Vector3[]; tangents: Vector3[]; normals: Vector3[]; binormals: Vector3[]; }; /** * 创建 onBeforeCompile 函数 * @param mender * @param uniforms * @returns */ export declare function createOnBeforeCompile<U extends Record<string, any>>(mender: OnBeforeCompile, uniforms?: U, material?: Material): (shader: Shader, renderer: WebGLRenderer) => void; /** * 根据折线生成 BandGeometry 所需要的数据 * @param points * @param options * @returns */ export declare function createPolylineBandGeometryData(points: Vector3[], options: CreateBandGeometryDataOptions): { position: number[]; normal: number[]; uv: number[]; color: number[]; index: number[]; lineDistance: number[]; length: number; lengths: number[]; points: Vector3[]; tangents: Vector3[]; normals: Vector3[]; binormals: Vector3[]; }; /** * 根据折线的 frenetFrames 生成 BandGeometry 所需要的数据 * @param points * @param options * @returns */ export declare function createPolylineBandGeometryDataByFrenetFrames(frenetFrames: Point_Length_FrenetFrames, options: CreateBandGeometryDataOptions): { position: number[]; normal: number[]; uv: number[]; color: number[]; index: number[]; lineDistance: number[]; length: number; lengths: number[]; points: Vector3[]; tangents: Vector3[]; normals: Vector3[]; binormals: Vector3[]; }; /** * 根据折线创建用于 PathGeometry 的数据 * @param points * @param options * @returns */ export declare function createPolylinePathGeometryData(points: Vector3[], options?: PathGeometryOptions | null): { color: number[]; position: number[]; lineDistance: number[]; lengths: number[]; points: Vector3[]; }; export declare type FrenetFramesOfCreateCurveBandGeometryData = FrenetFrames & { points: Vector3[]; length: number; }; /** * 获取与 target 最近的索引 * @param sortedNums - 按照从小到大顺序数字数组 * @param target - 目标值 * @returns */ export declare function getClosestIndex(sortedNums: ArrayLike<number>, target: number): number; /** * 获取曲线的点 * @param curve * @param options * @returns */ export declare function getCurvePoints(curve: Curve<Vector3>, options?: SampleOptions): Vector3[]; /** * 获取 target 附近的索引 * @param sortedNums - 按照从小到大顺序数字数组 * @param target - 目标值 * @param right - 是否获取目标值右侧的索引； * @returns 当返回 -1 时，表示没找到 */ export declare function getNearbyIndex(sortedNums: ArrayLike<number>, target: number, right?: boolean): number; /** * 获取 PathItem 的终点 * @param pathData * @returns */ export declare function getPathItemEndPoint(pathItem: PathItem): Vector3; /** * 获取 PathItem 的起始点 * @param pathData * @returns */ export declare function getPathItemStartPoint(pathItem: PathItem): Vector3; /** * 保存顶点长度的 AttributeName */ export declare const lengthAttributeName = "lineDistance"; /** * 长度连接类型 */ export declare enum LengthConnectType { /** * 保持原样 */ intact = "intact", /** * 累加 */ add = "add", /** * 累加，并将间隔计算进去 */ addGap = "addGap" } /** * lengthDrawRange 的片元着色器中增加的核心代码 */ export declare const lengthDrawRange_fragment_mainReplace = "\nuniform bool invert;\nuniform bool enableStart;\nuniform bool enableEnd;\n\nuniform float startLength;\nuniform float endLength;\nvoid main() {\n bool startDiscard = enableStart && vLineDistance < startLength;\n bool endDiscard = enableEnd && vLineDistance > endLength;\n bool isDiscard = startDiscard || endDiscard;\n if (invert){\n isDiscard = !isDiscard;\n }\n if (isDiscard) discard;\n"; /** * 针对于一切带有 lineDistance attribute 的几何体的材质的片元着色器增加的代码片段 * @remarks * 对于除 LineDashedMaterial 之外的材质的顶点着色器增加的代码 */ export declare const lengthDrawRange_fragment_pars_mainReplace = "\nvarying float vLineDistance;\n"; /** * 针对于一切带有 lineDistance attribute 的几何体的材质的 shader 的修改器 * @remarks * Mender 都是用于 `createOnBeforeCompile` 方法的 * 对于除 LineDashedMaterial 之外的材质的顶点着色器增加的代码 * @param shader */ export declare function lengthDrawRange_Mender(shader: Shader): void; /** * 针对于一切带有 lineDistance attribute 的几何体的材质的 onBeforeCompile 函数 */ export declare const lengthDrawRange_onBeforeCompile: OnBeforeCompile; /** * lengthDrawRange 增加的 uniforms */ export declare const lengthDrawRange_uniforms: { invert: boolean; enableStart: boolean; enableEnd: boolean; startLength: number; endLength: number; }; /** * 针对于一切带有 lineDistance attribute 的几何体的材质的顶点着色器增加的代码 * @remarks * 对于除 LineDashedMaterial 之外的材质的顶点着色器增加的代码 */ export declare const lengthDrawRange_vertex_mainReplace = "\nattribute float lineDistance;\nvarying float vLineDistance;\nvoid main() {\n vLineDistance = lineDistance;\n"; /** * 用于一切带有 lineDistance attribute 的几何体的材质的长度范围渲染的材质修改器 * @remarks * 材质被修改后可具备设置渲染指定长度范围内的线的功能 * @param material * @returns */ export declare function lengthDrawRangeModifier<M extends Material>(material: M): ModifiedMaterial<M, { invert: boolean; enableStart: boolean; enableEnd: boolean; startLength: number; endLength: number; }>; /** * 用于线性几何体的属性数据 */ export declare interface LineAttributesData { position: number[]; lineDistance: number[]; lengths: number[]; color?: number[]; } /** * 针对于 LineDashedMaterial 材质的 shader 的修改器 * @remarks * Mender 都是用于 `createOnBeforeCompile` 方法的 * @param shader */ export declare function lineDashedLengthDrawRange_Mender(shader: Shader): void; /** * 针对于 LineDashedMaterial 材质的 onBeforeCompile 函数 */ export declare const lineDashedLengthDrawRange_onBeforeCompile: OnBeforeCompile; /** * 用于Mesh几何体的属性数据 */ export declare interface MeshAttributesData extends LineAttributesData { normal?: number[]; uv?: number[]; index?: number[]; points: Vector3[]; } export declare const minFun_Regex: RegExp; export declare type ModifiedMaterial<M extends Material, U extends Record<string, any>> = M & { uniforms: RecordToUniforms<U>; } & U; export declare type OnBeforeCompile = Material["onBeforeCompile"]; export declare type PathData<Vec extends Vector3 | Vector2 = Vector3> = PathItem<Vec>[]; /** * 路径数据转连续曲线 * @remarks * 保证转换后的所有曲线段是首尾相接的 * @param pathData * @returns */ export declare function pathDataToContinuousCurves<Vec extends Vector3 | Vector2>(pathData: PathData<Vec>): Curve<Vec>[]; /** * 路径数据转曲线 * @remarks * 只是将 pathData 中所描述的曲线段数据转成对应的曲线； * 不保证转换后的所有曲线段是首尾相接的； * @param pathData * @returns */ export declare function pathDataToCurves<Vec extends Vector3 | Vector2>(pathData: PathData<Vec>): Curve<Vec>[]; export declare enum PathDrawType { /** * 以曲线的方式来绘制 */ curve = "curve", /** * 以折线的方式来绘制 */ polyline = "polyline", /** * 使用混合的方式来绘制 * @remarks * 会根据组成曲线的各个子曲线的具体类型来分别绘制各个子曲线 */ blend = "blend" } /** * 路径Geometry * @remarks * 可根据曲线、点来生成路径几何体； * 支持路径追加； * 支持设置起始长度 * 支持起始-终点颜色渐变 * 支持绘制的指定的长度区间 * */ export declare class PathGeometry<Options extends PathGeometryOptions> extends BufferGeometry { readonly isPathGeometry = true; constructor(options?: Options); /** * 全局选项 * @remarks * 类级别的选项，对所有后续创建的实例有效； * 优化级低于实例级别的选项 * * @defaultValue default_PathGeometryOptions */ static options: PathGeometryOptions; /** * 全局选项 */ get globalOptions(): Options; protected _options: Options | null; /** * 实例级别的选项 * @remarks * 优先级高于类级别的选项 */ get options(): Options; set options(value: Options); /** * 路径的宽度 */ get width(): number; set width(value: number); /** * 采样长度 */ get sampleLength(): number; set sampleLength(value: number); /** * 采样数 */ get sampleNum(): number | undefined; set sampleNum(value: number | undefined); /** * 是否自动闭合 */ get autoClose(): boolean | undefined; set autoClose(value: boolean | undefined); /** * 当前是否已经闭合 */ get closed(): boolean; /** * 线的颜色 * @remarks * 顶点颜色 */ get color(): ColorRepresentation | null | undefined; set color(value: ColorRepresentation | null | undefined); /** * 线开始处的颜色 * @remarks * 用于生成路径的从开始颜色到结束颜色的过渡颜色 * * @defaultValue this.color */ get startColor(): ColorRepresentation | null; set startColor(value: ColorRepresentation | null); /** * 终点处的颜色 * @remarks * 用于生成路径的从开始颜色到结束颜色的过渡颜色 * * @defaultValue this.color */ get endColor(): ColorRepresentation | null; set endColor(value: ColorRepresentation | null); /** * 路径起始位置处的长度 */ get startLength(): number; set startLength(value: number); /** * 终点位置处的长度 */ get endLength(): number; /** * 获取顶点对应的长度的数组 */ get lineDistance(): ArrayLike<number>; /** * 获取与指定长度值最近的索引 * @param length - 目标长度值 * @returns */ getClosestIndex(length: number): number; /** * 获取目标长度值附近的索引 * @param length - 目标长度值 * @param right - 是否获取目标值右侧的索引； * @returns 当返回 -1 时，表示没找到 */ getNearbyIndex(length: number, right?: boolean): number; /** * 设置绘制的长度范围 * @param startLength * @param endLength */ setDrawLength(startLength: number, endLength?: number | null): void; protected _startDrawLength: number; /** * 开始绘制的长度范围 */ get startDrawLength(): number; set startDrawLength(value: number); protected _endDrawLength: number | null; /** * 结束绘制的长度范围 */ get endDrawLength(): number; set endDrawLength(value: number); copy(source: BufferGeometry): this; /** * 顶点个数 */ get vertexCount(): number; /** * 路径数据 */ get pathData(): PathData<Vector3>; set pathData(value: PathData<Vector3>); protected _pathData: PathData<Vector3>; get closedPathData(): PathData<Vector3>; /** * 组成路径的曲线列表 */ get curves(): Curve<Vector3>[]; set curves(value: Curve<Vector3>[]); protected _curves: Curve<Vector3>[]; /** * 表示路径的曲线 */ get curvePath(): CurvePath<Vector3>; set curvePath(value: CurvePath<Vector3>); protected _curvePath: CurvePath<Vector3>; /** * 闭合的曲线路径 */ get closedCurvePath(): CurvePath<Vector3>; /** * 生成曲线 * @returns */ generateCurvePath(): CurvePath<Vector3>; /** * 所有的顶点 */ points: Vector3[]; /** * 曲线上生成的点 */ lengths: number[]; /** * 线性几何体本身的长度 */ get length(): number; /** * curvePath 上的最后一个点 */ get lastPoint(): Vector3; /** * curvePath 上的第一个点 */ get firstPoint(): Vector3; append(pathItem: PathItem): void; set(pathItem: PathItem): void; updateGeometry(): void; /** * 追加新的属性 * @param attrs */ appendAttributes(attrs: MeshAttributesData): void; /** * 重围所有的 Attributes * @param attrs */ resetAttributes(attrs: MeshAttributesData): void; /** * position 属性中的最后一个点 */ get lastPosition(): Vector3 | null; } /** * PathGeometry 的选项 */ export declare interface PathGeometryOptions extends SampleOptions { /** * 路径的宽度 */ width?: number; /** * 路径起始位置处的长度 */ startLength?: number; /** * 是否自动闭合 */ autoClose?: boolean; /** * 线的颜色 * @remarks * 顶点颜色 */ color?: ColorRepresentation | null; /** * 线开始处的颜色 * @remarks * 用于生成路径的从开始颜色到结束颜色的过渡颜色 * * @defaultValue this.color */ startColor?: ColorRepresentation | null; /** * 终点处的颜色 * @remarks * 用于生成路径的从开始颜色到结束颜色的过渡颜色 * * @defaultValue this.color */ endColor?: ColorRepresentation | null; } export declare type PathItem<Vec extends Vector3 | Vector2 = Vector3> = Curve<Vec> | PolylinePoints<Vec> | Vec; /** * pathItem 转曲线 * @param item * @param lastPoint * @param continuous - 是否生成连续的曲线；如果是，则会连接 lastPoint 和曲线开始点 * @returns */ export declare function pathItemToCurve<Vec extends Vector3 | Vector2>(item: PathItem<Vec>, lastPoint?: Vec | null, continuous?: boolean): Curve<Vec> | null; /** * pathItem 转曲线 * @param item * @param lastPoint * @param continuous - 是否生成连续的曲线；如果是，则会连接 lastPoint 和曲线开始点 * @returns */ export declare function pathItemToCurves<Vec extends Vector3 | Vector2>(item: PathItem<Vec>, lastPoint?: Vec | null, continuous?: boolean): Curve<Vec>[]; export declare type PolylinePoints<Vec extends Vector3 | Vector2 = Vector3> = Vec[]; export declare type RecordToUniforms<U extends Record<string, any>> = { [K in keyof U]: IUniform<U[K]>; }; /** * uvDrawRange 在片元着色器中增加的代核心代码 */ export declare const uvDrawRange_fragment_mainReplace = "\nuniform bool invert;\nuniform bool enableURange;\nuniform bool enableVRange;\n\nuniform vec2 uvMax;\nuniform vec2 uvMin;\nvoid main() {\n bool isDiscard = false;\n #if defined(USE_MAP) || defined(USE_UV)\n vec2 rangeUV; \n #ifdef USE_MAP\n rangeUV = vMapUv;\n #else\n rangeUV = vUv;\n #endif\n bool xDiscard = enableURange && ( uvMin.x > rangeUV.x || rangeUV.x > uvMax.x);\n bool yDiscard = enableVRange && (uvMin.y > rangeUV.y || rangeUV.y > uvMax.y);\n isDiscard = xDiscard || yDiscard;\n #endif\n\n if (invert){\n isDiscard = !isDiscard;\n }\n if (isDiscard) discard;\n"; /** * uvDrawRange 的 shader 的修改器 * @remarks * Mender 都是用于 `createOnBeforeCompile` 方法的 * @param shader */ export declare function uvDrawRange_Mender(shader: Shader): void; /** * uvDrawRange 用于材质的 onBeforeCompile 函数 */ export declare const uvDrawRange_onBeforeCompile: OnBeforeCompile; /** * uvDrawRange 增加的 uniforms */ export declare const uvDrawRange_uniforms: { invert: boolean; enableURange: boolean; enableVRange: boolean; uvMax: Vector2; uvMin: Vector2; }; /** * 用于实现绘制指定uv范围的材质修改器 * @remarks * 材质被修改后可具备设置绘制指定uv范围 * @param material * @returns */ export declare function uvDrawRangeModifier<M extends Material>(material: M): ModifiedMaterial<M, { invert: boolean; enableURange: boolean; enableVRange: boolean; uvMax: Vector2; uvMin: Vector2; }>; export { }