1/*
2 *  Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
3 *
4 *  Use of this source code is governed by a BSD-style license
5 *  that can be found in the LICENSE file in the root of the source
6 *  tree. An additional intellectual property rights grant can be found
7 *  in the file PATENTS.  All contributing project authors may
8 *  be found in the AUTHORS file in the root of the source tree.
9 */
10
11#ifndef WEBRTC_MODULES_VIDEO_RENDER_VIDEO_RENDER_H_
12#define WEBRTC_MODULES_VIDEO_RENDER_VIDEO_RENDER_H_
13
14/*
15 * video_render.h
16 *
17 * This header file together with module.h and module_common_types.h
18 * contains all of the APIs that are needed for using the video render
19 * module class.
20 *
21 */
22
23#include "webrtc/modules/include/module.h"
24#include "webrtc/modules/video_render/video_render_defines.h"
25
26namespace webrtc {
27
28// Class definitions
29class VideoRender: public Module
30{
31public:
32    /*
33     *   Create a video render module object
34     *
35     *   id              - unique identifier of this video render module object
36     *   window          - pointer to the window to render to
37     *   fullscreen      - true if this is a fullscreen renderer
38     *   videoRenderType - type of renderer to create
39     */
40    static VideoRender
41            * CreateVideoRender(
42                                          const int32_t id,
43                                          void* window,
44                                          const bool fullscreen,
45                                          const VideoRenderType videoRenderType =
46                                                  kRenderDefault);
47
48    /*
49     *   Destroy a video render module object
50     *
51     *   module  - object to destroy
52     */
53    static void DestroyVideoRender(VideoRender* module);
54
55    int64_t TimeUntilNextProcess() override = 0;
56    int32_t Process() override = 0;
57
58    /**************************************************************************
59     *
60     *   Window functions
61     *
62     ***************************************************************************/
63
64    /*
65     *   Get window for this renderer
66     */
67    virtual void* Window() = 0;
68
69    /*
70     *   Change render window
71     *
72     *   window      - the new render window, assuming same type as originally created.
73     */
74    virtual int32_t ChangeWindow(void* window) = 0;
75
76    /**************************************************************************
77     *
78     *   Incoming Streams
79     *
80     ***************************************************************************/
81
82    /*
83     *   Add incoming render stream
84     *
85     *   streamID    - id of the stream to add
86     *   zOrder      - relative render order for the streams, 0 = on top
87     *   left        - position of the stream in the window, [0.0f, 1.0f]
88     *   top         - position of the stream in the window, [0.0f, 1.0f]
89     *   right       - position of the stream in the window, [0.0f, 1.0f]
90     *   bottom      - position of the stream in the window, [0.0f, 1.0f]
91     *
92     *   Return      - callback class to use for delivering new frames to render.
93     */
94    virtual VideoRenderCallback
95            * AddIncomingRenderStream(const uint32_t streamId,
96                                      const uint32_t zOrder,
97                                      const float left, const float top,
98                                      const float right, const float bottom) = 0;
99    /*
100     *   Delete incoming render stream
101     *
102     *   streamID    - id of the stream to add
103     */
104    virtual int32_t
105            DeleteIncomingRenderStream(const uint32_t streamId) = 0;
106
107    /*
108     *   Add incoming render callback, used for external rendering
109     *
110     *   streamID     - id of the stream the callback is used for
111     *   renderObject - the VideoRenderCallback to use for this stream, NULL to remove
112     *
113     *   Return      - callback class to use for delivering new frames to render.
114     */
115    virtual int32_t
116            AddExternalRenderCallback(const uint32_t streamId,
117                                      VideoRenderCallback* renderObject) = 0;
118
119    /*
120     *   Get the porperties for an incoming render stream
121     *
122     *   streamID    - [in] id of the stream to get properties for
123     *   zOrder      - [out] relative render order for the streams, 0 = on top
124     *   left        - [out] position of the stream in the window, [0.0f, 1.0f]
125     *   top         - [out] position of the stream in the window, [0.0f, 1.0f]
126     *   right       - [out] position of the stream in the window, [0.0f, 1.0f]
127     *   bottom      - [out] position of the stream in the window, [0.0f, 1.0f]
128     */
129    virtual int32_t
130            GetIncomingRenderStreamProperties(const uint32_t streamId,
131                                              uint32_t& zOrder,
132                                              float& left, float& top,
133                                              float& right, float& bottom) const = 0;
134    /*
135     *   The incoming frame rate to the module, not the rate rendered in the window.
136     */
137    virtual uint32_t
138            GetIncomingFrameRate(const uint32_t streamId) = 0;
139
140    /*
141     *   Returns the number of incoming streams added to this render module
142     */
143    virtual uint32_t GetNumIncomingRenderStreams() const = 0;
144
145    /*
146     *   Returns true if this render module has the streamId added, false otherwise.
147     */
148    virtual bool
149            HasIncomingRenderStream(const uint32_t streamId) const = 0;
150
151    /*
152     *   Registers a callback to get raw images in the same time as sent
153     *   to the renderer. To be used for external rendering.
154     */
155    virtual int32_t
156            RegisterRawFrameCallback(const uint32_t streamId,
157                                     VideoRenderCallback* callbackObj) = 0;
158
159    /**************************************************************************
160     *
161     *   Start/Stop
162     *
163     ***************************************************************************/
164
165    /*
166     *   Starts rendering the specified stream
167     */
168    virtual int32_t StartRender(const uint32_t streamId) = 0;
169
170    /*
171     *   Stops the renderer
172     */
173    virtual int32_t StopRender(const uint32_t streamId) = 0;
174
175    /*
176     *   Resets the renderer
177     *   No streams are removed. The state should be as after AddStream was called.
178     */
179    virtual int32_t ResetRender() = 0;
180
181    /**************************************************************************
182     *
183     *   Properties
184     *
185     ***************************************************************************/
186
187    /*
188     *   Returns the preferred render video type
189     */
190    virtual RawVideoType PreferredVideoType() const = 0;
191
192    /*
193     *   Returns true if the renderer is in fullscreen mode, otherwise false.
194     */
195    virtual bool IsFullScreen() = 0;
196
197    /*
198     *   Gets screen resolution in pixels
199     */
200    virtual int32_t
201            GetScreenResolution(uint32_t& screenWidth,
202                                uint32_t& screenHeight) const = 0;
203
204    /*
205     *   Get the actual render rate for this stream. I.e rendered frame rate,
206     *   not frames delivered to the renderer.
207     */
208    virtual uint32_t RenderFrameRate(const uint32_t streamId) = 0;
209
210    /*
211     *   Set cropping of incoming stream
212     */
213    virtual int32_t SetStreamCropping(const uint32_t streamId,
214                                      const float left,
215                                      const float top,
216                                      const float right,
217                                      const float bottom) = 0;
218
219    /*
220     * re-configure renderer
221     */
222
223    // Set the expected time needed by the graphics card or external renderer,
224    // i.e. frames will be released for rendering |delay_ms| before set render
225    // time in the video frame.
226    virtual int32_t SetExpectedRenderDelay(uint32_t stream_id,
227                                           int32_t delay_ms) = 0;
228
229    virtual int32_t ConfigureRenderer(const uint32_t streamId,
230                                      const unsigned int zOrder,
231                                      const float left,
232                                      const float top,
233                                      const float right,
234                                      const float bottom) = 0;
235
236    virtual int32_t SetTransparentBackground(const bool enable) = 0;
237
238    virtual int32_t FullScreenRender(void* window, const bool enable) = 0;
239
240    virtual int32_t SetBitmap(const void* bitMap,
241                              const uint8_t pictureId,
242                              const void* colorKey,
243                              const float left, const float top,
244                              const float right, const float bottom) = 0;
245
246    virtual int32_t SetText(const uint8_t textId,
247                            const uint8_t* text,
248                            const int32_t textLength,
249                            const uint32_t textColorRef,
250                            const uint32_t backgroundColorRef,
251                            const float left, const float top,
252                            const float right, const float bottom) = 0;
253
254    /*
255     * Set a start image. The image is rendered before the first image has been delivered
256     */
257    virtual int32_t SetStartImage(const uint32_t streamId,
258                                  const VideoFrame& videoFrame) = 0;
259
260    /*
261     * Set a timout image. The image is rendered if no videoframe has been delivered
262     */
263    virtual int32_t SetTimeoutImage(const uint32_t streamId,
264                                    const VideoFrame& videoFrame,
265                                    const uint32_t timeout) = 0;
266};
267}  // namespace webrtc
268#endif  // WEBRTC_MODULES_VIDEO_RENDER_VIDEO_RENDER_H_
269