RawBufferFd Struct Reference

Validity-tracked handle to a native DMA buffer (dmabuf) file descriptor from the camera capture pool. More...

Functions
bool	isValid () const noexcept
	Check whether the capture pool that minted this descriptor is still alive. More...
	operator bool () const noexcept
	Same as isValid(). More...

Attributes
int	fd = -1
	The dmabuf file descriptor, valid in the current process. -1 if unset. More...
uint64_t	generation = 0
	Generation counter of the capture pool that minted this descriptor. More...

Detailed Description

Validity-tracked handle to a native DMA buffer (dmabuf) file descriptor from the camera capture pool.

On Jetson GMSL cameras captured through the Argus pipeline, the capture pre-allocates a fixed pool of dmabuf buffers at open time and cycles them for the whole capture session. This handle wraps one of those file descriptors together with a liveness hook so that a stale descriptor can be detected after the pool has been retired.

Typical use is a zero-copy publisher/subscriber system: query the full pool once with Camera::getRawBufferPoolFds(), send the descriptors to each subscriber a single time (e.g. over a Unix socket with SCM_RIGHTS), then publish only {generation, fd} per frame through shared memory, with no syscall in the per-frame path. Per-frame handles are available through RawBuffer::getFd() / RawBuffer::getFdRight() and match the pool entries by fd value within the same generation.

Warning

The pool is NOT stable across camera recovery: when the capture recovers from a freeze (or the camera is closed), all descriptors are destroyed and, on recovery, a new pool with a new generation is allocated. isValid() flips to false before the old descriptors are destroyed. The OS may recycle the same integer fd values for the new pool, so never compare raw fd numbers across generations: re-query the pool and re-share it with subscribers whenever isValid() returns false (or retrieveImage() returns ERROR_CODE::CAMERA_REBOOTING).

Note

isValid() is advisory (the pool can be retired right after the call). This is safe by construction for subscribers: a descriptor received via SCM_RIGHTS is a kernel-level duplicate that keeps the underlying memory alive, so the worst case is processing a stale frame, never a dangling mapping. In the publisher process itself, do not use fd after isValid() returns false, as the integer may have been recycled by the OS for an unrelated resource.

Not supported on the HDR camera family (ZED X HDR / HDR Mini / HDR Max, ZED X One HDR): these models use a different V4L2 capture backend (sensor-side ISP) that does not expose a stable dmabuf pool. On these cameras Camera::getRawBufferPoolFds() returns ERROR_CODE::INVALID_FUNCTION_CALL and per-frame handles always report isValid() == false.

Functions

isValid()

bool isValid ( ) const

inlinenoexcept

Check whether the capture pool that minted this descriptor is still alive.

Returns

true if fd is set and the pool has not been retired (camera close or internal recovery).

Note

Lock-free and syscall-free (one atomic load), safe to call in the per-frame hot path.

operator bool()

operator bool ( ) const

inlineexplicitnoexcept

Same as isValid().

Variables

fd

int fd = -1

The dmabuf file descriptor, valid in the current process. -1 if unset.

generation

uint64_t generation = 0

Generation counter of the capture pool that minted this descriptor.

Bumped each time the pool is (re)allocated (open or internal recovery). Use it to tag per-frame messages so subscribers can detect that a descriptor belongs to a retired pool.