@league-of-foundry-developers/foundry-vtt-types 13.340.0 → 13.345.1-beta.20250704.94554

package/src/foundry/client/canvas/containers/elements/sprite-mesh.d.mts

@@ -0,0 +1,370 @@
+import type { Identity } from "#utils";
+import type { BaseSamplerShader } from "#client/canvas/rendering/shaders/_module.d.mts";
+
+/**
+ * An extension of PIXI.Mesh which emulate a PIXI.Sprite with a specific shader.
+ */
+declare class SpriteMesh extends PIXI.Container {
+  /**
+   * @param texture   - Texture bound to this sprite mesh.
+   *                    (default: `PIXI.Texture.EMPTY`)
+   * @param shaderCls - Shader class used by this sprite mesh.
+   *                    (default: `BaseSamplerShader`)
+   */
+  constructor(texture?: PIXI.Texture | null, shaderClass?: BaseSamplerShader.AnyConstructor);
+
+  /** @defaultValue `true` */
+  override isSprite: boolean;
+
+  /**
+   * Snapshot of some parameters of this display object to render in batched mode.
+   */
+  protected _batchData: SpriteMesh.BatchData;
+
+  /**
+   * The indices of the geometry.
+   */
+  indices: Uint16Array;
+
+  /**
+   * The width of the sprite (this is initially set by the texture).
+   * @defaultValue `0`
+   */
+  protected _width: number;
+
+  /**
+   * The height of the sprite (this is initially set by the texture).
+   * @defaultValue `0`
+   */
+  protected _height: number;
+
+  /**
+   * The texture that the sprite is using.
+   */
+  protected _texture: PIXI.Texture | null;
+
+  /**
+   * The texture ID
+   * @defaultValue `-1`
+   */
+  protected _textureID: number;
+
+  /**
+   * Cached tint value so we can tell when the tint is changed.
+   * @defaultValue `[1, 1, 1, 1]`
+   */
+  protected _cachedTint: Color.RGBAColorVector;
+
+  /**
+   * The texture trimmed ID.
+   * @defaultValue `-1`
+   */
+  protected _textureTrimmedID: number;
+
+  /**
+   * This is used to store the uvs data of the sprite, assigned at the same time
+   * as the vertexData in calculateVertices().
+   */
+  protected uvs: Float32Array;
+
+  /**
+   * The anchor point defines the normalized coordinates
+   * in the texture that map to the position of this
+   * sprite.
+   *
+   * By default, this is `(0,0)` (or `texture.defaultAnchor`
+   * if you have modified that), which means the position
+   * `(x,y)` of this `Sprite` will be the top-left corner.
+   *
+   * Note: Updating `texture.defaultAnchor` after
+   * constructing a `Sprite` does _not_ update its anchor.
+   *
+   * {@link https://docs.cocos2d-x.org/cocos2d-x/en/sprites/manipulation.html}
+   */
+  protected _anchor: PIXI.ObservablePoint;
+
+  /**
+   * This is used to store the vertex data of the sprite (basically a quad).
+   */
+  protected vertexData: Float32Array;
+
+  /**
+   * This is used to calculate the bounds of the object IF it is a trimmed sprite.
+   * @defaultValue `null`
+   */
+  protected vertexTrimmedData: Float32Array | null;
+
+  /**
+   * The transform ID.
+   * @defaultValue `-1`
+   */
+  private _transformID: number;
+
+  /**
+   * The transform ID.
+   * @defaultValue `-1`
+   */
+  private _transformTrimmedID: number;
+
+  /**
+   * The tint applied to the sprite. This is a hex value. A value of 0xFFFFFF will remove any tint effect.
+   * @defaultValue `new PIXI.Color(0xFFFFFF)`
+   */
+  protected _tintColor: PIXI.Color;
+
+  /**
+   * The tint applied to the sprite. This is a RGB value. A value of 0xFFFFFF will remove any tint effect.
+   * @defaultValue `0xFFFFFF`
+   */
+  protected _tintRGB: number;
+
+  /**
+   * An instance of a texture uvs used for padded SpriteMesh.
+   * Instanced only when padding becomes non-zero.
+   * @defaultValue `null`
+   */
+  protected _textureUvs: PIXI.TextureUvs | null;
+
+  /**
+   * Used to track a tint or alpha change to execute a recomputation of _cachedTint.
+   * @defaultValue `true`
+   */
+  protected _tintAlphaDirty: boolean;
+
+  /**
+   * The shader bound to this mesh.
+   */
+  get shader(): BaseSamplerShader;
+
+  /**
+   * The shader bound to this mesh.
+   */
+  protected _shader: BaseSamplerShader;
+
+  /**
+   * The x padding in pixels (must be a non-negative value.)
+   */
+  get paddingX(): number;
+
+  set paddingX(value);
+
+  /**
+   * They y padding in pixels (must be a non-negative value.)
+   */
+  get paddingY(): number;
+
+  set paddingY(value);
+
+  /**
+   * The maximum x/y padding in pixels (must be a non-negative value.)
+   */
+  get padding(): number;
+
+  /** @throws If `value < 0` */
+  set padding(value);
+
+  /**
+   * @defaultValue `0`
+   */
+  protected _paddingX: number;
+
+  /**
+   * @defaultValue `0`
+   */
+  protected _paddingY: number;
+
+  /**
+   * The blend mode applied to the SpriteMesh.
+   * @defaultValue `PIXI.BLEND_MODES.NORMAL`
+   */
+  set blendMode(value: PIXI.BLEND_MODES);
+
+  get blendMode();
+
+  /**
+   * If true PixiJS will Math.round() x/y values when rendering, stopping pixel interpolation.
+   * Advantages can include sharper image quality (like text) and faster rendering on canvas.
+   * The main disadvantage is movement of objects may appear less smooth.
+   * To set the global default, change PIXI.settings.ROUND_PIXELS
+   * @defaultValue `PIXI.settings.ROUND_PIXELS`
+   */
+  set roundPixels(value: boolean);
+
+  get roundPixels();
+
+  /**
+   * Used to force an alpha mode on this sprite mesh.
+   * If this property is non null, this value will replace the texture alphaMode when computing color channels.
+   * Affects how tint, worldAlpha and alpha are computed each others.
+   */
+  get alphaMode(): PIXI.ALPHA_MODES;
+
+  set alphaMode(mode);
+
+  /**
+   * Returns the SpriteMesh associated batch plugin. By default the returned plugin is that of the associated shader.
+   * If a plugin is forced, it will returns the forced plugin.
+   * @defaultValue `this._shader.pluginName`
+   */
+  get pluginName(): string;
+
+  set pluginName(name);
+
+  override get width(): number;
+
+  override set width(width);
+
+  /**
+   * The texture that the sprite is using
+   */
+  get texture(): PIXI.Texture | null;
+
+  set texture(texture);
+
+  /**
+   * The anchor sets the origin point of the sprite. The default value is taken from the {@linkcode PIXI.Texture}
+   * and passed to the constructor.
+   *
+   * The default is `(0,0)`, this means the sprite's origin is the top left.
+   *
+   * Setting the anchor to `(0.5,0.5)` means the sprite's origin is centered.
+   *
+   * Setting the anchor to `(1,1)` would mean the sprite's origin point will be the bottom right corner.
+   *
+   * If you pass only single parameter, it will set both x and y to the same value as shown in the example below.
+   * @privateRemarks Technically should be `ObservablePoint<this>` but this breaks `PrimarySpriteMesh`
+   */
+  get anchor(): PIXI.ObservablePoint<SpriteMesh.Any>;
+
+  set anchor(anchor);
+
+  /**
+   * The tint applied to the sprite. This is a hex value.
+   *
+   * A value of 0xFFFFFF will remove any tint effect.
+   * @defaultValue `0xFFFFFF`
+   */
+  get tint(): number;
+
+  set tint(tint);
+
+  /**
+   * The HTML source element for this SpriteMesh texture.
+   * @privateRemarks This could possibly be `PIXI.ImageSource | null`, but the below is Foundry's typing, which I think is accurate in practice
+   */
+  get sourceElement(): HTMLImageElement | HTMLVideoElement | null;
+
+  /**
+   * Is this SpriteMesh rendering a video texture?
+   */
+  get isVideo(): boolean;
+
+  /**
+   * When the texture is updated, this event will fire to update the scale and frame.
+   */
+  protected _onTextureUpdate(): void;
+
+  /**
+   * Called when the anchor position updates.
+   */
+  protected _onAnchorUpdate(): void;
+
+  /**
+   * Update uvs and push vertices and uv buffers on GPU if necessary.
+   */
+  updateUvs(): void;
+
+  /**
+   * Initialize shader based on the shader class type.
+   * @param shaderClass - The shader class
+   */
+  setShaderClass(shaderClass: BaseSamplerShader.AnyConstructor): void;
+
+  override updateTransform(): void;
+
+  /**
+   * Calculates the worldTransform * vertices, store it in vertexData
+   */
+  calculateVertices(): void;
+
+  /**
+   * Calculates worldTransform * vertices for a non texture with a trim. store it in vertexTrimmedData.
+   *
+   * This is used to ensure that the true width and height of a trimmed texture is respected.
+   */
+  calculateTrimmedVertices(): void;
+
+  override _render(renderer: PIXI.Renderer): void;
+
+  /**
+   * Update the batch data object.
+   */
+  protected _updateBatchData(): void;
+
+  override _calculateBounds(): void;
+
+  override getLocalBounds(rect: PIXI.Rectangle): PIXI.Rectangle;
+
+  /** @privateRemarks Foundry still marks this `@override` from when this class used to extend `PIXI.Mesh` */
+  containsPoint(point: PIXI.IPointData): boolean;
+
+  override destroy(options?: PIXI.IDestroyOptions | boolean): void;
+
+  /**
+   * Create a SpriteMesh from another source.
+   * You can specify texture options and a specific shader class derived from BaseSamplerShader.
+   * @param source         - Source to create texture from.
+   * @param textureOptions - See {@linkcode PIXI.BaseTexture}'s constructor for options.
+   * @param shaderClass    - The shader class to use. BaseSamplerShader by default.
+   */
+  static from(
+    source: PIXI.Texture | HTMLImageElement | HTMLVideoElement | string,
+    textureOptions?: PIXI.IBaseTextureOptions,
+    shaderClass?: BaseSamplerShader.AnyConstructor,
+  ): SpriteMesh;
+}
+
+declare namespace SpriteMesh {
+  interface Any extends AnySpriteMesh {}
+  interface AnyConstructor extends Identity<typeof AnySpriteMesh> {}
+
+  /** Snapshot of some parameters of this display object to render in batched mode. */
+  interface BatchData {
+    _tintRGB: number | undefined;
+    _texture: PIXI.Texture | undefined | null;
+
+    /**
+     * @defaultValue `this.#geometry.indexBuffer.data`
+     * @remarks Set during construction
+     */
+    indices: number[];
+
+    /**
+     * @defaultValue `this.#geometry.buffers[1].data`
+     * @remarks Set during construction
+     */
+    uvs: number[];
+
+    blendMode: PIXI.BLEND_MODES | undefined;
+
+    /**
+     * @defaultValue `this.#geometry.buffers[0].data`
+     * @remarks Set during construction
+     */
+    vertexData: number[];
+
+    worldAlpha: number | undefined;
+
+    /**
+     * @defaultValue `this`
+     * @remarks Set during construction
+     */
+    object: SpriteMesh;
+  }
+}
+
+export default SpriteMesh;
+
+declare abstract class AnySpriteMesh extends SpriteMesh {
+  constructor(...args: never);
+}

