Lock And Extract Interop Handles

Overview

The Lock And Extract Interop Handles sample demonstrates how to create a VPI-owned image and then extract exactly one interop handle from it.

The sample supports three zero-copy export modes:

• cuda_ptr via vpiImageLockData(..., VPI_IMAGE_BUFFER_CUDA_PITCH_LINEAR, ...)
• nvbufsurface via vpiImageLockData(..., VPI_IMAGE_BUFFER_NVBUFFER, ...) and NvBufSurfaceFromFd
• nvscibuf via vpiImageLockData(..., VPI_IMAGE_BUFFER_NVSCIBUF, ...)

The sample creates a default VPI context, which enables all backends supported by the running platform, reads those backend flags with vpiContextGetFlags, and passes the backend flags to vpiImageCreate instead of wrapping external memory first. This is the preferred direction when a pipeline wants VPI to own the image and then needs to hand the image to CUDA, multimedia, or NvSci code afterwards.

Instructions

This sample takes one command line parameter:

./vpi_sample_23_lock_extract_interop <cuda_ptr|nvbufsurface|nvscibuf>

Examples:

• Export a CUDA pointer from a VPI-owned image

  ./vpi_sample_23_lock_extract_interop cuda_ptr

• Export an NvBufSurface from a VPI-owned image

  ./vpi_sample_23_lock_extract_interop nvbufsurface

• Export an NvSciBufObj from a VPI-owned image

  ./vpi_sample_23_lock_extract_interop nvscibuf

Note

This sample is available only on Tegra platforms.

NvBufSurface extraction through VPI_IMAGE_BUFFER_NVBUFFER is Thor-only. On Orin, use either cuda_ptr or nvscibuf.

Interop Guidance

• Wrapping external CUDA memory or NvBufSurface memory into a VPIImage while enabling all supported backends may require internal copies.
• Creating a VPI-owned image with the VPIBackend flags needed by the VPI stages that will consume it, then extracting a CUDA pointer, NvBufSurface, or NvSciBufObj from it with vpiImageLockData, is zero-copy when the platform and format support the requested mapping.
• For mixed VPI/CUDA/multimedia/NvSci pipelines, prefer create in VPI first, extract afterwards.

Workflow

1. Create a VPI-owned image with explicit backend flags. This sample passes the backend flags enabled by the default context, equivalent to creating the image with 0.
2. Choose one export mode on the command line.
3. Lock the image with the buffer type that matches that mode.
4. Read the returned CUDA pointer, NvBufSurface, or NvSciBufObj handle.
5. Unlock the image when finished using the exported handle.

Source Code

For convenience, here's the code that is also installed in the samples directory.

#include <nvbufsurface.h>
#include <nvscibuf.h>
#include <vpi/Context.h>
#include <vpi/Image.h>
 
#include <cstdint>
#include <cstdlib>
#include <iostream>
#include <sstream>
#include <stdexcept>
#include <string>
 
#define CHECK_STATUS(STMT)                                                                  \
    do                                                                                      \
    {                                                                                       \
        VPIStatus status = (STMT);                                                          \
        if (status != VPI_SUCCESS)                                                          \
        {                                                                                   \
            char buffer[VPI_MAX_STATUS_MESSAGE_LENGTH];                                     \
            vpiGetLastStatusMessage(buffer, sizeof(buffer));                                \
            std::ostringstream ss;                                                          \
            ss << "line " << __LINE__ << " " << vpiStatusGetName(status) << ": " << buffer; \
            throw std::runtime_error(ss.str());                                             \
        }                                                                                   \
    } while (0)
 
