Refactor tracker creation pattern

Author: nvddr

docs/source/device/add_device.rst

@@ -14,8 +14,14 @@ The reference implementation is the **generic 3-axis foot pedal**:
      - :code-file:`src/core/schema/fbs/pedals.fbs`
    * - Device Plugin
      - :code-dir:`src/plugins/generic_3axis_pedal`
-   * - Device Tracker
-     - :code-file:`src/core/deviceio/cpp/generic_3axis_pedal_tracker.cpp`
+   * - Tracker facade (``Generic3AxisPedalTracker``)
+     - :code-file:`src/core/deviceio_trackers/cpp/generic_3axis_pedal_tracker.cpp` and
+       :code-file:`src/core/deviceio_trackers/cpp/inc/deviceio/generic_3axis_pedal_tracker.hpp`
+   * - Live backend (``LiveGeneric3AxisPedalTrackerImpl``)
+     - :code-file:`src/core/deviceio_live_implementation/cpp/live_generic_3axis_pedal_tracker_impl.cpp` and
+       :code-file:`src/core/deviceio_live_implementation/cpp/live_generic_3axis_pedal_tracker_impl.hpp`
+   * - ``SchemaTracker`` / ``SampleResult``
+     - :code-file:`src/core/deviceio_live_implementation/cpp/inc/deviceio_live_implementation/schema_tracker.hpp`
    * - Debug printer
      - :code-file:`examples/schemaio/pedal_printer.cpp`
 
@@ -93,18 +99,26 @@ Step 3: Implement a tracker
 ----------------------------
 
 The tracker runs inside a consumer process (e.g. Teleop pipeline or a small reader app). It
