C++ API Reference

Core C++ API for MediaX video streaming.

Stream Information

The StreamInformation structure defines stream parameters:

#include "rtp/rtp.h"

struct mediax::rtp::StreamInformation {
    std::string session_name;     // Stream name for SAP
    std::string hostname;         // Multicast address or IP
    uint16_t port;                // UDP port
    uint32_t width;               // Frame width in pixels
    uint32_t height;              // Frame height in pixels
    uint32_t framerate;           // Frames per second
    ColourspaceType encoding;     // Colorspace/codec type
};

Colorspace Types

enum class mediax::rtp::ColourspaceType {
    kColourspaceRgb24,      // 24-bit RGB
    kColourspaceYuv422,     // YCbCr 4:2:2 (UYVY)
    kColourspaceMono8,      // 8-bit grayscale
    kColourspaceMono16,     // 16-bit grayscale
    kColourspaceH264Part10, // H.264/AVC
    kColourspaceH265,       // H.265/HEVC
    kColourspaceAv1,        // AV1
    kColourspaceJpeg2000,   // JPEG 2000
};

Payloader Classes

Uncompressed Payloader

#include "uncompressed/rtp_uncompressed_payloader.h"

class mediax::rtp::uncompressed::RtpUncompressedPayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    bool Transmit(const uint8_t* data, bool blocking = true);
};

H.264 VAAPI Payloader

#include "h264/vaapi/rtp_h264_vaapi_payloader.h"

class mediax::rtp::h264::vaapi::RtpH264VaapiPayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    bool Transmit(const uint8_t* data, bool blocking = true);
};

H.265 VAAPI Payloader

#include "h265/vaapi/rtp_h265_vaapi_payloader.h"

class mediax::rtp::h265::vaapi::RtpH265VaapiPayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    bool Transmit(const uint8_t* data, bool blocking = true);
};

AV1 Payloader

#include "av1/vaapi/rtp_av1_vaapi_payloader.h"

class mediax::rtp::av1::vaapi::RtpAv1VaapiPayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    bool Transmit(const uint8_t* data, bool blocking = true);
};

Depayloader Classes

Uncompressed Depayloader

#include "uncompressed/rtp_uncompressed_depayloader.h"

class mediax::rtp::uncompressed::RtpUncompressedDepayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    void Start();
    void Stop();
    bool Receive(uint8_t* data, int timeout_ms = 0);
    void RegisterCallback(std::function<void(const RtpFrameData&)> callback);
};

H.264 VAAPI Depayloader

#include "h264/vaapi/rtp_h264_vaapi_depayloader.h"

class mediax::rtp::h264::vaapi::RtpH264VaapiDepayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    void Start();
    void Stop();
    bool Receive(uint8_t* data, int timeout_ms = 0);
    void RegisterCallback(std::function<void(const RtpFrameData&)> callback);
};

H.265 VAAPI Depayloader

#include "h265/vaapi/rtp_h265_vaapi_depayloader.h"

class mediax::rtp::h265::vaapi::RtpH265VaapiDepayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    void Start();
    void Stop();
    bool Receive(uint8_t* data, int timeout_ms = 0);
    void RegisterCallback(std::function<void(const RtpFrameData&)> callback);
};

AV1 Depayloader

#include "av1/vaapi/rtp_av1_vaapi_depayloader.h"

class mediax::rtp::av1::vaapi::RtpAv1VaapiDepayloader {
public:
    void SetStreamInfo(const StreamInformation& info);
    bool Open();
    void Close();
    void Start();
    void Stop();
    bool Receive(uint8_t* data, int timeout_ms = 0);
    void RegisterCallback(std::function<void(const RtpFrameData&)> callback);
};

Frame Data Structure

struct mediax::rtp::RtpFrameData {
    uint8_t* cpu_buffer;          // Pointer to frame data
    struct {
        uint32_t width;
        uint32_t height;
    } resolution;
    ColourspaceType encoding;
    uint32_t timestamp;
};

SAP Classes

