cvedia::rt::api::transport ¶

Classes ¶

	Name
struct	cvedia::rt::api::transport::PluginSupport Aggregated per-plugin entry for a transport URI.
struct	cvedia::rt::api::transport::TransportInfo Transport information structure.

Types ¶

	Name
enum class	PluginKind { Other = 0, Decoder, Encoder, Inference} Declare plugin support for a transport URI.

Functions ¶

	Name
void	registerTransportPlugin(std::unique_ptr< iface::TransportPlugin > plugin) Register a transport plugin.
void	declareSupportForUri(std::string const & pluginId, std::string const & transportUri, std::string const & pluginDescription ="", bool isZeroCopy =true, PluginKind kind =PluginKind::Other)
std::optional< std::string >	identifyDevice(void * handle, iface::NativeHandleType type) Identify transport URI from a native API handle.
bool	isSamePhysicalDevice(std::string const & uri1, std::string const & uri2) Check if two transport URIs refer to the same physical device.
std::vector< std::string >	getTransportUrisForDevice(std::string const & anyUri) Get all transport URIs for a physical device.
std::vector< std::string >	getAvailableSchemes() Get all available transport schemes.
std::vector< TransportInfo >	getAllTransports() Get all registered transports.
std::vector< TransportInfo >	getTransportsForScheme(std::string const & scheme, std::string const & targetInteropScheme ="") Get transports for a specific scheme.
bool	hasTransportsForScheme(std::string const & scheme) Check whether a scheme currently provides at least one transport.
std::vector< std::string >	getPluginsSupportingUri(std::string const & uri) Get plugins supporting a transport URI.
std::vector< PluginSupport >	getPluginSupportForUri(std::string const & uri) Get full plugin-support entries (id + kind + description + zeroCopy) for a URI.
std::string	getPluginDescription(std::string const & pluginId) Get description for a plugin ID.
bool	isZeroCopySupport(std::string const & uri, std::string const & pluginId) Check if a plugin supports a transport URI with zero-copy.
void	declareBackendHandlesScheme(std::string const & backendName, std::string const & scheme) Declare buffer backend handles a transport scheme.
void	declareSchemeInterop(std::string const & backendName, std::string const & sourceScheme, std::string const & targetScheme, bool requiresSameDevice) Declare interop capability between two transport schemes.
bool	isValidTransportUri(std::string const & transportUri) Check if transport URI is valid and registered.
std::optional< std::string >	getUriScheme(std::string const & transportUri) Extract scheme from transport URI.
std::optional< std::string >	getBackendForUri(std::string const & transportUri) Get buffer backend for a transport URI.
std::vector< std::pair< std::string, std::string > >	getInteropPaths(std::string const & sourceUri) Get interop paths available from a transport URI.
std::shared_ptr< void >	createNativeContext(std::string const & transportUri, iface::NativeHandleType type) Create a new native context handle for a transport URI.
void	setNativeContext(std::string const & transportUri, iface::NativeHandleType type, std::shared_ptr< void > handle) Store (or replace) the shared native context handle for a transport URI.
void	clearNativeContext(std::string const & transportUri, iface::NativeHandleType type) Remove the native context handle entry for a transport URI.
std::recursive_mutex &	nativeContextMutex(std::string const & transportUri) Serialize all access to the single shared native context for a URI.
std::mutex &	nativeSubmissionMutex(std::string const & transportUri) Serialize native API command submission across plugin modules.
void	registerTransportPlugin(std::unique_ptr< TransportPlugin > plugin)
std::optional< std::string >	identifyDevice(void * handle, NativeHandleType type)
std::shared_ptr< void >	createNativeContext(std::string const & transportUri, NativeHandleType type)
void	setNativeContext(std::string const & transportUri, NativeHandleType type, std::shared_ptr< void > handle)
void	clearNativeContext(std::string const & transportUri, NativeHandleType type)

Types Documentation ¶

enum PluginKind ¶

Enumerator	Value	Description
Other	0
Decoder
Encoder
Inference

Declare plugin support for a transport URI.

Parameters:

