WaitForFrame API signature mismatch: match your call to the SDK

You wrote the acquisition call exactly as the online class reference shows, and the compiler refuses it — or the call compiles and behaves nothing like the page promises. In the case behind this guide, a blocking frame call named WaitForFrame() in frame_grabber.h appeared with one form in the reference and returned std::shared_future<Frame::Ptr> in the header inside a container image tagged stable. Neither page is wrong: they describe two releases of one SDK. This guide shows you how to prove which generation your build actually calls, what a shared-future return changes in your code, how to size a wait timeout so a mismatch cannot hide, and how to pin one version across container, compiler and CI.

The decision: the header your compiler reads is the truth

Code to the signature that exists in the header set your build compiles against, and pin that set so it cannot drift. The online class reference is a secondary source until its version selector matches the installed release.

A container tag such as stable floats: the registry can serve a newer build the next time your pipeline pulls. If the header in that image declares std::shared_future<Frame::Ptr> as the return of WaitForFrame(), you are on the asynchronous generation of the API. Write the call for it, record the release, and stop reading a reference page from a different one. The same discipline applied to firmware and SDK together is in 3D camera header version mismatch: fix firmware and SDK alignment.

Why one call has two signatures

Three mechanisms produce the contradiction, in this order of likelihood:

1. Two releases, two pages. Documentation sites build a class reference per release, and the version selector opens on the newest. Your container image holds whichever release it was built with. The pages disagree because they are different documents, not because one is broken.
2. Two copies of the SDK on one build path. The compiler finds headers on the host while the runtime loads the library inside the container, or two installs fight over the include path. You read one header and the linker ships another.
3. An API change riding an ABI change. In C++ a changed return type is a recompile-everything event: "Programs compiled against version 1 of the library will not work with version 2 of the library without recompilation." Even a matching reference page does not excuse the rebuild.

Prove which generation you are calling

Two proofs: one at compile time, one at runtime.

The compile-time proof is a static assertion on the call's return type, in a small source file that includes only your SDK's acquisition header:

// Example probe — use your SDK's own header and type names
#include <type_traits>
#include <future>
#include "frame_grabber.h"

static_assert(std::is_same<
    decltype(std::declval<FrameGrabber&>().WaitForFrame()),
    std::shared_future<Frame::Ptr>>::value,
    "this build sees the shared_future generation of the API");

If the assertion fires, the header your compiler reads is not the one you read online, and no amount of doc reading will fix the build. The names here are the ones from the case that prompted this guide; keep the pattern and substitute your own.

The runtime proof is the version print. Most camera SDKs ship a version macro in a header and a command-line tool that reports the installed release. Run that tool from a shell inside the same image your CI builds against — not on the host — and copy the number into the build log. When the stack will not even start under the container runtime, running 3D camera control software in Docker: fix startup failures covers that layer first.

What a shared_future return changes in your code

A std::shared_future<Frame::Ptr> return is not a cosmetic difference. "std::shared_future supports multiple consumers of a shared result." Three consequences:

• get() can be called more than once, and every caller receives the same frame. One acquisition thread can feed a display loop, a processing stage and a logger from a single wait.
• Ownership is shared. The frame pointer is a reference-counted smart pointer: hold it as long as you use it, and never free it yourself — the library's destructor releases it when the last reference goes away.
• Blocking happens on the future, not inside your loop. Wait with a deadline, as in the next section, instead of calling get() bare — otherwise one lost frame hangs the thread.

Worked example: a 100 ms guard for a 30 fps stream with 10 ms exposure

Inputs, read from the camera's acquisition page; the two values here are example inputs for a typical stereo setup:

• Frame rate: 30 fps
• Exposure: 10 ms
• Tolerance: two consecutive missed frames before reconnect

The rule: the wait deadline must cover two full frame periods, so one late frame never reads as a fault.

Arithmetic:

• T_frame = 1000 ms / 30 = 33.3 ms
• Exposure 10 ms < 33.3 ms, so exposure sits inside one period and does not add to it
• t_wait = 2 × 33.3 ms = 66.7 ms → round up to 100 ms for trigger jitter and container scheduling

The loop that uses it, with the guard doing the diagnosis for you:

// Example: deadline from the worked example
const int fps = 30;                              // camera setting
const std::chrono::milliseconds t_wait{100};     // 2 frame periods, rounded up
int missed = 0;
// fg: the frame grabber object your SDK's builder returned
// reconnect(): your recovery routine

std::shared_future<Frame::Ptr> fut = fg->WaitForFrame();
if (fut.wait_for(t_wait) != std::future_status::ready) {
    ++missed;                                    // one late frame: not a fault
    if (missed >= 2) reconnect();                // two periods missed: real fault
} else {
    missed = 0;
    Frame::Ptr frame = fut.get();
}

Decision: with a 100 ms deadline, a healthy 30 fps stream returns in about 33 ms and never trips the guard; a mismatch that returns an invalid future or blocks forever declares itself within 100 ms. Keep exactly one wait call alive per frame — frame didn't arrive within timeout: one wait call per frame explains why extra waits steal frames from each other.

The fix: pin one version everywhere

1. Pin the exact SDK release in the container recipe — a digest or a full version tag, never a floating name.
2. Set the documentation site's version selector to that same release and bookmark it.
3. Delete the second SDK copy from the host or the image, so one header set exists on the build path.
4. Rebuild everything that links the library; the ABI note above makes recompilation mandatory, not optional.
5. Add the static assertion and the version print to CI, so the build fails loudly the day a signature moves again.

The container-build half of this — locking library versions in the recipe so a rebuild cannot pull a newer release — is covered in Docker build SDK version mismatch: pin one library version everywhere.

When the SDK is not the culprit

Some signature hunts end on the transport. A NIC driver, a frame grabber or a cable that drops link produces stalls that look exactly like an API fault, and the probe above is what separates them: if the assertion passes and the link counters still move, the fault sits below the library.

On the transport side, keep the card matched to the camera's interface — a PoE GigE card for a gigabit camera, a 10GigE card when the sensor streams at that rate.

On the sensor side, each family ships its own SDK generation, so a laser galvanometer stereo camera and a projected structured-light camera from the same shelf do not share headers.

Treat any 3D laser sensor as a laser product: respect the laser class on its label and never defeat its interlocks. The full 3D sensors and frame grabbers ranges list the current models.

Checks before you rebuild

• SDK version printed from inside the image, pasted into the CI log
• Documentation version selector set to that release
• One header set on the include path; the second copy deleted
• Static assertion on the acquisition call's return type passing
• Wait deadline equal to two frame periods, rounded up
• Reconnect after two consecutive missed frames, not before

Keep it from coming back

Pinning once is a snapshot; CI is the enforcement. Fail the build when the version print changes, and treat any signature change as a deliberate upgrade with a recompile and a changelog read, never as a surprise from a floating tag. The same pin-one-version rule holds across the whole automation stack — a PLC standard library version mismatch fix follows the identical discipline.

If the fault turns out to sit on the hardware side, the camera finder lists 3D sensors by type and the accessory finder lists frame grabbers by interface. Bring the SDK version line and the static-assert output to the contact page and we will narrow it down with you.