SAP Announcer

#include "sap/sap_announcer.h"

class mediax::sap::SapAnnouncer {
public:
    void AddSapAnnouncement(const rtp::StreamInformation& info);
    void DeleteSapAnnouncement(const std::string& session_name);
    void DeleteAllSapAnnouncements();
    void Start();
    void Stop();
};

SAP Listener

#include "sap/sap_listener.h"

class mediax::sap::SapListener {
public:
    void Start();
    void Stop();
    const std::map<std::string, rtp::StreamInformation>& GetSapAnnouncements();
    void RegisterCallback(std::function<void(const rtp::StreamInformation&)> callback);
};

Codec Query Interface

Discover which codecs are compiled into the library and available at runtime.

CodecInfo Structure

#include "rtp/codec_query.h"

struct mediax::rtp::CodecInfo {
    std::string name;               // e.g. "H.264 VAAPI"
    std::string backend;            // e.g. "vaapi", "openh264", "nvenc"
    ColourspaceType colourspace;    // Codec type enum
    CodecDirection direction;       // kEncoder, kDecoder, or kBidirectional
    AccelerationType acceleration;  // kSoftware or kHardware
    bool compiled;                  // Compiled into this build
    bool available;                 // Hardware available at runtime
    std::string description;        // Human-readable description
};

Enumerations

enum class mediax::rtp::CodecDirection {
    kEncoder,       // Encode (payloader) only
    kDecoder,       // Decode (depayloader) only
    kBidirectional  // Both encode and decode
};

enum class mediax::rtp::AccelerationType {
    kSoftware,  // CPU / software-only codec
    kHardware   // Hardware-accelerated (GPU, ASIC, V4L2 M2M)
};

CodecQuery Class

#include "rtp/codec_query.h"

class mediax::rtp::CodecQuery {
public:
    // List all known backends (compiled and uncompiled)
    static std::vector<CodecInfo> GetCodecs();

    // Filter by direction
    static std::vector<CodecInfo> GetEncoders();
    static std::vector<CodecInfo> GetDecoders();

    // Filter by acceleration type
    static std::vector<CodecInfo> GetHardwareCodecs();
    static std::vector<CodecInfo> GetSoftwareCodecs();

    // Only compiled AND runtime-available backends
    static std::vector<CodecInfo> GetAvailableCodecs();

    // Filter by colourspace type
    static std::vector<CodecInfo> GetCodecsByColourspace(ColourspaceType type);

    // Quick check: is a named backend usable?
    static bool IsBackendAvailable(const std::string& backend);

    // Print formatted summary table
    static void PrintCodecSummary(std::ostream& os = std::cout);
};

Codec Query Examples

Print all available codecs:

#include "rtp/codec_query.h"

int main() {
    mediax::rtp::CodecQuery::PrintCodecSummary();
    return 0;
}

Output:

Codec                   Backend     Direction   Accel       Compiled  Available
--------------------------------------------------------------------------------
Uncompressed RGB24      uncompressed Both       Software    Yes       Yes
Uncompressed YUV422     uncompressed Both       Software    Yes       Yes
Uncompressed Mono8      uncompressed Both       Software    Yes       Yes
Uncompressed Mono16     uncompressed Both       Software    Yes       Yes
H.264 OpenH264          openh264    Both        Software    Yes       Yes
H.264 VAAPI             vaapi       Both        Hardware    Yes       Yes
H.265 VAAPI             vaapi       Both        Hardware    Yes       Yes
AV1 VAAPI               vaapi       Both        Hardware    Yes       Yes
H.264 NVENC Encoder     nvenc       Encoder     Hardware    No        No
H.264 NVDEC Decoder     nvenc       Decoder     Hardware    No        No

Choose a backend at runtime:

#include "rtp/codec_query.h"
#include <iostream>

