api/api/buffer.h

Namespaces

Name
cvedia
cvedia::rt API for controlling the server and lifecycle management of runtime instances.
cvedia::rt::iface
cvedia::rt::api
cvedia::rt::api::buffer

Functions

	Name
cbuffer	allocate(int width, int height, BufferDataType type, std::string const & transportUri ="cpu://") Allocate new empty buffer (replaces createBuffer, clearer naming)
expected< cbuffer >	fromData(int width, int height, BufferDataType type, void * data, size_t stride, std::string const & transportUri, BufferOwnership ownership, std::shared_ptr< void > const & keepAlive =nullptr) Create buffer from raw data pointer - UNIFIED FUNCTION.
expected< cbuffer >	fromInterop(void * nativeHandle, std::string const & sourceUri, std::string const & targetScheme, std::optional< cv::Rect2i > crop =std::nullopt) Create buffer from hardware decoder interop (D3D11/VAAPI → OpenCL)
expected< cbuffer >	fromInterop(void * nativeHandle, std::string const & sourceUri, std::string const & targetScheme, std::optional< cv::Rect2i > crop, std::shared_ptr< void > const & keepAlive) Create buffer from hardware decoder interop with external lifecycle token.
expected< cbuffer >	fromInterop(void * nativeHandle, std::string const & sourceUri, std::string const & targetScheme, std::optional< cv::Rect2i > crop, std::shared_ptr< void > const & keepAlive, void * sourceContext) Create buffer from hardware decoder interop with explicit native display context.
expected< cbuffer >	decodeImage(void const * compressedData, size_t dataSize, std::string const & transportUri ="cpu://") Decode compressed image from memory (JPEG, PNG, etc.)
cbuffer	mergeChannels(cbuffer const & r, cbuffer const & g, cbuffer const & b)
NODISCARD expected< cbuffer >	createMotionBuffer(cbuffer const & source1, Rect const & region1, cbuffer const & source2, Rect const & region2, Size outputSize) Create motion buffer from two grayscale/NV12 sources (fused operation)
cbuffer	createBufferFromHorizontalConcat(cbuffer const & left, cbuffer const & right, std::string const & transportUri ="cpu://")
NODISCARD expected< cbuffer >	loadImage(std::string const & imagePath, std::string const & transportUri ="cpu://")
cbuffer	downloadAsGrayscale(cbuffer const & buffer)
NODISCARD expected< std::vector< uint8_t > >	toJpeg(cbuffer const & buffer, int quality =85) Encode buffer to JPEG format.

Functions Documentation

function allocate

cbuffer allocate(
    int width,
    int height,
    BufferDataType type,
    std::string const & transportUri ="cpu://"
)

Allocate new empty buffer (replaces createBuffer, clearer naming)

Creates buffer with newly allocated, managed memory. Buffer owns memory and frees on destruction.

function fromData

expected< cbuffer > fromData(
    int width,
    int height,
    BufferDataType type,
    void * data,
    size_t stride,
    std::string const & transportUri,
    BufferOwnership ownership,
    std::shared_ptr< void > const & keepAlive =nullptr
)

Create buffer from raw data pointer - UNIFIED FUNCTION.

Parameters:

• ownership COPY=copies data, BORROW=zero-copy view, ADOPT=transfer ownership
• keepAlive RAII token to keep external resource alive (optional)

Replaces: createFromData(), createFromBlob(), wrapBuffer(), adoptBuffer() Ownership parameter determines copy vs wrap vs adopt behavior.

COPY: Buffer allocates new memory, copies data, standard cleanup BORROW: Buffer references data directly, caller manages lifetime (or use keepAlive) ADOPT: Buffer takes ownership of data, releases when destroyed

keepAlive: shared_ptr to any RAII object. Buffer retains a copy and releases it only when fully destroyed. Use for decoder surfaces, mapped frames, etc.

function fromInterop

expected< cbuffer > fromInterop(
    void * nativeHandle,
    std::string const & sourceUri,
    std::string const & targetScheme,
    std::optional< cv::Rect2i > crop =std::nullopt
)

Create buffer from hardware decoder interop (D3D11/VAAPI → OpenCL)

Parameters:

