feat: Add methods to retrieve parsed sprite and image (#3614)

Introduce two new methods for obtaining parsed sprites and images from the sprite sheet, enhancing the functionality for rendering and image manipulation.

Author: jyoung4242

site/docs/04-graphics/04.1-spritesheets.mdx

@@ -57,3 +57,22 @@ const ss = ex.SpriteSheet.fromImageSourceWithSourceViews({
   ],
 })
 ```
+
+## Parsing Out Discrete Images
+
+If you pass a large sheet image into a SpriteSheet then use a Sprite via `getSprite()`, Excalibur draws a window into that larger sheet.
+But what if you want a completely isolated Sprite parsed out of the host image?
+What if you wanted to use that Sprite in an HTML image for UI? 
+We got convenience methods to help with that.  They work exactly like `getSprite()` but they return NEW and unique Sprites and ImageElements.
+
+```ts
+const myNewSprite = ss.getSpriteAsStandalone(x,y); // new Sprite
+```
+
+or
+
+```ts
+const myNewImage = getSpriteAsImage(x,y); // new HTMLImageElement
+```
+
+

src/engine/Graphics/SpriteSheet.ts

@@ -1,4 +1,4 @@
-import type { ImageSource } from './ImageSource';
+import { ImageSource } from './ImageSource';
 import type { SourceView } from './Sprite';
 import { Sprite } from './Sprite';
 import type { GraphicOptions } from './Graphic';
@@ -178,6 +178,114 @@ export class SpriteSheet {
     throw Error(`Invalid sprite coordinates (${x}, ${y})`);
   }
 
+  /**
+   * Returns a sprite that has a new backing image the exact size of the sprite that tha is a copy of the original sprite slice.
+   *
+   * Useful if you need to apply effects, manipulate, or mutate the image and you don't want to disturb the original sprite sheet.
+   *
+   */
+  public async getSpriteAsStandalone(x: number, y: number): Promise<Sprite> {
+    if (x >= this.columns || x < 0) {
+      throw Error(`No sprite exists in the SpriteSheet at (${x}, ${y}), x: ${x} should be between 0 and ${this.columns - 1} columns`);
+    }
+    if (y >= this.rows || y < 0) {
+      throw Error(`No sprite exists in the SpriteSheet at (${x}, ${y}), y: ${y} should be between 0 and ${this.rows - 1} rows`);
+    }
+    const spriteIndex = x + y * this.columns;
+    const sprite = this.sprites[spriteIndex];
+    const cnv = document.createElement('canvas');
+    const ctx = cnv.getContext('2d');
+    cnv.width = sprite.width;
+    cnv.height = sprite.height;
+
+    if (!sprite) {
+      throw Error(`Invalid sprite coordinates (${x}, ${y})`);
+    }
+    if (!ctx) {
+      throw Error('Unable to create canvas context');
+    }
+
+    ctx.drawImage(
+      sprite.image.image,
+      sprite.sourceView.x,
+      sprite.sourceView.y,
+      sprite.sourceView.width,
+      sprite.sourceView.height,
+      0,
+      0,
+      sprite.sourceView.width,
+      sprite.sourceView.height
+    );
+
+    const imgSrc = new ImageSource(cnv.toDataURL());
+    await imgSrc.load();
+
+    return new Sprite({
+      image: imgSrc,
+      sourceView: {
+        x: 0,
+        y: 0,
+        width: sprite.width,
+        height: sprite.height
+      },
+      destSize: {
+        width: sprite.width,
+        height: sprite.height
+      }
+    });
+  }
+
+  /**
+   * Returns a new image exact size and copy of the original sprite slice.
+   *
+   * Useful if you need to apply effects, manipulate, or mutate the image and you don't want to disturb the original sprite sheet.
+   */
+  public async getSpriteAsImage(x: number, y: number): Promise<HTMLImageElement> {
+    if (x >= this.columns || x < 0) {
+      throw Error(`No sprite exists in the SpriteSheet at (${x}, ${y}), x: ${x} should be between 0 and ${this.columns - 1} columns`);
+    }
+    if (y >= this.rows || y < 0) {
+      throw Error(`No sprite exists in the SpriteSheet at (${x}, ${y}), y: ${y} should be between 0 and ${this.rows - 1} rows`);
+    }
+    const spriteIndex = x + y * this.columns;
+    const sprite = this.sprites[spriteIndex];
+    const cnv = document.createElement('canvas');
+    const ctx = cnv.getContext('2d');
+    cnv.width = sprite.width;
+    cnv.height = sprite.height;
+
+    if (!sprite) {
+      throw Error(`Invalid sprite coordinates (${x}, ${y})`);
+    }
+    if (!ctx) {
+      throw Error('Unable to create canvas context');
+    }
+
+    ctx.drawImage(
+      sprite.image.image,
+      sprite.sourceView.x,
+      sprite.sourceView.y,
+      sprite.sourceView.width,
+      sprite.sourceView.height,
+      0,
+      0,
+      sprite.sourceView.width,
+      sprite.sourceView.height
+    );
+
+    const imgSrc = new Image(sprite.width, sprite.height);
+    imgSrc.src = cnv.toDataURL();
+
+    return await new Promise((resolve, reject) => {
+      imgSrc.onload = () => {
+        resolve(imgSrc);
+      };
+      imgSrc.onerror = (e) => {
+        reject(e);
+      };
+    });
+  }
+
   /**
    * Create a sprite sheet from a sparse set of {@apilink SourceView} rectangles
    * @param options

src/spec/vitest/SpriteSheetSpec.ts

@@ -229,4 +229,52 @@ describe('A SpriteSheet for Graphics', () => {
     expect(ss.rows).toBe(clone.rows);
     expect(ss.columns).toBe(clone.columns);
   });
+
+  it('can produce a unique image element by x,y', async () => {
+    const image = new ex.ImageSource('/src/spec/assets/images/SpriteSheetSpec/kenny-cards.png');
+
+    await image.load();
+    const ss = ex.SpriteSheet.fromImageSource({
+      image,
+      grid: {
+        rows: 4,
+        columns: 14,
+        spriteWidth: 42,
+        spriteHeight: 60
+      },
+      spacing: {
+        originOffset: { x: 11, y: 2 },
+        margin: { x: 23, y: 5 }
+      }
+    });
+
+    const newImage = await ss.getSpriteAsImage(0, 0);
+    expect(newImage.width).toBe(42);
+    expect(newImage.height).toBe(60);
+    expect(newImage).toBeInstanceOf(Image);
+  });
+
+  it('can produce a unique Sprite Object by x,y', async () => {
+    const image = new ex.ImageSource('/src/spec/assets/images/SpriteSheetSpec/kenny-cards.png');
+
+    await image.load();
+    const ss = ex.SpriteSheet.fromImageSource({
+      image,
+      grid: {
+        rows: 4,
+        columns: 14,
+        spriteWidth: 42,
+        spriteHeight: 60
+      },
+      spacing: {
+        originOffset: { x: 11, y: 2 },
+        margin: { x: 23, y: 5 }
+      }
+    });
+
+    const newSprite = await ss.getSpriteAsStandalone(0, 0);
+    expect(newSprite.width).toBe(42);
+    expect(newSprite.height).toBe(60);
+    expect(newSprite).toBeInstanceOf(ex.Sprite);
+  });
 });