dl::V2::ISensor Class Reference

Extended sensor interface: zero-copy frame delivery into caller-owned image buffers. More...

#include <dlapi.h>

Public Member Functions
virtual size_t	getMinImageBufferPx () const =0
	getMinImageBufferPx()
virtual bool	registerImageBuffers (unsigned short *const *pBuffers, size_t count, size_t bufferPx)=0
	registerImageBuffers() Register a pool of caller-owned buffers for direct frame reconstruction.
virtual void	unregisterImageBuffers ()=0
	unregisterImageBuffers() Return to internal DLAPI-owned buffering. After this call DLAPI holds no reference to the registered memory (the caller may free it), and the previously delivered image (ISensor::getImage()) is invalid until the next download completes.
virtual size_t	getLastFilledBufferIndex () const =0
	getLastFilledBufferIndex()

Static Public Attributes
static const size_t	NoBufferFilled = static_cast<size_t>(0) - 1
	Sentinel returned by getLastFilledBufferIndex() before the first completed frame.

Detailed Description

Extended sensor interface: zero-copy frame delivery into caller-owned image buffers.

Obtain via dynamic_cast<dl::V2::ISensor*>(pCamera->getSensor(n)); a nullptr means this DLAPI build predates the interface. Supported only on network streaming sensors - getMinImageBufferPx() returns non-zero after ICamera::initialize() when supported.

Usage:

1. Initialize the camera.
2. Allocate count >= 2 buffers of at least getMinImageBufferPx() unsigned shorts each.
3. Call registerImageBuffers(). Frames are then reconstructed directly into your buffers in strict round-robin order: when a startDownload() promise completes successfully, the buffer at getLastFilledBufferIndex() holds the frame, and ISensor::getImage()->getBufferData() returns that same pointer (zero copies).

Contract / ownership:

• Registered buffers are BORROWED by DLAPI from registerImageBuffers() until unregisterImageBuffers(); they must stay alive for that entire window. DLAPI never frees them.
• DLAPI writes only the next rotation slot, so the last delivered slot stays valid for (count - 1) further successful downloads.
• A failed download does NOT advance the rotation; the same slot (possibly holding partial data) is the target of the next attempt.
• Frames are delivered RAW: the full sensor frame, unbinned, uncropped, margins included. Pixel post-processing (subframe crop, software binning, descrambling) is skipped in this mode; metadata-only processing (extended metadata keys, OOB readout diagnostics) still runs. Subframes are injected at their true rows within the full frame.
• Buffer sizing is full-frame, so subframe/geometry changes never require re-registration.
• registerImageBuffers()/unregisterImageBuffers() while a download is in progress fail (return false / no-op). The calls are thread-safe with respect to each other, but must not race ISensor::startDownload(); register between downloads.
• Pre-fault the buffers (e.g. write a byte per 4 KB page) before rapid imaging to avoid first-touch page faults on the download thread.

Member Function Documentation

getLastFilledBufferIndex()

virtual size_t dl::V2::ISensor::getLastFilledBufferIndex ( ) const

pure virtual

getLastFilledBufferIndex()

Returns

the index (into the registered array) of the buffer holding the most recently completed frame, or NoBufferFilled if none has completed since registration.

getMinImageBufferPx()

virtual size_t dl::V2::ISensor::getMinImageBufferPx ( ) const

pure virtual

getMinImageBufferPx()

Returns

the minimum capacity, in pixels (unsigned shorts), each registered buffer must have: full sensor width x height. Returns 0 if the sensor does not support caller-registered buffers (non-streaming transport, or before initialization).

registerImageBuffers()

virtual bool dl::V2::ISensor::registerImageBuffers ( unsigned short *const * pBuffers, size_t count, size_t bufferPx )

pure virtual

registerImageBuffers() Register a pool of caller-owned buffers for direct frame reconstruction.

Parameters

pBuffers	an array of count pointers, each to a buffer of bufferPx unsigned shorts.
count	the number of buffers; must be >= 2 (2 = classic ping-pong).
bufferPx	the capacity of EACH buffer in pixels; must be >= getMinImageBufferPx().

Returns

true on success; false on invalid arguments, an unsupported sensor, or a download in progress. Replaces any previous registration and resets the rotation to buffer 0 (getLastFilledBufferIndex() returns NoBufferFilled).

unregisterImageBuffers()

virtual void dl::V2::ISensor::unregisterImageBuffers ( )

pure virtual

unregisterImageBuffers() Return to internal DLAPI-owned buffering. After this call DLAPI holds no reference to the registered memory (the caller may free it), and the previously delivered image (ISensor::getImage()) is invalid until the next download completes.

Member Data Documentation

NoBufferFilled

const size_t dl::V2::ISensor::NoBufferFilled = static_cast<size_t>(0) - 1

static

Sentinel returned by getLastFilledBufferIndex() before the first completed frame.

---

The documentation for this class was generated from the following file:

• C:/Users/arobi/Perforce/nightly/DL_Imaging/Aluma_Software/dlapi/src/dlapi.h