@overwolf/ow-electron-packages-types 1.1.5 → 1.1.6-1

package/package.json

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

package/types.d.ts

@@ -1,3 +1,4 @@
+import '@overwolf/ow-electron';
 import type {
   BrowserWindow,
   BrowserWindowConstructorOptions,
@@ -69,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:
@@ -1781,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',
@@ -1807,7 +1809,8 @@ export interface AudioFilterBase {
 
 /**
  * A specialized filter for dynamic range compression.
- * * @example
+ *
+ * @example
  * ```typescript
  * const vocalComp: AudioCompressorFilter = {
  * id: 'compressor_filter',
@@ -1862,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',
@@ -1931,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',
@@ -1962,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',
@@ -1984,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',
@@ -2024,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',
@@ -2082,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',
@@ -3070,6 +3079,18 @@ interface EncoderSettingsNVENC extends VideoEncoderSettingsBase {
    */
   rate_control?: kNVENCEncoderRateControl;
 
+  /**
+   * Constant Quantization Parameter (CQP) level.
+   *
+   * Sets a fixed quality level for the entire stream. Only applies when
+   * {@link rate_control} is `'CQP'`.
+   *
+   * Range: `1`–`51` (`1`–`63` for AV1).
+   *
+   * @default 20
+   */
+  cqp?: number;
+
   /**
    * Encoding quality preset.
    *
@@ -3253,11 +3274,21 @@ interface EncoderSettingsAMF extends VideoEncoderSettingsBase {
   ffmpeg_opts?: string;
 
   /**
-   * Constant Peak Quantizer (CPQ) value.
-   * Determines the quality level when using quantizer-based rate control modes.
+   * Constant Quantization Parameter (CQP) level.
+   *
+   * Determines the quality level for quantizer-based rate control. Only applies
+   * when {@link rate_control} is `'CQP'` or `'QVBR'`.
+   *
+   * Range: `0`–`51` (`0`–`63` for AV1).
    *
    * @default 20
    */
+  cqp?: number;
+
+  /**
+   * @deprecated Use {@link cqp} instead. Retained for backward compatibility;
+   * this value is ignored by the encoder.
+   */
   cpq?: number;
 
   /**
@@ -3363,6 +3394,30 @@ interface EncoderSettingsQuickSync extends VideoEncoderSettingsBase {
    */
   rate_control?: kQuickSyncEncoderRateControl;
 
+  /**
+   * Constant Quantization Parameter (CQP) level.
+   *
+   * Sets a fixed quantizer for the entire stream. Only applies when
+   * {@link rate_control} is `'CQP'`.
+   *
+   * Range: `1`–`51` (`1`–`63` for AV1).
+   *
+   * @default 23
+   */
+  cqp?: number;
+
+  /**
+   * Intelligent Constant Quality (ICQ) level.
+   *
+   * Lower values yield higher quality. Only applies when
+   * {@link rate_control} is `'ICQ'`.
+   *
+   * Range: `1`–`51`.
+   *
+   * @default 23
+   */
+  icq_quality?: number;
+
   /**
    * Target usage or encoding preset that balances performance and quality.
    *
@@ -3454,6 +3509,18 @@ interface EncoderSettingsX264 extends VideoEncoderSettingsBase {
    */
   rate_control?: kX264EncoderRateControl;
 
+  /**
+   * Constant Rate Factor (CRF) quality level.
+   *
+   * Lower values yield higher quality and larger files. Only applies when
+   * {@link rate_control} is `'CRF'` or `'VBR'`.
+   *
+   * Range: `0`–`51`.
+   *
+   * @default 23
+   */
+  crf?: number;
+
   /**
    * Specifies the encoding speed/quality trade-off preset.
    * A slower preset provides better compression (quality per bitrate).
@@ -3756,6 +3823,32 @@ interface EncoderInformation {
   audio: AudioEncoderInfo[];
 }
 
+/**
+ * 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 = 'off' | 'mini' | 'full';
+
+/**
+ * Crash dump configuration for the OBS host process.
+ */
+interface CrashDumpOptions {
+  /**
+   * Dump detail level; defaults to `mini`. Set to `off` to disable crash dump
+   * capture entirely. See {@link CrashDumpType}.
+   */
+  type?: CrashDumpType;
+
+  /**
+   * Max crash dumps to retain in `ow-obs/crashdumps`; the oldest are deleted
+   * beyond this count. Positive integer, defaults to `3`.
+   */
+  maxFiles?: number;
+}
+
 /**
  * Configuration options for launching or customizing the recording application behavior.
  *
@@ -3767,6 +3860,7 @@ interface EncoderInformation {
  * const options: RecordingAppOptions = {
  *   showDebugWindow: true,
  *   enableDebugLogs: true,
+ *   maxLogFiles: 20,
  * };
  * ```
  */
@@ -3782,6 +3876,23 @@ interface RecordingAppOptions {
    * Can be used to troubleshoot issues during recording.
    */
   enableDebugLogs?: boolean;
+
+  /**
+   * Maximum number of OBS log files to retain under the recorder's
+   * `ow-obs/logs` folder. Once the number of logs exceeds this value, the
+   * oldest logs are gradually pruned.
+   * Must be a positive integer. Defaults to `10`.
+   */
+  maxLogFiles?: number;
+
+  /**
+   * 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}
+   */
+  crashDumps?: CrashDumpOptions;
 }
 
 
@@ -4895,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.
  *
@@ -4980,10 +5128,42 @@ 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;
 
+  /**
+   * ⚠️ BETA — this option is experimental and its behavior may change in
+   * a future release.
+   *
+   * `true`—renders this overlay window through a GPU shared texture
+   * instead of copying pixels through shared memory on every paint. The overlay
+   * forwards the GPU texture handle directly to the injected game process, which
+   * composites it without any CPU-side pixel copy, significantly lowering
+   * per-frame CPU overhead.
+   *
+   * 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
+   * shared-memory (CPU copy) path on a game that does not support shared
+   * texture, and restores the shared-texture path on a game that does — so the
+   * window stays visible on every game.
+   *
+   * @default false
+   *
+   * @see {@link https://dev.overwolf.com/ow-electron/reference/examples/overlay | Overlay examples}
+   *
+   * @since 2.0.2
+   */
+  useSharedTexture?: boolean;
+
   /**
    * Enables Chromium process isolation (sandboxing).
    * Used to enforce stricter security policies or prevent resource sharing between renderer processes.
@@ -5332,11 +5512,43 @@ interface GameWindowInfo {
 
   /**
    * Indicates if fullscreen rendering is disabled.
-   * 
+   *
    * Relevant only for OOPO games.
    * @since 1.9.0
    */
   readonly isOOPOFullscreenRenderingDisabled?: boolean;
+
+  /**
+   * 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;
 }
 
 /**
@@ -5677,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.
@@ -5797,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.
    */
@@ -5918,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;
 }