frust_gpu/

context.rs

//! Instance, adapter and lazy logical-device creation: [`RenderContext`] and
//! [`DeviceHandle`].
//!
//! This is the crate's entry point — everything else in `frust-gpu` consumes a
//! [`DeviceHandle`] rather than reaching for a `wgpu::Adapter` itself. A
//! [`RenderContext`] owns one `wgpu::Instance` and at most one logical device,
//! created lazily on the first surface (or the first [`RenderContext::device`]
//! call) and then reused: a logical device is display-independent, so surface
//! loss and recreation (rotation, backgrounding) must not rebuild it.
//!
//! This is also the type `frust-render` re-exports as its own
//! `frust_render::RenderContext`, which is what every platform shell holds: the
//! device/surface foundation lives here, and the renderer above adds only the
//! render-path decisions specific to how a frame is drawn.
//!
//! Surface creation itself lives in [`crate::surface`] and the raw-pointer
//! constructors in [`crate::lifecycle`]; [`RenderContext::create_render_surface`]
//! is the one entry point that ties them to a device.
//!
//! # Pure decision vs. platform lookup
//!
//! Every environment-sensitive choice here is split into a pure function taking
//! the environment as an argument (`effective_instance_flags`,
//! [`effective_limits`], `device_features`, [`decide_log_action`]) plus a
//! separate lookup that answers what the environment actually is
//! (`is_android_emulator`, [`is_ios_simulator`]). Only the lookups are
//! platform-gated, so the policies stay unit-testable on any host with no GPU
//! and no mobile target in the loop — the same split
//! [`crate::caps::TierCaps::probe`]/[`crate::caps::TierCaps::fake`] gives
//! adapter capabilities.
//!
//! # Two mitigations worth knowing about
//!
//! - The Android **emulator** cannot survive `wgpu::InstanceFlags::DEBUG`, so
//!   the instance is built with those flags stripped there and nowhere else
//!   (`effective_instance_flags`).
//! - The iOS **Simulator** misreports its uniform-buffer alignment, so a device
//!   request made there is forced back up to 256 bytes ([`effective_limits`]).
//!
//! # The Android hardware-buffer device
//!
//! `wgpu`'s own `request_device` never enables
//! `VK_ANDROID_external_memory_android_hardware_buffer`, so a device it opens
//! can never import an `AHardwareBuffer` ([`crate::import`]). On Android, with
//! the `FRUST_ANDROID_HWBUFFER_IMPORT` knob on (the compile-time or runtime
//! environment variable, or the `debug.frust.hwbuffer_import` system property,
//! any value but `0`), a Vulkan device is instead opened by this module itself:
//! the same features, limits and memory hints `request_device` would have been
//! given, plus the import extensions (`hwbuffer_import_extensions`), through
//! `wgpu_hal::vulkan::Adapter::open_with_callback` and
//! `wgpu::Adapter::create_device_from_hal`. When any extension is missing the
//! device is opened through `wgpu` as usual, and [`TierCaps::hwbuffer_import`]
//! records which path produced it. Knob off — and on every other target — the
//! device request is exactly the plain `request_device` one.

use std::ffi::CStr;
use std::sync::atomic::{AtomicU32, Ordering};
use std::sync::{Arc, OnceLock};

use anyhow::{Result, anyhow};

use crate::caps::{DownlevelProfile, TierCaps, env_flag_enabled};
use crate::surface::{
    ConfiguredSurface, SurfaceAlphaRequest, SurfaceFactory, resolve_alpha_mode,
    select_surface_format,
};

/// Default `wgpu::Device` debug label, used when a caller supplies no
/// [`ContextOptions::device_label`] of its own.
const DEFAULT_DEVICE_LABEL: &str = "frust-gpu device";

/// How a [`RenderContext`] should build its instance and request its device.
///
/// Every field has a working default, so `ContextOptions::default()` is the
/// ordinary construction — a field exists here only where a host genuinely has
/// a choice to make, and [`RenderContext::new`] takes the defaults.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct ContextOptions {
    /// Debug label attached to the created `wgpu::Device`, surfaced by graphics
    /// debuggers and in validation messages.
    pub device_label: String,
    /// Backends the `wgpu::Instance` is restricted to. `None` — the default —
    /// takes `wgpu::Backends::from_env()` (the `WGPU_BACKEND` knob) and falls
    /// back to every backend compiled in, which is what a shell wants. A
    /// headless caller that must pin one backend regardless of the ambient
    /// environment sets it explicitly.
    pub backends: Option<wgpu::Backends>,
}

impl Default for ContextOptions {
    fn default() -> Self {
        Self {
            device_label: DEFAULT_DEVICE_LABEL.to_string(),
            backends: None,
        }
    }
}

/// A logical device, the adapter it was created from, the queue that executes
/// its command buffers, and the capabilities that adapter reported.
///
/// Cheap to clone: `wgpu`'s `Adapter`/`Device`/`Queue` are all `Arc`-backed
/// handles to one underlying object, so a clone is another handle to the *same*
/// device rather than a second device. Clone it freely to hand a subsystem the
/// device it needs instead of threading a `&RenderContext` borrow through it.
#[derive(Clone, Debug)]
pub struct DeviceHandle {
    /// The adapter the device was created from.
    pub adapter: wgpu::Adapter,
    /// The logical device.
    pub device: wgpu::Device,
    /// The queue that executes this device's command buffers.
    pub queue: wgpu::Queue,
    /// What [`Self::adapter`] reported at device-creation time. Captured once
    /// so downstream pipeline/atlas decisions read plain data instead of
    /// re-probing the adapter.
    pub caps: TierCaps,
    /// The first uncaptured error this device raised, latched by the handler
    /// installed in [`create_device`]. See [`Self::first_uncaptured_error`].
    first_uncaptured_error: Arc<OnceLock<String>>,
}

impl DeviceHandle {
    /// The **first** uncaptured `wgpu` error this device ever raised, or `None`
    /// if it has raised none.
    ///
    /// Latched, never overwritten: a frame loop polling this wants the error
    /// that started the trouble, not the last one in a storm the first one
    /// caused. It is also the only programmatic view of an uncaptured error a
    /// caller gets — the handler otherwise only logs (see
    /// [`decide_log_action`]) — so a host can degrade or report instead of
    /// silently rendering nothing every frame.
    ///
    /// Deliberately not clearable: "this device has seen an uncaptured error"
    /// is a property of the device, and a device that has raised one is not
    /// reliably recoverable by forgetting about it.
    pub fn first_uncaptured_error(&self) -> Option<&str> {
        self.first_uncaptured_error.get().map(String::as_str)
    }
}

/// Owns the `wgpu::Instance` and the single logical device this crate's
/// consumers render with.
///
/// A single `RenderContext` is shared across every surface a shell creates
/// (frust is single-window); the device is created lazily on the first surface
/// and reused across surface loss/recreation (rotation, backgrounding) since a
/// logical device is display-independent. [`RenderContext::new`] performs no
/// adapter enumeration at all, so a host may build one early (before it has a
/// window, or on a thread that will never render) and pay for the device only
/// at the first surface — or at an explicit
/// [`ensure_device_headless`](Self::ensure_device_headless) pre-init.
pub struct RenderContext {
    instance: wgpu::Instance,
    options: ContextOptions,
    /// `None` until a surface (or an explicit pre-init) creates the device.
    device: Option<DeviceHandle>,
}

impl Default for RenderContext {
    fn default() -> Self {
        Self::new()
    }
}

