Module context 

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).

Structs

ContextOptions

How a RenderContext should build its instance and request its device.

DeviceHandle

A logical device, the adapter it was created from, the queue that executes its command buffers, and the capabilities that adapter reported.

RenderContext

Owns the wgpu::Instance and the single logical device this crate’s consumers render with.

Enums

LogAction

What the uncaptured-error handler should do for the count-th uncaptured error (1-indexed) it has observed on a given device.

Functions

decide_log_action

Pure latch policy for the uncaptured-error handler (see LogAction).

effective_limits

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.

is_ios_simulator

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.

optional_device_features

The wgpu::Features a device request opportunistically asks for when the adapter exposes them.

test_device_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.