<?php

declare(strict_types=1);

namespace Drupal\ffmpeg_media\Service;

/**
 * Interface for probing system-level GPU hardware presence.
 *
 * This service checks for actual hardware devices on the system,
 * independent of FFmpeg compilation flags. It verifies that the
 * physical GPU hardware and drivers are present and accessible.
 *
 * @internal
 */
interface HardwareProbeInterface {

  /**
   * PCI vendor ID for NVIDIA.
   */
  public const string VENDOR_NVIDIA = '0x10de';

  /**
   * PCI vendor ID for Intel.
   */
  public const string VENDOR_INTEL = '0x8086';

  /**
   * PCI vendor ID for AMD.
   */
  public const string VENDOR_AMD = '0x1002';

  /**
   * Checks if an NVIDIA GPU is present and accessible.
   *
   * Verifies via NVIDIA device files (/dev/nvidia*) or nvidia-smi.
   *
   * @return bool
   *   TRUE if NVIDIA GPU hardware is detected.
   */
  #[\NoDiscard]
  public function isNvidiaGpuPresent(): bool;

  /**
   * Checks if an Intel GPU is present and accessible.
   *
   * Verifies via DRM device vendor files for Intel vendor ID (0x8086).
   *
   * @return bool
   *   TRUE if Intel GPU hardware is detected.
   */
  #[\NoDiscard]
  public function isIntelGpuPresent(): bool;

  /**
   * Checks if an AMD GPU is present and accessible.
   *
   * Verifies via DRM device vendor files for AMD vendor ID (0x1002).
   *
   * @return bool
   *   TRUE if AMD GPU hardware is detected.
   */
  #[\NoDiscard]
  public function isAmdGpuPresent(): bool;

  /**
   * Checks if a DRI render device is present.
   *
   * @param string $device
   *   Device path, defaults to '/dev/dri/renderD128'.
   *
   * @return bool
   *   TRUE if the DRI device exists.
   */
  #[\NoDiscard]
  public function isDriDevicePresent(string $device = '/dev/dri/renderD128'): bool;

  /**
   * Checks if a specific PCI vendor GPU is present via DRM subsystem.
   *
   * @param string $vendorId
   *   PCI vendor ID (e.g., '0x8086' for Intel, '0x1002' for AMD).
   *
   * @return bool
   *   TRUE if a GPU with the given vendor ID is found.
   */
  #[\NoDiscard]
  public function hasGpuVendor(string $vendorId): bool;

  /**
   * Gets all detected GPU vendor IDs from the DRM subsystem.
   *
   * @return array<int, string>
   *   List of PCI vendor IDs found (e.g., ['0x10de', '0x8086']).
   */
  #[\NoDiscard]
  public function getDetectedGpuVendors(): array;

  /**
   * Checks if any GPU hardware is present on the system.
   *
   * Returns TRUE if NVIDIA, Intel, or AMD GPU is detected via DRM
   * subsystem or vendor-specific device files. Used to gate Vulkan
   * hardware acceleration which requires an actual GPU device.
   *
   * @return bool
   *   TRUE if any GPU hardware is detected.
   */
  #[\NoDiscard]
  public function isAnyGpuPresent(): bool;

}