impl RenderContext {
    /// Creates a context with a fresh wgpu `Instance` and no device yet
    /// (the device is created lazily on first surface creation).
    ///
    /// The instance flags come from the build configuration
    /// (`InstanceFlags::from_build_config`, which turns `DEBUG`/`VALIDATION` on
    /// in debug builds) plus the standard `WGPU_*` environment overrides. When
    /// actually running on an Android *emulator* they are then run through
    /// `effective_instance_flags`, which strips `DEBUG`/`VALIDATION`: the
    /// `DEBUG` flag makes wgpu enable `VK_EXT_debug_utils` and set object-name
    /// labels via `vkSetDebugUtilsObjectNameEXT`, and the emulator's gfxstream
    /// Vulkan HAL (`vulkan.ranchu.so`) segfaults inside that entry point during
    /// adapter enumeration (observed crash: `#00 vulkan.ranchu.so
    /// vk_common_SetDebugUtilsObjectNameEXT`) — the same class of debug-utils
    /// fragility a MoltenVK Vulkan backend is also known to have. Debug object
    /// labels are only a developer convenience, so dropping them on the
    /// emulator is a safe way to keep GPU bring-up alive there while leaving
    /// physical devices' validation safety net — and desktop behavior —
    /// untouched.
    pub fn new() -> Self {
        Self::with_options(ContextOptions::default())
    }

    /// [`Self::new`] with an explicit [`ContextOptions`] — a headless harness
    /// that must label its device or pin one backend regardless of the ambient
    /// environment. Every shell takes `new()`'s defaults instead.
    pub fn with_options(options: ContextOptions) -> Self {
        let backends = options
            .backends
            .unwrap_or_else(|| wgpu::Backends::from_env().unwrap_or_default());
        let build_flags = wgpu::InstanceFlags::from_build_config().with_env();
        #[cfg(target_os = "android")]
        let flags = effective_instance_flags(build_flags, is_android_emulator());
        #[cfg(not(target_os = "android"))]
        let flags = build_flags;
        let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
            display: None,
            backends,
            flags,
            memory_budget_thresholds: wgpu::MemoryBudgetThresholds::default(),
            backend_options: wgpu::BackendOptions::from_env_or_default(),
        });
        Self {
            instance,
            options,
            device: None,
        }
    }

    /// A cloneable [`SurfaceFactory`] sharing this context's wgpu `Instance`,
    /// for creating a [`DetachedSurface`](crate::surface::DetachedSurface) on
    /// the windowing/main thread when the context itself lives on the render
    /// thread (the render-thread split). The surface a clone produces stays
    /// compatible with the device this context creates, since both share one
    /// Arc-backed instance.
    pub fn surface_factory(&self) -> SurfaceFactory {
        SurfaceFactory::new(&self.instance)
    }

    /// This context's wgpu `Instance`, for the two raw-pointer surface
    /// constructors in [`crate::lifecycle`] (the mobile shells' path, which
    /// receives an `ANativeWindow*`/`CAMetalLayer*` rather than a window
    /// handle a [`SurfaceFactory`] could take).
    ///
    /// Hidden from the rendered docs rather than made private, on the same
    /// grounds as
    /// [`DetachedSurface::into_surface`](crate::surface::DetachedSurface::into_surface):
    /// the renderer crate above this one is the intended (and only) caller,
    /// and no layer above *it* may re-export this accessor.
    #[doc(hidden)]
    pub fn instance(&self) -> &wgpu::Instance {
        &self.instance
    }

    /// The single logical device, panicking if no surface has created it yet.
    ///
    /// Only called from the renderer's install/resize/render paths, all of
    /// which run strictly after a `create_*_surface`, so the device is always
    /// present. Use [`Self::device`] for the fallible, creating form.
    ///
    /// Hidden from the rendered docs for the same reason as [`Self::instance`].
    #[doc(hidden)]
    pub fn device_handle(&self) -> &DeviceHandle {
        self.device
            .as_ref()
            .expect("device must be created before it is used (surface creation creates it)")
    }

    /// The logical device, creating it on first call and returning the same one
    /// afterwards.
    ///
    /// Adapter selection goes through
    /// `wgpu::util::initialize_adapter_from_env_or_default`, so
    /// `WGPU_ADAPTER_NAME`/`WGPU_POWER_PREF` pick the adapter on a host with
    /// more than one — the only way to pin a specific GPU on a multi-adapter
    /// machine.
    ///
    /// # Errors
    ///
    /// When no adapter is available at all, or when the device request the
    /// adapter's own limits were computed for is nonetheless refused. Both are
    /// terminal for GPU rendering; neither is retryable by calling again.
    pub async fn device(&mut self) -> Result<&DeviceHandle> {
        self.ensure_device_headless().await?;
        Ok(self
            .device
            .as_ref()
            .expect("device was just created or already present"))
    }

    /// What the live device's adapter reported, or `None` while the device is
    /// still uncreated — capabilities are an adapter's answer, and no adapter
    /// has been selected before the first device creation.
    pub fn caps(&self) -> Option<&TierCaps> {
        self.device.as_ref().map(|handle| &handle.caps)
    }

    /// Whether the live device was created with `wgpu::Features::PIPELINE_CACHE`.
    ///
    /// wgpu only implements the persisted pipeline cache on Vulkan — every
    /// Vulkan adapter advertises it (Android, Linux, Windows-on-Vulkan);
    /// Metal and DX12 adapters never do, so it is absent there and
    /// [`create_pipeline_cache`](Self::create_pipeline_cache) returns `None` —
    /// the renderer then behaves exactly as it did before this path existed.
    /// Panics if no surface (and thus no device) has been created yet.
    pub fn pipeline_cache_supported(&self) -> bool {
        self.device_handle()
            .device
            .features()
            .contains(wgpu::Features::PIPELINE_CACHE)
    }

    /// The adapter fingerprint a persisted pipeline-cache blob is tagged with
    /// (see [`crate::pipeline_cache`]). Panics if no device has been created yet.
    pub fn adapter_cache_key(&self) -> String {
        crate::pipeline_cache::adapter_cache_key(&self.device_handle().adapter.get_info())
    }

    /// Creates a `wgpu::PipelineCache` for the live device, seeded from a
    /// previously persisted, framed `blob` when it validates for this adapter.
    ///
    /// Returns `None` when the device lacks `PIPELINE_CACHE` support (Metal/
    /// desktop) — the renderer then runs its original, cache-less path. A `blob`
    /// that fails framing/adapter validation
    /// ([`crate::pipeline_cache::unframe`]) is discarded and the cache starts
    /// empty; a `None` `blob` is a cold start.
    ///
    /// Hidden from the rendered docs for the same reason as [`Self::instance`].
    ///
    /// # Safety
    ///
    /// One of this module's two sanctioned unsafe sites (the other is the
    /// Android hardware-buffer device open, `hwbuffer_device`), and the only
    /// one whose obligation is the caller's, not something this method can
    /// fully close on its own: `unframe`'s magic-tag-plus-adapter-fingerprint check proves
    /// only that `blob` was framed by `frust-gpu`'s own framing for *this*
    /// adapter — provenance by convention, not a proof of the actual wgpu
    /// contract on [`wgpu::Device::create_pipeline_cache`], which requires a
    /// non-`None` `data` to have come from a prior `PipelineCache::get_data()`
    /// on a `pipeline_cache_key`-compatible adapter. The caller must ensure
    /// `blob` is exactly that: a blob previously produced by this driver's own
    /// pipeline-cache output for this adapter, as persisted by `frust-render`'s
    /// caching layer (`SurfaceRenderer::pipeline_cache_data`/
    /// `set_initial_pipeline_cache_data`). A forged blob that nonetheless
    /// passes the framing/fingerprint check is undefined behaviour per wgpu's
    /// contract — `fallback: true` only covers a residual *internal* mismatch
    /// wgpu itself detects, not a blob that misleads it into misbehaving.
    #[doc(hidden)]
    pub unsafe fn create_pipeline_cache(&self, blob: Option<&[u8]>) -> Option<wgpu::PipelineCache> {
        if !self.pipeline_cache_supported() {
            return None;
        }
        let handle = self.device_handle();
        let key = crate::pipeline_cache::adapter_cache_key(&handle.adapter.get_info());
        let data = blob.and_then(|b| crate::pipeline_cache::unframe(b, &key));
        log::debug!(
            "frust-gpu: creating wgpu PipelineCache (seed: {})",
            if data.is_some() {
                "persisted blob"
            } else {
                "empty"
            }
        );
        // SAFETY: see this method's `# Safety` section — `data` has already been
        // validated against this adapter's fingerprint by `unframe`, and
        // `fallback: true` turns any residual internal mismatch into a
        // fall-back-to-empty cache rather than UB.
        let cache = unsafe {
            handle
                .device
                .create_pipeline_cache(&wgpu::PipelineCacheDescriptor {
                    label: Some("frust-gpu pipeline cache"),
                    data,
                    fallback: true,
                })
        };
        Some(cache)
    }

    /// Lazily create the logical device compatible with `surface`, requesting
    /// the adapter's own limits (never `Limits::default()`, which the iOS
    /// Simulator cannot satisfy) plus the #7057 alignment mitigation. Reuses
    /// an already-created device when it is compatible with `surface`, so
    /// surface loss/recreation (rotation, backgrounding) never rebuilds it — and
    /// so a device the [`ensure_device_headless`](Self::ensure_device_headless)
    /// pre-init created before any surface existed is adopted here rather than
    /// rebuilt.
    ///
    /// Hidden from the rendered docs for the same reason as [`Self::instance`]:
    /// the renderer above calls it to have a device in hand before it sizes its
    /// own per-surface attachments; nothing higher may.
    #[doc(hidden)]
    pub async fn ensure_device(&mut self, surface: &wgpu::Surface<'static>) -> Result<()> {
        if let Some(existing) = &self.device
            && existing.adapter.is_surface_supported(surface)
        {
            return Ok(());
        }
        self.device = Some(create_device(&self.instance, &self.options, Some(surface)).await?);
        Ok(())
    }

    /// Create the logical device **before any surface exists**, so the wgpu
    /// instance/adapter/device bring-up can run on a
    /// background thread kicked at native-library load (`JNI_OnLoad`) and be
    /// joined by `nativeInit` instead of running serially after `surfaceCreated`.
    /// Idempotent: a no-op when a device already exists.
    ///
    /// # Android singular-adapter assumption
    ///
    /// Requesting the adapter with `compatible_surface: None` picks wgpu's
    /// default adapter rather than one filtered to a specific surface. On Android
    /// the Vulkan backend exposes a single physical device, so the adapter chosen
    /// here is the same one a later surface-filtered request would pick, and
    /// [`ensure_device`](Self::ensure_device)'s `is_surface_supported` reuse check
    /// accepts it — the surface created at `nativeInit` reuses this device with no
    /// rebuild. On a hypothetical multi-adapter device where the pre-init adapter
    /// did *not* support the eventual surface, `ensure_device` simply rebuilds the
    /// device against that surface (still correct, just without the overlap win).
    /// This is the sole production caller that passes `None` below; desktop/iOS
    /// create their device through the surface path and never invoke it.
    pub async fn ensure_device_headless(&mut self) -> Result<()> {
        if self.device.is_some() {
            return Ok(());
        }
        self.device = Some(create_device(&self.instance, &self.options, None).await?);
        Ok(())
    }

    /// Builds a configured [`ConfiguredSurface`] from a raw wgpu `Surface`,
    /// creating the logical device if needed.
    ///
    /// The result is renderer-agnostic: the swapchain, the configuration it was
    /// brought up with, and the resolved alpha facts. Whatever per-frame render
    /// path a renderer pairs with it is that renderer's own business — see
    /// `frust_render::context`'s `EngineSurface`.
    ///
    /// Hidden from the rendered docs for the same reason as [`Self::instance`].
    #[doc(hidden)]
    pub async fn create_render_surface(
        &mut self,
        surface: wgpu::Surface<'static>,
        width: u32,
        height: u32,
        present_mode: wgpu::PresentMode,
        alpha: SurfaceAlphaRequest,
    ) -> Result<ConfiguredSurface> {
        self.ensure_device(&surface).await?;
        let handle = self.device_handle();

        let capabilities = surface.get_capabilities(&handle.adapter);
        // Resolved from the request and the surface's reported caps alone; the
        // renderer above reads it back off the returned configuration to pick
        // its own per-frame path.
        let alpha_mode = resolve_alpha_mode(alpha, &capabilities);
        // Whichever supported format the surface reports FIRST — the surface's
        // own preference order, not this module's (see `select_surface_format`).
        let format = select_surface_format(&capabilities)?;

        Ok(ConfiguredSurface::configure(
            surface,
            &handle.device,
            format,
            alpha_mode,
            (width, height),
            present_mode,
        ))
    }
}