package/src/foundry/client/canvas/extensions/_module.d.mts

@@ -0,0 +1,9 @@
+// In Foundry itself this file contains re-exports of these other modules.
+// Therefore it has a runtime effect and uses `.mjs` instead of `.d.mts`.
+// While `.mts` could work, to avoid `import-x/no-unresolved` from erroring `.mjs` is used.
+/* eslint-disable import-x/extensions */
+
+export { default as extendPIXICircle } from "./circle-extension.mjs";
+export { default as extendPIXIPolygon } from "./polygon-extension.mjs";
+export { default as extendPIXIRectangle } from "./rectangle-extension.mjs";
+export { default as extendPIXIGraphics } from "./graphics-extension.mjs";

package/src/foundry/client/canvas/extensions/circle-extension.d.mts

@@ -0,0 +1,150 @@
+import type { InexactPartial } from "#utils";
+import type { LineCircleIntersection } from "#common/utils/geometry.d.mts";
+import type { Canvas } from "#client/canvas/_module.d.mts";
+import * as _PIXI from "pixi.js";
+
+export default function extendPIXICircle(): void;
+
+declare global {
+  namespace PIXI {
+    interface Circle {
+      /**
+       * Determine the center of the circle.
+       * Trivial, but used to match center method for other shapes.
+       * @remarks `defineProperty`'d with no explicit options
+       */
+      get center(): PIXI.Point;
+
+      /**
+       * Determine if a point is on or nearly on this circle.
+       * @param point   - Point to test
+       * @param epsilon - Tolerated margin of error (default: `1e-08`)
+       * @returns Is the point on the circle within the allowed tolerance?
+       */
+      pointIsOn(point: Canvas.Point, epsilon?: number): boolean;
+
+      /**
+       * Get all intersection points on this circle for a segment A|B
+       * Intersections are sorted from A to B.
+       * @param a - The first endpoint on segment A|B
+       * @param b - The second endpoint on segment A|B
+       * @returns Points where the segment A|B intersects the circle
+       */
+      segmentIntersections(a: Canvas.Point, b: Canvas.Point): LineCircleIntersection["intersections"];
+
+      /**
+       * Calculate an x,y point on this circle's circumference given an angle
+       * - `0`: due east
+       * - `π/2`: due south
+       * - `π` or `-π`: due west
+       * - `-π/2`: due north
+       * @param angle - Angle of the point, in radians
+       * @returns The point on the circle at the given angle
+       */
+      pointAtAngle(angle: number): Canvas.Point;
+
+      /**
+       * Get all the points for a polygon approximation of this circle between two points.
+       * The two points can be anywhere in 2d space. The intersection of this circle with the line from this circle center
+       * to the point will be used as the start or end point, respectively.
+       * This is used to draw the portion of the circle (the arc) between two intersection points on this circle.
+       * @param a       - Point in 2d space representing the start point
+       * @param b       - Point in 2d space representing the end point
+       * @param options - Options passed on to the {@linkcode pointsForArc} method
+       * @returns An array of points arranged clockwise from start to end
+       */
+      pointsBetween(a: Canvas.Point, b: Canvas.Point, options?: Circle.PointsForArcOptions): Canvas.Point[];
+
+      /**
+       * Get the points that would approximate a circular arc along this circle, given a starting and ending angle.
+       * Points returned are clockwise. If from and to are the same, a full circle will be returned.
+       * @param fromAngle - Starting angle, in radians. `π` is due north, `π/2` is due east
+       * @param toAngle   - Ending angle, in radians
+       * @param options   - Options which affect how the circle is converted
+       * @returns An array of points along the requested arc
+       */
+      pointsForArc(fromAngle: number, toAngle: number, options?: Circle.PointsForArcOptions): Canvas.Point[];
+
+      /**
+       * Approximate this {@linkcode _PIXI.Circle | PIXI.Circle} as a {@linkcode _PIXI.Polygon | PIXI.Polygon}
+       * @param options - Options forwarded on to the pointsForArc method
+       * @returns The `Circle` expressed as a `PIXI.Polygon`
+       */
+      toPolygon(options?: Circle.PointsForArcOptions): PIXI.Polygon;
+
+      /**
+       * Intersect this {@linkcode _PIXI.Circle | PIXI.Circle} with a {@linkcode _PIXI.Polygon | PIXI.Polygon}.
+       * @param polygon - A `PIXI.Polygon`
+       * @param options - Options which configure how the intersection is computed
+       * @returns The intersected polygon
+       */
+      intersectPolygon(polygon: PIXI.Polygon, options?: PIXI.Circle.WACIntersectPolygonOptions): PIXI.Polygon;
+      intersectPolygon(polygon: PIXI.Polygon, options?: PIXI.Circle.ClipperLibIntersectPolygonOptions): PIXI.Polygon;
+
+      /**
+       * Intersect this {@linkcode _PIXI.Circle | PIXI.Circle} with an array of {@linkcode PIXI.Polygon.ClipperPoint | ClipperPoint}s.
+       * Convert the circle to a {@linkcode _PIXI.Polygon | Polygon} approximation and use {@linkcode PIXI.Polygon.intersectPolygon | intersectPolygon}.
+       * In the future we may replace this with more specialized logic which uses the line-circle intersection formula.
+       * @param clipperPoints - Array of `ClipperPoint`s generated by {@linkcode PIXI.Polygon.toClipperPoints | PIXI.Polygon#toClipperPoints()}
+       * @param options       - Options which configure how the intersection is computed
+       * @returns The intersected polygon
+       */
+      intersectClipper(
+        clipperPoints: PIXI.Polygon.ClipperPoint[],
+        options?: PIXI.Circle.IntersectClipperOptions,
+      ): PIXI.Polygon;
+    }
+
+    namespace Circle {
+      /**
+       * @remarks The options for `intersectPolygon` when `weilerAtherton` is true (or not provided)
+       * @privateRemarks Does not include `density` as {@linkcode WeilerAthertonClipper.combine} does not take that prop in its options
+       */
+      interface WACIntersectPolygonOptions extends PIXI.Rectangle.WACIntersectPolygonOptions {}
+
+      /**
+       * @remarks The options for {@linkcode PIXI.Circle.intersectPolygon | PIXI.Circle#intersectPolygon}when `weilerAtherton` is false.
+       * @privateRemarks Includes `density` as it is used in `PIXI.Circle#intersectPolygon` before the rest of the options are passed on
+       * to {@linkcode PIXI.Polygon.intersectPolygon | PIXI.Polygon#intersectPolygon}
+       */
+      interface ClipperLibIntersectPolygonOptions
+        extends PIXI.Rectangle.ClipperLibIntersectPolygonOptions,
+          Pick<PIXI.Circle.PointsForArcOptions, "density"> {}
+
+      /** @internal */
+      type _PointsForArcOptions = InexactPartial<{
+        /**
+         * The number of points which defines the density of approximation
+         * @defaultValue {@linkcode PIXI.Circle.approximateVertexDensity | PIXI.Circle.approximateVertexDensity(this.radius)}
+         */
+        density: number;
+
+        /**
+         * Whether to include points at the circle where the arc starts and ends
+         * @defaultValue `true`
+         */
+        includeEndpoints: boolean;
+      }>;
+
+      interface PointsForArcOptions extends _PointsForArcOptions {}
+
+      interface IntersectClipperOptions
+        extends PIXI.Polygon.IntersectClipperOptions,
+          Pick<PIXI.Circle.PointsForArcOptions, "density"> {}
+    }
+
+    class Circle extends _PIXI.Circle {
+      /**
+       * The recommended vertex density for the regular polygon approximation of a circle of a given radius.
+       * Small radius circles have fewer vertices. The returned value will be rounded up to the nearest integer.
+       * See the formula described at:
+       * {@link https://math.stackexchange.com/questions/4132060/compute-number-of-regular-polgy-sides-to-approximate-circle-to-defined-precision}
+       * @param radius  - `Circle` radius
+       * @param epsilon - The maximum tolerable distance between an approximated line segment and the true radius.
+       *  A larger epsilon results in fewer points for a given radius. (default: `1`)
+       * @returns The number of points for the approximated polygon
+       */
+      static approximateVertexDensity(radius: number, epsilon?: number): number;
+    }
+  }
+}

