Stream buffer handling mode: set newest only on the transport layer

You set StreamBufferHandlingMode to newest only, the driver answers 'node not found', and the preview still shows an image several frames old. The failure is structural, not a typo: GenICam keeps the buffer handling controls in the transport layer's stream node map, while most camera drivers open and configure only the device feature map. Here you get the location of the node, the way to open the stream map in any acquisition stack, the latency arithmetic for all three modes, and the decision rule for when newest only is wrong. The whole calculation is one division: frame period in milliseconds equals 1000 divided by the frame rate.

Where does the stream buffer handling mode actually live?

The StreamBufferHandlingMode enum lives in the transport layer's stream node map, not in the camera's device feature map: GenICam puts it under the stream's Buffer Handling Control category, so a driver that opens only the device map cannot see or write it.

A GenICam camera exposes two node maps in daily use. The device map holds exposure, gain, ROI and triggering — everything the camera itself executes. The transport layer keeps its own maps, and once the driver allocates a stream, that stream carries a node map containing BufferHandlingControl and its StreamBufferHandlingMode enum. A GUI feature browser shows the node under the stream parameters tree for exactly this reason: the browser opens the stream map as well as the device map.

Search before you code. Load the device XML your SDK reports and look for StreamBufferHandlingMode: if it is absent there but visible in the GUI's stream parameters, the stream map is the only route. In GenTL terms the map hangs off the data-stream port you open after stream allocation. On the hardware side, the same stream discipline applies to any of the area scan cameras you shortlist.

Why does your configuration report the node not found?

Your driver's YAML or parameter file writes into the device node map, and that map contains no stream buffer handling node: the SDK has to allocate the stream and open the data-stream node map as a separate port before the enum exists to write.

The failure you saw is a flattened path — BufferHandlingControl/StreamBufferHandlingMode — resolved against the device map and rejected, so it is a wrong-map problem, not a spelling problem. Most drivers can prove it: many expose a dump flag (one open-source camera driver calls it dump_node_map) that prints every node they loaded. Run it and search the output; StreamBufferHandlingMode will not appear, because the map that holds it was never opened.

The fix therefore belongs in driver code, not in configuration. Recent drivers open the stream map automatically during stream setup; with older ones your application opens the data-stream port directly, as the next section shows.

What do the three GenICam buffer handling modes do?

The GenICam standard defines three values: NewestOnly hands you the latest completed frame and discards the rest, OldestFirst delivers every frame in order and waits when buffers run out, and OldestFirstOverwrite delivers in order but drops the oldest frame once the queue is full.

'Completed' means fully assembled: on a GigE Vision link, packet resends have already repaired loss before a frame enters this queue. The modes therefore decide delivery order, not link quality. Identifier gaps are normal under NewestOnly; under OldestFirst a gap is a genuine loss signal worth chasing.

How much latency does newest only remove?

Newest only caps the age of the image your code receives at one frame period: at 60 fps that is 16.7 ms, while a first-in-first-out queue that runs behind adds one frame period for every frame of backlog and grows without limit.

Worked example. The LS-CMR-0053 is a 12 MP GigE area scan camera streaming 9 fps. So T = 1000 / 9 = 111 ms, and a processing loop that needs 150 ms per image runs at 1000 / 150 = 6.7 fps, which makes an oldest-first backlog grow at 9.0 - 6.7 = 2.3 frames per second. A 10-buffer ring fills after 10 / 2.3 ≈ 4.3 s, by which time the oldest waiting image has aged 10 × 111 = 1110 ms, about 1.1 s. NewestOnly holds the delivered age between 0 and 111 ms — about 56 ms on average — however slow the loop becomes. At 60 fps the same rule caps worst-case delivery at 1000 / 60 = 16.7 ms.

The stale-frame symptom this removes, with its other causes and fixes, is worked through in Camera image latency: diagnose and reduce stale frames.

How do you set the mode on the stream node map?