/// Selects an adapter, probes it, and requests the logical device — the body
/// both [`RenderContext::ensure_device`] and
/// [`RenderContext::ensure_device_headless`] share.
///
/// `compatible_surface` filters adapter selection to one that can present to the
/// given surface; `None` (the pre-init path, and every headless caller) selects
/// wgpu's default adapter — see the singular-adapter note on
/// `ensure_device_headless`. The capability probe, limits mitigation, feature
/// request and uncaptured-error handler are identical either way: the surface
/// only ever affected adapter selection, never the device it yields.
///
/// A free function rather than a method so it borrows the instance and options
/// separately from the `device` field the callers assign into.
async fn create_device(
    instance: &wgpu::Instance,
    options: &ContextOptions,
    compatible_surface: Option<&wgpu::Surface<'static>>,
) -> Result<DeviceHandle> {
    let adapter = wgpu::util::initialize_adapter_from_env_or_default(instance, compatible_surface)
        .await
        .map_err(|e| anyhow!("frust-gpu: no compatible GPU adapter: {e}"))?;

    let caps = TierCaps::probe(&adapter);

    // The device request is built from the resolved downlevel profile, not
    // unconditionally from the adapter's raw limits — see `base_device_limits`
    // for the shared derivation, and `effective_limits` for the iOS Simulator
    // alignment mitigation layered on top of it.
    let base_limits = base_device_limits(caps.downlevel_profile, adapter.limits());
    let required_limits = effective_limits(base_limits, is_ios_simulator());
    let required_features =
        device_features(adapter.features(), &caps, cfg!(feature = "perf-trace"));

    let descriptor = wgpu::DeviceDescriptor {
        label: Some(&options.device_label),
        required_features,
        required_limits,
        ..Default::default()
    };
    let (device, queue, hwbuffer_import) = open_device(&adapter, &caps, &descriptor).await?;
    let caps = TierCaps {
        hwbuffer_import,
        ..caps
    };

    // Route wgpu's uncaptured errors to the log and a latch instead of its
    // default handler, which aborts the process by panicking ("handling wgpu
    // errors as fatal by default"). A UI framework must survive a driver's
    // *transient* GPU error and recover on a later frame rather than crash —
    // e.g. the Android emulator's SwiftShader path can raise a one-off
    // swapchain-acquire validation error under load, which used to wedge the
    // app into a per-frame panic loop (the surface stayed ready and every
    // subsequent render re-hit the fatal handler). Pairing this with the
    // `Invalid`-acquire → reconfigure recovery (see [`crate::lifecycle`]) lets
    // the swapchain rebuild and rendering resume. Across a mobile FFI boundary
    // the default handler's abort means killing the host app outright. Genuine
    // API misuse is still surfaced — loudly, at error level — just without
    // killing the process.
    //
    // Two pieces of state, both per-device (captured fresh each time this
    // closure is installed, i.e. once per logical device) and both behind `Arc`
    // because `on_uncaptured_error`'s handler must be `Fn`, not `FnMut`:
    //
    // - `error_count` drives the log latch ([`decide_log_action`]), so a device
    //   wedged in a genuine per-frame error storm (as opposed to a one-off
    //   driver hiccup) cannot flood the log forever.
    // - `first_error` latches the first error's text for the frame loop to
    //   poll via [`DeviceHandle::first_uncaptured_error`]. `OnceLock` gives
    //   exactly first-write-wins with no lock held across the handler body.
    let error_count = Arc::new(AtomicU32::new(0));
    let first_error: Arc<OnceLock<String>> = Arc::new(OnceLock::new());
    let latch = Arc::clone(&first_error);
    device.on_uncaptured_error(Arc::new(move |error| {
        let count = error_count.fetch_add(1, Ordering::Relaxed) + 1;
        let _ = latch.set(error.to_string());
        match decide_log_action(count) {
            LogAction::Log => {
                log::error!("frust-gpu: uncaptured wgpu error: {error}");
            }
            LogAction::SuppressionNotice => {
                log::error!(
                    "frust-gpu: further uncaptured wgpu errors suppressed \
                     (total so far: {count})"
                );
            }
            LogAction::Silent { debug_bump } => {
                if debug_bump {
                    log::debug!(
                        "frust-gpu: uncaptured wgpu error count now {count} \
                         (still suppressed)"
                    );
                }
            }
        }
    }));

    Ok(DeviceHandle {
        adapter,
        device,
        queue,
        caps,
        first_uncaptured_error: first_error,
    })
}

