* Added documentation

Signed-off-by: Christian Berger <christian.berger@gu.se>

Author: chrberger

README.md

@@ -1,2 +1,78 @@
-# opendlv-video-vpx-encode
-OpenDLV Microservice to convert an image in shared memory to a vpx frame
+## OpenDLV Microservice to encode images in I420 format into VP8 or VP9 for network broadcast
+
+This repository provides source code to encode images in I420 format that are accessible
+via a shared memory area into VP8 or VP9 frames for the OpenDLV software ecosystem.
+
+[![License: GPLv3](https://img.shields.io/badge/license-GPL--3-blue.svg
+)](https://www.gnu.org/licenses/gpl-3.0.txt)
+
+
+## Table of Contents
+* [Dependencies](#dependencies)
+* [Usage](#usage)
+* [Build from sources on the example of Ubuntu 16.04 LTS](#build-from-sources-on-the-example-of-ubuntu-1604-lts)
+* [License](#license)
+
+
+## Dependencies
+You need a C++14-compliant compiler to compile this project.
+
+The following dependency is part of the source distribution:
+* [libcluon](https://github.com/chrberger/libcluon) - [![License: GPLv3](https://img.shields.io/badge/license-GPL--3-blue.svg
+)](https://www.gnu.org/licenses/gpl-3.0.txt)
+
+The following dependencies are downloaded and installed during the Docker-ized build:
+* [libvpx 1.7.0](https://github.com/webmproject/libvpx/releases/tag/v1.7.0) - [![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) - [Google Patent License Conditions](https://raw.githubusercontent.com/webmproject/libvpx/f80be22a1099b2a431c2796f529bb261064ec6b4/PATENTS)
+* [libyuv](https://chromium.googlesource.com/libyuv/libyuv/+/master) - [![License: BSD 3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause) - [Google Patent License Conditions](https://chromium.googlesource.com/libyuv/libyuv/+/master/PATENTS)
+
+
+## Usage
+To run this microservice using `docker-compose`, you can simply add the following
+section to your `docker-compose.yml`:
+
+```yml
+version: '2' # Must be present exactly once at the beginning of the docker-compose.yml file
+services:    # Must be present exactly once at the beginning of the docker-compose.yml file
+    video-vpx-encoder:
+        image: chalmersrevere/opendlv-video-vpx-encoder-multi:v0.0.2
+        restart: on-failure
+        network_mode: "host"
+        ipc: "host"
+        volumes:
+        - /tmp:/tmp
+        command: "--cid=111 --name=video0.i420 --width=640 --height=480 --vp8"
+```
+
+As this microservice is connecting to another video frame-providing microservice
+via a shared memory area using SysV IPC, the `docker-compose.yml` file specifies
+the use of `ipc:host`. The parameter `network_mode: "host"` is necessary to
+broadcast the resulting frames into an `OD4Session` for OpenDLV. The folder
+`/tmp` is shared into the Docker container to attach to the shared memory area.
+The parameters to the application are:
+
+* `--cid=111`: Identifier of the OD4Session to broadcast the VP8 or VP9 frames to
+* `--id=2`: Optional identifier to set the senderStamp in broadcasted VP8 or VP9 frames in case of multiple instances of this microservice
+* `--name=XYZ`: Name of the shared memory area to attach to
+* `--width=W`: Width of the image in the shared memory area
+* `--height=H`: Height of the image in the shared memory area
+* `--bitrate=B`: desired bitrate (default: 800,000)
+* `--gop=G`: desired length of group of pictures (default: 10)
+* `--vp8`: use VP8 for encoding the frames
+* `--vp9`: use VP8 for encoding the frames
+
+
+## Build from sources on the example of Ubuntu 16.04 LTS
+To build this software, you need cmake, C++14 or newer, libyuv, libvpx, and make.
+Having these preconditions, just run `cmake` and `make` as follows:
+
+```
+mkdir build && cd build
+cmake -D CMAKE_BUILD_TYPE=Release ..
+make && make test && make install
+```
+
+
+## License
+
+* This project is released under the terms of the GNU GPLv3 License
+

src/opendlv-video-vpx-encoder.cpp

@@ -40,7 +40,7 @@ int32_t main(int32_t argc, char **argv) {
         std::cerr << "Usage:   " << argv[0] << " --cid=<OpenDaVINCI session> --name=<name of shared memory area> --width=<width> --height=<height> [--gop=<GOP>] [--bitrate=<bitrate>] [--verbose] [--id=<identifier in case of multiple instances]" << std::endl;
         std::cerr << "         --vp8:     use VP8 encoder" << std::endl;
         std::cerr << "         --vp9:     use VP9 encoder" << std::endl;
-        std::cerr << "         --cid:     CID of the OD4Session to send h264 frames" << std::endl;
+        std::cerr << "         --cid:     CID of the OD4Session to send VP8 or VP9 frames" << std::endl;
         std::cerr << "         --id:      when using several instances, this identifier is used as senderStamp" << std::endl;
         std::cerr << "         --name:    name of the shared memory area to attach" << std::endl;
         std::cerr << "         --width:   width of the frame" << std::endl;
@@ -67,22 +67,22 @@ int32_t main(int32_t argc, char **argv) {
 
         std::unique_ptr<cluon::SharedMemory> sharedMemory(new cluon::SharedMemory{NAME});
         if (sharedMemory && sharedMemory->valid()) {
-            std::clog << argv[0] << ": Attached to '" << sharedMemory->name() << "' (" << sharedMemory->size() << " bytes)." << std::endl;
+            std::clog << "[opendlv-video-vpx-encoder]: Attached to '" << sharedMemory->name() << "' (" << sharedMemory->size() << " bytes)." << std::endl;
 
             vpx_codec_iface_t *encoderAlgorithm{(VP8 ? &vpx_codec_vp8_cx_algo : &vpx_codec_vp9_cx_algo)};
 
             vpx_image_t yuvFrame;
             memset(&yuvFrame, 0, sizeof(yuvFrame));
             if (!vpx_img_alloc(&yuvFrame, VPX_IMG_FMT_I420, WIDTH, HEIGHT, 1)) {
-                std::cerr << argv[0] << ": Failed to allocate image." << std::endl;
+                std::cerr << "[opendlv-video-vpx-encoder]: Failed to allocate image." << std::endl;
                 return retCode;
             }
 
             struct vpx_codec_enc_cfg parameters;
             memset(&parameters, 0, sizeof(parameters));
             vpx_codec_err_t result = vpx_codec_enc_config_default(encoderAlgorithm, &parameters, 0);
             if (result) {
-                std::cerr << argv[0] << ": Failed to get default configuration: " << vpx_codec_err_to_string(result) << std::endl;
+                std::cerr << "[opendlv-video-vpx-encoder]: Failed to get default configuration: " << vpx_codec_err_to_string(result) << std::endl;
                 return retCode;
             }
 
@@ -106,11 +106,11 @@ int32_t main(int32_t argc, char **argv) {
             memset(&codec, 0, sizeof(codec));
             result = vpx_codec_enc_init(&codec, encoderAlgorithm, &parameters, 0);
             if (result) {
-                std::cerr << argv[0] << ": Failed to initialize encoder: " << vpx_codec_err_to_string(result) << std::endl;
+                std::cerr << "[opendlv-video-vpx-encoder]: Failed to initialize encoder: " << vpx_codec_err_to_string(result) << std::endl;
                 return retCode;
             }
             else {
-                std::clog << argv[0] << ": Using " << vpx_codec_iface_name(encoderAlgorithm) << std::endl;
+                std::clog << "[opendlv-video-vpx-encoder]: Using " << vpx_codec_iface_name(encoderAlgorithm) << std::endl;
             }
             vpx_codec_control(&codec, VP8E_SET_CPUUSED, 4);
 
@@ -149,7 +149,7 @@ int32_t main(int32_t argc, char **argv) {
                 int flags{ (0 == (frameCounter%GOP)) ? VPX_EFLAG_FORCE_KF : 0 };
                 result = vpx_codec_encode(&codec, &yuvFrame, frameCounter, 1, flags, VPX_DL_REALTIME);
                 if (result) {
-                    std::cerr << argv[0] << ": Failed to encode frame: " << vpx_codec_err_to_string(result) << std::endl;
+                    std::cerr << "[opendlv-video-vpx-encoder]: Failed to encode frame: " << vpx_codec_err_to_string(result) << std::endl;
                 }
                 if (VERBOSE) {
                     after = cluon::time::now();
@@ -177,7 +177,7 @@ int32_t main(int32_t argc, char **argv) {
                         od4.send(ir, sampleTimeStamp, ID);
 
                         if (VERBOSE) {
-                            std::clog << argv[0] << ": Frame size = " << totalSize << " bytes; encoding took " << cluon::time::deltaInMicroseconds(after, before) << " microseconds." << std::endl;
+                            std::clog << "[opendlv-video-vpx-encoder]: Frame size = " << totalSize << " bytes; encoding took " << cluon::time::deltaInMicroseconds(after, before) << " microseconds." << std::endl;
                         }
                         frameCounter++;
                     }
@@ -189,7 +189,7 @@ int32_t main(int32_t argc, char **argv) {
             retCode = 0;
         }
         else {
-            std::cerr << argv[0] << ": Failed to attach to shared memory '" << NAME << "'." << std::endl;
+            std::cerr << "[opendlv-video-vpx-encoder]: Failed to attach to shared memory '" << NAME << "'." << std::endl;
         }
     }
     return retCode;