.. _cpp_api:

C++ API Reference
=================

The ``epc::TOFCam`` API provides a high-level interface for controlling the EPC670
Time-of-Flight camera module and accessing captured frames.

Overview
--------

The API is split into two main classes:

- :cpp:class:`epc::TOFCam` — camera control: open/close, stream management, control parameters
- :cpp:class:`epc::TOFFrame` — frame data access: DCS, amplitude, distance, phase and metadata

A frame is always **owned by a** ``std::unique_ptr<TOFFrame>`` and is valid until the pointer
goes out of scope.

Quick Start
-----------

.. literalinclude:: ../../../samples/cpp_examples/src/cpp_api_example.cpp
   :language: cpp
   :linenos:

Frame Types
-----------

Use the following structs with ``TOFFrame::get<T>()`` to access typed frame data:

+------------------------------------+------------+----------+---------------------------+
| Tag struct                         | Data type  | Unit     | Description               |
+====================================+============+==========+===========================+
| ``epc::DCSFrame``                  | uint16_t   | LSB      | Raw DCS images            |
+------------------------------------+------------+----------+---------------------------+
| ``epc::AmplitudeFrame``            | uint16_t   | LSB      | Amplitude image           |
+------------------------------------+------------+----------+---------------------------+
| ``epc::DistanceFrame``             | uint16_t   | mm       | Computed distance image   |
+------------------------------------+------------+----------+---------------------------+
| ``epc::PhaseFrame``                | float      | radian   | Phase image               |
+------------------------------------+------------+----------+---------------------------+

API Documentation
-----------------

.. doxygenclass:: epc::TOFCam
   :project: epctofcam
   :members:
   :undoc-members:

.. doxygenclass:: epc::TOFFrame
   :project: epctofcam
   :members:
   :undoc-members:

.. doxygenstruct:: epc::TOFMetadata
   :project: epctofcam
   :members:

.. doxygenenum:: epc::FrameType
   :project: epctofcam

.. doxygenenum:: epc::TOFSensor
   :project: epctofcam


Control Parameters
------------------

The following control parameters can be passed to ``setControl()`` and ``getControl()``
as the first argument:

.. doxygenenum:: epc::ControlID
   :project: epctofcam

Acquisition Modes
-----------------

.. doxygenenum:: epc::AcquisitionMode
   :project: epctofcam
