.. |sdkname| replace:: Astra

************************
4 Retrieving Stream Data
************************
Stream Types
============

The |sdkname| SDK comes "stock" with a variety of stream types. Low-level stream types are generated by the sensor and passed along through the SDK to an application. Higher-level stream types are efficiently computed from low-level stream types by SDK plugins. In general, higher-level streams should be preferred to the low-level ones when they can be used.

Low Level
---------
+----------------+------------------------------------------------------------------------+
|Stream Type     |Description                                                             |
+================+========================================================================+
|ColorStream     | RGB pixel data from the sensor.  The ``data`` array included           |
|                | in each ``ColorFrame`` contains values ranging from 0-255              |
|                | for each color component of each pixel.                                |
+----------------+------------------------------------------------------------------------+
|DepthStream     | Depth data from the sensor. The ``data`` array included in each        |
|                | ``DepthFrame`` contains values in millimeters for each pixel           |
|                | within the sensor's field of view.                                     |
+----------------+------------------------------------------------------------------------+

Higher-Level
------------
+----------------+------------------------------------------------------------------------+
|Stream Type     |Description                                                             |
+================+========================================================================+
|PointStream     | World coordinates (XYZ) computed from the depth data.                  |
|                | The ``data`` array included in each ``PointFrame`` is an               |
|                | array of ``astra:Vector3f`` elements to more easily                    |
|                | access the ``x``, ``y`` and ``z`` values for each pixel.               |
+----------------+------------------------------------------------------------------------+
|HandStream      | Hand points computed from the depth data. On each ``HandFrame``,       |
|                | the number of points detected at any given time can be retrieved       |
|                | through the ``HandFrame::handpoint_count`` function, and a             |
|                | ``astra::HandFrame::HandPointList`` can be retrieved through the       |
|                | ``HandFrame::handpoints`` function.                                    |
+----------------+------------------------------------------------------------------------+

Getting the Data
================
Two methods are provided by the |sdkname| SDK to get stream data. Depending on your particular use case and the complexity of your application, one method may be better suited than the other.

Polling
-------
The polling method for getting frame data is the most direct method for getting stream data, and is also the method used in the Hello World tutorial. To use this method, you only need to call the ``get_latest_frame`` function on the ``StreamReader``, then use the templated ``get<T>`` function on the returned frame to retrieve specific frame types. "``T``" in this case must be a valid frame type. The ``get_latest_frame`` function is blocking, so application execution will suspend until a new frame is returned. A ``timeout`` can be passed as a parameter to the ``get_latest_frame`` function if you want to limit the amount of time that the SDK will wait for a new frame to arrive.

.. code-block:: c++
   :emphasize-lines: 8,9

   astra::initialize();

   astra::StreamSet streamSet;
   astra::StreamReader reader = streamSet.create_reader();

   reader.stream<astra::DepthStream>().start();

   astra::Frame frame = reader.get_latest_frame();
   const auto depthFrame = frame.get<astra::DepthFrame>();

   astra::terminate();


- Retrieving a depth frame using the polling method

Listening
---------

The listening method for getting frame data requires a small amount of additional setup, but allows the developer to delegate the handling of a frame to one or more separate classes. The |sdkname| SDK provides an abstract class called ``FrameListener`` which implements a single function called ``FrameListener::on_frame_ready``. ``FrameListener::on_frame_ready`` is called as soon as the frame is ready for processing and passed a reference to that frame.

.. code-block:: c++

   class DepthFrameListener : public astra::FrameListener
   {
      virtual void on_frame_ready(astra::StreamReader& reader,
                                  astra::Frame& frame) override
      {
         const astra::DepthFrame depthFrame = frame.get<astra::DepthFrame>();

         if (depthFrame.is_valid())
         {
            // do all the things
         }
      }
   };

- An example of a listener class derived from ``frame_listener``

After defining a listener class, in order to use it you must instantiate the listener in your application and add it to the ``StreamReader`` using the ``StreamReader::add_listener`` function.

.. code-block:: c++
   :emphasize-lines: 8,9

   astra::initialize();

   astra::StreamSet streamSet;
   astra::StreamReader reader = streamSet.create_reader();

   reader.stream<astra::DepthStream>().start();

   DepthFrameListener listener;
   reader.add_listener(listener);

   while(true)
   {
      astra_update();
   }

- Example usage of a listener. In practice, the loop over ``astra_update`` should only execute until the application is closed or another application-specific event takes place.

Once the listener is added, we need to pump the SDK's event loop using the ``astra_update`` function. Doing this allows the SDK to check if a frame is available, and if so will, in this case, call the ``DepthFrameListener::on_frame_ready`` function and pass along a reference to the latest frame.

For a more practical example of a listener, continue on to our :doc:`Simple Depth Reader Tutorial <simpledepthreader>`.

.. toctree::
   :hidden:

   Simple Depth Reader <simpledepthreader>
