sensors/docs/usecase3.md

Go to the documentation of this file.

# Copyright (c) 2019-2020, NVIDIA CORPORATION.  All rights reserved.

@page sensors_usecase3 Sensors Serialization

@note SW Release Applicability: This tutorial is applicable to modules in both **NVIDIA DriveWorks** and **NVIDIA DRIVE Software** releases.

Sensor serialization is useful for saving sensor information for future playback and analysis.

**Initialization**

In order to initialize a sensor serializer, first serialization parameters must be populated. These are as follows:
```{.cpp}
const char* parameters;
dwSensorSerializerOnDataFunc_t onData;
```
The parameters is a string containing `type`, `file`, `file-buffer-size`, `format`, `bitrate`, and `framerate`. Each of the listed are key/value pairs that are specified in the string as `"key1=value1,key2=value2,key3=value3"`.

* `type` - Required. Specifies data-sink settings. If the value of `type` is `disk`, the serializer streams data to the file specified in the `file` key. If the value of `type` is `user`, the serializer uses the provided callback to stream data. When new data is available, the serializer calls the function provided in `onData` and puts the data in the buffer provided by `userData`.
* `file` - See description for `type`.
* `file-buffer-size` - Size of output buffer to use for file operations.
* `format` - Required. Specifies the video format. Supported values are `h264` and `raw`. Only applies to camera sensors.
* `bitrate` - Required if `format` is `h264`; optional if it is `raw`. This only applies to camera sensors.
* `framerate` - Optional. Controls the framerate of the recorded stream and only applies to camera sensors.

The `onData` parameter is a callback when specifying a sensor serializer with the `type=user`.

Once the parameters are set, the sensor serializer can be initialized via the following function:
```{.cpp}
dwSensorSerializer_initialize()
```
In addition to passing the parameters, the sensor that is being serialized must be passed into this function.

The serializer can run in async mode (on its own thread) or in non-async mode. Async mode allows the serializer to put the work of i/o on another thread. To run in async mode, the following methods must be used:

```{.cpp}
dwSensorSerializer_start() // called to start the i/o thread.
dwSensorSerializer_serializeDataAsync() // for generalized sensor data
dwSensorSerializer_serializeCameraFrameAsync() // for camera data
dwSensorSerializer_stop() // called to stop the i/o thread.
```
If running the serializer in async mode and multiple serializers are running together (for multiple sensors), one serializer can share its I/O thread with other serializers so that I/O happens for all serializers on the same thread. This is accomplished by attaching one serializer to another via the `dwSensorSerializer_attachTo()` method where one serializer is specified as the master serialzier and another is the slave.


If running the serializer in non-async mode, the following methods are used for serialization:
```{.cpp}
dwSensorSerializer_serializeData() // for general sensor data
dwSensorSerializer_serializeCameraFrame() // for camera data
```

The following is an example of how instatiate a serializer with a camera sensor and save camera frames to an h264 elementary stream file:
```{.cpp}
dwSAL_initialize(&sal, sdk);

dwSensorHandle_t cameraSensor = DW_NULL_HANDLE;
dwSensorParams params;
std::string parameterString = "output-format=yuv";
// CODE: other sensor specific parameters
params.protocol             = "camera.gmsl";
dwSAL_createSensor(&cameraSensor, params, sal);

dwSensorSerializerHandle_t serializer;
dwSerializerParams serializerParams;
serializerParams.parameters = "format=h264,bitrate=800000,framerate=30,type=disk,file=out.h264";

dwSensorSerializer_initialize(&serializer, &serializerParams, cameraSensor);
dwSensorSerializer_start(serializer);

while(loop) {
    dwSensorCamera_readFrame(...);
    dwImageHandle_t image;
    dwSensorCamera_getImage(&image, DW_CAMERA_OUTPUT_NATIVE_PROCESSED,...);

    dwSensorSerializer_serializeCameraFrameAsync(image,...);

    // CODE: use and return frame
}

dwSensorSerializer_stop(serializer);
dwSensorSerializer_release(&serializer);

dwSAL_releaseSensor(&cameraSensor);
dwSAL_release(&sal);
```

For more examples of sensor serialization refer to:
- @ref dwx_camera_gmsl_custom_sample