Trait GpuPipelineProvider 

pub trait GpuPipelineProvider: Send + Sync {
    // Required methods
    fn name(&self) -> &str;
    fn build_pipeline_tail(
        &self,
        pixel_format: PixelFormat,
    ) -> Result<GpuPipelineTail, MediaError>;
    fn bridge_sample(
        &self,
        feed_id: FeedId,
        seq: &Arc<Atomic<u64>>,
        pixel_format: PixelFormat,
        sample: &Sample,
        ptz: Option<PtzTelemetry>,
    ) -> Result<FrameEnvelope, MediaError>;
}

Extension point for GPU-resident pipeline construction.

Platform-specific crates implement this trait to provide tailored pipeline topology and frame bridging for their GPU memory model.

The built-in CUDA path is available via DeviceResidency::Cuda without implementing this trait. Applications only need a custom provider when the built-in elements are unavailable (e.g., NVMM on JetPack 5.x) or when a different GPU memory model is required.

Thread safety

Implementations must be Send + Sync because the provider is shared between the pipeline-building code (source management thread) and the appsink callback (GStreamer streaming thread) via Arc.

Example

use std::sync::Arc;
use nv_media::gpu_provider::GpuPipelineProvider;
use nv_media::DeviceResidency;

let provider: Arc<dyn GpuPipelineProvider> = Arc::new(MyJetsonProvider::new());

let config = FeedConfig::builder()
    .device_residency(DeviceResidency::Provider(provider))
    // ...
    .build()?;

Required Methods

fn name(&self) -> &str

Human-readable name for logging and diagnostics.

fn build_pipeline_tail( &self, pixel_format: PixelFormat, ) -> Result<GpuPipelineTail, MediaError>

Build the GPU pipeline tail (converter elements + appsink).

Called once per session during pipeline construction. The returned elements are added to the pipeline and linked in order, followed by the appsink.

Arguments

• pixel_format — the target pixel format for the appsink caps.

Errors

Return MediaError::Unsupported if the required GStreamer elements or capabilities are not available at runtime.

fn bridge_sample( &self, feed_id: FeedId, seq: &Arc<Atomic<u64>>, pixel_format: PixelFormat, sample: &Sample, ptz: Option<PtzTelemetry>, ) -> Result<FrameEnvelope, MediaError>

Bridge a GStreamer sample into a device-resident FrameEnvelope.

Called on every frame from the appsink streaming thread. Must be efficient — allocations and blocking should be minimized.

The returned FrameEnvelope should carry PixelData::Device with a platform-specific handle (e.g., CudaBufferHandle or NvmmBufferHandle) and optionally a HostMaterializeFn for transparent CPU fallback.

Implementors