pluginId Plugin identifier (e.g., "nvidia.nvdec", "tensorrt", "intel.vpl")
transportUri Transport URI the plugin supports (e.g., "cuda://0")

Called by decoder/inference/processing plugins to declare which transport URIs they support. This information is used to visualize zero-copy opportunities and track data transfers.

Example usage in NVDEC decoder:

NvidiaVideoDecoder::NvidiaVideoDecoder(...) {
    // ... create CUDA context ...
    auto uri = api::transport::identifyDevice(context,
                                              NativeHandleType::CUDA_CONTEXT);
    if (uri) {
        api::transport::declareSupportForUri("nvidia.nvdec", *uri);
    }
}

Thread-safe. Multiple plugins can declare support concurrently.

Functional role of a plugin in the transport ledger.

Two subplugins that target the same device (e.g. Blaize decoder and Blaize inference engine) may share the same pluginId (e.g. "blaize.1") because it identifies the device, not the capability. PluginKind disambiguates them in the ledger so both show up on the same URI without colliding.

Functions Documentation ¶

function registerTransportPlugin ¶

void registerTransportPlugin(
    std::unique_ptr< iface::TransportPlugin > plugin
)

Register a transport plugin.

Parameters:

plugin Unique pointer to transport plugin implementation

Called by transport plugins during their registerHandler() function. The plugin is stored and its transports are enumerated immediately.

Example usage in TransportCUDA plugin:

extern "C" EXPORT void registerHandler() {
    auto plugin = std::make_unique<TransportCUDA>();
    api::transport::registerTransportPlugin(std::move(plugin));
}

Thread-safe. Can be called from multiple plugin loaders concurrently.

function declareSupportForUri ¶

void declareSupportForUri(
    std::string const & pluginId,
    std::string const & transportUri,
    std::string const & pluginDescription ="",
    bool isZeroCopy =true,
    PluginKind kind =PluginKind::Other
)

function identifyDevice ¶

std::optional< std::string > identifyDevice(
    void * handle,
    iface::NativeHandleType type
)

Identify transport URI from a native API handle.

Parameters:

handle Pointer to native API handle
type Type of the native handle

Return: Transport URI if identified, std::nullopt otherwise

Queries all registered transport plugins to identify which transport URI corresponds to the given native handle. Used by plugins to discover their transport URI without manually tracking device indices.

Example usage in TensorRT:

TrtCore::loadBackend() {
    cudaSetDevice(deviceID_);

    auto uri = api::transport::identifyDevice(&deviceID_,
                                              NativeHandleType::CUDA_DEVICE);
    if (uri) {
        api::transport::declareSupportForUri("tensorrt", *uri);
    }
}

Thread-safe.

function isSamePhysicalDevice ¶

bool isSamePhysicalDevice(
    std::string const & uri1,
    std::string const & uri2
)

Check if two transport URIs refer to the same physical device.

Parameters:

uri1 First transport URI
uri2 Second transport URI

Return: true if both URIs refer to the same physical device, false otherwise

Uses physical device identifiers to match devices across different APIs. Matching priority: UUID > PCI Address > LUID > Vendor+Device ID

Example:

bool sameDevice = api::transport::isSamePhysicalDevice("cuda://0",
                                                        "opencl://0-0");
// Returns true if both are NVIDIA GPU on PCI bus 0000:01:00.0

Used for:

Detecting zero-copy opportunities between plugins
Buffer interop capability checking
Device topology visualization Thread-safe.

function getTransportUrisForDevice ¶

std::vector< std::string > getTransportUrisForDevice(
    std::string const & anyUri
)

Get all transport URIs for a physical device.

Parameters:

anyUri Any transport URI for the device

Return: Vector of all transport URIs referring to the same physical device

Example:

auto uris = api::transport::getTransportUrisForDevice("cuda://0");
// Might return: ["cuda://0", "opencl://0-0", "d3d11://0"]

Used for visualizing multi-API access to same device.

Thread-safe.

function getAvailableSchemes ¶

std::vector< std::string > getAvailableSchemes()

Get all available transport schemes.

Return: Vector of scheme names (e.g., ["cpu", "cuda", "opencl"])

Used by rtcmd for tab-completion and filtering.

