1/*
2Copyright (c) 2012, Broadcom Europe Ltd
3All rights reserved.
4
5Redistribution and use in source and binary forms, with or without
6modification, are permitted provided that the following conditions are met:
7 * Redistributions of source code must retain the above copyright
8 notice, this list of conditions and the following disclaimer.
9 * Redistributions in binary form must reproduce the above copyright
10 notice, this list of conditions and the following disclaimer in the
11 documentation and/or other materials provided with the distribution.
12 * Neither the name of the copyright holder nor the
13 names of its contributors may be used to endorse or promote products
14 derived from this software without specific prior written permission.
15
16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26*/
27
28#ifndef SVP_H
29#define SVP_H
30
31#ifdef __cplusplus
32extern "C" {
33#endif
34
35/** \file
36 * Simple video player using MMAL.
37 * Uses MMAL container reader plus video decode component, and provides callback to retrieve
38 * buffers of decoded video frames.
39 *
40 * Thread-safety: The public API functions must be called from the same thread for a given SVP_T
41 * instance. The user is notified of decoded frames and other events from a separate
42 * thread, started by svp_start().
43 */
44
45/** Flags indicating reason for processing stop */
46/** Stop on to user request */
47#define SVP_STOP_USER (1 << 0)
48/** Stop on end-of-stream */
49#define SVP_STOP_EOS (1 << 1)
50/** Stop on error */
51#define SVP_STOP_ERROR (1 << 2)
52/** Stop on timer */
53#define SVP_STOP_TIMEUP (1 << 3)
54
55/**
56 * Callback functions and context for player to communicate asynchronous data
57 * and events to user.
58 */
59typedef struct SVP_CALLBACKS_T
60{
61 /** Private pointer specified by caller, passed to callback functions.
62 * Not examined by svp_ functions, so may have any value, including NULL.
63 */
64 void *ctx;
65
66 /** Callback for decoded video frames.
67 * The buffer is released when this function returns, so the callback must either have processed
68 * the buffer or acquired a reference before returning.
69 * @param ctx Caller's private context, as specified by SVP_CALLBACKS_T::ctx.
70 * @param ob MMAL opaque buffer handle.
71 */
72 void (*video_frame_cb)(void *ctx, void *buf);
73
74 /** Callback for end of processing.
75 * @param ctx Caller's private context, as specified by SVP_CALLBACKS_T::ctx.
76 * @param reason Bitmask of SVP_STOP_XXX values giving reason for stopping.
77 */
78 void (*stop_cb)(void *ctx, uint32_t stop_reason);
79} SVP_CALLBACKS_T;
80
81/** Options to SVP playback */
82typedef struct SVP_OPTS_T
83{
84 /** Duration of playback, in milliseconds. 0 = default, which is full duration for media and
85 * a limited duration for camera.
86 */
87 unsigned duration_ms;
88} SVP_OPTS_T;
89
90/** Playback stats */
91typedef struct SVP_STATS_T
92{
93 /** Total number of video frames processed since the last call to svp_start().
94 * 0 if svp_start() has never been called. */
95 unsigned video_frame_count;
96} SVP_STATS_T;
97
98/** Simple Video Player instance. Opaque structure. */
99typedef struct SVP_T SVP_T;
100
101/**
102 * Create a simple video player instance.
103 * @param uri URI to media, or NULL to use camera preview.
104 * @param callbacks Callbacks for caller to receive notification of events,
105 * such as decoded buffers.
106 * @param opts Player options.
107 * @return Newly created simple video player instance, or NULL on error.
108 */
109SVP_T *svp_create(const char *uri, SVP_CALLBACKS_T *callbacks, const SVP_OPTS_T *opts);
110
111/**
112 * Destroy a simple video player instance.
113 * @param svp Simple video player instance. May be NULL, in which case this
114 * function does nothing.
115 */
116void svp_destroy(SVP_T *svp);
117
118/**
119 * Start a simple video player instance.
120 * Decoded frames are returned to the SVP_CALLBACKS_T::video_frame_cb function
121 * passed to svp_create().
122 * @param svp Simple video player instance.
123 * @return 0 on success; -1 on failure.
124 */
125int svp_start(SVP_T *svp);
126
127/**
128 * Stop a simple video player instance.
129 * If the player is not running, then this function does nothing.
130 * @param svp Simple video player instance.
131 */
132void svp_stop(SVP_T *svp);
133
134/**
135 * Get player stats.
136 * @param svp Simple video player instance.
137 * @param stats Buffer in which stats are returned.
138 */
139void svp_get_stats(SVP_T *svp, SVP_STATS_T *stats);
140
141
142#ifdef __cplusplus
143}
144#endif
145
146#endif /* SVP_H */
147