diff --git a/src/foundry/client/config.d.ts b/src/foundry/client/config.d.ts index 3755115ff..9d3f6515a 100644 --- a/src/foundry/client/config.d.ts +++ b/src/foundry/client/config.d.ts @@ -1789,7 +1789,9 @@ declare global { [key: string]: LayerDefinition; } - interface GroupDefinition { + interface GroupDefinition< + GroupClass extends ToSpriteConstructor = ToSpriteConstructor, + > { groupClass: GroupClass; parent: string; } @@ -1893,6 +1895,10 @@ interface CanvasGroupConstructor extends PixiContainerConstructor { /** * The name of this canvas group + * @remarks Not used in EffectsCanvasGroup in v11 */ - groupName: string; + groupName?: string; } + +type ToSpriteConstructor any> = Pick & + (new (sprite: SpriteMesh) => InstanceType); diff --git a/src/foundry/client/pixi/core/containers/base-canvas-group.d.ts b/src/foundry/client/pixi/core/containers/base-canvas-group.d.ts index 1a1e25226..2d357b039 100644 --- a/src/foundry/client/pixi/core/containers/base-canvas-group.d.ts +++ b/src/foundry/client/pixi/core/containers/base-canvas-group.d.ts @@ -34,7 +34,7 @@ declare global { * @param ContainerClass - The parent Container class being mixed. * @returns A ContainerClass subclass mixed with BaseCanvasMixin features. */ - function BaseCanvasMixin( + function BaseCanvasMixin>( ContainerClass: BaseClass, ): Mixin; } diff --git a/src/foundry/client/pixi/groups/effects.d.ts b/src/foundry/client/pixi/groups/effects.d.ts index 552960e70..95bf34914 100644 --- a/src/foundry/client/pixi/groups/effects.d.ts +++ b/src/foundry/client/pixi/groups/effects.d.ts @@ -1,29 +1,166 @@ -/** - * A container group which contains visual effects rendered above the primary group. - */ -declare class EffectsCanvasGroup extends PIXI.Container { - constructor(); +export {}; - walls: WallsLayer; +type CanvasBackgroundAlterationEffects = unknown; - lighting: LightingLayer; +type CanvasIlluminationEffects = unknown; - weather: WeatherLayer; +type CanvasColorationEffects = unknown; - sight: SightLayer; - - /** @defaultValue `true` */ - sortableChildren: boolean; +type CanvasVisibility = unknown; +declare global { /** - * The name of this canvas group - * @defaultValue `"effects"` + * A container group which contains visual effects rendered above the primary group. */ - static groupName: string; + class EffectsCanvasGroup extends PIXI.Container { + constructor(); - /** - * Create the member layers of the scene container - * @internal - */ - protected _createLayers(): void; + /** + * The current global light source. + */ + globalLightSource: GlobalLightSource; + + /** + * Whether to currently animate light sources. + */ + animateLightSources: boolean; + + /** + * Whether to currently animate vision sources. + */ + animateVisionSources: boolean; + + /** + * A mapping of light sources which are active within the rendered Scene. + */ + lightSources: Collection; + + /** + * A Collection of vision sources which are currently active within the rendered Scene. + */ + visionSources: Collection; + + /** + * A set of vision mask filters used in visual effects group + */ + visualEffectsMaskingFilters: Set; + + /** + * A layer of background alteration effects which change the appearance of the primary group render texture. + */ + background: CanvasBackgroundAlterationEffects; + + /** + * A layer which adds illumination-based effects to the scene. + */ + illumination: CanvasIlluminationEffects; + + /** + * A layer which adds color-based effects to the scene. + */ + coloration: CanvasColorationEffects; + + /** + * A layer which controls the current visibility of the scene. + */ + visibility: CanvasVisibility; + + /** + * Clear all effects containers and animated sources. + */ + clearEffects(): void; + + /** + * Draw the component layers of the canvas group. + */ + draw(): Promise; + + /** + * Actions to take when the darkness level is changed + * @param darkness - The new darkness level + * @param prior - The prior darkness level + * @internal + */ + _onDarknessChange(darkness: number, prior: number): void; + + /** + * Initialize LightSource objects for all AmbientLightDocument instances which exist within the active Scene. + */ + initializeLightSources(): void; + + /** + * Update the global light source which provides global illumination to the Scene. + * @param options - Options which modify how the source is updated + */ + updateGlobalLightSource(options: { + /** + * Defer updating perception to manually update it later + * @defaultValue `false` + */ + defer: boolean; + }): void; + + /** + * Refresh the state and uniforms of all LightSource objects. + */ + refreshLightSources(): boolean; + + /** + * Refresh the state and uniforms of all VisionSource objects. + */ + refreshVisionSources(): boolean; + + /** + * Refresh the active display of lighting. + */ + refreshLighting(): boolean; + + /** + * Perform a deconstruction workflow for this canvas group when the canvas is retired. + */ + tearDown(): Promise; + + /** + * Activate vision masking for visual effects + * @param enabled - Whether to enable or disable vision masking + * (default: `true`) + */ + toggleMaskingFilters(enabled: boolean): void; + + /** + * Activate post-processing effects for a certain effects channel. + * @param filterMode - The filter mode to target. + * @param postProcessingModes - The post-processing modes to apply to this filter. + * @param uniforms - The uniforms to update. + */ + activatePostProcessingFilters( + filterMode: VisualEffectsMaskingFilter.FilterMode, + postProcessingModes: VisualEffectsMaskingFilter.PostProcessModes, + uniforms: AbstractBaseShader.Uniforms, + ): void; + + /** + * Reset post-processing modes on all Visual Effects masking filters. + */ + resetPostProcessingFilters(): void; + + /** + * Activate light source animation for AmbientLight objects within this layer + */ + activateAnimation(): void; + + /** + * Deactivate light source animation for AmbientLight objects within this layer + */ + deactivateAnimation(): void; + + /** + * Animate a smooth transition of the darkness overlay to a target value. + * Only begin animating if another animation is not already in progress. + * @param target - The target darkness level between 0 and 1 + * @param duration - The desired animation time in milliseconds. Default is 10 seconds + * @returns A Promise which resolves once the animation is complete + */ + animateDarkness(target: number, duration: number): Promise; + } } diff --git a/src/foundry/client/pixi/groups/environment.d.ts b/src/foundry/client/pixi/groups/environment.d.ts new file mode 100644 index 000000000..c2c1405b0 --- /dev/null +++ b/src/foundry/client/pixi/groups/environment.d.ts @@ -0,0 +1,20 @@ +export {}; + +declare global { + /** + * A container group which contains the primary canvas group and the effects canvas group. + */ + class EnvironmentCanvasGroup extends BaseCanvasMixin(PIXI.Container) { + /** + * @defaultValue `"environment"` + */ + static override groupName: string; + + /** + * @defaultValue `false` + */ + static override tearDownChildren: boolean; + + override draw(): Promise; + } +} diff --git a/src/foundry/client/pixi/groups/hidden.d.ts b/src/foundry/client/pixi/groups/hidden.d.ts new file mode 100644 index 000000000..d438a5e52 --- /dev/null +++ b/src/foundry/client/pixi/groups/hidden.d.ts @@ -0,0 +1,37 @@ +import type { EventMode } from "pixi.js"; + +export {}; + +declare global { + /** + * A specialized canvas group for rendering hidden containers before all others (like masks). + */ + class HiddenCanvasGroup extends BaseCanvasMixin(PIXI.Container) { + /** + * @defaultValue `"none"` + */ + override eventMode: EventMode; + + /** + * The container which hold masks. + */ + masks: PIXI.Container; + + /** + * @defaultValue `"hidden"` + */ + static override groupName: string; + + /** + * Add a mask to this group. + * @param name - Name of the mask. + * @param displayObject - Display object to add. + * @param position - Position of the mask. + */ + addMask(name: string, displayObject: PIXI.DisplayObject, position?: number | undefined): void; + + override draw(): Promise; + + override tearDown(): Promise; + } +} diff --git a/src/foundry/client/pixi/groups/index.d.ts b/src/foundry/client/pixi/groups/index.d.ts index 7de78c175..8a308ac40 100644 --- a/src/foundry/client/pixi/groups/index.d.ts +++ b/src/foundry/client/pixi/groups/index.d.ts @@ -1,3 +1,7 @@ import "./effects"; +import "./environment"; +import "./hidden"; import "./interface"; +import "./overlay"; import "./primary"; +import "./rendered"; diff --git a/src/foundry/client/pixi/groups/interface.d.ts b/src/foundry/client/pixi/groups/interface.d.ts index ea3b5df90..d2cf08713 100644 --- a/src/foundry/client/pixi/groups/interface.d.ts +++ b/src/foundry/client/pixi/groups/interface.d.ts @@ -1,27 +1,72 @@ -/** - * A container group which displays interface elements rendered above other canvas groups. - */ -declare class InterfaceCanvasGroup extends PIXI.Container { - constructor(); +export {}; - sounds: SoundsLayer; +declare global { + /** + * A container group which displays interface elements rendered above other canvas groups. + */ + class InterfaceCanvasGroup extends BaseCanvasMixin(PIXI.Container) { + /** + * @defaultValue `"interface"` + */ + static override groupName: string; - notes: NotesLayer; + /** + * Draw the canvas group and all its component layers. + */ + override draw(): Promise; - controls: ControlsLayer; + /** + * Display scrolling status text originating from this ObjectHUD container. + * @param origin - An origin point where the text should first emerge + * @param content - The text content to display + * @param options - Options which customize the text animation + * @returns - The created PreciseText object which is scrolling + */ + createScrollingText( + origin: Point, + content: string, + options?: { + /** + * The duration of the scrolling effect in milliseconds + * @defaultValue `2000` + */ + duration?: number; - /** @defaultValue `true` */ - sortableChildren: boolean; + /** + * The distance in pixels that the scrolling text should travel + * @defaultValue (2 * text.width) + */ + distance?: number; - /** - * The name of this canvas group - * @defaultValue `"interface"` - */ - static groupName: string; + /** + * The original anchor point where the text appears + */ + anchor: foundry.CONST.TEXT_ANCHOR_POINTS; - /** - * Create the member layers of the scene container - * @internal - */ - protected _createLayers(): void; + /** + * The direction in which the text scrolls + */ + direction: foundry.CONST.TEXT_ANCHOR_POINTS; + + /** + * An amount of randomization between [0, 1] applied to the initial position + * @defaultValue `0` + */ + jitter: number; + + /** + * Additional parameters of PIXI.TextStyle which are applied to the text + */ + textStyle: InexactPartial; + }, + ): Promise; + + /** + * @deprecated since v11, will be removed in v13 + * @remarks "InterfaceCanvasGroup.reverseMaskfilter is deprecated. + * Please create your own ReverseMaskFilter, or instead of attaching the filter to each of your objects extend the + * already masked GridLayer with a container for these objects, which is much better for performance." + */ + get reverseMaskfilter(): ReverseMaskFilter; + } } diff --git a/src/foundry/client/pixi/groups/overlay.d.ts b/src/foundry/client/pixi/groups/overlay.d.ts new file mode 100644 index 000000000..48eec7cc4 --- /dev/null +++ b/src/foundry/client/pixi/groups/overlay.d.ts @@ -0,0 +1,18 @@ +export {}; + +declare global { + /** + * A container group which is not bound to the stage world transform. + */ + class OverlayCanvasGroup extends BaseCanvasMixin(UnboundContainer) { + /** + * @defaultValue `"overlay"` + */ + static override groupName: string; + + /** + * @defaultValue `false` + */ + static override tearDownChildren: boolean; + } +} diff --git a/src/foundry/client/pixi/groups/primary.d.ts b/src/foundry/client/pixi/groups/primary.d.ts index 59fe2d07d..9db7fddf6 100644 --- a/src/foundry/client/pixi/groups/primary.d.ts +++ b/src/foundry/client/pixi/groups/primary.d.ts @@ -1,40 +1,177 @@ -/** - * A cached container group which renders the primary visible contents of a Scene. - */ -declare class PrimaryCanvasGroup extends CachedContainer { - constructor(); +export {}; - background: BackgroundLayer; +type PrimaryDrawingContainer = unknown; +type TokenMesh = unknown; +type TileMesh = unknown; +type TileSprite = unknown; +type DrawingShape = unknown; +type PrimaryCanvasObject = unknown; - drawings: DrawingsLayer; +declare global { + /** + * The primary Canvas group which generally contains tangible physical objects which exist within the Scene. + * This group is a {@link CachedContainer} which is rendered to the Scene as a {@link SpriteMesh}. + * This allows the rendered result of the Primary Canvas Group to be affected by a {@link BaseSamplerShader}. + */ + class PrimaryCanvasGroup extends BaseCanvasMixin(CachedContainer) { + constructor(sprite: SpriteMesh); - grid: GridLayer; + /** + * @defaultValue `"primary"` + */ + static override groupName: string; - templates: TemplateLayer; + /** + * @defaultValue `"none"` + */ + override eventMode: PIXI.EventMode; - tokens: TokenLayer; + /** + * @defaultValue `[0, 0, 0, 0]` + */ + override clearColor: [r: number, g: number, b: number, a: number]; - foreground: ForegroundLayer; + /** + * Track the set of HTMLVideoElements which are currently playing as part of this group. + */ + videoMeshes: Set; - /** @defaultValue `true` */ - sortableChildren: boolean; + /** + * Allow API users to override the default elevation of the background layer. + * This is a temporary solution until more formal support for scene levels is added in a future release. + */ + static BACKGROUND_ELEVATION: number; - /** - * The name of this canvas group - * @defaultValue `"primary"` - */ - static groupName: string; + /** + * The primary background image configured for the Scene, rendered as a SpriteMesh. + */ + background: SpriteMesh; - /** - * @defaultValue `[0, 0, 0, 0]` - */ - override clearColor: [r: number, g: number, b: number, a: number]; + /** + * The primary foreground image configured for the Scene, rendered as a SpriteMesh. + */ + foreground: SpriteMesh; - /** - * Create the member layers of the scene container - * @internal - */ - protected _createLayers(): void; + /** + * A Quadtree which partitions and organizes primary canvas objects. + */ + quadtree: CanvasQuadtree; + + /** + * The collection of PrimaryDrawingContainer objects which are rendered in the Scene. + */ + drawings: Collection; + + /** + * The collection of SpriteMesh objects which are rendered in the Scene. + */ + tokens: Collection; + + /** + * The collection of SpriteMesh objects which are rendered in the Scene. + */ + tiles: Collection; + + /** + * Render all tokens in their own render texture. + * @param renderer - The renderer to use. + */ + _renderTokens(renderer: PIXI.Renderer): void; + + /** + * Return the base HTML image or video element which provides the background texture. + */ + get backgroundSource(): HTMLImageElement | HTMLVideoElement; + + /** + * Return the base HTML image or video element which provides the foreground texture. + */ + get foregroundSource(): HTMLImageElement | HTMLVideoElement; + + /** + * Refresh the primary mesh. + */ + refreshPrimarySpriteMesh(): void; + + /** + * Draw the canvas group and all its component layers. + */ + draw(): Promise; + + /** + * Remove and destroy all children from the group. + * Clear container references to rendered objects. + */ + tearDown(): Promise; + + /** + * Draw the SpriteMesh for a specific Token object. + * @param token - The Token being added + * @returns The added TokenMesh + */ + addToken(token: Token): TokenMesh; + + /** + * Remove a TokenMesh from the group. + * @param token - The Token being removed + */ + removeToken(token: Token): void; + + /** + * Draw the SpriteMesh for a specific Token object. + * @param tile - The Tile being added + * @returns The added TileMesh or TileSprite + */ + addTile(tile: Tile): TileMesh | TileSprite; + + /** + * Remove a TokenMesh from the group. + * @param tile - The Tile being removed + */ + removeTile(tile: Tile): void; + + /** + * Add a DrawingShape to the group. + * @param drawing - The Drawing being added + * @returns The created DrawingShape instance + */ + addDrawing(drawing: Drawing): DrawingShape; + + /** + * Remove a DrawingShape from the group. + * @param drawing - The Drawing being removed + */ + removeDrawing(drawing: Drawing): void; + + /** + * Map an elevation value to a depth value with the right precision. + * @param elevation - A current elevation (or zIndex) in distance units. + * @returns The depth value for this elevation on the range [1/255, 1] + */ + mapElevationToDepth(elevation: number): number; + + /** + * Override the default PIXI.Container behavior for how objects in this container are sorted. + * @override + */ + sortChildren(): void; + + /** + * The sorting function used to order objects inside the Primary Canvas Group. + * Overrides the default sorting function defined for the PIXI.Container. + * Sort TokenMesh above other objects except WeatherEffects, then DrawingShape, all else held equal. + * @param a - An object to display + * @param b - Some other object to display + */ + static _sortObjects( + a: PrimaryCanvasObject | PIXI.DisplayObject, + b: PrimaryCanvasObject | PIXI.DisplayObject, + ): number; - override render(renderer: Parameters[0]): void; + /** + * @deprecated since v11, will be removed in v13 + * @remarks "PrimaryCanvasGroup#mapElevationAlpha is deprecated in favor of PrimaryCanvasGroup#mapElevationToDepth" + */ + mapElevationAlpha(elevation: number): number; + } } diff --git a/src/foundry/client/pixi/groups/rendered.d.ts b/src/foundry/client/pixi/groups/rendered.d.ts new file mode 100644 index 000000000..49e54be7d --- /dev/null +++ b/src/foundry/client/pixi/groups/rendered.d.ts @@ -0,0 +1,18 @@ +export {}; + +declare global { + /** + * A container group which contains the environment canvas group and the interface canvas group. + */ + class RenderedCanvasGroup extends BaseCanvasMixin(PIXI.Container) { + /** + * @defaultValue `"rendered"` + */ + static override groupName: string; + + /** + * @defaultValue `false` + */ + static override tearDownChildren: boolean; + } +} diff --git a/src/types/utils.d.ts b/src/types/utils.d.ts index 2cf33396f..130872449 100644 --- a/src/types/utils.d.ts +++ b/src/types/utils.d.ts @@ -142,6 +142,9 @@ type PropertyTypeOrFallback = Key extends keyof */ type RequiredProps = Required> & Omit; +type AnyConstructor any> = Pick & + (new (...args: any) => InstanceType); + type Mixin< MixinClass extends new (...args: any[]) => any, BaseClass extends abstract new (...args: any[]) => any,