Deprecate Callback for Spritesheet.parse (pixijs#8396)

michaeljherrmann · Jun 13, 2022 · 4e1ab76 · 4e1ab76
1 parent 9aeaeb7
commit 4e1ab76
Show file tree

Hide file tree

Showing 3 changed files with 68 additions and 43 deletions.
diff --git a/packages/spritesheet/src/Spritesheet.ts b/packages/spritesheet/src/Spritesheet.ts
@@ -1,6 +1,6 @@
 import { Rectangle } from '@pixi/math';
 import { Texture, BaseTexture } from '@pixi/core';
-import { getResolutionOfUrl } from '@pixi/utils';
+import { deprecation, getResolutionOfUrl } from '@pixi/utils';
 import type { Dict } from '@pixi/utils';
 import type { ImageResource } from '@pixi/core';
 import type { IPointData } from '@pixi/math';
@@ -55,7 +55,8 @@ export interface ISpritesheetData
  * Alternately, you may circumvent the loader by instantiating the Spritesheet directly:
  * ```js
  * const sheet = new PIXI.Spritesheet(texture, spritesheetData);
- * sheet.parse(() => console.log('Spritesheet ready to use!'));
+ * await sheet.parse();
+ * console.log('Spritesheet ready to use!');
  * ```
  *
  * With the `sheet.textures` you can create Sprite objects,`sheet.animations` can be used to create an AnimatedSprite.
@@ -182,24 +183,49 @@ export class Spritesheet
     /**
      * Parser spritesheet from loaded data. This is done asynchronously
      * to prevent creating too many Texture within a single process.
+     * @method PIXI.Spritesheet#parse
+     */
+    public parse(): Promise<Dict<Texture>>;
+
+    /**
+     * Please use the Promise-based version of this function.
+     * @method PIXI.Spritesheet#parse
+     * @deprecated since version 6.5.0
      * @param {Function} callback - Callback when complete returns
      *        a map of the Textures for this spritesheet.
      */
-    public parse(callback: (textures?: Dict<Texture>) => void): void
-    {
-        this._batchIndex = 0;
-        this._callback = callback;
+    public parse(callback?: (textures?: Dict<Texture>) => void): void;
 
-        if (this._frameKeys.length <= Spritesheet.BATCH_SIZE)
+    /** @ignore */
+    public parse(callback?: (textures?: Dict<Texture>) => void): Promise<Dict<Texture>>
+    {
+        // #if _DEBUG
+        if (callback)
         {
-            this._processFrames(0);
-            this._processAnimations();
-            this._parseComplete();
+            deprecation('6.5.0', 'Spritesheet.parse callback is deprecated, use the return Promise instead.');
         }
-        else
+        // #endif
+
+        return new Promise((resolve) =>
         {
-            this._nextBatch();
-        }
+            this._callback = (textures: Dict<Texture>) =>
+            {
+                callback?.(textures);
+                resolve(textures);
+            };
+            this._batchIndex = 0;
+
+            if (this._frameKeys.length <= Spritesheet.BATCH_SIZE)
+            {
+                this._processFrames(0);
+                this._processAnimations();
+                this._parseComplete();
+            }
+            else
+            {
+                this._nextBatch();
+            }
+        });
     }
 
     /**

diff --git a/packages/spritesheet/src/SpritesheetLoader.ts b/packages/spritesheet/src/SpritesheetLoader.ts
@@ -109,7 +109,7 @@ export class SpritesheetLoader
                 resource.url
             );
 
-            spritesheet.parse(() =>
+            spritesheet.parse().then(() =>
             {
                 resource.spritesheet = spritesheet;
                 resource.textures = spritesheet.textures;

diff --git a/packages/spritesheet/test/SpritesheetLoader.tests.ts b/packages/spritesheet/test/SpritesheetLoader.tests.ts
@@ -57,9 +57,8 @@ describe('SpritesheetLoader', () =>
         expect(res.textures).to.be.undefined;
     });
 
-    it('should load the image & create textures if json is properly formatted', () =>
+    it('should load the image & create textures if json is properly formatted', (next) =>
     {
-        const spy = sinon.spy();
         const res = createMockResource(LoaderResource.TYPE.JSON, getJsonSpritesheet());
         const loader = new Loader();
         const addStub = sinon.stub(loader, 'add');
@@ -69,33 +68,33 @@ describe('SpritesheetLoader', () =>
 
         addStub.yields(imgRes);
 
-        SpritesheetLoader.use.call(loader, res, spy);
-
-        addStub.restore();
-
-        expect(spy).to.have.been.calledOnce;
-        expect(addStub).to.have.been.calledWith(
-            `${res.name}_image`,
-            `${path.dirname(res.url)}/${res.data.meta.image}`
-        );
-        expect(res).to.have.property('textures')
-            .that.is.an('object')
-            .with.keys(Object.keys(getJsonSpritesheet().frames))
-            .and.has.property('0.png')
-            .that.is.an.instanceof(Texture);
-
-        expect(res.textures['0.png'].frame.x).to.equal(14);
-        expect(res.textures['0.png'].frame.y).to.equal(28);
-        expect(res.textures['0.png'].defaultAnchor.x).to.equal(0.3);
-        expect(res.textures['0.png'].defaultAnchor.y).to.equal(0.4);
-        expect(res.textures['1.png'].defaultAnchor.x).to.equal(0.0); // default of defaultAnchor is 0,0
-        expect(res.textures['1.png'].defaultAnchor.y).to.equal(0.0);
-
-        expect(res).to.have.property('spritesheet')
-            .to.have.property('animations')
-            .to.have.property('png123');
-        expect(res.spritesheet.animations.png123.length).to.equal(3);
-        expect(res.spritesheet.animations.png123[0]).to.equal(res.textures['1.png']);
+        SpritesheetLoader.use.call(loader, res, () =>
+        {
+            addStub.restore();
+            expect(addStub).to.have.been.calledWith(
+                `${res.name}_image`,
+                `${path.dirname(res.url)}/${res.data.meta.image}`
+            );
+            expect(res).to.have.property('textures')
+                .that.is.an('object')
+                .with.keys(Object.keys(getJsonSpritesheet().frames))
+                .and.has.property('0.png')
+                .that.is.an.instanceof(Texture);
+
+            expect(res.textures['0.png'].frame.x).to.equal(14);
+            expect(res.textures['0.png'].frame.y).to.equal(28);
+            expect(res.textures['0.png'].defaultAnchor.x).to.equal(0.3);
+            expect(res.textures['0.png'].defaultAnchor.y).to.equal(0.4);
+            expect(res.textures['1.png'].defaultAnchor.x).to.equal(0.0); // default of defaultAnchor is 0,0
+            expect(res.textures['1.png'].defaultAnchor.y).to.equal(0.0);
+
+            expect(res).to.have.property('spritesheet')
+                .to.have.property('animations')
+                .to.have.property('png123');
+            expect(res.spritesheet.animations.png123.length).to.equal(3);
+            expect(res.spritesheet.animations.png123[0]).to.equal(res.textures['1.png']);
+            next();
+        });
     });
 
     it('should not load binary images as an image loader type', (done) =>