• nativeHandle ID3D11Texture2D* or VASurfaceID
• sourceUri Source device transport URI (from decoder)
• targetScheme Target backend scheme ("opencl")
• crop Optional logical crop rectangle

Return: cbuffer with zero-copy interop, or error

function fromInterop

expected< cbuffer > fromInterop(
    void * nativeHandle,
    std::string const & sourceUri,
    std::string const & targetScheme,
    std::optional< cv::Rect2i > crop,
    std::shared_ptr< void > const & keepAlive
)

Create buffer from hardware decoder interop with external lifecycle token.

The keepAlive token is a shared_ptr to any RAII object that controls the lifetime of the native resource (e.g., a DX11 decoder surface). The backend will retain a copy of this token and only release it once it has fully released all interop resources, ensuring correct destruction order across derived buffers.

function fromInterop

expected< cbuffer > fromInterop(
    void * nativeHandle,
    std::string const & sourceUri,
    std::string const & targetScheme,
    std::optional< cv::Rect2i > crop,
    std::shared_ptr< void > const & keepAlive,
    void * sourceContext
)

Create buffer from hardware decoder interop with explicit native display context.

Parameters:

• nativeHandle ID3D11Texture2D* or VASurfaceID
• sourceUri Source device transport URI (from decoder)
• targetScheme Target backend scheme ("opencl")
• crop Optional logical crop rectangle
• keepAlive RAII token to keep native resource alive
• sourceContext Native display handle (VaapiInteropSourceContext* on Linux, ID3D11Device on Windows). On Linux, may include a per-decoder OpenCL command queue for parallel interop operations. If nullptr, the backend will look up the display from sourceUri.

Return: cbuffer with zero-copy interop, or error

This overload allows passing an explicit native display context (VADisplay on Linux, ID3D11Device on Windows) that the backend should use for interop. This is necessary when the decoder (e.g., VPL) creates its own display driver instance that differs from the one in the transport registry.

function decodeImage

expected< cbuffer > decodeImage(
    void const * compressedData,
    size_t dataSize,
    std::string const & transportUri ="cpu://"
)

Decode compressed image from memory (JPEG, PNG, etc.)

Replaces: loadImage(void*, int, ...) - renamed for clarity

function mergeChannels

cbuffer mergeChannels(
    cbuffer const & r,
    cbuffer const & g,
    cbuffer const & b
)

function createMotionBuffer

NODISCARD expected< cbuffer > createMotionBuffer(
    cbuffer const & source1,
    Rect const & region1,
    cbuffer const & source2,
    Rect const & region2,
    Size outputSize
)

Create motion buffer from two grayscale/NV12 sources (fused operation)

Parameters:

• source1 First source buffer (GRAY or NV12)
• region1 Absolute pixel region in source1
• source2 Second source buffer (GRAY or NV12)
• region2 Absolute pixel region in source2
• outputSize Target dimensions for output buffer

Return: New BGR buffer with fused operation result

Extracts Y-plane from GRAY or NV12 sources, resizes regions to outputSize, and merges into BGR buffer where B=source1, G=source2, R=black. Transport is auto-selected (prefers GPU over CPU).

function createBufferFromHorizontalConcat

cbuffer createBufferFromHorizontalConcat(
    cbuffer const & left,
    cbuffer const & right,
    std::string const & transportUri ="cpu://"
)

function loadImage

NODISCARD expected< cbuffer > loadImage(
    std::string const & imagePath,
    std::string const & transportUri ="cpu://"
)

function downloadAsGrayscale

cbuffer downloadAsGrayscale(
    cbuffer const & buffer
)

function toJpeg

NODISCARD expected< std::vector< uint8_t > > toJpeg(
    cbuffer const & buffer,
    int quality =85
)

Encode buffer to JPEG format.

Parameters:

• buffer Input buffer to encode (NV12 format preferred for hardware)
• quality JPEG quality (1-100, default 85)

Return: JPEG-encoded bytes on success, error code on failure

Uses the JpegEncoderRegistry to find the best encoder for the buffer's transport URI. Automatically selects hardware encoding when available for zero-copy encoding, with fallback to software encoding.

Example:

auto jpeg = api::buffer::toJpeg(buffer, 90);
if (jpeg) {
    // Write to file, send over network, etc.
}

---