/// Opens the logical device `descriptor` describes on `adapter`, answering
/// whether it can import Android hardware buffers.
///
/// On Android, a Vulkan adapter with the hardware-buffer knob on
/// (`hwbuffer_import_requested`) is first offered to `hwbuffer_device::open`;
/// a refusal there (a missing extension, a failed `vkCreateDevice`) is logged
/// and falls through to the plain `request_device` every other case takes, so
/// the knob can never turn a working adapter into no device at all.
#[cfg_attr(not(target_os = "android"), allow(unused_variables))]
async fn open_device(
    adapter: &wgpu::Adapter,
    caps: &TierCaps,
    descriptor: &wgpu::DeviceDescriptor<'_>,
) -> Result<(wgpu::Device, wgpu::Queue, bool)> {
    #[cfg(target_os = "android")]
    if caps.backend == wgpu::Backend::Vulkan && hwbuffer_import_requested() {
        match hwbuffer_device::open(adapter, descriptor) {
            Ok((device, queue)) => {
                log::info!(
                    "frust-gpu: Vulkan device opened by frust-gpu with the AHardwareBuffer \
                     import extensions"
                );
                return Ok((device, queue, true));
            }
            Err(reason) => log::warn!(
                "frust-gpu: AHardwareBuffer import unavailable ({reason}); opening the device \
                 through wgpu, native frames stay on the CPU path"
            ),
        }
    }
    let (device, queue) = adapter
        .request_device(descriptor)
        .await
        .map_err(|e| anyhow!("frust-gpu: failed to create GPU device: {e}"))?;
    Ok((device, queue, false))
}

/// `VK_ANDROID_external_memory_android_hardware_buffer`: import of an
/// `AHardwareBuffer` as `VkDeviceMemory`.
const EXT_ANDROID_HARDWARE_BUFFER: &CStr = c"VK_ANDROID_external_memory_android_hardware_buffer";
/// `VK_EXT_queue_family_foreign`: the ownership transfer that makes a buffer a
/// foreign producer wrote visible to this device.
const EXT_QUEUE_FAMILY_FOREIGN: &CStr = c"VK_EXT_queue_family_foreign";
/// `VK_KHR_external_memory`, core since Vulkan 1.1.
const EXT_EXTERNAL_MEMORY: &CStr = c"VK_KHR_external_memory";
/// `VK_KHR_dedicated_allocation`, core since Vulkan 1.1.
const EXT_DEDICATED_ALLOCATION: &CStr = c"VK_KHR_dedicated_allocation";
/// `VK_KHR_sampler_ycbcr_conversion`, core since Vulkan 1.1 (an NV12 buffer's
/// sampler, not needed for the RGBA8 buffers imported today).
const EXT_SAMPLER_YCBCR_CONVERSION: &CStr = c"VK_KHR_sampler_ycbcr_conversion";

/// `VK_MAKE_API_VERSION(0, 1, 1, 0)`.
const VULKAN_1_1: u32 = (1 << 22) | (1 << 12);

/// Given the effective Vulkan API version (the lower of the instance's and the
/// physical device's) and which device extensions the physical device reports,
/// the extensions a hardware-buffer import device adds to the ones `wgpu`
/// itself enables — or why such a device cannot be opened.
///
/// The import extension's own dependencies are "Vulkan 1.1 and
/// `VK_EXT_queue_family_foreign`" (or the four pre-1.1 KHR extensions, which
/// this refuses rather than juggle): so a 1.0 device, or one without either of
/// the two required names, is refused. The three KHR extensions 1.1 promoted
/// (external memory, dedicated allocation, sampler Y'CbCr conversion) are core
/// there and are only *named* when the device also lists them — enabling a
/// name the device does not list would fail `vkCreateDevice`.
///
/// Pure, over plain values: unit-testable on any host, like
/// [`effective_limits`].
#[cfg_attr(not(target_os = "android"), allow(dead_code))]
fn hwbuffer_import_extensions(
    api_version: u32,
    supports: impl Fn(&CStr) -> bool,
) -> std::result::Result<Vec<&'static CStr>, String> {
    if api_version < VULKAN_1_1 {
        return Err(format!(
            "the device reports Vulkan {}.{}, and the import needs 1.1",
            api_version >> 22,
            (api_version >> 12) & 0x3ff
        ));
    }
    let required = [EXT_ANDROID_HARDWARE_BUFFER, EXT_QUEUE_FAMILY_FOREIGN];
    let missing: Vec<_> = required.iter().filter(|name| !supports(name)).collect();
    if !missing.is_empty() {
        return Err(format!("the device lacks {missing:?}"));
    }
    let promoted = [
        EXT_EXTERNAL_MEMORY,
        EXT_DEDICATED_ALLOCATION,
        EXT_SAMPLER_YCBCR_CONVERSION,
    ];
    Ok(required
        .into_iter()
        .chain(promoted.into_iter().filter(|name| supports(name)))
        .collect())
}

/// Whether the hardware-buffer knob is on, given its three halves: the
/// compile-time and runtime `FRUST_ANDROID_HWBUFFER_IMPORT` environment
/// variable, and the `debug.frust.hwbuffer_import` system property (the one
/// an installed APK can be switched by: `adb shell setprop
/// debug.frust.hwbuffer_import 1`). Any value but `0` (or an empty property,
/// which is how an unset one can read back) turns it on.
#[cfg_attr(not(target_os = "android"), allow(dead_code))]
fn hwbuffer_import_knob(
    compile_time: Option<&str>,
    runtime: Option<String>,
    property: Option<String>,
) -> bool {
    env_flag_enabled(compile_time, runtime)
        || matches!(property.as_deref(), Some(v) if !v.is_empty() && v != "0")
}

