DvsenseDriver  1.3.0
The SDK for dvsense products.
Loading...
Searching...
No Matches
SDK 1.3.0 API Migration Guide

Language: Chinese

Version and Binary Compatibility

1.3.0 extends the fusion camera API and refactors its implementation. DvsenseBase, DvsenseHal, and DvsenseDriver shared-library SOVERSION values increase from 1 to 2. The ApsFrame layout and FusionCamera virtual interface have changed. Replacing shared libraries alone is insufficient: upgrade SDK and Insight together, and rebuild and relink all custom C++ applications and extension modules.

Custom FusionCamera subclasses must implement the new addSharedEventsStreamHandleCallback() and removeSharedEventsStreamHandleCallback() methods. Applications opening SDK cameras through DvsCameraManager::openFusionCamera() do not need to instantiate concrete camera classes.

Ubuntu support covers 22.04/24.04 on amd64 and arm64. 20.04 is no longer supported; 26.04 support is coming soon. See Software and SDK Installation.

Discovery and DVSyncPro

getCameraDescs() updates the device list. USB DVSync reports product DVSync; the on-camera MIPI device reports DVSyncPro with INTERFACE_TYPE::MIPI. The reference board currently uses the logical serial DVSyncPro-MIPI-0, not a unique serial stored in hardware. Open either device using openFusionCamera(desc.serial).

DVSyncCameraBase provides common fusion behavior, DVSyncCamera uses USB, and DVSyncProCamera uses on-camera Linux MIPI/V4L2. Windows packages do not provide internal MIPI acquisition. Reference-board DVSyncPro start() accepts only FUSION_STREAM; DVS-only and APS-only requests return an error. APS Master acquisition uses its dedicated sample.

For lower-level integration, see dvsense::DVSyncProInterface and dvsense::V4l2StreamConfig. Default V4L2, I2C, and PWM paths target the reference board and are not portable to arbitrary ARM boards. See DVSyncPro (Fusion Pro) Quick Start Guide for USB host use, the on-camera desktop, and WebRTC.

Event Callbacks and Shared Buffers

API Data lifetime Usage
FusionCamera::addEventsStreamHandleCallback() [begin, end) is valid only during the callback Process immediately or copy for asynchronous use
FusionCamera::addSharedEventsStreamHandleCallback() Valid until the last shared_ptr is released Retain the batch for a worker thread
DvsApsFusionProccessor::addFusionDataCallback() APS reference and DVS pointers are valid only during the callback Process matched data immediately
DvsApsFusionProccessor::addSharedFusionDataCallback() DVS buffer may be retained; APS reference is still callback-scoped Copy the ApsFrame object and retain the event shared_ptr

Shared callbacks do not create worker threads. Return promptly and avoid retaining an unbounded number of buffers. Shared ownership does not make concurrent mutation safe; consumers should treat input as read-only.

Remove camera-level shared callbacks with their independent IDs via removeSharedEventsStreamHandleCallback(id). The fusion processor stores one callback of each kind. When both are registered, the ordinary callback runs first. removeFusionDataCallback() removes both.

APS Frame Ownership

Copy construction and assignment of dvsense::ApsFrame share pixel storage; clone() performs a deep copy. The new constructor accepting std::shared_ptr<std::vector<uint8_t>> retains the buffer. Supply a non-null buffer containing at least width * height * 3 contiguous BGR888 bytes, and do not resize or reallocate it while frames use it.

The external-pointer constructor borrows memory with own_data=false and does not extend its lifetime. With own_data=true, it copies pixels into internal storage; it neither takes ownership of nor frees the supplied pointer.

DvsApsFusionProccessor::addApsData() deep-copies pixels. addSharedApsData() copies only the frame object and shares storage. Use it only when frame copies keep that storage alive, not with borrowed memory that may expire while queued.

Fusion Policy and Threading

// Default: no event truncation, retain queued synchronization groups.
// Preview: keep at most 200000 events per group and discard older queued input.
dvsense::DvsApsFusionProccessor preview_processor(200000, true);
Pair APS frames with completed DVS synchronization groups in FIFO order.
Definition DvsApsFusionProccessor.hpp:39

max_events_per_frame=0 disables the event limit; positive values discard excess events in each group. latest_only=true discards older queued input, making it suitable for low-latency preview rather than complete-data processing. The processor pairs APS frames in FIFO order with DVS groups closed by rising synchronization edges; it is not a general nearest-timestamp matcher.

Feed the three sources through addDvsData(), addSharedApsData() (or addApsData()), and addSyncSignal(). Fusion callbacks may execute before APS/sync input methods return and run with the queue mutex held. Do not call clear() or feed APS/sync input into the same processor from a callback. Register callbacks before starting acquisition. Callers must serialize DVS accumulation and callback changes; arbitrary concurrent calls are not supported.

Calibration and Python

Calibrator::mapApsToDvs() still returns a newly allocated frame. The new mapApsToDvsBgr(src, dst, dst_size) writes into reusable caller-owned storage. Supply at least dvs_cols * dvs_rows * 3 output bytes from the calibration dimensions, and contiguous BGR888 input matching the calibrated APS dimensions. Output has DVS dimensions, with out-of-image mappings filled black. A null destination or insufficient output capacity returns false. mapDvsToAps(begin, end) modifies event coordinates in place and does not return an image.

Python adds DvsApsFusionProccessor.connect_camera(camera), which connects event, APS, and synchronization inputs internally in C++. Keep the returned DvsApsFusionConnection alive. Stop acquisition with camera.stop() before calling connection.disconnect(). add_fusion_data_callback() now uses shared event storage internally; a capsule keeps the callback's NumPy event array backed by valid storage.

Calibrator.render_fusion(aps_frame, events) performs mapping and event overlay in C++, releasing the GIL during computation. Python does not directly expose the C++ shared methods above or mapApsToDvsBgr(); converting their names to snake_case does not produce valid Python APIs. See python/samples/dvsync_camera_sample.py for the complete workflow.

Optional Samples

dvsense_fusion_sync_viewer supports the DVSync family. Linux WebRTC samples require GStreamer, libsoup 3, and json-glib; the APS Master sample additionally requires Rockchip RKAIQ. Source-build options are BUILD_DVSYNCPRO_WEBRTC_VIEWER and BUILD_DVSYNCPRO_APS_MASTER_WEBRTC_VIEWER, both disabled by default and requiring BUILD_SAMPLES. The development package supplies sample source code; the default precompiled Samples package omits these two optional executables.