package/src/foundry/client/canvas/extensions/graphics-extension.d.mts

@@ -0,0 +1,45 @@
+export default function extendPIXIGraphics(): void;
+
+declare global {
+  namespace PIXI {
+    namespace Graphics {
+      type PointsAndSmoothingTuple = [points: PIXI.Polygon | PIXI.Polygon.Points, smoothingFactor?: number];
+
+      type Path = PointsAndSmoothingTuple | PIXI.Polygon.Points;
+    }
+  }
+}
+
+/**
+ * @remarks Internal helper to accommodate for the reuse of functions across the various Graphics classes
+ */
+interface GraphicsHelper {
+  /**
+   * Draws a path.
+   * @param path - The polygon or points.
+   * @returns This Graphics instance.
+   */
+  drawPath(...path: PIXI.Graphics.Path): this;
+
+  /**
+   * Draws a smoothed polygon.
+   * @param path - The polygon or points.
+   * @returns This Graphics instance.
+   */
+  drawSmoothedPolygon(...path: PIXI.Graphics.Path): this;
+
+  /**
+   * Draws a smoothed path.
+   * @param path - The polygon or points.
+   * @returns This Graphics instance.
+   */
+  drawSmoothedPath(...path: PIXI.Graphics.Path): this;
+}
+
+declare module "pixi.js" {
+  interface Graphics extends GraphicsHelper {}
+}
+
+declare module "@pixi/graphics-smooth" {
+  interface SmoothGraphics extends GraphicsHelper {}
+}