/// [`hwbuffer_import_knob`] over this process's actual environment. Read at
/// every device creation rather than cached: it is consulted once per device.
#[cfg(target_os = "android")]
fn hwbuffer_import_requested() -> bool {
    hwbuffer_import_knob(
        option_env!("FRUST_ANDROID_HWBUFFER_IMPORT"),
        std::env::var("FRUST_ANDROID_HWBUFFER_IMPORT").ok(),
        android_system_properties::AndroidSystemProperties::new()
            .get("debug.frust.hwbuffer_import"),
    )
}

/// The hand-opened Vulkan device: the sanctioned unsafe zone behind
/// [`TierCaps::hwbuffer_import`].
///
/// # Invariants
///
/// - The device is opened from `adapter`'s own hal adapter with the very
///   features, limits and memory hints of the `wgpu::DeviceDescriptor` it is
///   then wrapped with (`create_device_from_hal`), and those were derived from
///   that adapter's own reports (`device_features`, `base_device_limits`) — so
///   the descriptor's features are a subset of the hal device's, as the wrap
///   requires.
/// - The open callback only *adds* extensions, and only ones
///   [`hwbuffer_import_extensions`] confirmed the physical device lists; it
///   never touches features, queues or the `pNext` chain, so it changes nothing
///   the device does not support (`open_with_callback`'s contract).
/// - The hal adapter guard is dropped before the wrap, and nothing here keeps a
///   raw handle past this function: `wgpu` owns the raw device from then on and
///   destroys it with the `wgpu::Device`.
#[cfg(target_os = "android")]
mod hwbuffer_device {
    use wgpu::hal::api::Vulkan;
    use wgpu::hal::vulkan::{CreateDeviceCallback, CreateDeviceCallbackArgs};

    /// Opens `descriptor` on `adapter` with the hardware-buffer import
    /// extensions enabled, or answers why it could not.
    pub(super) fn open(
        adapter: &wgpu::Adapter,
        descriptor: &wgpu::DeviceDescriptor<'_>,
    ) -> Result<(wgpu::Device, wgpu::Queue), String> {
        let open_device = {
            // SAFETY: the guard only borrows the adapter's hal object for this
            // block; nothing here destroys it (see the module invariants).
            let hal_adapter = unsafe { adapter.as_hal::<Vulkan>() }
                .ok_or_else(|| "the adapter is not a Vulkan adapter".to_string())?;
            let capabilities = hal_adapter.physical_device_capabilities();
            let api_version = capabilities
                .properties()
                .api_version
                .min(hal_adapter.shared_instance().instance_api_version());
            let extra = super::hwbuffer_import_extensions(api_version, |name| {
                capabilities.supports_extension(name)
            })?;
            let callback: Box<CreateDeviceCallback<'_>> =
                Box::new(move |args: CreateDeviceCallbackArgs<'_, '_, '_>| {
                    for name in extra {
                        if !args.extensions.contains(&name) {
                            args.extensions.push(name);
                        }
                    }
                });
            // SAFETY: features and limits are the adapter's own (the module
            // invariants), and the callback only adds extensions the physical
            // device lists.
            unsafe {
                hal_adapter.open_with_callback(
                    descriptor.required_features,
                    &descriptor.required_limits,
                    &descriptor.memory_hints,
                    Some(callback),
                )
            }
            .map_err(|e| format!("vkCreateDevice with the import extensions failed: {e}"))?
        };
        // SAFETY: `open_device` was opened from this adapter's hal adapter with
        // exactly `descriptor.required_features`, so they are a subset of the
        // hal device's features.
        unsafe { adapter.create_device_from_hal::<Vulkan>(open_device, descriptor) }
            .map_err(|e| format!("wrapping the hand-opened device failed: {e}"))
    }
}

/// Given the resolved downlevel profile and the adapter's own reported
/// limits, the `wgpu::Limits` a device request should ask for — the pure half
/// of the derivation this module's `create_device` uses, extracted so both it
/// and [`test_device_limits`] share exactly one implementation rather than two
/// that could drift apart.
///
/// Under `DownlevelProfile::WebGl2` (a real `Gl` backend, or
/// `FRUST_ENGINE_DOWNLEVEL=1` rehearsing it) this asks for the GLES-3.0/WebGL2
/// downlevel default shape — or the override would only relabel a full
/// desktop device rather than actually exercising it — with
/// `using_resolution` folding in `adapter_limits`' own texture-dimension
/// limits so the request never asks for a resolution the adapter cannot
/// satisfy (the swapchain may need more than the downlevel default allows)
/// while every other WebGL2 default limit is requested as-is. Under
/// `DownlevelProfile::Full` — every shipping device — `adapter_limits` is
/// returned unchanged: feeding the *adapter's* limits (rather than
/// `Limits::default()`) is what keeps the request from over-asking and
/// failing on a constrained mobile adapter — or on the iOS Simulator, whose
/// macOS-Metal-backed device refuses `Limits::default()` outright.
///
/// Pure decision logic over plain values, mirroring [`effective_limits`]'s
/// split of pure decision vs. platform lookup: `adapter_limits` is already
/// `wgpu::Adapter::limits()`'s output by the time this runs, so the function
/// itself needs no adapter and is unit-testable on any host with no GPU.
fn base_device_limits(profile: DownlevelProfile, adapter_limits: wgpu::Limits) -> wgpu::Limits {
    if profile == DownlevelProfile::WebGl2 {
        wgpu::Limits::downlevel_webgl2_defaults().using_resolution(adapter_limits)
    } else {
        adapter_limits
    }
}

/// The `wgpu::Limits` a test fixture's own `request_device` call should ask
/// for, given `adapter` and its already-probed `caps` — exactly the
/// derivation [`create_device`] uses for the production device request
/// (shared via [`base_device_limits`] plus [`effective_limits`]), so a
/// fixture requesting these limits can never over-ask relative to what the
/// production path would request for the very same adapter.
///
/// This is the fix for the iOS Simulator's constrained Apple2 Metal profile
/// (15 inter-stage shader variables, where `wgpu::Limits::default()` demands
/// 16): a fixture that hard-codes `Limits::default()` panics with
/// `LimitsExceeded` there even though the production path — which always
/// requests the adapter's own limits — never would. Every fixture already
/// probes `TierCaps::probe(&adapter)` before requesting its device, so `caps`
/// is available at the same call site this replaces.
///
/// Public (not test-only/`#[cfg(test)]`) because the fixtures that need it
/// live in other crates' `tests/` integration binaries and
/// `frust-testing`'s own `EngineOracle`, none of which can reach a
/// `#[cfg(test)]` item in this crate.
pub fn test_device_limits(adapter: &wgpu::Adapter, caps: &TierCaps) -> wgpu::Limits {
    let base_limits = base_device_limits(caps.downlevel_profile, adapter.limits());
    effective_limits(base_limits, is_ios_simulator())
}

/// Given the build-config-derived instance flags and whether the process is
/// currently running on an Android emulator, decides the flags wgpu's
/// `Instance` should actually be created with.
///
/// The `DEBUG` flag makes wgpu enable `VK_EXT_debug_utils` and set object-name
/// labels via `vkSetDebugUtilsObjectNameEXT`, and the emulator's gfxstream
/// Vulkan HAL (`vulkan.ranchu.so`) segfaults inside that entry point during
/// adapter enumeration (observed crash: `#00 vulkan.ranchu.so
/// vk_common_SetDebugUtilsObjectNameEXT`) — the same class of debug-utils
/// fragility a MoltenVK Vulkan backend is also known to have. Debug object
/// labels are only a developer convenience, so dropping them on the emulator
/// keeps GPU bring-up alive there while leaving physical devices' validation
/// safety net — and desktop behaviour — untouched.
///
/// Pure decision logic, kept separate from the platform property lookup in
/// `is_android_emulator` so it is unit-testable on any host without an Android
/// target.
#[cfg_attr(not(target_os = "android"), allow(dead_code))]
fn effective_instance_flags(flags: wgpu::InstanceFlags, is_emulator: bool) -> wgpu::InstanceFlags {
    if is_emulator {
        flags - (wgpu::InstanceFlags::DEBUG | wgpu::InstanceFlags::VALIDATION)
    } else {
        flags
    }
}

