Enum DeviceResidency 

pub enum DeviceResidency {
    Host,
    Cuda,
    Provider(Arc<dyn GpuPipelineProvider>),
}

Where decoded frames reside after the media bridge.

Controls whether the pipeline tail maps frames to host memory (default), uses the built-in CUDA path, or delegates to a custom GpuPipelineProvider.

Resolution order

The pipeline builder resolves the device residency strategy in this order:

1. Provider — the provider builds the pipeline tail and bridges frames. No built-in CUDA elements are needed. If the provider fails, pipeline construction returns an error — there is no silent fallback to Host, because the user explicitly selected a specific hardware integration.
2. Cuda — the built-in upstream CUDA path (cudaupload, cudaconvert). Requires the cuda cargo feature and GStreamer ≥ 1.20. Falls back to Host with a warning if the elements are not available.
3. Host — standard videoconvert → appsink path. Frames arrive in CPU-accessible mapped memory.

Feature gating

• Cuda requires the cuda cargo feature on nv-media. Without it, requesting Cuda returns MediaError::Unsupported.
• Provider does not require the cuda feature — the provider decides which GStreamer elements to use.

Hardware extension

To add support for a new hardware backend (e.g., AMD ROCm), implement GpuPipelineProvider in a new crate and pass DeviceResidency::Provider(Arc::new(MyProvider::new())). No changes to the core library are needed.

Variants

Host

Frames are mapped to CPU-accessible memory (zero-copy GStreamer buffer mapping). This is the standard path.

Cuda

Frames remain on the GPU as CUDA device memory via the built-in upstream GStreamer CUDA elements (cudaupload, cudaconvert).

Requires the cuda cargo feature. On GStreamer < 1.20 (where the CUDA elements are unavailable), falls back to Host with a warning.

Stages access the device pointer via FrameEnvelope::accelerated_handle::<CudaBufferHandle>(). CPU consumers can still call FrameEnvelope::require_host_data() — the materializer downloads device data on first access and caches the result.

Provider(Arc<dyn GpuPipelineProvider>)

Frames remain on a device managed by the supplied provider.

The provider controls pipeline tail construction and frame bridging. This variant does not require the cuda cargo feature — the provider decides which GStreamer elements and memory model to use.

See GpuPipelineProvider for the trait contract.

Implementations

impl DeviceResidency

pub fn is_device(&self) -> bool

Whether this residency requests device-resident frames (non-host).

pub fn provider(&self) -> Option<&Arc<dyn GpuPipelineProvider>>

Extract the provider reference, if this is the Provider variant.

Trait Implementations

impl Clone for DeviceResidency

fn clone(&self) -> DeviceResidency

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for DeviceResidency

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for DeviceResidency

fn default() -> DeviceResidency

Returns the “default value” for a type.