Thread-safe.

function getAllTransports ¶

std::vector< TransportInfo > getAllTransports()

Get all registered transports.

Return: Vector of TransportInfo for all registered transport URIs

Used by rtcmd transport command to display all available transports.

Thread-safe.

function getTransportsForScheme ¶

std::vector< TransportInfo > getTransportsForScheme(
    std::string const & scheme,
    std::string const & targetInteropScheme =""
)

Get transports for a specific scheme.

Parameters:

scheme Scheme name (e.g., "cuda", "opencl")
targetInteropScheme Optional: only return transports capable of interop with this target scheme

Return: Vector of TransportInfo for the specified scheme

Used by rtcmd transport command with scheme filter.

Thread-safe.

function hasTransportsForScheme ¶

inline bool hasTransportsForScheme(
    std::string const & scheme
)

Check whether a scheme currently provides at least one transport.

Parameters:

scheme Scheme name (e.g., "cuda", "opencl")

Return: true if at least one transport is available for the scheme

A transport plugin can be registered successfully while providing no transports, for example when its driver is installed but no usable device is available. Hardware-dependent plugins can use this check before entering their own vendor runtime during registration.

Thread-safe.

function getPluginsSupportingUri ¶

std::vector< std::string > getPluginsSupportingUri(
    std::string const & uri
)

Get plugins supporting a transport URI.

Parameters:

uri Transport URI

Return: Vector of plugin IDs that declared support for this URI

Example:

auto plugins = api::transport::getPluginsSupportingUri("cuda://0");
// Might return: ["nvidia.nvdec", "tensorrt", "opencv.cuda"]

Used by rtcmd to visualize plugin compatibility and zero-copy opportunities.

Thread-safe.

function getPluginSupportForUri ¶

std::vector< PluginSupport > getPluginSupportForUri(
    std::string const & uri
)

Get full plugin-support entries (id + kind + description + zeroCopy) for a URI.

Prefer this over the tuple of getPluginsSupportingUri/getPluginDescription/ isZeroCopySupport when rendering the transport ledger: it preserves the (pluginId, kind) distinction so two subplugins sharing a pluginId don't collide into a single row.

function getPluginDescription ¶

std::string getPluginDescription(
    std::string const & pluginId
)

Get description for a plugin ID.

Parameters:

pluginId Plugin identifier

Return: Plugin description if available, empty string otherwise

Used by rtcmd to display plugin info like "nvidia.1 (NVIDIA Decoder)"

Thread-safe.

function isZeroCopySupport ¶

bool isZeroCopySupport(
    std::string const & uri,
    std::string const & pluginId
)

Check if a plugin supports a transport URI with zero-copy.

Parameters:

uri Transport URI
pluginId Plugin identifier

Return: true if plugin supports URI with zero-copy, false if copy required or not supported

Thread-safe.

function declareBackendHandlesScheme ¶

void declareBackendHandlesScheme(
    std::string const & backendName,
    std::string const & scheme
)

Declare buffer backend handles a transport scheme.

Parameters:

backendName Buffer backend name (e.g., "BufferCpu", "BufferCuda")
scheme Transport scheme (e.g., "cpu", "cuda", "opencl")

Example: declareBackendHandlesScheme("BufferCuda", "cuda") This declares BufferCuda handles all cuda:// URIs (cuda://0, cuda://1, etc.)

Thread-safe.

function declareSchemeInterop ¶

void declareSchemeInterop(
    std::string const & backendName,
    std::string const & sourceScheme,
    std::string const & targetScheme,
    bool requiresSameDevice
)

Declare interop capability between two transport schemes.

Parameters:

backendName Backend providing interop (e.g., "BufferOpenCL")
sourceScheme Source transport scheme (e.g., "d3d11")
targetScheme Target transport scheme (e.g., "opencl")
requiresSameDevice Whether interop requires same physical device

Example: declareSchemeInterop("BufferOpenCL", "d3d11", "opencl", true) This declares BufferOpenCL can convert d3d11://N ↔ opencl://M when both on same device.

Thread-safe.

function isValidTransportUri ¶

bool isValidTransportUri(
    std::string const & transportUri
)