/// Detects whether the current process is running on an Android emulator
/// (goldfish/ranchu), as opposed to a physical device, via the standard
/// `ro.kernel.qemu` system property (`"1"` on emulators, unset/absent on real
/// hardware). A failed property read is treated as "not an emulator" so
/// physical devices — and any environment where the property cannot be read —
/// default to keeping validation on.
#[cfg(target_os = "android")]
fn is_android_emulator() -> bool {
    android_system_properties::AndroidSystemProperties::new()
        .get("ro.kernel.qemu")
        .as_deref()
        == Some("1")
}

/// The uniform-buffer offset alignment the iOS Simulator's Metal validation
/// actually enforces, regardless of what the adapter reports.
const IOS_SIMULATOR_MIN_UNIFORM_BUFFER_OFFSET_ALIGNMENT: u32 = 256;

/// Given a base `wgpu::Limits` and whether the process is currently running on
/// an iOS Simulator, decides the `Limits` a device request should actually use.
///
/// Mitigates [wgpu #7057](https://github.com/gfx-rs/wgpu/issues/7057): the iOS
/// Simulator is macOS-Metal-backed and requires 256-byte
/// `min_uniform_buffer_offset_alignment`, but wgpu's Metal backend reports the
/// (lower) iOS-device value, which trips Metal API validation on the simulator.
/// Physical iOS devices are unaffected and pass `base` through unchanged; a
/// `base` whose alignment is already at or above 256 is left alone, never
/// lowered.
///
/// Upstream [gfx-rs/wgpu PR #10189](https://github.com/gfx-rs/wgpu/pull/10189)
/// makes this unnecessary — drop it once a pinned wgpu release contains it.
///
/// Pure decision logic, mirroring `effective_instance_flags`'s split of pure
/// decision vs. platform lookup. It is fed the profile-resolved base limits
/// (see this module's `create_device`) — the adapter's own limits under
/// `DownlevelProfile::Full`, the WebGL2 downlevel defaults resolution-folded
/// with the adapter otherwise — so the device request never over-asks.
pub fn effective_limits(base: wgpu::Limits, is_ios_simulator: bool) -> wgpu::Limits {
    if is_ios_simulator
        && base.min_uniform_buffer_offset_alignment
            < IOS_SIMULATOR_MIN_UNIFORM_BUFFER_OFFSET_ALIGNMENT
    {
        wgpu::Limits {
            min_uniform_buffer_offset_alignment: IOS_SIMULATOR_MIN_UNIFORM_BUFFER_OFFSET_ALIGNMENT,
            ..base
        }
    } else {
        base
    }
}

/// Whether this binary is running on the iOS Simulator
/// (`aarch64-apple-ios-sim` / `x86_64-apple-ios` under the simulator), which
/// sets `target_abi = "sim"`. Compile-time constant: the simulator mitigation
/// only needs to apply to simulator builds, never physical-device or desktop
/// ones.
pub const fn is_ios_simulator() -> bool {
    cfg!(all(target_os = "ios", target_abi = "sim"))
}

/// The `wgpu::Features` a device request opportunistically asks for when the
/// adapter exposes them.
///
/// `PIPELINE_CACHE` alone: it is what
/// [`create_pipeline_cache`](RenderContext::create_pipeline_cache) needs to
/// seed the renderer's shader-pipeline compilation from a persisted blob. An
/// optional feature is only ever *added* when the adapter already offers it,
/// so this can never turn a working adapter into a failed device request.
pub fn optional_device_features() -> wgpu::Features {
    wgpu::Features::PIPELINE_CACHE
}

/// The `wgpu::Features` a device request must genuinely *require*, given what
/// the adapter reported ([`TierCaps`]) and whether this build compiled the
/// `perf-trace` feature in.
///
/// The policy is deliberately minimal: **empty** by default. A required feature
/// is a hard device-creation failure on any adapter lacking it, so asking for
/// something the crate does not actually need converts a working device into no
/// device at all. `TIMESTAMP_QUERY` is the single exception — it is what the
/// GPU timing probes ([`crate::diag::TimestampRing`]) are built on, so a
/// `perf-trace` build asks for it, and even then only when the adapter offers
/// it. A device that did not get the feature leaves the ring inert (`gpu_q=0`),
/// exactly as a build without `perf-trace` does.
///
/// A plain `bool` parameter rather than reading `cfg!` internally, so both
/// branches are unit-testable regardless of which features this crate was
/// compiled with.
fn required_features(caps: &TierCaps, perf_trace: bool) -> wgpu::Features {
    if perf_trace && caps.has_timestamp_query {
        wgpu::Features::TIMESTAMP_QUERY
    } else {
        wgpu::Features::empty()
    }
}

/// The complete `required_features` set a device request is made with: the
/// opportunistic set ([`optional_device_features`]) narrowed to what
/// `adapter_features` actually offers, plus the genuinely required set
/// ([`required_features`]).
///
/// Both halves are adapter-conditioned, so this can never turn a working
/// adapter into a failed device request — which is why the policy is split out
/// of [`create_device`] as a pure function over plain values.
fn device_features(
    adapter_features: wgpu::Features,
    caps: &TierCaps,
    perf_trace: bool,
) -> wgpu::Features {
    (adapter_features & optional_device_features()) | required_features(caps, perf_trace)
}

/// Number of uncaptured `wgpu` errors logged at error level per device before
/// the handler latches into suppression. A single flaky frame under a driver
/// hiccup (e.g. the Android emulator's SwiftShader path) is expected to surface
/// a handful of errors; past this the process is either wedged in a genuine
/// per-frame error storm or the driver is fundamentally broken, and re-logging
/// every single one would flood the log without adding information.
const MAX_LOGGED_UNCAPTURED_ERRORS: u32 = 5;

/// How often (in error count) a latched handler bumps a debug-level "still
/// happening" line once past [`MAX_LOGGED_UNCAPTURED_ERRORS`] and the one
/// suppression notice. Debug level (not error) because this is diagnostic noise
/// for someone actively investigating, not an actionable signal.
const UNCAPTURED_ERROR_DEBUG_BUMP_PERIOD: u32 = 100;

/// What the uncaptured-error handler should do for the `count`-th uncaptured
/// error (1-indexed) it has observed on a given device.
///
/// Also the latch the renderer above reuses for its own per-frame event that
/// can reproduce every vsync (an engine frame refusal), so the two report at
/// the same cadence.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum LogAction {
    /// One of the first `MAX_LOGGED_UNCAPTURED_ERRORS`: log the error itself
    /// at error level.
    Log,
    /// The first error past the cap: log one suppression notice (naming the
    /// running total) instead of the error itself.
    SuppressionNotice,
    /// Past the cap and past the suppression notice: stay silent, except a
    /// periodic debug-level count bump when `debug_bump` is set.
    Silent { debug_bump: bool },
}