-implements the **ITracker** interface and uses **SchemaTracker** (from the ``deviceio`` library)
-to read raw tensor samples from OpenXR. Implement a concrete tracker class (e.g.
+implements the **ITracker** interface (tracker **facade** in ``deviceio_trackers``); the
+**live backend** in ``deviceio_live_implementation`` composes **SchemaTracker** to read raw
+tensor samples from OpenXR. Implement a concrete tracker class (e.g.
 ``Generic3AxisPedalTracker``) that:
 
 - **Extends ITracker** — Override ``get_required_extensions()``, ``get_name()``,
   ``get_schema_name()``, ``get_schema_text()``, and ``get_record_channels()``. Return
   ``SchemaTracker::get_required_extensions()`` for extensions; return the Record type name
   and binary schema for MCAP; return at least one channel name.
-- **Holds SchemaTrackerConfig** — Same logical fields as the pusher: ``collection_id``,
-  ``max_flatbuffer_size``, ``tensor_identifier``, ``localized_name``. Must match the plugin.
-- **create_tracker()** — Return an ``ITrackerImpl`` that holds a ``SchemaTracker`` and
-  implements ``update(XrTime)`` and ``serialize_all(channel_index, callback)``.
+- **Holds user configuration** — Same logical inputs as the pusher (e.g. ``collection_id``,
+  ``max_flatbuffer_size``). The live ``ITrackerImpl`` builds the internal tensor settings
+  (``SchemaTrackerConfig``) so they match the plugin.
+- **create_tracker_impl(TrackerFactory&)** — Override this to delegate to the provided
+  ``TrackerFactory``. The implementation uses double dispatch: call the factory method
+  specific to your tracker type (e.g.
+  ``factory.create_generic_3axis_pedal_tracker_impl(this)``) and return the resulting
+  ``std::unique_ptr<ITrackerImpl>``. The factory constructs an ``ITrackerImpl`` that holds
+  a ``SchemaTracker``, builds a ``SchemaTrackerConfig`` from the tracker's stored
+  configuration, and implements ``update(XrTime)`` and
+  ``serialize_all(channel_index, callback)``.
 
 In the **Impl**:
 
@@ -118,11 +132,19 @@ In the **Impl**:
   device disappeared and there are no samples, you may emit one record with null data and
   the update-tick timestamp so the MCAP stream marks absence.
 
-Reference implementation: :code-file:`src/core/deviceio/cpp/generic_3axis_pedal_tracker.cpp`. It
-composes ``SchemaTracker``, implements ``Impl::update()`` and ``Impl::serialize_all()``,
-and exposes ``get_data(session)`` returning ``Generic3AxisPedalOutputTrackedT``. See also
-:code-file:`inc/deviceio/schema_tracker.hpp <src/core/deviceio/cpp/inc/deviceio/schema_tracker.hpp>` for ``SchemaTracker`` and ``SampleResult`` (buffer +
-timestamp).
+Reference implementation — split across facade and live backend:
+
+- **Tracker facade** — :code-file:`src/core/deviceio_trackers/cpp/generic_3axis_pedal_tracker.cpp`
+  (class ``Generic3AxisPedalTracker``): holds collection configuration, implements ``ITracker`` and
+  ``create_tracker_impl(TrackerFactory&)``, and exposes ``get_data(session)`` returning
+  ``Generic3AxisPedalOutputTrackedT`` by dispatching to the session’s
+  ``Generic3AxisPedalTrackerImpl`` (see :code-file:`src/core/deviceio_base/cpp/inc/deviceio_base/generic_3axis_pedal_tracker_impl.hpp`).
+- **Live backend** — :code-file:`src/core/deviceio_live_implementation/cpp/live_generic_3axis_pedal_tracker_impl.cpp`
+  (``LiveGeneric3AxisPedalTrackerImpl``): composes ``SchemaTracker``, implements ``update()`` and
+  ``serialize_all()``, and uses ``SchemaTracker::read_all_samples()`` with
+  ``std::vector<SchemaTracker::SampleResult>`` for the pending batch. See
+  :code-file:`src/core/deviceio_live_implementation/cpp/inc/deviceio_live_implementation/schema_tracker.hpp`
+  for ``SchemaTracker`` and ``SampleResult`` (buffer + timestamp metadata).
 
 Step 4: Implement a simple C++ printer (optional)
 -------------------------------------------------
@@ -182,13 +204,14 @@ Both exit after 100 samples, or press Ctrl+C to exit early.
   extensions: takes externally-provided OpenXR session handles, creates a tensor collection with
   the configured identifier, provides ``push_buffer()`` for raw serialized data. Use composition
   to create typed wrappers (e.g. ``Generic3AxisPedalPusher`` in :code-file:`examples/schemaio/pedal_pusher.cpp`).
-- **SchemaTracker** (``deviceio`` library) — Base for reading FlatBuffer schema data via OpenXR:
-  implements ``ITracker`` for use with ``DeviceIOSession``, discovers collections by identifier,
-  exposes ``read_all_samples()``; subclasses implement ``update()`` to deserialize and
-  ``serialize_all()`` to re-serialize typed data.
-- **Generic3AxisPedalTracker** — Concrete tracker for ``Generic3AxisPedalOutput``: extends
-  ``SchemaTracker`` with schema-specific deserialization and provides ``get_data()`` for the latest
-  ``Generic3AxisPedalOutputT``.
+- **SchemaTracker** (``deviceio_live_implementation``) — Helper for reading FlatBuffer schema data via
+  OpenXR tensor collections: discovers collections by identifier, exposes ``read_all_samples()`` into
+  ``SampleResult`` values. Live tracker implementations (e.g. ``LiveGeneric3AxisPedalTrackerImpl``)
+  compose a ``SchemaTracker`` and implement ``ITrackerImpl::update()`` / ``serialize_all()``.
+- **Generic3AxisPedalTracker** (tracker facade in ``deviceio_trackers``) — Concrete ``ITracker`` for
+  ``Generic3AxisPedalOutput``: holds configuration, implements ``create_tracker_impl()``, and
+  ``get_data(session)`` returning ``Generic3AxisPedalOutputTrackedT`` via the session’s
+  ``Generic3AxisPedalTrackerImpl``.
 - **DeviceIOSession** — Session manager: collects required OpenXR extensions from registered
   trackers, creates tracker implementations with session handles, and calls ``update()`` on all
   trackers during the update loop.

docs/source/device/trackers.rst

@@ -1,8 +1,8 @@
 Device Trackers
 ===============
 
-Trackers (defined in :code-dir:`src/core/deviceio`) are the consumer-side API for reading device
-data from an active :code-file:`DeviceIOSession <src/core/deviceio/cpp/inc/deviceio/deviceio_session.hpp>`.
+Trackers (defined in :code-dir:`src/core/deviceio_trackers`) are the consumer-side API for reading device
+data from an active :code-file:`DeviceIOSession <src/core/deviceio_session/cpp/inc/deviceio/deviceio_session.hpp>`.
 Each tracker manages one logical device, queries the OpenXR runtime every frame,
 and exposes the latest sample through typed ``get_*()`` accessors.
 
@@ -11,17 +11,17 @@ There are two categories of trackers:
 **OpenXR-direct trackers** -- read pose and input data through standard OpenXR
 APIs (``xrLocateSpace``, ``xrSyncActions``, etc.):
 
-- :code-file:`HeadTracker <src/core/deviceio/cpp/inc/deviceio/head_tracker.hpp>` -- HMD head pose
-- :code-file:`HandTracker <src/core/deviceio/cpp/inc/deviceio/hand_tracker.hpp>` -- articulated hand joints (left and right)
-- :code-file:`ControllerTracker <src/core/deviceio/cpp/inc/deviceio/controller_tracker.hpp>` -- controller poses and button/axis inputs (left and right)
-- :code-file:`FullBodyTrackerPico <src/core/deviceio/cpp/inc/deviceio/full_body_tracker_pico.hpp>` -- 24-joint full body pose (PICO ``XR_BD_body_tracking``)
+- :code-file:`HeadTracker <src/core/deviceio_trackers/cpp/inc/deviceio/head_tracker.hpp>` -- HMD head pose
+- :code-file:`HandTracker <src/core/deviceio_trackers/cpp/inc/deviceio/hand_tracker.hpp>` -- articulated hand joints (left and right)
+- :code-file:`ControllerTracker <src/core/deviceio_trackers/cpp/inc/deviceio/controller_tracker.hpp>` -- controller poses and button/axis inputs (left and right)
+- :code-file:`FullBodyTrackerPico <src/core/deviceio_trackers/cpp/inc/deviceio/full_body_tracker_pico.hpp>` -- 24-joint full body pose (PICO ``XR_BD_body_tracking``)
 
 **SchemaTracker-based trackers** -- create new device type by defining a FlatBuffer schema and
 reading it from OpenXR tensor collections via the
-:code-file:`SchemaTracker <src/core/deviceio/cpp/inc/deviceio/schema_tracker.hpp>` utility.
+:code-file:`SchemaTracker <src/core/deviceio_live_implementation/cpp/inc/deviceio_live_implementation/schema_tracker.hpp>` utility.
 
-- :code-file:`FrameMetadataTrackerOak <src/core/deviceio/cpp/inc/deviceio/frame_metadata_tracker_oak.hpp>` -- per-stream frame metadata from OAK cameras
-- :code-file:`Generic3AxisPedalTracker <src/core/deviceio/cpp/inc/deviceio/generic_3axis_pedal_tracker.hpp>` -- foot pedal axis values
+- :code-file:`FrameMetadataTrackerOak <src/core/deviceio_trackers/cpp/inc/deviceio/frame_metadata_tracker_oak.hpp>` -- per-stream frame metadata from OAK cameras
+- :code-file:`Generic3AxisPedalTracker <src/core/deviceio_trackers/cpp/inc/deviceio/generic_3axis_pedal_tracker.hpp>` -- foot pedal axis values
 
 All trackers follow the same lifecycle:
 
@@ -203,7 +203,7 @@ FrameMetadataTrackerOak
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 Multi-channel tracker for per-frame metadata from OAK camera streams.
-Uses the :code-file:`SchemaTracker <src/core/deviceio/cpp/inc/deviceio/schema_tracker.hpp>`
+Uses the :code-file:`SchemaTracker <src/core/deviceio_live_implementation/cpp/inc/deviceio_live_implementation/schema_tracker.hpp>`
 utility internally.
 
 - Schema: :code-file:`src/core/schema/fbs/oak.fbs`
@@ -224,7 +224,7 @@ Generic3AxisPedalTracker
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 Reads foot pedal axis values pushed by a device plugin through OpenXR tensor
-collections. Uses the :code-file:`SchemaTracker <src/core/deviceio/cpp/inc/deviceio/schema_tracker.hpp>`
+collections. Uses the :code-file:`SchemaTracker <src/core/deviceio_live_implementation/cpp/inc/deviceio_live_implementation/schema_tracker.hpp>`
 utility internally.
 
 - Schema: :code-file:`src/core/schema/fbs/pedals.fbs`

src/core/CMakeLists.txt

@@ -21,8 +21,15 @@ add_subdirectory(oxr)
 # Build PusherIO library (depends on oxr for session management)
 add_subdirectory(pusherio)
 
-# Build DEVICEIO library first (depends on oxr_utils for types)
-add_subdirectory(deviceio)
+# DeviceIO: 4-module design
+#   1. deviceio_base           — abstract interfaces (ITracker, TrackerFactory, typed impl bases)
+#   2. deviceio_trackers       — public tracker classes (HeadTracker, HandTracker, etc.)
+#   3. deviceio_live_implementation — live OpenXR tracker impls (depends on trackers)
+#   4. deviceio_session        — DeviceIOSession + backward-compat deviceio_core INTERFACE
+add_subdirectory(deviceio_base)
+add_subdirectory(deviceio_trackers)
+add_subdirectory(deviceio_live_implementation)
+add_subdirectory(deviceio_session)
 
 # Build MCAP library (depends on deviceio for DeviceIOSession and tracker interfaces)
 add_subdirectory(mcap)