Open the camera, allocate its stream, open the stream's node map as its own port, write NewestOnly to StreamBufferHandlingMode there, and read it back before you start acquisition; most stacks lock stream nodes while streaming.

1. Open the camera and its device node map as usual.
2. Allocate the stream and open the data-stream port that allocation returns — GenTL naming; your SDK may call it the transport-layer stream.
3. Open the node map attached to that port: this is the map your configuration file was missing.
4. Write NewestOnly to the enum StreamBufferHandlingMode; GUI trees spell the value Newest Only.
5. Read the enum back and confirm it holds NewestOnly.
6. Start acquisition, then run the slow-loop test below.

In the feature browser the same node sits under Stream Parameters, Buffer Handling Control, StreamBufferHandlingMode. In code the order matters: the enum becomes writable only after the stream exists, so set it in the acquisition setup path, never in a static camera configuration file.

How do you verify the mode took effect?

Delivered-frame age is the test: read each buffer's frame identifier and camera timestamp, compute age as receive time minus capture time, and confirm that under NewestOnly the age stays below one frame period while identifiers jump whenever your loop runs slow.

Force the condition instead of hoping for it. With the 9 fps camera above, set the processing loop to sleep 222 ms — twice the 111 ms frame period — for ten seconds and log what arrives. NewestOnly shows identifier gaps of two or more and a logged age that never exceeds 111 ms. OldestFirst shows gapless identifiers and an age that climbs past 500 ms within seconds.

If staleness survives the test, the queue you are reading sits downstream of the transport layer; the two common culprits and their cures are in Latest image only returns duplicate frames: drain the buffer queue and Torn frames in a camera callback: copy the buffer before you queue it.

When is newest only the wrong choice?

Any inspection where every part must be judged needs OldestFirst, because NewestOnly discards frames silently and a discarded frame is an uninspected part: keep newest only for display, robot guidance and tracking, where an image older than one frame period is already too late.

Decide by consumer behavior. Steady overload — the loop is permanently slower than the camera — is a processing problem, and no queue or mode hides it; the bottleneck arithmetic is in Acquisition faster than processing: fix the frame rate gap. Short bursts — the loop pauses for a second, then catches up — suit OldestFirstOverwrite with the ring sized for the longest burst: buffers = burst seconds × frame rate, plus two spare. At 9 fps and 2 s bursts that is 9 × 2 + 2 = 20 buffers. Multi-camera hosts running oldest-first FIFOs freeze when callbacks stall; the failure pattern and its cure are in Multi-camera acquisition freezes: callbacks and buffer queues.

So: preview, HMI and robot guidance get NewestOnly; inspection and measurement get OldestFirst; bursty consumers get OldestFirstOverwrite with a sized ring.

Which network hardware keeps a GigE stream loss-free?

A queue can only hand over frames the network delivered, so a GigE stream that loses packets or overruns its receive descriptors delivers old or incomplete data whatever mode you set: give each camera a dedicated NIC port or frame-grabber port instead of sharing the office interface.

Identifier gaps under OldestFirst point at the link or the host, never at the enum. Practical layout: one camera per host port, deterministic port assignment — the recipe is in Assign cameras to ports reliably in a multi-camera system — and an interface chosen for the cable run and bandwidth, which 5GBASE-T camera interface: bandwidth, cables and distance covers for copper.

The MV-GE2002P dual-port PoE GigE NIC puts a single camera stream on its own host interface.

The MV-GE1104 4-port GigE frame grabber gives a multi-camera host one dedicated port per camera.

For 10GigE streams, the MV-GT2104 quad-port copper 10GbE NIC is the matching card.

Browse the frame grabbers in the accessories finder for the rest of the range. If you are assembling a station rather than fixing one, the camera finder filters GigE models by resolution and shutter, the system configurator walks camera, lens, light and controller in order, and more acquisition-level fixes are collected on the systems topic page.