/// Pure latch policy for the uncaptured-error handler (see [`LogAction`]).
///
/// Split out of the handler closure in this module's `create_device` so the
/// discipline — log the first few, announce the latch once, then go quiet
/// except an occasional debug bump — is unit-testable without a GPU or a real
/// `wgpu::Error`.
pub fn decide_log_action(count: u32) -> LogAction {
    if count <= MAX_LOGGED_UNCAPTURED_ERRORS {
        LogAction::Log
    } else if count == MAX_LOGGED_UNCAPTURED_ERRORS + 1 {
        LogAction::SuppressionNotice
    } else {
        LogAction::Silent {
            debug_bump: count.is_multiple_of(UNCAPTURED_ERROR_DEBUG_BUMP_PERIOD),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::caps::DownlevelProfile;

    #[test]
    fn emulator_strips_debug_and_validation() {
        let build_flags = wgpu::InstanceFlags::DEBUG | wgpu::InstanceFlags::VALIDATION;
        let flags = effective_instance_flags(build_flags, true);
        assert!(!flags.contains(wgpu::InstanceFlags::DEBUG));
        assert!(!flags.contains(wgpu::InstanceFlags::VALIDATION));
    }

    #[test]
    fn physical_device_keeps_debug_and_validation() {
        let build_flags = wgpu::InstanceFlags::DEBUG | wgpu::InstanceFlags::VALIDATION;
        let flags = effective_instance_flags(build_flags, false);
        assert!(flags.contains(wgpu::InstanceFlags::DEBUG));
        assert!(flags.contains(wgpu::InstanceFlags::VALIDATION));
    }

    #[test]
    fn emulator_with_no_debug_flags_stays_empty() {
        let flags = effective_instance_flags(wgpu::InstanceFlags::empty(), true);
        assert!(flags.is_empty());
    }

    #[test]
    fn ios_simulator_bumps_alignment_to_256() {
        let base = wgpu::Limits::default();
        let limits = effective_limits(base.clone(), true);
        assert_eq!(limits.min_uniform_buffer_offset_alignment, 256);
        // Nothing else about the base limits should change.
        assert_eq!(
            wgpu::Limits {
                min_uniform_buffer_offset_alignment: base.min_uniform_buffer_offset_alignment,
                ..limits.clone()
            },
            base
        );
    }

    #[test]
    fn non_simulator_leaves_limits_untouched() {
        let base = wgpu::Limits::default();
        let limits = effective_limits(base.clone(), false);
        assert_eq!(limits, base);
    }

    #[test]
    fn base_already_at_or_above_256_is_not_lowered() {
        let base = wgpu::Limits {
            min_uniform_buffer_offset_alignment: 512,
            ..wgpu::Limits::default()
        };
        let limits = effective_limits(base.clone(), true);
        assert_eq!(limits.min_uniform_buffer_offset_alignment, 512);
        assert_eq!(limits, base);
    }

    #[test]
    fn simulator_alignment_uses_real_adapter_limits_not_defaults() {
        // A low-alignment adapter (the #7057 shape: Metal reports a lower
        // alignment than the simulator driver actually enforces) is bumped to
        // 256 while every other adapter-reported limit is preserved — the
        // whole point of feeding *adapter* limits rather than `Limits::default`.
        let adapter = wgpu::Limits {
            min_uniform_buffer_offset_alignment: 64,
            max_texture_dimension_2d: 4096,
            ..wgpu::Limits::default()
        };
        let limits = effective_limits(adapter.clone(), true);
        assert_eq!(limits.min_uniform_buffer_offset_alignment, 256);
        assert_eq!(limits.max_texture_dimension_2d, 4096);
    }

    #[test]
    fn first_n_uncaptured_errors_log() {
        for count in 1..=MAX_LOGGED_UNCAPTURED_ERRORS {
            assert_eq!(
                decide_log_action(count),
                LogAction::Log,
                "expected Log at count={count}"
            );
        }
    }

    #[test]
    fn nplus1_uncaptured_error_suppresses() {
        assert_eq!(
            decide_log_action(MAX_LOGGED_UNCAPTURED_ERRORS + 1),
            LogAction::SuppressionNotice
        );
    }

    #[test]
    fn further_uncaptured_errors_stay_silent_between_debug_bumps() {
        let past_notice = MAX_LOGGED_UNCAPTURED_ERRORS + 2;
        assert_eq!(
            decide_log_action(past_notice),
            LogAction::Silent { debug_bump: false }
        );
    }

    #[test]
    fn uncaptured_error_debug_bump_is_periodic() {
        assert_eq!(
            decide_log_action(UNCAPTURED_ERROR_DEBUG_BUMP_PERIOD),
            LogAction::Silent { debug_bump: true }
        );
        assert_eq!(
            decide_log_action(UNCAPTURED_ERROR_DEBUG_BUMP_PERIOD * 2),
            LogAction::Silent { debug_bump: true }
        );
        assert_eq!(
            decide_log_action(UNCAPTURED_ERROR_DEBUG_BUMP_PERIOD + 1),
            LogAction::Silent { debug_bump: false }
        );
    }

    #[test]
    fn default_build_requires_no_device_features() {
        let caps = TierCaps::fake(DownlevelProfile::Full);
        assert!(caps.has_timestamp_query, "fixture precondition");
        assert_eq!(required_features(&caps, false), wgpu::Features::empty());
    }

    #[test]
    fn perf_trace_build_requires_timestamp_query_when_offered() {
        let caps = TierCaps::fake(DownlevelProfile::Full);
        assert_eq!(
            required_features(&caps, true),
            wgpu::Features::TIMESTAMP_QUERY
        );
    }

    #[test]
    fn perf_trace_build_requires_nothing_when_adapter_lacks_timestamp_query() {
        // An adapter that cannot do timestamp queries must still yield a
        // device: a required feature it lacks would fail the request outright,
        // so `perf-trace` degrades to no probes rather than to no GPU.
        let caps = TierCaps::fake(DownlevelProfile::WebGl2);
        assert!(!caps.has_timestamp_query, "fixture precondition");
        assert_eq!(required_features(&caps, true), wgpu::Features::empty());
    }

    #[test]
    fn pipeline_cache_is_requested_whenever_the_adapter_offers_it() {
        // The shipped Android/Vulkan warm-start path: `PIPELINE_CACHE` is
        // opportunistically added, which is what makes
        // `RenderContext::pipeline_cache_supported` true there and the
        // persisted-blob seed possible at all. Dropping it would silently kill
        // the warm start on every Vulkan adapter.
        let caps = TierCaps::fake(DownlevelProfile::Full);
        let adapter = wgpu::Features::PIPELINE_CACHE | wgpu::Features::DEPTH_CLIP_CONTROL;
        assert_eq!(
            device_features(adapter, &caps, false),
            wgpu::Features::PIPELINE_CACHE,
            "an offered optional feature is taken, and nothing else is"
        );
    }

    #[test]
    fn an_adapter_without_pipeline_cache_is_never_asked_for_it() {
        // Metal/DX12: the feature is absent, so the request must not name it —
        // a required feature the adapter lacks is a hard device-creation
        // failure, i.e. no GPU at all rather than merely no persisted cache.
        let caps = TierCaps::fake(DownlevelProfile::Full);
        assert_eq!(
            device_features(wgpu::Features::empty(), &caps, false),
            wgpu::Features::empty()
        );
    }

    #[test]
    fn a_perf_trace_build_asks_for_both_halves_when_both_are_offered() {
        let caps = TierCaps::fake(DownlevelProfile::Full);
        assert!(caps.has_timestamp_query, "fixture precondition");
        assert_eq!(
            device_features(wgpu::Features::PIPELINE_CACHE, &caps, true),
            wgpu::Features::PIPELINE_CACHE | wgpu::Features::TIMESTAMP_QUERY
        );
    }

    #[test]
    fn base_device_limits_full_profile_passes_adapter_limits_through_unclamped() {
        // The iOS Simulator shape: an adapter reporting fewer inter-stage
        // shader variables than `wgpu::Limits::default()` demands (15 vs 16).
        // Under `Full`, `base_device_limits` must request no more than what
        // the adapter itself reported, never `Limits::default()`.
        let adapter_limits = wgpu::Limits {
            max_inter_stage_shader_variables: 15,
            ..wgpu::Limits::default()
        };
        let limits = base_device_limits(DownlevelProfile::Full, adapter_limits.clone());
        assert!(limits.max_inter_stage_shader_variables <= 15);
        assert_eq!(limits, adapter_limits);
    }

    #[test]
    fn base_device_limits_webgl2_profile_never_exceeds_the_constrained_adapter() {
        // The WebGL2 downlevel-default shape already asks for 15 inter-stage
        // shader variables (lower than `Limits::default()`'s 16), so folding
        // in a constrained adapter's own limits must still land at or below
        // what that adapter reports.
        let adapter_limits = wgpu::Limits {
            max_inter_stage_shader_variables: 15,
            ..wgpu::Limits::default()
        };
        let limits = base_device_limits(DownlevelProfile::WebGl2, adapter_limits);
        assert!(limits.max_inter_stage_shader_variables <= 15);
    }

    /// A `supports` predicate over a fixed list of extension names.
    fn listing(names: &'static [&'static CStr]) -> impl Fn(&CStr) -> bool {
        move |name| names.contains(&name)
    }

    #[test]
    fn a_vulkan_1_1_device_with_both_required_extensions_gets_them() {
        let extensions = hwbuffer_import_extensions(
            VULKAN_1_1,
            listing(&[EXT_ANDROID_HARDWARE_BUFFER, EXT_QUEUE_FAMILY_FOREIGN]),
        )
        .expect("both required extensions are listed");
        assert_eq!(
            extensions,
            [EXT_ANDROID_HARDWARE_BUFFER, EXT_QUEUE_FAMILY_FOREIGN],
            "the promoted names are not enabled when the device does not list them"
        );
    }

    #[test]
    fn listed_promoted_extensions_are_named_too() {
        let extensions = hwbuffer_import_extensions(
            VULKAN_1_1 + 5,
            listing(&[
                EXT_ANDROID_HARDWARE_BUFFER,
                EXT_QUEUE_FAMILY_FOREIGN,
                EXT_EXTERNAL_MEMORY,
                EXT_DEDICATED_ALLOCATION,
                EXT_SAMPLER_YCBCR_CONVERSION,
            ]),
        )
        .expect("every extension is listed");
        assert_eq!(extensions.len(), 5);
    }

    #[test]
    fn a_device_without_the_import_extension_is_refused() {
        let refusal = hwbuffer_import_extensions(VULKAN_1_1, listing(&[EXT_QUEUE_FAMILY_FOREIGN]))
            .expect_err("the import extension is missing");
        assert!(refusal.contains("VK_ANDROID_external_memory_android_hardware_buffer"));
    }

    #[test]
    fn a_device_without_the_foreign_queue_family_is_refused() {
        let refusal =
            hwbuffer_import_extensions(VULKAN_1_1, listing(&[EXT_ANDROID_HARDWARE_BUFFER]))
                .expect_err("the foreign queue family extension is missing");
        assert!(refusal.contains("VK_EXT_queue_family_foreign"));
    }

    #[test]
    fn a_vulkan_1_0_device_is_refused_even_with_every_extension() {
        let refusal = hwbuffer_import_extensions(
            1 << 22,
            listing(&[EXT_ANDROID_HARDWARE_BUFFER, EXT_QUEUE_FAMILY_FOREIGN]),
        )
        .expect_err("1.0 is refused");
        assert!(refusal.contains("1.0"), "{refusal}");
    }

    #[test]
    fn the_hardware_buffer_knob_is_off_unless_one_half_turns_it_on() {
        assert!(!hwbuffer_import_knob(None, None, None));
        assert!(!hwbuffer_import_knob(None, None, Some(String::new())));
        assert!(!hwbuffer_import_knob(
            Some("0"),
            Some("0".to_string()),
            Some("0".to_string())
        ));
        assert!(hwbuffer_import_knob(Some("1"), None, None));
        assert!(hwbuffer_import_knob(None, Some("1".to_string()), None));
        assert!(hwbuffer_import_knob(None, None, Some("1".to_string())));
    }

    #[test]
    fn default_options_label_the_device_and_leave_backends_to_the_environment() {
        let options = ContextOptions::default();
        assert_eq!(options.device_label, DEFAULT_DEVICE_LABEL);
        assert_eq!(options.backends, None);
    }

    #[test]
    fn a_fresh_context_has_no_device_and_therefore_no_caps() {
        // Construction must not enumerate adapters, so this is a host test, not
        // a GPU one: it passes on a machine with no usable GPU at all.
        let context = RenderContext::new();
        assert!(context.caps().is_none());
    }

    #[test]
    #[ignore = "needs a real GPU adapter; run with `cargo test -p frust-gpu -- --ignored` \
                (pin the adapter on a multi-GPU host with WGPU_BACKEND / WGPU_ADAPTER_NAME)"]
    fn gpu_device_creation_reports_adapter_caps() {
        pollster::block_on(async {
            let mut context = RenderContext::new();
            let handle = context.device().await.expect("device creation");

            let info = handle.adapter.get_info();
            println!(
                "frust-gpu adapter: name={:?} backend={:?} device_type={:?} \
                 driver={:?} driver_info={:?} vendor={:#06x} device={:#06x}",
                info.name,
                info.backend,
                info.device_type,
                info.driver,
                info.driver_info,
                info.vendor,
                info.device
            );
            println!("frust-gpu caps: {:#?}", handle.caps);
            println!(
                "frust-gpu device limits: max_texture_dimension_2d={} \
                 min_uniform_buffer_offset_alignment={}",
                handle.device.limits().max_texture_dimension_2d,
                handle.device.limits().min_uniform_buffer_offset_alignment
            );

            assert_eq!(handle.caps.adapter_name, info.name);
            assert_eq!(handle.caps.backend, info.backend);
            // Only an Android device frust-gpu opened itself can import a
            // hardware buffer; every host device comes from `request_device`.
            if !cfg!(target_os = "android") {
                assert!(!handle.caps.hwbuffer_import);
            }
            assert!(!handle.caps.adapter_name.is_empty());
            assert!(handle.caps.max_texture_dimension_2d > 0);
            assert!(handle.caps.resource_texture_dim > 0);
            // Nothing has been submitted, so the latch must still be empty.
            assert_eq!(handle.first_uncaptured_error(), None);

            // With `FRUST_ENGINE_DOWNLEVEL=1` set for the whole test process
            // (the override is read once and cached in a `OnceLock`), both the
            // probed caps and the created device must actually report the
            // clamped WebGL2 shape rather than a desktop backend merely
            // relabelled `WebGl2`. Without it, this rig's real backend
            // (Vulkan/Metal/Dx12) must report `Full` unchanged, proving the
            // knob rehearses the downlevel shape rather than always forcing
            // it.
            let downlevel_env_set = std::env::var("FRUST_ENGINE_DOWNLEVEL").is_ok_and(|v| v != "0");
            if downlevel_env_set {
                assert_eq!(handle.caps.downlevel_profile, DownlevelProfile::WebGl2);
                assert!(!handle.caps.has_storage_buffers);
                assert!(handle.caps.max_texture_dimension_2d <= 2048);
                assert_eq!(handle.caps.min_uniform_buffer_offset_alignment, 256);
                assert!(handle.device.limits().max_texture_dimension_2d > 0);
            } else {
                assert_eq!(handle.caps.downlevel_profile, DownlevelProfile::Full);
            }

            let caps = context.caps().cloned().expect("caps after device creation");
            assert_eq!(caps.adapter_name, info.name);

            // The device is created once and reused: a second call must hand
            // back the same logical device, not build another one.
            let again = context.device().await.expect("device reuse");
            assert_eq!(again.caps, caps);
        });
    }
}