@overwolf/ow-electron-packages-types 1.1.6-beta.1 → 1.1.6-beta.3

package/package.json

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

package/types.d.ts

@@ -70,9 +70,9 @@ interface IOverwolfUtilityApi {
    * Allows injection into high elevation games.
    * No-ops if files are already present.
    *
-   * @throws \{HelperInstallError\} `exitCode 1223` — user cancelled the UAC prompt (ERROR_CANCELLED)
-   * @throws - {HelperInstallError} `err.exitCode !== 1223` — the installer process failed. Log `err.exitCode` and investigate.
-   * @throws \{HelperInstallError\} any other non-zero exitCode — installation failed.
+   * @throws `HelperInstallError` `exitCode 1223` — user cancelled the UAC prompt (ERROR_CANCELLED)
+   * @throws `HelperInstallError` `err.exitCode !== 1223` — the installer process failed. Log `err.exitCode` and investigate.
+   * @throws `HelperInstallError` any other non-zero exitCode — installation failed.
    *
    * @remarks
    * The helper binaries are installed to:
@@ -1782,7 +1782,8 @@ type VideoRecordingSplitType =
  * 
  * This interface serves as a blueprint for all audio filters within the system,
  * ensuring they have a unique identifier and a flexible container for settings.
- * * @example
+ *
+ * @example
  * ```typescript
  * const lowPass: AudioFilterBase = {
  * id: 'low-pass-001',
@@ -1808,7 +1809,8 @@ export interface AudioFilterBase {
 
 /**
  * A specialized filter for dynamic range compression.
- * * @example
+ *
+ * @example
  * ```typescript
  * const vocalComp: AudioCompressorFilter = {
  * id: 'compressor_filter',
@@ -1863,7 +1865,8 @@ export interface AudioCompressorFilter extends AudioFilterBase {
 
 /**
  * A specialized filter for dynamic range expansion or noise gating.
- * * @example
+ *
+ * @example
  * ```typescript
  * const noiseGate: AudioExpanderFilter = {
  * id: 'expander_filter',
@@ -1932,7 +1935,8 @@ export interface AudioExpanderFilter extends AudioFilterBase {
 
 /**
  * A simple filter used to adjust the volume or amplitude of an audio signal.
- * * @example
+ *
+ * @example
  * ```typescript
  * const boost: AudioGainFilter = {
  * id: 'gain_filter',
@@ -1963,7 +1967,8 @@ export interface AudioGainFilter extends AudioFilterBase {
 
 /**
  * A utility filter that flips the phase of the audio signal by 180 degrees.
- * * @example
+ *
+ * @example
  * ```typescript
  * const phaseFlip: AudioInvertPolarityFilter = {
  * id: 'invert_polarity_filter',
@@ -1985,7 +1990,8 @@ export interface AudioInvertPolarityFilter extends AudioFilterBase {
 
 /**
  * A specialized dynamics processor used to prevent an audio signal from exceeding a specific decibel level.
- * * @example
+ *
+ * @example
  * ```typescript
  * const masterLimiter: AudioLimiterFilter = {
  * id: 'limiter_filter',
@@ -2025,7 +2031,8 @@ export interface AudioLimiterFilter extends AudioFilterBase {
 /**
  * A noise gate filter used to attenuate signals that fall below a certain threshold.
  * It is primarily used to remove background noise during silent passages.
- * * @example
+ *
+ * @example
  * ```typescript
  * const gate: AudioNoiseGateFilter = {
  * id: 'noise_gate_filter',
@@ -2083,7 +2090,8 @@ export interface AudioNoiseGateFilter extends AudioFilterBase {
 
 /**
  * An advanced noise suppression filter utilizing machine learning or digital signal processing algorithms.
- * * @example
+ *
+ * @example
  * ```typescript
  * const aiDenoise: AudioNoiseSuppressFilterV2 = {
  * id: 'noise_suppress_filter_v2',
@@ -3817,17 +3825,20 @@ interface EncoderInformation {
 
 /**
  * Crash dump detail level for the OBS host process.
+ * - `off`: no crash dumps are captured. The OBS text crash report is still
+ *   written, and dump files already on disk are left untouched.
  * - `mini`: small dump (thread stacks + module list); the default.
  * - `full`: complete-memory dump; large — opt-in for debugging only.
  */
-type CrashDumpType = 'mini' | 'full';
+type CrashDumpType = 'off' | 'mini' | 'full';
 
 /**
  * Crash dump configuration for the OBS host process.
  */
 interface CrashDumpOptions {
   /**
-   * Dump detail level; defaults to `mini`. See {@link CrashDumpType}.
+   * Dump detail level; defaults to `mini`. Set to `off` to disable crash dump
+   * capture entirely. See {@link CrashDumpType}.
    */
   type?: CrashDumpType;
 
@@ -3875,8 +3886,9 @@ interface RecordingAppOptions {
   maxLogFiles?: number;
 
   /**
-   * Tune OBS-host crash dumps. Mini-dump capture is always on; these options
-   * only change the detail level and retention count.
+   * Tune OBS-host crash dumps. Mini-dump capture is on by default; these
+   * options change the detail level and retention count, or turn capture off
+   * entirely via `type: 'off'`.
    *
    * @see {@link CrashDumpOptions}
    */
@@ -4994,6 +5006,43 @@ type ZOrderType = "default" | "topMost" | "bottomMost";
 
 
 
+/**
+ * Which GPU Windows should run this application on.
+ *
+ * - `default`—No preference is recorded; Windows decides (normally the adapter driving the primary display).
+ * - `highPerformance`—Pin the application to the high-performance (usually discrete) adapter.
+ *
+ * @see {@link IOverwolfOverlayApi.setGpuPreference}.
+ *
+ * @since 2.0.5
+ */
+type GpuPreference = "default" | "highPerformance";
+
+/**
+ * Why the shared-texture rendering path cannot be used with the current game.
+ *
+ * - `unsupportedGraphicsApi`—The game's graphics API cannot composite GPU textures
+ *   (D3D9 / OpenGL / Vulkan). Nothing to fix; the overlay uses the CPU copy path for this
+ *   game.
+ * - `gpuAdapterMismatch`—The game renders on a different GPU adapter than Chromium,
+ *   and a shared texture handle can only be opened on the adapter that created it. Fixable
+ *   with {@link IOverwolfOverlayApi.setGpuPreference} and an application restart.
+ * - `copyFailure`—The game repeatedly failed to open the shared texture handles it
+ *   received in-game. The overlay retried, then fell back to the CPU copy path.
+ *   {@link IOverwolfOverlayApi.setGpuPreference} may help when the root cause is
+ *   adapter-related.
+ *
+ * @see {@link IOverwolfOverlayApi.on} `shared-texture-unavailable`.
+ *
+ * @since 2.0.5
+ */
+type SharedTextureUnavailableReason =
+  | "unsupportedGraphicsApi"
+  | "gpuAdapterMismatch"
+  | "copyFailure";
+
+
+
 /**
  * Overlay configuration options for creating or modifying an overlay window.
  *
@@ -5079,6 +5128,8 @@ interface OverlayWindowOptions
    *
    * @default false
    *
+   * @see {@link https://www.electronjs.org/docs/latest/tutorial/offscreen-rendering#software-output-device | Software output device}
+   *
    * @since 1.13.20
    */
   disableHardwareAcceleration?: boolean;
@@ -5093,10 +5144,11 @@ interface OverlayWindowOptions
    * composites it without any CPU-side pixel copy, significantly lowering
    * per-frame CPU overhead.
    *
-   * Requires hardware acceleration to be enabled and the current game to report
-   * shared-texture support (see {@link GameWindowInfo.isSharedTextureSupported}).
-   * The flag is silently ignored when either condition is not met, falling back
-   * to the shared-memory (CPU copy) path.
+   * Requires hardware acceleration to be enabled and the shared-texture path to
+   * be usable with the current game (see
+   * {@link GameWindowInfo.isSharedTextureAvailable}). The flag is silently
+   * ignored when either condition is not met, falling back to the
+   * shared-memory (CPU copy) path.
    *
    * The rendering path follows the active game: when the overlay moves to a
    * different game, a shared-texture window automatically falls back to the
@@ -5106,6 +5158,8 @@ interface OverlayWindowOptions
    *
    * @default false
    *
+   * @see {@link https://dev.overwolf.com/ow-electron/reference/examples/overlay | Overlay examples}
+   *
    * @since 2.0.2
    */
   useSharedTexture?: boolean;
@@ -5465,10 +5519,36 @@ interface GameWindowInfo {
   readonly isOOPOFullscreenRenderingDisabled?: boolean;
 
   /**
-   * Indicates if the game supports shared-texture (GPU) overlay rendering.
+   * Indicates whether the game's **graphics API** supports shared-texture (GPU) overlay
+   * rendering: `true` for D3D11 / D3D12, `false` for D3D9 / OpenGL / Vulkan.
+   *
+   * This is a capability probe only — to decide whether the path can actually be used
+   * on this machine, gate on {@link GameWindowInfo.isSharedTextureAvailable} instead.
+   *
+   * `undefined` until the game is injected and its graphics API is detected.
+   *
    * @since 2.0.0
    */
   readonly isSharedTextureSupported?: boolean;
+
+  /**
+   * Indicates whether shared-texture (GPU) overlay rendering can actually be used with this
+   * game — gate `useSharedTexture` window creation on it.
+   *
+   * `true` when the game's graphics API supports it
+   * ({@link GameWindowInfo.isSharedTextureSupported}), no GPU adapter mismatch was detected,
+   * **and** the path was not abandoned after repeated in-game copy failures. When it is
+   * `false`, the `shared-texture-unavailable` event names the reason. It can therefore turn
+   * `false` mid-game: the copy-failure verdict is reached only after frames were sent and
+   * repeatedly failed to draw.
+   *
+   * `undefined` until the game is injected and its graphics API is detected.
+   *
+   * @see {@link https://dev.overwolf.com/ow-electron/reference/examples/overlay | Overlay examples}
+   *
+   * @since 2.0.5
+   */
+  readonly isSharedTextureAvailable?: boolean;
 }
 
 /**
@@ -5809,7 +5889,7 @@ interface IOverwolfOverlayApi extends EventEmitter {
    * Allows injection into high elevation games.
    * No-ops if files are already present.
    *
-   * @throws \{HelperInstallError\}
+   * @throws `HelperInstallError`
    *  - `exitCode 1223` — user cancelled the UAC prompt (ERROR_CANCELLED)
    *  - `err.exitCode !== 1223` — the installer process failed. Log `err.exitCode` and investigate.
    *  - any other non-zero exitCode — installation failed.
@@ -5929,6 +6009,65 @@ interface IOverwolfOverlayApi extends EventEmitter {
    */
   takeScreenshot(filePath: string, format?: 'jpg' | 'bmp'): Promise<void>;
 
+  /**
+   * Records a Windows per-executable GPU preference for this application, so
+   * Chromium's GPU process runs on the same adapter as games do.
+   *
+   * The shared-texture path requires that: a shared GPU texture handle can only be opened on
+   * the adapter that created it, and Chromium takes the adapter driving the **primary
+   * display** while games run on the discrete GPU. When those differ the overlay falls back
+   * to the CPU copy path and emits `shared-texture-unavailable`.
+   *
+   * **An application restart is normally required.** DXGI reads this preference when a
+   * process creates its D3D device, which Chromium's GPU process has already done by the time
+   * this API is reachable. Call {@link IOverwolfOverlayApi.getGpuPreference} to learn whether
+   * the application is *already* aligned and therefore needs no restart; this method is
+   * idempotent, so calling it unconditionally is safe.
+   *
+   * **Side effects &mdash; read before calling.** It moves the **entire application's**
+   * rendering to that GPU, draining laptop battery and keeping the discrete GPU awake; it is
+   * persistent, user-visible Windows state under
+   * Settings &rarr; System &rarr; Display &rarr; Graphics; and it is keyed on the executable
+   * path, so moving or renaming the application leaves a stale entry behind. It is therefore
+   * **never applied implicitly**. Pass `'default'` to remove the entry, the recommended
+   * revert on uninstall or when the user turns the overlay off.
+   *
+   * @param preference - `'highPerformance'` to pin this application to the high-performance
+   *   adapter, or `'default'` to remove the entry and let Windows decide.
+   * @returns A promise that resolves once the preference has been recorded.
+   * @throws If the registry cannot be written, or on a non-Windows platform.
+   * @see {@link GpuPreference}.
+   * @see {@link https://dev.overwolf.com/ow-electron/reference/examples/overlay | Overlay examples}
+   *
+   * @example
+   * ```ts
+   * overlay.on('shared-texture-unavailable', async (reason) => {
+   *   if (reason !== 'gpuAdapterMismatch') return;
+   *   if ((await overlay.getGpuPreference()) === 'highPerformance') return;
+   *   await overlay.setGpuPreference('highPerformance');
+   *   promptUserToRestart(); // takes effect on the next launch
+   * });
+   * ```
+   *
+   * @since 2.0.5
+   */
+  setGpuPreference(preference: GpuPreference): Promise<void>;
+
+  /**
+   * Returns the GPU preference currently recorded for this application's executable.
+   *
+   * Resolves to `'default'` when no entry exists &mdash; "no entry" and "let Windows decide"
+   * are the same state, so this never resolves `undefined`.
+   *
+   * @returns A promise resolving to the recorded preference.
+   * @throws On a non-Windows platform.
+   * @see {@link IOverwolfOverlayApi.setGpuPreference}.
+   * @see {@link GpuPreference}.
+   *
+   * @since 2.0.5
+   */
+  getGpuPreference(): Promise<GpuPreference>;
+
   /**
    * Fires when an internal error occurs within the overlay system.
    */
@@ -6050,6 +6189,50 @@ interface IOverwolfOverlayApi extends EventEmitter {
     eventName: 'game-input-exclusive-mode-changed',
     listener: (info: GameInputInterception) => void,
   ): this;
+
+  /**
+   * Fires when the shared-texture rendering path cannot be used with the current game, with
+   * the reason:
+   *
+   * - `unsupportedGraphicsApi`&mdash;the game's graphics API cannot composite GPU textures
+   *   (D3D9 / OpenGL / Vulkan). Nothing to fix.
+   * - `gpuAdapterMismatch`&mdash;the game renders on a **different GPU adapter than
+   *   Chromium**; a shared texture handle can only be opened on the adapter that created it.
+   *   Fixable with {@link IOverwolfOverlayApi.setGpuPreference} and a restart; both adapters
+   *   are named in the overlay log.
+   * - `copyFailure`&mdash;the game **repeatedly failed to open the shared texture handles it
+   *   received in-game**. The overlay retried, then abandoned the path for this game.
+   *   {@link IOverwolfOverlayApi.setGpuPreference} may help when the root cause is
+   *   adapter-related; details are in the overlay log.
+   *
+   * Fires at most **once per injected game**. The first two reasons are detected when the
+   * game's graphics are detected, before any frame is sent; `copyFailure` is reached only
+   * after frames were sent and repeatedly failed to draw. Either way, the affected overlay
+   * windows have already been switched to the CPU copy path by the time the event fires, so
+   * they stay visible and interactive, and
+   * {@link GameWindowInfo.isSharedTextureAvailable} reports `false` for the game.
+   *
+   * @param eventName - `shared-texture-unavailable`
+   * @param listener - Callback invoked once for the current game with the reason.
+   *
+   * @see {@link https://dev.overwolf.com/ow-electron/reference/examples/overlay | Overlay examples}
+   *
+   * @example
+   * ```ts
+   * overlay.on('shared-texture-unavailable', async (reason) => {
+   *   if (reason !== 'gpuAdapterMismatch') return;
+   *   if ((await overlay.getGpuPreference()) === 'highPerformance') return;
+   *   await overlay.setGpuPreference('highPerformance');
+   *   promptUserToRestart();
+   * });
+   * ```
+   *
+   * @since 2.0.5
+   */
+  on(
+    eventName: 'shared-texture-unavailable',
+    listener: (reason: SharedTextureUnavailableReason) => void,
+  ): this;
 }