namespace {
 
enum class ExportMode
{
    CUDA_PTR,
    NVBUFSURFACE,
    NVSCIBUF
};
 
ExportMode ParseExportMode(int argc, char *argv[])
{
    if (argc != 2)
    {
        throw std::runtime_error(std::string("Usage: ") + argv[0] + " <cuda_ptr|nvbufsurface|nvscibuf>");
    }
 
    std::string mode = argv[1];
 
    if (mode == "cuda_ptr")
    {
        return ExportMode::CUDA_PTR;
    }
    if (mode == "nvbufsurface")
    {
        return ExportMode::NVBUFSURFACE;
    }
    if (mode == "nvscibuf")
    {
        return ExportMode::NVSCIBUF;
    }
 
    throw std::runtime_error("Export mode must be one of cuda_ptr, nvbufsurface or nvscibuf");
}
 
void PrintCudaPointer(VPIImage image)
{
    VPIImageData cudaData{};
    CHECK_STATUS(vpiImageLockData(image, VPI_LOCK_READ, VPI_IMAGE_BUFFER_CUDA_PITCH_LINEAR, &cudaData));
 
    const VPIImagePlanePitchLinear &plane = cudaData.buffer.pitch.planes[0];
 
    std::cout << "CUDA pointer export\n";
    std::cout << "  pointer         : " << static_cast<void *>(plane.pBase) << "\n";
    std::cout << "  offsetBytes     : " << plane.offsetBytes << "\n";
    std::cout << "  pitchBytes      : " << plane.pitchBytes << "\n";
    std::cout << "  note            : This export is zero-copy.\n";
 
    CHECK_STATUS(vpiImageUnlock(image));
}
 
void PrintNvBufSurface(VPIImage image)
{
    VPIImageData nvBufferData{};
    CHECK_STATUS(vpiImageLockData(image, VPI_LOCK_READ, VPI_IMAGE_BUFFER_NVBUFFER, &nvBufferData));
 
    NvBufSurface *surface = nullptr;
    if (NvBufSurfaceFromFd(nvBufferData.buffer.fd, reinterpret_cast<void **>(&surface)) != 0 || surface == nullptr)
    {
        CHECK_STATUS(vpiImageUnlock(image));
        throw std::runtime_error("NvBufSurfaceFromFd failed");
    }
 
    std::cout << "NvBufSurface export\n";
    std::cout << "  dmabuf fd       : " << nvBufferData.buffer.fd << "\n";
    std::cout << "  surface pointer : " << surface << "\n";
    std::cout << "  note            : This export is zero-copy.\n";
 
    CHECK_STATUS(vpiImageUnlock(image));
}
 
void PrintNvSciBufObj(VPIImage image)
{
    VPIImageData nvSciData{};
    CHECK_STATUS(vpiImageLockData(image, VPI_LOCK_READ, VPI_IMAGE_BUFFER_NVSCIBUF, &nvSciData));
 
    std::cout << "NvSciBufObj export\n";
    std::cout << "  object handle   : " << nvSciData.buffer.nvscibuf.buffer << "\n";
    std::cout << "  note            : This export is zero-copy.\n";
 
    CHECK_STATUS(vpiImageUnlock(image));
}
 
} // namespace
 
int main(int argc, char *argv[])
{
    ExportMode exportMode = ParseExportMode(argc, argv);
 
    std::cout
        << "This sample shows how to extract either a CUDA pointer, an NvBufSurface, or an NvSciBufObj\n"
           "from a VPI-owned image. These extraction paths are zero-copy.\n"
           "The image is created with all platform-supported backend flags so VPI can choose compatible memory.\n\n";
 
    VPIContext context = nullptr;
    CHECK_STATUS(vpiContextCreate(0, &context));
    CHECK_STATUS(vpiContextSetCurrent(context));
 
    uint64_t imageBackends = 0;
    CHECK_STATUS(vpiContextGetFlags(context, &imageBackends));
    imageBackends &= VPI_BACKEND_ALL;
 
    VPIImage image = nullptr;
 
    try
    {
        CHECK_STATUS(vpiImageCreate(320, 240, VPI_IMAGE_FORMAT_NV12_ER, imageBackends, &image));
 
        if (exportMode == ExportMode::CUDA_PTR)
        {
            PrintCudaPointer(image);
        }
        else if (exportMode == ExportMode::NVBUFSURFACE)
        {
            PrintNvBufSurface(image);
        }
        else
        {
            PrintNvSciBufObj(image);
        }
    }
    catch (...)
    {
        if (image != nullptr)
        {
            vpiImageDestroy(image);
        }
        if (context != nullptr)
        {
            vpiContextDestroy(context);
        }
        throw;
    }
 
    vpiImageDestroy(image);
    vpiContextDestroy(context);
 
    // dummy