void select_h264_encoder() {
    using namespace mediax::rtp;

    // Prefer hardware, fall back to software
    if (CodecQuery::IsBackendAvailable("vaapi")) {
        std::cout << "Using VAAPI hardware encoder\n";
        // Use RtpH264VaapiPayloader
    } else if (CodecQuery::IsBackendAvailable("nvenc")) {
        std::cout << "Using NVENC hardware encoder\n";
        // Use RtpH264NvencPayloader
    } else if (CodecQuery::IsBackendAvailable("openh264")) {
        std::cout << "Using OpenH264 software encoder\n";
        // Use RtpH264OpenH264Payloader
    } else {
        std::cerr << "No H.264 encoder available\n";
    }
}

List only hardware codecs:

auto hw = mediax::rtp::CodecQuery::GetHardwareCodecs();
for (const auto& c : hw) {
    std::cout << c.name << " - " << c.description
              << " [" << (c.available ? "ready" : "not available") << "]\n";
}

Find all H.264 backends:

auto h264 = mediax::rtp::CodecQuery::GetCodecsByColourspace(
    mediax::rtp::ColourspaceType::kColourspaceH264Part10);
for (const auto& c : h264) {
    std::cout << c.name << " (" << c.backend << ") "
              << (c.acceleration == mediax::rtp::AccelerationType::kHardware
                  ? "[HW]" : "[SW]")
              << "\n";
}

Complete Example

#include <iostream>
#include <vector>
#include "rtp/rtp.h"
#include "uncompressed/rtp_uncompressed_payloader.h"
#include "sap/sap_announcer.h"

int main() {
    // Configure stream
    mediax::rtp::StreamInformation stream_info;
    stream_info.session_name = "example-stream";
    stream_info.hostname = "239.192.1.1";
    stream_info.port = 5004;
    stream_info.width = 1920;
    stream_info.height = 1080;
    stream_info.framerate = 30;
    stream_info.encoding = mediax::rtp::ColourspaceType::kColourspaceRgb24;

    // Setup SAP announcer
    mediax::sap::SapAnnouncer announcer;
    announcer.AddSapAnnouncement(stream_info);
    announcer.Start();

    // Setup payloader
    mediax::rtp::uncompressed::RtpUncompressedPayloader payloader;
    payloader.SetStreamInfo(stream_info);
    payloader.Open();

    // Transmit frames
    std::vector<uint8_t> buffer(1920 * 1080 * 3);
    for (int i = 0; i < 100; ++i) {
        // Fill buffer with frame data...
        payloader.Transmit(buffer.data(), true);
    }

    // Cleanup
    payloader.Close();
    announcer.Stop();
    announcer.DeleteAllSapAnnouncements();

    return 0;
}

Linking

find_package(mediax REQUIRED)
target_link_libraries(your_app PRIVATE mediax::mediax)

GigE Vision API

Requires -DBUILD_GIGE=ON.

GigEDevice — camera emulation

#include "gige/gige_device.h"

class mediax::gige::GigEDevice {
public:
  /// Set manufacturer/model strings written into the GenICam XML
  void SetDeviceInfo(std::string_view manufacturer, std::string_view model,
                     std::string_view version, std::string_view serial,
                     std::string_view user_name);

  /// Set pixel format, resolution and frame rate
  void SetImageParams(uint32_t width, uint32_t height,
                      GvspPixelFormat pixel_format, uint32_t framerate);

  /// Register callbacks fired on AcquisitionStart / AcquisitionStop commands
  void SetAcquisitionStartCallback(std::function<void()> cb);
  void SetAcquisitionStopCallback(std::function<void()> cb);

  /// Open GVCP port (UDP 3956) — returns false if port unavailable
  bool Open();
  void Close();

  /// Returns true once the host has sent AcquisitionStart
  bool IsStreaming() const;

  /// Send one frame. Pixels must match the configured pixel format and dimensions.
  bool SendFrame(const uint8_t* pixels);
};

GigEReceiver — host-side receiver

#include "gige/gige_receiver.h"
#include "gige/gvsp/gvsp_receiver.h"