Check if transport URI is valid and registered.

Parameters:

transportUri Transport URI to validate

Return: true if URI is registered in transport registry, false otherwise

Example:

if (api::transport::isValidTransportUri("cuda://0")) {
    // URI is available on this system
}

Thread-safe.

function getUriScheme ¶

std::optional< std::string > getUriScheme(
    std::string const & transportUri
)

Extract scheme from transport URI.

Parameters:

transportUri Transport URI (e.g., "cuda://0", "opencl://0-0")

Return: Scheme string if valid URI format, nullopt otherwise

Example: "cuda://0" → "cuda", "opencl://0-0" → "opencl"

This is a pure parsing function that does NOT check if the scheme is registered. Use isValidTransportUri() to validate URI existence.

Thread-safe (no registry access).

function getBackendForUri ¶

std::optional< std::string > getBackendForUri(
    std::string const & transportUri
)

Get buffer backend for a transport URI.

Parameters:

transportUri Transport URI (e.g., "cuda://0", "cpu://")

Return: Backend name if found, nullopt otherwise

Matches by URI scheme. Example: "cuda://0" → "BufferCuda"

Thread-safe.

function getInteropPaths ¶

std::vector< std::pair< std::string, std::string > > getInteropPaths(
    std::string const & sourceUri
)

Get interop paths available from a transport URI.

Parameters:

sourceUri Source transport URI

Return: Vector of (target URI, backend name) pairs

Example: "d3d11://0" → [("opencl://1-0", "BufferOpenCL")] if on same Intel GPU

Applies requiresSameDevice rules automatically.

Thread-safe.

function createNativeContext ¶

std::shared_ptr< void > createNativeContext(
    std::string const & transportUri,
    iface::NativeHandleType type
)

Create a new native context handle for a transport URI.

Creates a fresh native context (D3D11 device, OpenCL context, etc.) each time called. Contexts are reference-counted via std::shared_ptr with a custom deleter that releases the underlying native object (clReleaseContext, ID3D11Device::Release, etc.). Caller controls lifetime by holding the returned shared_ptr.

function setNativeContext ¶

void setNativeContext(
    std::string const & transportUri,
    iface::NativeHandleType type,
    std::shared_ptr< void > handle
)

Store (or replace) the shared native context handle for a transport URI.

function clearNativeContext ¶

void clearNativeContext(
    std::string const & transportUri,
    iface::NativeHandleType type
)

Remove the native context handle entry for a transport URI.

function nativeContextMutex ¶

std::recursive_mutex & nativeContextMutex(
    std::string const & transportUri
)

Serialize all access to the single shared native context for a URI.

Some accelerators (e.g. the Blaize GSP) permit exactly one native context per device, so the decode buffer plugin and the inference engine share a single context published under "vx://:". Executing graphs and creating/releasing context objects on that shared context from decode and inference threads concurrently corrupts context state (intermittent garbled frames). Every operation on the shared context must be performed while holding this per-URI mutex.

The mutex is owned by the core (not by a plugin module) so a single instance is visible across the separately loaded plugin modules that share the context. Recursive, so a thread already holding it may re-enter helpers that re-acquire it. Thread-safe.

function nativeSubmissionMutex ¶

std::mutex & nativeSubmissionMutex(
    std::string const & transportUri
)

Serialize native API command submission across plugin modules.

This mutex is owned by the core so separately loaded buffer and inference plugins can coordinate short command-submission sections for the same transport without holding the lock while device work completes.

function registerTransportPlugin ¶

void registerTransportPlugin(
    std::unique_ptr< TransportPlugin > plugin
)

function identifyDevice ¶

std::optional< std::string > identifyDevice(
    void * handle,
    NativeHandleType type
)

function createNativeContext ¶

std::shared_ptr< void > createNativeContext(
    std::string const & transportUri,
    NativeHandleType type
)

function setNativeContext ¶

void setNativeContext(
    std::string const & transportUri,
    NativeHandleType type,
    std::shared_ptr< void > handle
)

function clearNativeContext ¶

void clearNativeContext(
    std::string const & transportUri,
    NativeHandleType type
)