camera_frame.h File Reference

Zero-copy container for a single image / video frame plus pixel-format metadata. More...

#include <cstdint>
#include <string_view>
#include "../base/bytes.h"
#include "./header.h"

Include dependency graph for camera_frame.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Namespaces
	vlink
	vlink::zerocopy

Functions
struct	vlink::zerocopy::VLINK_EXPORT_AND_ALIGNED (8) AudioFrame final

Detailed Description

Zero-copy container for a single image / video frame plus pixel-format metadata.

CameraFrame is the canonical conduit for camera capture, ISP outputs, and compressed video streams in the VLink autonomous-driving stack. One frame carries pixel data (raw or codec-encoded), resolution, pixel format, camera channel id, capture frequency, video stream-frame type (I/P/B), plus a 40-byte Header for sequencing and dual-timestamp latency measurement.

Pixel formats

Enum	Family	Description
kFormatYuv420	Planar YUV	4:2:0 (I420)
kFormatYuv422	Planar YUV	4:2:2
kFormatYuv444	Planar YUV	4:4:4
kFormatNv12	Semi-planar YUV	Y plane + interleaved UV (4:2:0)
kFormatNv21	Semi-planar YUV	Y plane + interleaved VU (4:2:0)
kFormatYuyv	Packed YUV	YUYV 4:2:2
kFormatYvyu	Packed YUV	YVYU 4:2:2
kFormatUyvy	Packed YUV	UYVY 4:2:2
kFormatVyuy	Packed YUV	VYUY 4:2:2
kFormatBgr888Packed	Packed RGB	24-bit BGR, 3 bytes per pixel
kFormatRgb888Packed	Packed RGB	24-bit RGB, 3 bytes per pixel
kFormatRgb888Planar	Planar RGB	Separate R, G, B planes
kFormatMono8, kFormatMono16	Grayscale	8/16-bit mono image
kFormatRgba8888Packed, kFormatBgra8888Packed	Packed RGB	32-bit RGBA / BGRA
kFormatUint8C1 .. kFormatFloat64C4	OpenCV/ROS	Generic numeric images
kFormatBayerRggb8 .. kFormatBayerGrbg16	Bayer	RGGB/BGGR/GBRG/GRBG, 8/16-bit
kFormatJpeg, kFormatMjpeg	Compressed image	JPEG / Motion-JPEG
kFormatPng, kFormatWebp	Compressed image	PNG / WebP
kFormatH264, kFormatH265	Compressed video	H.264 / H.265
kFormatH266, kFormatAv1	Compressed video	H.266 / AV1

Image buffer layout

Planar YUV 4:2:0 (I420):
    +---------------------------+
    | Y plane  (width * height) |
    +---------------------------+
    | U plane  (width/2 * h/2)  |
    +---------------------------+
    | V plane  (width/2 * h/2)  |
    +---------------------------+
 
Semi-planar NV12/NV21:
    +---------------------------+
    | Y plane   (width * height)|
    +---------------------------+
    | UV or VU  (width * h / 2) |
    +---------------------------+
 
Packed RGB888:
    [ R G B | R G B | R G B | ... ]   stride = width * 3
 
Compressed JPEG/PNG/WebP/MJPEG/H.26x/AV1:
    opaque codec bitstream of size_ bytes

Wire format

CameraFrame is POD; the canonical serialiser is memcpy. The sizeof value is locked by static_assert and forms a permanent contract: vlink::zerocopy::* containers offer NO forward and NO backward binary compatibility – every field, including reserved bytes, is wire-locked.

static_assert(sizeof(CameraFrame) == 80, "Sizeof must be 80 bytes.");

Memory layout

Offset  Size  Field
------  ----  ----------------------
     0    40  Header   header
    40     8  uint8_t* data_
    48     8  size_t   size_
    56     4  uint32_t channel_
    60     4  uint32_t width_
    64     4  uint32_t height_
    68     4  uint32_t freq_
    72     1  Format   format_
    73     1  Stream   stream_
    74     1  bool     is_owner_
    75     1  (padding)
    76     4  uint32_t reserved_buf_
------  ----  ----------------------
 Total    80  bytes (alignas 8)
 
Wire envelope:
[ magic_begin (4) | version (4) | CameraFrame struct (80) | pixel bytes (size_) | magic_end (4) ]

Reserved bytes

reserved_buf_ is exposed through get_reserved() and persists through both clear() and the copy / move helpers so application bridges can stash minor identifiers. It is part of the wire contract and MUST NOT be redefined: future library revisions may bind the slot to a real field.

Example

vlink::zerocopy::CameraFrame frame;
frame.set_width(1920);
frame.set_height(1080);
frame.set_format(vlink::zerocopy::CameraFrame::kFormatNv12);
frame.create(1920 * 1080 * 3 / 2);
 
// Intra-process zero-copy publishing (no serialisation hop):
VLINK_INTRA_DATA_DECLARE(vlink::zerocopy::CameraFrame, "camera/front");
vlink::Bytes wire;
frame >> wire;