@league-of-foundry-developers/foundry-vtt-types 9.280.1 → 12.331.2-beta

package/src/foundry/client/pixi/perception/vision-mode.d.mts

@@ -0,0 +1,202 @@
+import type { AnyObject, InexactPartial, SimpleMerge, ValueOf } from "../../../../types/utils.d.mts";
+import type { fields } from "../../../common/data/module.d.mts";
+
+declare global {
+  class ShaderField<
+    const Options extends ShaderField.Options = ShaderField.DefaultOptions,
+    const AssignmentType = ShaderField.AssignmentType<Options>,
+    const InitializedType = ShaderField.InitializedType<Options>,
+    const PersistedType extends typeof AbstractBaseShader | null | undefined = ShaderField.InitializedType<Options>,
+  > extends foundry.data.fields.DataField<Options, AssignmentType, InitializedType, PersistedType> {
+    /**
+     * @defaultValue
+     * ```typescript
+     * const defaults = super._defaults;
+     * defaults.nullable = true;
+     * defaults.initial = undefined;
+     * return defaults;
+     * ```
+     */
+    static override get _defaults(): ShaderField.DefaultOptions;
+
+    // TODO: _cast blatantly breaks inheritance so this is difficult to work with
+    /** @remarks The value provided to a ShaderField must be an AbstractBaseShader subclass. */
+    override _cast(value: any): Exclude<InitializedType, undefined | null>; // typeof AbstractBaseShader;
+  }
+
+  /**
+   * A Vision Mode which can be selected for use by a Token.
+   * The selected Vision Mode alters the appearance of various aspects of the canvas while that Token is the POV.
+   */
+  class VisionMode extends foundry.abstract.DataModel<VisionMode.Schema> {
+    /**
+     * Construct a Vision Mode using provided configuration parameters and callback functions.
+     * @param data    - Data which fulfills the model defined by the VisionMode schema.
+     * @param options - Additional options passed to the DataModel constructor.
+     */
+    constructor(data: InexactPartial<any>, options?: AnyObject);
+
+    static defineSchema(): VisionMode.Schema;
+
+    /** The lighting illumination levels which are supported. */
+    static LIGHTING_LEVELS: typeof CONST.LIGHTING_LEVELS;
+
+    /**
+     * Flags for how each lighting channel should be rendered for the currently active vision modes:
+     * - Disabled: this lighting layer is not rendered, the shaders does not decide.
+     * - Enabled: this lighting layer is rendered normally, and the shaders can choose if they should be rendered or not.
+     * - Required: the lighting layer is rendered, the shaders does not decide.
+     */
+    static LIGHTING_VISIBILITY: {
+      DISABLED: 0;
+      ENABLED: 1;
+      REQUIRED: 2;
+    };
+
+    /**
+     * A flag for whether this vision source is animated
+     * @defaultValue `false`
+     */
+    animated: boolean;
+
+    /**
+     * Does this vision mode enable light sources?
+     * True unless it disables lighting entirely.
+     */
+    get perceivesLight(): boolean;
+
+    /**
+     * Special activation handling that could be implemented by VisionMode subclasses
+     * @param source - Activate this VisionMode for a specific source
+     */
+    _activate(source: foundry.canvas.sources.PointVisionSource.Any): void;
+
+    /**
+     * Special deactivation handling that could be implemented by VisionMode subclasses
+     * @param source - Deactivate this VisionMode for a specific source
+     */
+    _deactivate(source: foundry.canvas.sources.PointVisionSource.Any): void;
+
+    /**
+     * Special handling which is needed when this Vision Mode is activated for a VisionSource.
+     * @param source - Activate this VisionMode for a specific source
+     */
+    activate(source: foundry.canvas.sources.PointVisionSource.Any): void;
+
+    /**
+     * Special handling which is needed when this Vision Mode is deactivated for a VisionSource.
+     * @param source - Deactivate this VisionMode for a specific source
+     */
+    deactivate(source: foundry.canvas.sources.PointVisionSource.Any): void;
+
+    /**
+     * An animation function which runs every frame while this Vision Mode is active.
+     * @param dt - The deltaTime passed by the PIXI Ticker
+     */
+    animate(dt: number): void;
+  }
+
+  namespace ShaderField {
+    type Options = DataFieldOptions<typeof AbstractBaseShader>;
+
+    type DefaultOptions = SimpleMerge<
+      foundry.data.fields.DataField.DefaultOptions,
+      {
+        nullable: true;
+        initial: undefined;
+      }
+    >;
+
+    /**
+     * A helper type for the given options type merged into the default options of the BooleanField class.
+     * @typeParam Opts - the options that override the default options
+     */
+    type MergedOptions<Opts extends Options> = SimpleMerge<DefaultOptions, Opts>;
+
+    /**
+     * A shorthand for the assignment type of a BooleanField class.
+     * @typeParam Opts - the options that override the default options
+     */
+    type AssignmentType<Opts extends Options> = foundry.data.fields.DataField.DerivedAssignmentType<
+      typeof AbstractBaseShader,
+      MergedOptions<Opts>
+    >;
+
+    /**
+     * A shorthand for the initialized type of a BooleanField class.
+     * @typeParam Opts - the options that override the default options
+     */
+    type InitializedType<Opts extends Options> = foundry.data.fields.DataField.DerivedInitializedType<
+      typeof AbstractBaseShader,
+      MergedOptions<Opts>
+    >;
+  }
+
+  namespace VisionMode {
+    type ShaderSchema = fields.SchemaField<{
+      shader: ShaderField;
+      uniforms: fields.ObjectField;
+    }>;
+
+    type LightingSchema = fields.SchemaField<{
+      visibility: fields.NumberField;
+      postProcessingModes: fields.ArrayField<fields.StringField>;
+      uniforms: fields.ObjectField;
+    }>;
+
+    type LightingLevels = Record<
+      ValueOf<typeof CONST.LIGHTING_LEVELS>,
+      ValueOf<typeof CONST.LIGHTING_LEVELS>
+    >;
+    type LightingMultipliers = Record<ValueOf<typeof VisionMode.LIGHTING_LEVELS>, number>;
+
+    interface Schema extends DataSchema {
+      id: fields.StringField<{ blank: false }>;
+      label: fields.StringField<{ blank: false }>;
+      tokenConfig: fields.BooleanField<{ initial: true }>;
+      canvas: fields.SchemaField<{
+        shader: ShaderField;
+        uniforms: fields.ObjectField;
+      }>;
+      lighting: fields.SchemaField<{
+        background: LightingSchema;
+        coloration: LightingSchema;
+        illumination: LightingSchema;
+        levels: fields.ObjectField<
+          {
+            validate: (o: unknown) => boolean;
+            validationError: "may only contain a mapping of keys from VisionMode.LIGHTING_LEVELS";
+          },
+          LightingLevels,
+          LightingLevels,
+          LightingLevels
+        >;
+        multipliers: fields.ObjectField<
+          {
+            validate: (o: unknown) => boolean;
+            validationError: "must provide a mapping of keys from VisionMode.LIGHTING_LEVELS to numeric multiplier values";
+          },
+          LightingMultipliers,
+          LightingMultipliers,
+          LightingMultipliers
+        >;
+      }>;
+      vision: fields.SchemaField<{
+        background: ShaderSchema;
+        coloration: ShaderSchema;
+        illumination: ShaderSchema;
+        darkness: fields.SchemaField<{
+          adaptive: fields.BooleanField<{ initial: true }>;
+        }>;
+        defaults: fields.SchemaField<{
+          color: fields.ColorField<{required: false, initial: undefined}>;
+          attenuation: fields.AlphaField<{required: false, initial: undefined}>;
+          brightness: fields.NumberField<{required: false, initial: undefined, nullable: false, min: number, max: number}>;
+          saturation: fields.NumberField<{required: false, initial: undefined, nullable: false, min: number, max: number}>;
+          contrast: fields.NumberField<{required: false, initial: undefined, nullable: false, min: number, max: number}>;
+        }>;
+        preferred: fields.BooleanField<{ initial: false }>;
+      }>;
+    }
+  }
+}

