video_streamer_c_api.h

Go to the documentation of this file.

#ifndef INCLUDE_VIDEO_STREAMER_C_API_H_
#define INCLUDE_VIDEO_STREAMER_C_API_H_
 
/** @file video_streamer_c_api.h
 * API in this file is intended for external clients which will use this library in a plug-in
 * manner like dlopen(). This is not intended to be compiled by C compiler and thus references C++
 * code (like enums).
 * All strings in the API are UTF-8 encoded where not otherwise specified.
 *
 * @section workflow Overall workflow
 *
 * The library responsibility is to produce
 * <a href="https://gwg.nga.mil/misb/misp_pubs.html">MISP-compliant</a> video stream with telemetry
 * metadata integrated. It is up to the library user to obtain the video stream suitable for the
 * library input (raw H.264 video stream) and telemetry values. Typically the input video stream can
 * be obtained using ffmpeg or gstreamer library from some local video input devices or network
 * video stream (see @ref ffmpeg_v4l_example and @ref stdin_example). DJI drones provide such stream
 * in their DJI SDK. In some cases the source may not provide H.264-encoded stream and uses either
 * another encoder or provides raw unencoded video. It is up to the library user to perform
 * transcoding or encoding into H.264 in such case.
 *
 * First, the library must be initialized by calling @ref VsInitialize(). The passed callback allows
 * integration with a logging framework used in your application. No other calls are permitted
 * before the library is initialized. Then the streamer instance can be created by calling @ref
 * VsCreate(). To use, for example, with UgCS video server, the URL like
 * `urtp+connect://<ip_address>://3341` should be passed in @ref VsParams, where `<ip_address>` is
 * UgCS video server address. The status callback argument allows to specify function which will
 * receive all updates about the streamer instance status. The returned instance handle should be
 * used for all the rest instance-bound calls. Then the instance can be started by calling @ref
 * VsStart() method. After started the video data can be fed by @ref VsFeedData() function. It
 * expects raw H.264 video stream. At the same time telemetry data can be provided by @ref
 * VsFeedTelemetry() function. Call @ref VsStop() when done with the streamer instance and @ref
 * VsTerminate() when done with the entire library.
 */
 
#include <streamer.h>
 
/** Represents handle for video streamer instance. One instance is bound to one streaming target. */
typedef void *VideoStreamerHandle;
 
/** Called on each log message.
 * @param opaque Caller-defined parameter specified in @ref VsParams.
 */
typedef void (*VsLogCallback)(Log::Level level, const char *msg);
 
/** Called on streamer status change.
 * @param opaque Caller-defined parameter specified in @ref VsParams.
 * @see @ref Streamer::Status
 */
typedef void (*VsStatusCallback)(Streamer::Status status, void *opaque);
 
/** Called when queue is overflowed or when it is consumed again.
 * @param status True when overflowed, false when back in normal state.
 */
typedef void (*VsQueueOverflowCallback)(bool status, void *opaque);
 
/** Error code. Will be extended with more specific error codes when necessarily. */
enum class VsError {
    /** No error. */
    NONE,
    /** Parameter is invalid. */
    INVALID_PARAM,
    /** Requested operation is not permitted in current state. */
    INVALID_OP,
    /** Internal error which indicates a software bug. Should not be caught in any way. */
    INTERNAL_ERROR,
 
    /** Other error. */
    OTHER
};
 
/** Streamer parameters. */
struct VsParams {
    /** Caller-defined parameter to pass in callbacks. */
    void *opaque = nullptr;
    /** Vehicle ID (typically serial number). */
    const char *vehicleId;
    /** User-defined tail number, may be null. */
    const char *tailNumber = nullptr;
    /** Target URI for streaming. Examples:
     * * `udp://1.2.3.4:3338` - Plain UDP streaming, suitable for external MISP-compliant players
     *      such as GIS software or just a regular media player (metadata will not be available in
     *      such case).
     * * `urtp+connect://1.2.3.4://3341 - URTP streaming with outgoing connection. URTP is UgCS
     *      proprietary protocol supported by its Command Center components. It ensures better
     *      quality on unreliable links.
     */
    const char *targetUri;
    /** Zero value disables transcoding, -1 for auto (based on input bitrate and scale),
     * otherwise value in bits/s.
     */
    int64_t transcodeBitrate = 0;
    /** Frame size scale factor for transcoding output, 1.0 to preserve input size. */
    float transcodeScale = 1.0;
    /** Frame rate limit for transcoding output, fps. Zero to preserve all input frames. */
    float transcodeFramerateLimit = 0;
};
 
/** Updated telemetry data block. Any fields can be empty, only non-empty values are sent in next
 * metadata packet. String fields are empty when null, double values are empty when isPresent flag
 * is false. All fields correspond to ST 0601.13 defined fields, see there for additional details.
 */
