<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Interface for hardware acceleration detection service.
 *
 * @internal Runtime service, not part of the supported contrib extension API.
 */
interface HardwareDetectorInterface {

  /**
   * Detects available hardware acceleration.
   *
   * @return array<int, string>
   *   Array of available hardware types.
   */
  #[\NoDiscard]
  public function detectAvailableHardware(): array;

  /**
   * Checks if specific hardware acceleration is available.
   *
   * @param string $hwType
   *   Hardware type (use class constants).
   *
   * @return bool
   *   TRUE if available.
   */
  #[\NoDiscard]
  public function hasHardware(string $hwType): bool;

  /**
   * Gets hardware capabilities.
   *
   * @return array{
   *   gpu_name: string|null,
   *   available_encoders: array<int, string>,
   *   available_decoders: array<int, string>,
   *   max_resolution: string|null,
   *   memory: int|null
   *   }
   *   Hardware capability details.
   */
  #[\NoDiscard]
  public function getCapabilities(): array;

  /**
   * Gets hardware acceleration arguments for FFmpeg.
   *
   * @param string $hwType
   *   Hardware type to use.
   * @param string $operation
   *   Operation: 'encode' or 'decode'.
   *
   * @return array<int, string>
   *   FFmpeg arguments for hardware acceleration.
   */
  #[\NoDiscard]
  public function getHwaccelArguments(string $hwType, string $operation = 'encode'): array;

  /**
   * Refreshes hardware detection cache.
   */
  public function refresh(): void;

  /**
   * Records a successful encoding with hardware acceleration.
   *
   * Used by circuit breaker to track hardware reliability.
   *
   * @param string $hwType
   *   Hardware type that succeeded.
   */
  public function recordEncodingSuccess(string $hwType): void;

  /**
   * Records a failed encoding with hardware acceleration.
   *
   * Used by circuit breaker to track hardware reliability
   * and potentially disable failing hardware.
   *
   * @param string $hwType
   *   Hardware type that failed.
   */
  public function recordEncodingFailure(string $hwType): void;

  /**
   * Checks if hardware should be skipped due to circuit breaker.
   *
   * @param string $hwType
   *   Hardware type to check.
   *
   * @return bool
   *   TRUE if hardware should be skipped (circuit is open).
   */
  #[\NoDiscard]
  public function shouldSkipHardware(string $hwType): bool;

}
