@overwolf/ow-electron-packages-types 1.1.2-beta.3 → 1.1.2-beta.5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@overwolf/ow-electron-packages-types",
-    "version": "1.1.2-beta.3",
+    "version": "1.1.2-beta.5",
     "description": "Type definition file for autocompletion and documentation purposes for ow-electron packages",
     "license": "MIT",
     "types": "types.d.ts",

package/types.d.ts

@@ -5574,7 +5574,7 @@ interface IOverwolfOverlayApi extends EventEmitter {
    */
   exitExclusiveMode(): void;
 
-   /**
+  /**
    * Install ow-electron helpers to
    * `%CommonProgramFiles%\<app-name>\` with UAC elevation.
    * Allows injection into high elevation games.
@@ -5620,20 +5620,20 @@ interface IOverwolfOverlayApi extends EventEmitter {
    * }
    * ```
    * @returns Resolves when installation completes.
-   * 
-   * 
-   * 
+   *
+   *
+   *
    */
   installHighElevationHelper?(): Promise<void>;
 
   /**
    * Returns true if ow-electron helpers is already installed in
    * `%CommonProgramFiles%\<app-name>\`.
-   * 
+   *
    * @returns `true` if the helper is installed and ready.
-   * 
+   *
    * @example
-   * ```ts 
+   * ```ts
    * const installed: boolean = await api.isHighElevationHelperInstalled();
    * if (!installed) {
    *   // Prompt the user to run the one-time setup before injecting into elevated games
@@ -5642,6 +5642,64 @@ interface IOverwolfOverlayApi extends EventEmitter {
    */
   isHighElevationHelperInstalled?(): Promise<boolean>;
 
+  /**
+   * Captures the current game frame and saves it to disk.
+   *
+   * Only one screenshot can be in progress at a time. Calling this method
+   * while a previous capture is still pending will reject immediately —
+   * wait for the returned promise to settle before issuing the next call.
+   *
+   * The output format is resolved by precedence: an explicit `format`
+   * argument wins; otherwise the extension already present in `filePath`
+   * (`.jpg`/`.jpeg` or `.bmp`) is used; otherwise it defaults to `'bmp'`.
+   * The file extension is then normalized to match the resolved format, so
+   * an existing extension is rewritten rather than doubled (e.g.
+   * `shot.jpg` stays `shot.jpg`, and `shot.png` with `format: 'jpg'` becomes
+   * `shot.jpg`).
+   *
+   * Internally all backends (D3D9, D3D11, D3D12, Vulkan) capture as BMP
+   * first and transcode to JPEG on demand, ensuring correct colors across
+   * all graphics APIs and formats.
+   *
+   * @param filePath - Absolute path (UTF-8) where the image will be saved.
+   * @param format - Output image format: `'jpg'` or `'bmp'`. When omitted,
+   *   the extension in `filePath` is used, falling back to `'bmp'`.
+   * @returns A promise that resolves with the absolute path the file was
+   *   actually written to, including the normalized extension (which may
+   *   differ from `filePath`).
+   *
+   * @throws `'no active game'` — the overlay is not currently injected into
+   *   any game. Wait for the `game-injected` event before calling.
+   * @throws `'screenshot already in progress'` — a previous capture has not
+   *   yet completed. Await the previous promise before calling again.
+   * @throws `'no active graphics device'` — the game has no active GPU
+   *   device at this moment (e.g. the game window is minimized or in a
+   *   device-lost state). Try again once the game is in the foreground.
+   * @throws `'capture failed: <backend>'` — the GPU-side readback failed
+   *   (e.g. staging texture creation, memory map, or WIC encode error).
+   *
+   * @example
+   * ```ts
+   * overlay.on('game-injected', () => {
+   *   overlay.hotkeys.register(
+   *     { name: 'screenshot', keyCode: 'F9', passthrough: false },
+   *     async (hotkey, state) => {
+   *       if (state !== 'pressed') return;
+   *       const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+   *       const filePath = path.join(app.getPath('pictures'), `screenshot_${ts}`);
+   *       try {
+   *         const savedPath = await overlay.takeScreenshot(filePath, 'jpg');
+   *         console.log('screenshot written to', savedPath); // ...filePath.jpg
+   *       } catch (err) {
+   *         console.error('Screenshot failed:', err.message);
+   *       }
+   *     }
+   *   );
+   * });
+   * ```
+   */
+  takeScreenshot(filePath: string, format?: 'jpg' | 'bmp'): Promise<void>;
+
   /**
    * Fires when an internal error occurs within the overlay system.
    */
@@ -5655,7 +5713,10 @@ interface IOverwolfOverlayApi extends EventEmitter {
    * @param listener - Callback with game launch event and game metadata.
    * @see {@link GameInfo}.
    */
-  on(eventName: 'game-launched', listener: (event: GameLaunchEvent, gameInfo: GameInfo) => void): this;
+  on(
+    eventName: 'game-launched',
+    listener: (event: GameLaunchEvent, gameInfo: GameInfo) => void,
+  ): this;
 
   /**
    * Fires when a registered game process terminates.
@@ -5675,7 +5736,10 @@ interface IOverwolfOverlayApi extends EventEmitter {
    *
    * @see {@link GameInfo}.
    */
-  on(eventName: 'game-exit', listener: (gameInfo: GameInfo, wasInjected: boolean) => void): this;
+  on(
+    eventName: 'game-exit',
+    listener: (gameInfo: GameInfo, wasInjected: boolean) => void,
+  ): this;
 
   /**
    * Fires when the overlay is ready and successfully injected into the game.
@@ -5695,7 +5759,7 @@ interface IOverwolfOverlayApi extends EventEmitter {
    */
   on(
     eventName: 'game-injection-error',
-    listener: (gameInfo: GameInfo, error: string, ...args: any[]) => void
+    listener: (gameInfo: GameInfo, error: string, ...args: any[]) => void,
   ): this;
 
   /**
@@ -5711,8 +5775,8 @@ interface IOverwolfOverlayApi extends EventEmitter {
     listener: (
       window: GameWindowInfo,
       gameInfo: GameInfo,
-      focus: boolean
-    ) => void
+      focus: boolean,
+    ) => void,
   ): this;
 
   /**
@@ -5729,8 +5793,8 @@ interface IOverwolfOverlayApi extends EventEmitter {
     listener: (
       window: GameWindowInfo,
       gameInfo: GameInfo,
-      reason?: GameWindowUpdateReason
-    ) => void
+      reason?: GameWindowUpdateReason,
+    ) => void,
   ): this;
 
   /**
@@ -5743,7 +5807,7 @@ interface IOverwolfOverlayApi extends EventEmitter {
    */
   on(
     eventName: 'game-input-interception-changed',
-    listener: (info: GameInputInterception) => void
+    listener: (info: GameInputInterception) => void,
   ): this;
 
   /**
@@ -5755,7 +5819,7 @@ interface IOverwolfOverlayApi extends EventEmitter {
    */
   on(
     eventName: 'game-input-exclusive-mode-changed',
-    listener: (info: GameInputInterception) => void
+    listener: (info: GameInputInterception) => void,
   ): this;
 }