project-setup-c

# Project Setup (C) ## Overview ovstream provides a C API with a CMake config for easy integration. The recommended approach uses CMake `FetchContent` (wrapped in `ovstream_fetch()`) to download the matching ovstream binary archive from GitHub Releases at configure time. ## Project Structure ``` my-streaming-app/ CMakeLists.txt cmake/ ovstream.cmake # Copy from examples/c/cmake/ovstream.cmake main.cu # or main.cpp if you don't need CUDA kernels ``` ## CMakeLists.txt ```cmake cmake_minimum_required(VERSION 3.18) project(my-streaming-app LANGUAGES CXX CUDA) set(CMAKE_CXX_STANDARD 17) set(CMAKE_CXX_STANDARD_REQUIRED ON) # Fetch ovstream list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/cmake") include(ovstream) ovstream_fetch() add_executable(my-streaming-app main.cu) target_link_libraries(my-streaming-app PRIVATE ovstream::ovstream) # Configure runtime dependencies (rpath on Linux, DLL copying on Windows) ovstream_setup_runtime(my-streaming-app) ``` ## ovstream.cmake Copy [`examples/c/cmake/ovstream.cmake`](../../examples/c/cmake/ovstream.cmake) into your project's `cmake/` directory. Two macros it provides: - `ovstream_fetch()` — downloads the ovstream archive via FetchContent and makes the `ovstream::ovstream` imported target available. - `ovstream_setup_runtime(TARGET)` — copies the bundled DLLs + `gst-plugins/` (Windows) or sets rpath (Linux) so the executable can find ovstream runtime dependencies. Pin `OVSTREAM_VERSION` inside `ovstream.cmake` to the release you want. The macro derives the per-platform archive URL automatically: ``` https://github.com/NVIDIA-Omniverse/ovstream/releases/download/v<VERSION>/ovstream@<VERSION>.<PLATFORM>.zip ``` ## Working against a local build When iterating, point at an unzipped local package instead of downloading: ```bash cmake -B build -DOVSTREAM_LOCAL_PACKAGE_DIR=/path/to/extracted/ovstream-package ``` ## Minimal main.cu > **Source:** `examples/c/basic_stream/main.cu` snippet `initialize-sdk` > > Followed by: `examples/c/basic_stream/main.cu` snippet `create-server` > > Followed by: `examples/c/basic_stream/main.cu` snippet `configure-server` > > Followed by: `examples/c/basic_stream/main.cu` snippet `start-server` > > Followed by: `examples/c/basic_stream/main.cu` snippet `stream-loop` > > Followed by: `examples/c/basic_stream/main.cu` snippet `cleanup` > > See the full `basic_stream` example for the complete flow. ## Build and Run ```bash cmake -B build -DCMAKE_BUILD_TYPE=Release cmake --build build --config Release ./build/my-streaming-app # Linux .\build\Release\my-streaming-app.exe # Windows ``` ## Headers | Header | Purpose | |--------|---------| | `<ovstream/ovstream.h>` | Main API: initialize/shutdown, create/destroy server, start/stop, stream frames, register callbacks. | | `<ovstream/ovstream_types.h>` | All type definitions (handles, structs, enums, version macros). | | `<ovstream/ovstream_client.h>` | Unified backend-agnostic consumer API for writing readers (not producers). Transport selected by `ovstream_client_type_t`: `OVSTREAM_CLIENT_SHM` (host-resident), `OVSTREAM_CLIENT_CUDASHM` (GPU-resident, imports producer IPC handles via `cudaIpcOpenMemHandle`), `OVSTREAM_CLIENT_NATIVE` (network, decoded client-side via StreamSDK's NvStreamingMedia, which uses NVDEC on NVIDIA GPUs). | | `<ovstream_utils/loop.hpp>` | Optional header-only frame pacer (`ovstream_utils::Loop`). | ## Common Pitfalls - `ovstream_fetch()` requires CMake 3.18+ (CUDA language support and `FetchContent` semantics). - `ovstream_setup_runtime()` must be called once per executable target — without it, the bundled DLLs / `gst-plugins/` won't be on the load path at runtime on Windows. - The `OVSTREAM_VERSION` literal in `ovstream.cmake` must match the version you actually want; an out-of-sync pin yields 404 from the GitHub Release URL. - ovstream needs a working CUDA driver at runtime (not bundled). The CUDA *runtime* (`cudart`) is bundled in the release archive. - A **consumer** (reader) links the `ovstream::ovstream_client` target and includes `<ovstream/ovstream_client.h>` — never the server-side `ovstream` library. Backend-specific runtime dependencies: a CUDASHM consumer pulls in the CUDA runtime (`cudaIpcOpenMemHandle`); a NATIVE consumer pulls in the bundled `NvStreamingMedia` + `NVCodec` libraries for the decode and `StreamClientShared` for the StreamSDK session, and needs an NVIDIA GPU + driver on the consumer machine. An SHM-only consumer needs neither. - `ovstream_utils` ships as both a header-only C++ helper (`<ovstream_utils/loop.hpp>`, just include) and a small shared library for C consumers (`<ovstream_utils/loop.h>`, link `libovstream_utils.so` / `ovstream_utils.dll`). C++ users typically pick the header-only path; C users must link the shared library.