struct VsTelemetry {
    /** Optional floating point value. */
    struct DoubleValue {
        double value = 0.0;
        /** True if value specified, false if empty. */
        bool isPresent = false;
    };
    const char *missionId = nullptr,
               *platformDesignation = nullptr,
               *cameraManufacturer = nullptr,
               *cameraModel = nullptr;
    /** Platform heading angle, relative between longitudinal axis and True North measured in
     * the horizontal plane, radians.  Range: [0; 2*PI].
     */
    DoubleValue heading,
    /** Platform pitch angle, angle between longitudinal axis and horizontal plane, radians.
     * Only angle in range (-20; 20) degrees is properly transferred, other values are
     * transferred  as "out of range" indicator.
     */
        pitch,
    /** Platform roll angle, angle between transverse axis and transverse-longitudinal plane,
     * radians. Positive angles for lowered right wing.
     * Only angle in range (-50; 50) degrees is properly transferred, other values are
     * transferred as "out of range" indicator.
     */
        roll,
    /** Sensor coordinates, rad. */
        latitude, longitude,
    /** Sensor true altitude, meters. */
        altitude,
    /** Sensor horizontal field of view angle, radians. Range: [0; PI]. */
        sensorHorizontalFov,
    /** Sensor vertical field of view angle, radians.Range: [0; PI]. */
        sensorVerticalFov,
    /** Sensor relative azimuth angle, radians. Rotation angle between platform longitudinal axis
     * and camera pointing direction as seen from above the platform. Range: [0; 2*PI].
     */
        sensorRelativeAzimuth,
    /** Sensor relative elevation angle, radians. Relative elevation angle of sensor to platform
     * longitudinal-transverse plane, negative angles down.
     * Range: [-PI; PI].
     */
        sensorRelativeElevation,
    /** Relative roll angle of sensor to aircraft platform, radians. Top of image is zero degrees.
     * Positive angles are clockwise when looking from behind camera.
     * Range: [0; 2*PI].
     */
        sensorRelativeRoll,
    /** Slant range, meters. */
        slantRange,
    /** In millimeters. */
        cameraFocalLength;
};
 
extern "C" {
 
/** Get error from last API call in current thread. Each API call overwrites previously stored
 * error value. Calling VcGetLastError() does not change last error value.
 *
 * @param msgBuf Buffer for accepting error message (mostly for troubleshooting, not for forwarding
 * to user). UTF-8 encoded null-terminated message is stored here. The string is truncated if buffer
 * is too small, null terminator is always written.
 * @param bufSize Should contain buffer size in bytes on input. Contains necessary size to accept
 * whole the string on return (including null terminating character).
 * @return Last error code.
 */
VsError
VsGetLastError(char *msgBuf, uint32_t *bufSize);
 
/** Initialize the library. Should be called before any other API call.
 * @param logCbk Callback for connecting logging to the framework used by an application.
 * @return Zero on success, non-zero on failure.
 */
int
VsInitialize(VsLogCallback logCbk);
 
#ifdef HAS_FILESYSTEM
 
/** Crash reporting feature is armed after this call. May be not implemented on all platforms.
 * @param reportDir Directory to store report files. File name is generated automatically.
 * @return Zero on success, non-zero on failure.
 */
int
VsSetupCrashReport(const char *reportDir);
 
#endif /* HAS_FILESYSTEM */
 
/** Shutdown the library. Should be called when done working with the library. */
int
VsTerminate();
 
/** Create streamer instance. All events callbacks are called in a dedicated thread.
 *
 * @param Streamer parameters. Owned by the caller.
 * @param statusCbk Callback for status change events. See @ref VsStatusCallback.
 * @param queueOverflowCbk Callback for queue overflow events. See @ref VsQueueOverflowCallback.
 * @return Returned instance should be later released by VsDestroy(). Null can be returned in case
 *  of failure.
 */
VideoStreamerHandle
VsCreate(const VsParams *params, VsStatusCallback statusCbk,
         VsQueueOverflowCallback queueOverflowCbk);
 
/** Destroy the streamer instance and release all resources. */
void
VsDestroy(VideoStreamerHandle vs);
 
/** Start the streamer instance. Should be called before trying to pass any video or telemetry to
 * the streamer instance. VsStop() should be called after successful streamer start.
 * @return Zero on success, non-zero on failure.
 */
int
VsStart(VideoStreamerHandle vs);
 
/** Stop the streamer instance, releasing all the processing resources. Should not be called in
 * events thread.
 * @return Zero on success, non-zero on failure.
 */
int
VsStop(VideoStreamerHandle vs);
 
/** Set new tail number. This is user-readable part of composite tail number which can be changed at
 * any time (in contrast with vehicle ID part). Some non-permitted characters may be replaced.
 * @return Zero on success, non-zero on failure.
 */
int
VsSetTailNumber(VideoStreamerHandle vs, const char *tailNumber);
 
/** Feed next chunk of raw H.264 video stream. There are no requirements for chunks alignment
 * and sizes respectively to H.264 protocol data units.
 * @param dataBuf Buffer with the data chunk.
 * @param bufSize Size of the provided buffer in bytes.
 * @return Zero on success, non-zero on failure.
 */
int
VsFeedData(VideoStreamerHandle vs, const uint8_t *dataBuf, uint32_t bufSize);
 
/** Set most recent telemetry values to send in next metadata packet. Fields may be updated
 * selectively, only non-empty values are accounted in each invocation. Values are validated and
 * INVALID_PARAM error is set if any value is out of range. Whole the specified telemetry block is
 * discarded in such case.
 * @return Zero on success, non-zero on failure.
 */
int
VsFeedTelemetry(VideoStreamerHandle vs, const VsTelemetry *telemetry);
 
/** Get statistics report for the streamer instance.
 *
 * @param dataBuf Buffer which receives string with JSON statistics data. The data do not have any
 * fixed structure (actual content is a subject for change at any time) and are intended for
 * display/logging only. No any logic should be bound to. The returned string is always null
 * terminated.
 * @param bufSize Should contain buffer size in bytes on input. Contains necessary size to accept
 *  whole the string on return (including null terminating character). Keep in mind that next call
 *  will most probably return another string so some spare space is recommended.
 * @return Zero on success, non-zero on failure.
 */
int
VsGetStatistics(VideoStreamerHandle vs, char *dataBuf, uint32_t *bufSize);
 
} /* extern "C" */
 
#endif /* INCLUDE_VIDEO_STREAMER_C_API_H_ */