Add Deprecation: Advanced Bloom Filter

src/advanced-bloom/AdvancedBloomFilter.ts

@@ -1,10 +1,36 @@
-import { Filter, FilterSystem, GlProgram, GpuProgram, PointData, RenderSurface, Texture, TexturePool } from 'pixi.js';
+import {
+    deprecation,
+    Filter,
+    FilterSystem,
+    GlProgram,
+    GpuProgram,
+    PointData,
+    RenderSurface,
+    Texture,
+    TexturePool,
+    // eslint-disable-next-line camelcase
+    v8_0_0,
+} from 'pixi.js';
 import { vertex, wgslVertex } from '../defaults';
 import { KawaseBlurFilter } from '../kawase-blur/KawaseBlurFilter';
 import fragment from './advanced-bloom.frag';
 import source from './advanced-bloom.wgsl';
 import { ExtractBrightnessFilter } from './ExtractBrightnessFilter';
 
+type DeprecatedPixelSizeValue = PointData | number[] | number;
+
+interface DeprecatedAdvancedBloomFilterOptions
+{
+    threshold: number,
+    bloomScale: number,
+    brightness: number,
+    kernels: number[] | null,
+    blur: number,
+    quality: number,
+    pixelSize: DeprecatedPixelSizeValue,
+    resolution: number,
+}
+
 export interface AdvancedBloomFilterOptions
 {
     /**
@@ -22,7 +48,7 @@ export interface AdvancedBloomFilterOptions
      * @default 1
      */
     brightness?: number,
-    /** Sets the strength of the Blur properties simultaneously */
+    /** The strength of the Blur properties simultaneously */
     blur?: number,
     /**
      * The kernel size of the blur filter.
@@ -31,7 +57,7 @@ export interface AdvancedBloomFilterOptions
     /** The quality of the Blur filter. */
     quality?: number,
     /**
-     * Sets the pixel size of the blur filter. Large size is blurrier. For advanced usage.
+     * The pixel size of the blur filter. Large size is blurrier. For advanced usage.
      * @default {x:1,y:1}
      */
     pixelSize?: PointData,
@@ -73,11 +99,35 @@ export class AdvancedBloomFilter extends Filter
     private _extractFilter: ExtractBrightnessFilter;
     private _blurFilter: KawaseBlurFilter;
 
-    constructor(options?: AdvancedBloomFilterOptions)
+    constructor(options?: AdvancedBloomFilterOptions);
+    /**
+     * @deprecated since 8.0.0
+     *
+     * @param {object|number} [options] - The optional parameters of advanced bloom filter.
+     *                        When options is a number , it will be `options.threshold`.
+     * @param {number} [options.threshold=0.5] - Defines how bright a color needs to be to affect bloom.
+     * @param {number} [options.bloomScale=1.0] - To adjust the strength of the bloom. Higher values is
+     *        more intense brightness.
+     * @param {number} [options.brightness=1.0] - The brightness, lower value is more subtle brightness,
+     *        higher value is blown-out.
+     * @param {number} [options.blur=8] - Sets the strength of the Blur properties simultaneously
+     * @param {number} [options.quality=4] - The quality of the Blur filter.
+     * @param {number[]} [options.kernels=null] - The kernels of the Blur filter.
+     * @param {number|number[]|PIXI.PointData} [options.pixelSize=1] - the pixelSize of the Blur filter.
+     * @param {number} [options.resolution=PIXI.settings.FILTER_RESOLUTION] - The resolution of the Blur filter.
+     */
+    constructor(options?: Partial<DeprecatedAdvancedBloomFilterOptions>);
+    constructor(options?: AdvancedBloomFilterOptions | Partial<DeprecatedAdvancedBloomFilterOptions>)
     {
+        if (typeof options?.pixelSize === 'number' || Array.isArray(options?.pixelSize))
+        {
+            deprecation(v8_0_0, 'AdvancedBloomFilterOptions.pixelSize now only accepts {x, y} PointData type.');
+            options.pixelSize = convertDeprecatedPixelSize(options.pixelSize);
+        }
+
         options = { ...AdvancedBloomFilter.DEFAULT_OPTIONS, ...options };
 
-        const gpuProgram = new GpuProgram({
+        const gpuProgram = GpuProgram.from({
             vertex: {
                 source: wgslVertex,
                 entryPoint: 'mainVertex',
@@ -88,7 +138,7 @@ export class AdvancedBloomFilter extends Filter
             },
         });
 
-        const glProgram = new GlProgram({
+        const glProgram = GlProgram.from({
             vertex,
             fragment,
             name: 'advanced-bloom-filter',
@@ -158,42 +208,68 @@ export class AdvancedBloomFilter extends Filter
     get threshold(): number { return this._extractFilter.threshold; }
     set threshold(value: number) { this._extractFilter.threshold = value; }
 
-    /** Sets the kernels of the Blur Filter */
+    /** The kernels of the Blur Filter */
     get kernels(): number[] { return this._blurFilter.kernels; }
     set kernels(value: number[]) { this._blurFilter.kernels = value; }
 
     /**
-     * Sets the strength of the Blur properties simultaneously
+     * The strength of the Blur properties simultaneously
      * @default 2
      */
     get blur(): number { return this._blurFilter.strength; }
     set blur(value: number) { this._blurFilter.strength = value; }
 
     /**
-     * Sets the quality of the Blur Filter
+     * The quality of the Blur Filter
      * @default 4
      */
     get quality(): number { return this._blurFilter.quality; }
     set quality(value: number) { this._blurFilter.quality = value; }
 
     /**
-     * Sets the pixelSize of the Kawase Blur filter
+     * The pixel size of the Kawase Blur filter
      * @default {x:1,y:1}
      */
     get pixelSize(): PointData { return this._blurFilter.pixelSize; }
-    set pixelSize(value: PointData) { this._blurFilter.pixelSize = value; }
+    set pixelSize(value: PointData | DeprecatedPixelSizeValue)
+    {
+        if (typeof value === 'number' || Array.isArray(value))
+        {
+            deprecation(v8_0_0, 'AdvancedBloomFilter.pixelSize now only accepts {x, y} PointData type.');
+            this._blurFilter.pixelSize = convertDeprecatedPixelSize(value);
+
+            return;
+        }
+
+        this._blurFilter.pixelSize = value;
+    }
 
     /**
-     * Sets the pixelSize of the Kawase Blur filter on the `x` axis
+     * The horizontal pixelSize of the Kawase Blur filter
      * @default 1
      */
     get pixelSizeX(): number { return this._blurFilter.pixelSizeX; }
     set pixelSizeX(value: number) { this._blurFilter.pixelSizeX = value; }
 
     /**
-     * Sets the pixelSize of the Kawase Blur filter on the `y` axis
+     * The vertical pixel size of the Kawase Blur filter
      * @default 1
      */
     get pixelSizeY(): number { return this._blurFilter.pixelSizeY; }
     set pixelSizeY(value: number) { this._blurFilter.pixelSizeY = value; }
 }
+
+function convertDeprecatedPixelSize(value: DeprecatedPixelSizeValue): PointData
+{
+    if (typeof value === 'number')
+    {
+        return { x: value, y: value };
+    }
+
+    if (Array.isArray(value))
+    {
+        return { x: value[0], y: value[1] };
+    }
+
+    return value;
+}