package/src/foundry/client/pixi/perception/weiler-atherton-clipping.d.mts

@@ -0,0 +1,152 @@
+import type { InexactPartial, ValueOf } from "../../../../types/utils.d.mts";
+
+declare global {
+  /**
+   * An implementation of the Weiler Atherton algorithm for clipping polygons.
+   * This currently only handles combinations that will not result in any holes.
+   * Support may be added for holes in the future.
+   *
+   * This algorithm is faster than the Clipper library for this task because it relies on the unique properties of the
+   * circle, ellipse, or convex simple clip object.
+   * It is also more precise in that it uses the actual intersection points between the circle/ellipse and polygon,
+   * instead of relying on the polygon approximation of the circle/ellipse to find the intersection points.
+   *
+   * For more explanation of the underlying algorithm, see:
+   * https://en.wikipedia.org/wiki/Weiler%E2%80%93Atherton_clipping_algorithm
+   * https://www.geeksforgeeks.org/weiler-atherton-polygon-clipping-algorithm
+   * https://h-educate.in/weiler-atherton-polygon-clipping-algorithm/
+   */
+  class WeilerAthertonClipper {
+    /**
+     * Construct a WeilerAthertonClipper instance used to perform the calculation.
+     * @param polygon       - Polygon to clip
+     * @param clipObject    - Object used to clip the polygon
+     * @param clipType      - Type of clip to use
+     *                        (default: `0`)
+     * @param clipOpts      - Object passed to the clippingObject methods toPolygon and pointsBetween
+     *                        (default: `{}`)
+     */
+    constructor(
+      polygon: PIXI.Polygon,
+      clipObject: PIXI.Rectangle | PIXI.Circle,
+      clipType?: ValueOf<(typeof WeilerAthertonClipper)["CLIP_TYPES"]>,
+      clipOpts?: WeilerAthertonClipper.ClipOpts,
+    );
+
+    /**
+     * The supported clip types.
+     * Values are equivalent to those in ClipperLib.ClipType.
+     */
+    static readonly CLIP_TYPES: Readonly<{
+      INTERSECT: 0;
+      UNION: 1;
+    }>;
+
+    /**
+     * The supported intersection types.
+     */
+    static readonly INTERSECTION_TYPES: Readonly<{
+      OUT_IN: -1;
+      IN_OUT: 1;
+      TANGENT: 0;
+    }>;
+
+    polygon: PIXI.Polygon;
+
+    clipObject: PIXI.Rectangle | PIXI.Circle;
+
+    /**
+     * Configuration settings
+     * @param clipType  - One of CLIP_TYPES
+     * @param clipOpts  - Object passed to the clippingObject methods
+     *                    toPolygon and pointsBetween
+     * @defaultValue `{}`
+     */
+    config: {
+      clipType?: typeof WeilerAthertonClipper.CLIP_TYPES;
+      clipOpts?: WeilerAthertonClipper.ClipOpts;
+    };
+
+    /**
+     * Union a polygon and clipObject using the Weiler Atherton algorithm.
+     * @param polygon       - Polygon to clip
+     * @param clipObject    - Object to clip against the polygon
+     * @param clipOpts      - Options passed to the clipping object
+     *                        methods toPolygon and pointsBetween
+     */
+    static union(
+      polygon: PIXI.Polygon,
+      clipObject: PIXI.Rectangle | PIXI.Circle,
+      clipOpts: WeilerAthertonClipper.ClipOpts,
+    ): PIXI.Polygon[];
+
+    /**
+     * Intersect a polygon and clipObject using the Weiler Atherton algorithm.
+     * @param polygon       - Polygon to clip
+     * @param clipObject    - Object to clip against the polygon
+     * @param clipOpts      - Options passed to the clipping object
+     *                        methods toPolygon and pointsBetween
+     */
+    static intersect(
+      polygon: PIXI.Polygon,
+      clipObject: PIXI.Rectangle | PIXI.Circle,
+      clipOpts: WeilerAthertonClipper.ClipOpts,
+    ): PIXI.Polygon[];
+
+    /**
+     * Clip a given clipObject using the Weiler-Atherton algorithm.
+     *
+     * At the moment, this will return a single PIXI.Polygon in the array unless clipType is a union and the polygon
+     * and clipObject do not overlap, in which case the [polygon, clipObject.toPolygon()] array will be returned.
+     * If this algorithm is expanded in the future to handle holes, an array of polygons may be returned.
+     *
+     * @param polygon    - Polygon to clip
+     * @param clipObject - Object to clip against the polygon
+     * @param options    - Options which configure how the union or intersection is computed
+     * @returns Array of polygons and clipObjects
+     */
+    static combine(
+      polygon: PIXI.Polygon,
+      clipObject: PIXI.Rectangle | PIXI.Circle,
+      options?: InexactPartial<{
+        /**
+         * One of CLIP_TYPES
+         * @defaultValue `0`
+         */
+        clipType: ValueOf<typeof WeilerAthertonClipper.CLIP_TYPES>;
+
+        /**
+         * If the WeilerAtherton constructor could mutate or not the subject polygon points
+         */
+        canMutate: boolean;
+
+        /**
+         * Options passed to the WeilerAthertonClipper constructor
+         */
+        clipOpts: WeilerAthertonClipper.ClipOpts;
+      }>,
+    ): PIXI.Polygon[];
+
+    /**
+     * Test if one shape envelops the other. Assumes the shapes do not intersect.
+     *  1. Polygon is contained within the clip object. Union: clip object; Intersect: polygon
+     *  2. Clip object is contained with polygon. Union: polygon; Intersect: clip object
+     *  3. Polygon and clip object are outside one another. Union: both; Intersect: null
+     * @param polygon       - Polygon to clip
+     * @param clipObject    - Object to clip against the polygon
+     * @param clipType      - One of CLIP_TYPES
+     * @param clipOpts      - Clip options which are forwarded to toPolygon methods
+     * @returns Returns the polygon, the clipObject.toPolygon(), both, or neither.
+     */
+    static testForEnvelopment(
+      polygon: PIXI.Polygon,
+      clipObject: PIXI.Rectangle | PIXI.Circle,
+      clipType: typeof WeilerAthertonClipper.CLIP_TYPES,
+      clipOpts: WeilerAthertonClipper.ClipOpts,
+    ): PIXI.Polygon[];
+  }
+
+  namespace WeilerAthertonClipper {
+    type ClipOpts = PIXI.Circle.PointsForArcOptions;
+  }
+}