Migrating to libfreenect2 0.4

Table of Contents

• Language and platform floor
• Typed caller-owned frames
• Runtime statistics
• Calibration and registration
• Recording format
• Upgrade checklist

Version 0.4 adds conventional projective calibration, runtime health snapshots, and recording manifest version 2. The shared-library ABI changes from 0.3 to 0.4; rebuild all C++ consumers and bindings.

Language and platform floor

All targets now require C++17. CMake enforces CMAKE_CXX_STANDARD=17, disables compiler extensions, and exports API version 0.4. The supported Linux floor is Ubuntu 22.04 or an equivalent toolchain; Ubuntu 24.04 remains the primary CI matrix.

Downstream targets should request the same standard:

find_package(freenect2 0.4 REQUIRED)
target_link_libraries(my_target PRIVATE freenect2::freenect2)
target_compile_features(my_target PRIVATE cxx_std_17)

Typed caller-owned frames

The four-argument Frame(width, height, bytes, data) constructor remains source-compatible and still defaults to Frame::Invalid. New code should use the format-aware overload:

libfreenect2::Frame depth(width, height, sizeof(float), bytes,
                         libfreenect2::Frame::Float);

Consumers validate formats, so setting the type at construction prevents a partially initialized wrapper from reaching registration or vision code.

Runtime statistics

Freenect2Device::getRuntimeStatistics() returns a thread-safe snapshot. It includes start/stop/disconnect/stall counters and per-stream decoded frames, status errors, sequence gaps, and the most recent sequence, device timestamp, and host-arrival timestamp. Counters live for the device object's lifetime and are available for both live and replay devices. The call is observational; it does not reconnect or alter lifecycle state.

Calibration and registration

CalibrationProfile and ProjectiveRegistration are described in Conventional camera calibration profiles. Existing Registration behavior and factory calibration structs are retained. Choose explicitly:

• use Registration for Kinect factory polynomial color/depth mapping;
• use ProjectiveRegistration when you have conventional intrinsics and a measured rigid extrinsic transform.

Depth correction remains opt-in in both workflows.

Recording format

RecordingWriter publishes manifest version 2 when a canonical profile is attached and version 1 otherwise, so profile-less 0.4 recordings remain readable by 0.3 consumers. Version 2 has the same streams, clock semantics, durability protocol, and journal as version 1, plus an optional safe relative canonical-profile path. Readers accept both versions. A missing, malformed, or unsafe attached profile causes version-2 replay validation to fail; a serial-mismatched profile is accepted when the manifest records the writer's allow_serial_mismatch opt-in. The manifest is not signed, so that flag records intent rather than proving it.

Applications that construct internal manifest fixtures must accept versions 1 and 2. Public recording code should use RecordingWriter and Freenect2Replay::openRecording() rather than parsing JSON itself.

Upgrade checklist

1. Rebuild every binary consumer for ABI 0.4 and C++17.
2. Use the format-aware Frame constructor for external buffers.
3. Keep factory Registration unless a conventional profile is intentional.
4. Decide whether scalar depth correction should be enabled; it is never silently applied.
5. Update recording validators to accept manifest version 2 while retaining version 1 fixtures.
6. Surface runtime-statistics counters in the host application's existing observability system if desired.