class mediax::gige::GigEReceiver {
public:
  /// Set the local UDP port for GVSP streaming (default 55100)
  void SetReceivePort(uint16_t port);

  /// Discover and connect to a GigE Vision device at device_ip via GVCP
  bool Connect(const std::string& device_ip);

  /// Configure stream channel and send AcquisitionStart
  bool Open();
  void Close();

  /// Receive one frame. Returns false on timeout (timeout_ms).
  bool Receive(gvsp::GvspFrameData* frame, int timeout_ms);
};

struct mediax::gige::gvsp::GvspFrameData {
  uint32_t width;
  uint32_t height;
  GvspPixelFormat pixel_format;
  std::vector<uint8_t> pixels;  ///< Raw pixel data
};

GvspPixelFormat enum

#include "gige/gige_types.h"

enum class mediax::gige::GvspPixelFormat : uint32_t {
  kMono8      = 0x01080001,  ///< 8-bit monochrome
  kMono16     = 0x01100007,  ///< 16-bit monochrome (big-endian)
  kRgb8       = 0x02180014,  ///< 24-bit RGB
  kBayerGr8   = 0x01080008,  ///< 8-bit Bayer, GR phase
  kBayerRg8   = 0x01080009,  ///< 8-bit Bayer, RG phase
  kBayerGb8   = 0x0108000A,  ///< 8-bit Bayer, GB phase
  kBayerBg8   = 0x0108000B,  ///< 8-bit Bayer, BG phase
  kYcbcr422_8 = 0x0210003B,  ///< YCbCr 4:2:2, 8-bit YUYV
};

Colourspace Conversion API

BayerPattern enum

#include "utils/colourspace.h"

enum class mediax::video::BayerPattern : uint8_t {
  kRggb = 0,  ///< R G / G B  (top-left pixel is Red)
  kGrbg = 1,  ///< G R / B G
  kGbrg = 2,  ///< G B / R G
  kBggr = 3,  ///< B G / G R  (top-left pixel is Blue)
};

ColourSpaceCpu

CPU scalar with optional AVX2 SIMD (auto-detected at runtime on x86_64).

#include "utils/colourspace_cpu.h"

class mediax::video::ColourSpaceCpu {
public:
  /// Bayer raw → RGB24 bilinear demosaic.
  /// Returns number of output bytes written, or 0 on error.
  int BayerToRgb(uint32_t height, uint32_t width,
                 const uint8_t* bayer, uint8_t* rgb,
                 BayerPattern pattern) const;

  /// RGB24 → Bayer raw (CFA channel selection — no averaging).
  /// Returns number of output bytes written, or 0 on error.
  int RgbToBayer(uint32_t height, uint32_t width,
                 const uint8_t* rgb, uint8_t* bayer,
                 BayerPattern pattern) const;

  // Other conversions:
  int RgbToYuv(uint32_t height, uint32_t width,
               const uint8_t* rgb, uint8_t* yuv) const;
  int YuvToRgb(uint32_t height, uint32_t width,
               const uint8_t* yuv, uint8_t* rgb) const;
  int RgbToMono(uint32_t height, uint32_t width,
                const uint8_t* rgb, uint8_t* mono) const;
  int ScaleToSizeRgb(uint32_t src_h, uint32_t src_w, const uint8_t* src,
                     uint32_t dst_h, uint32_t dst_w, uint8_t* dst) const;
};

ColourSpaceCuda

GPU-accelerated version with the same interface, plus CUDA kernels for Bayer demosaicing. Requires -DBUILD_CUDA=ON.

#include "utils/colourspace_cuda.h"

class mediax::video::ColourSpaceCuda {
public:
  int BayerToRgb(uint32_t height, uint32_t width,
                 const uint8_t* bayer, uint8_t* rgb,
                 BayerPattern pattern) const;
  int RgbToBayer(uint32_t height, uint32_t width,
                 const uint8_t* rgb, uint8_t* bayer,
                 BayerPattern pattern) const;
  // ... same interface as ColourSpaceCpu for all other methods
};

Support