media/webrtc/trunk/src/modules/video_render/main/interface/video_render.h

   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_MAIN_INTERFACE_VIDEO_RENDER_H_
  12 #define WEBRTC_MODULES_VIDEO_RENDER_MAIN_INTERFACE_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 "modules/interface/module.h"
  24 #include "modules/video_render/main/interface/video_render_defines.h"
  25
  26 namespace webrtc {
  27
  28 #if defined(WEBRTC_ANDROID) && !defined(WEBRTC_CHROMIUM_BUILD)
  29 WebRtc_Word32 SetRenderAndroidVM(void* javaVM);
  30 #endif
  31
  32 // Class definitions
  33 class VideoRender: public Module
  34 {
  35 public:
  36     /*
  37      *   Create a video render module object
  38      *
  39      *   id              - unique identifier of this video render module object
  40      *   window          - pointer to the window to render to
  41      *   fullscreen      - true if this is a fullscreen renderer
  42      *   videoRenderType - type of renderer to create
  43      */
  44     static VideoRender
  45             * CreateVideoRender(
  46                                           const WebRtc_Word32 id,
  47                                           void* window,
  48                                           const bool fullscreen,
  49                                           const VideoRenderType videoRenderType =
  50                                                   kRenderDefault);
  51
  52     /*
  53      *   Destroy a video render module object
  54      *
  55      *   module  - object to destroy
  56      */
  57     static void DestroyVideoRender(VideoRender* module);
  58
  59     /*
  60      *   Change the unique identifier of this object
  61      *
  62      *   id      - new unique identifier of this video render module object
  63      */
  64     virtual WebRtc_Word32 ChangeUniqueId(const WebRtc_Word32 id) = 0;
  65
  66     virtual WebRtc_Word32 TimeUntilNextProcess() = 0;
  67     virtual WebRtc_Word32 Process() = 0;
  68
  69     /**************************************************************************
  70      *
  71      *   Window functions
  72      *
  73      ***************************************************************************/
  74
  75     /*
  76      *   Get window for this renderer
  77      */
  78     virtual void* Window() = 0;
  79
  80     /*
  81      *   Change render window
  82      *
  83      *   window      - the new render window, assuming same type as originally created.
  84      */
  85     virtual WebRtc_Word32 ChangeWindow(void* window) = 0;
  86
  87     /**************************************************************************
  88      *
  89      *   Incoming Streams
  90      *
  91      ***************************************************************************/
  92
  93     /*
  94      *   Add incoming render stream
  95      *
  96      *   streamID    - id of the stream to add
  97      *   zOrder      - relative render order for the streams, 0 = on top
  98      *   left        - position of the stream in the window, [0.0f, 1.0f]
  99      *   top         - position of the stream in the window, [0.0f, 1.0f]
 100      *   right       - position of the stream in the window, [0.0f, 1.0f]
 101      *   bottom      - position of the stream in the window, [0.0f, 1.0f]
 102      *
 103      *   Return      - callback class to use for delivering new frames to render.
 104      */
 105     virtual VideoRenderCallback
 106             * AddIncomingRenderStream(const WebRtc_UWord32 streamId,
 107                                       const WebRtc_UWord32 zOrder,
 108                                       const float left, const float top,
 109                                       const float right, const float bottom) = 0;
 110     /*
 111      *   Delete incoming render stream
 112      *
 113      *   streamID    - id of the stream to add
 114      */
 115     virtual WebRtc_Word32
 116             DeleteIncomingRenderStream(const WebRtc_UWord32 streamId) = 0;
 117
 118     /*
 119      *   Add incoming render callback, used for external rendering
 120      *
 121      *   streamID     - id of the stream the callback is used for
 122      *   renderObject - the VideoRenderCallback to use for this stream, NULL to remove
 123      *
 124      *   Return      - callback class to use for delivering new frames to render.
 125      */
 126     virtual WebRtc_Word32
 127             AddExternalRenderCallback(const WebRtc_UWord32 streamId,
 128                                       VideoRenderCallback* renderObject) = 0;
 129
 130     /*
 131      *   Get the porperties for an incoming render stream
 132      *
 133      *   streamID    - [in] id of the stream to get properties for
 134      *   zOrder      - [out] relative render order for the streams, 0 = on top
 135      *   left        - [out] position of the stream in the window, [0.0f, 1.0f]
 136      *   top         - [out] position of the stream in the window, [0.0f, 1.0f]
 137      *   right       - [out] position of the stream in the window, [0.0f, 1.0f]
 138      *   bottom      - [out] position of the stream in the window, [0.0f, 1.0f]
 139      */
 140     virtual WebRtc_Word32
 141             GetIncomingRenderStreamProperties(const WebRtc_UWord32 streamId,
 142                                               WebRtc_UWord32& zOrder,
 143                                               float& left, float& top,
 144                                               float& right, float& bottom) const = 0;
 145     /*
 146      *   The incoming frame rate to the module, not the rate rendered in the window.
 147      */
 148     virtual WebRtc_UWord32
 149             GetIncomingFrameRate(const WebRtc_UWord32 streamId) = 0;
 150
 151     /*
 152      *   Returns the number of incoming streams added to this render module
 153      */
 154     virtual WebRtc_UWord32 GetNumIncomingRenderStreams() const = 0;
 155
 156     /*
 157      *   Returns true if this render module has the streamId added, false otherwise.
 158      */
 159     virtual bool
 160             HasIncomingRenderStream(const WebRtc_UWord32 streamId) const = 0;
 161
 162     /*
 163      *   Registers a callback to get raw images in the same time as sent
 164      *   to the renderer. To be used for external rendering.
 165      */
 166     virtual WebRtc_Word32
 167             RegisterRawFrameCallback(const WebRtc_UWord32 streamId,
 168                                      VideoRenderCallback* callbackObj) = 0;
 169
 170     /*
 171      * This method is usefull to get last rendered frame for the stream specified
 172      */
 173     virtual WebRtc_Word32
 174             GetLastRenderedFrame(const WebRtc_UWord32 streamId,
 175                                  VideoFrame &frame) const = 0;
 176
 177     /**************************************************************************
 178      *
 179      *   Start/Stop
 180      *
 181      ***************************************************************************/
 182
 183     /*
 184      *   Starts rendering the specified stream
 185      */
 186     virtual WebRtc_Word32 StartRender(const WebRtc_UWord32 streamId) = 0;
 187
 188     /*
 189      *   Stops the renderer
 190      */
 191     virtual WebRtc_Word32 StopRender(const WebRtc_UWord32 streamId) = 0;
 192
 193     /*
 194      *   Resets the renderer
 195      *   No streams are removed. The state should be as after AddStream was called.
 196      */
 197     virtual WebRtc_Word32 ResetRender() = 0;
 198
 199     /**************************************************************************
 200      *
 201      *   Properties
 202      *
 203      ***************************************************************************/
 204
 205     /*
 206      *   Returns the preferred render video type
 207      */
 208     virtual RawVideoType PreferredVideoType() const = 0;
 209
 210     /*
 211      *   Returns true if the renderer is in fullscreen mode, otherwise false.
 212      */
 213     virtual bool IsFullScreen() = 0;
 214
 215     /*
 216      *   Gets screen resolution in pixels
 217      */
 218     virtual WebRtc_Word32
 219             GetScreenResolution(WebRtc_UWord32& screenWidth,
 220                                 WebRtc_UWord32& screenHeight) const = 0;
 221
 222     /*
 223      *   Get the actual render rate for this stream. I.e rendered frame rate,
 224      *   not frames delivered to the renderer.
 225      */
 226     virtual WebRtc_UWord32 RenderFrameRate(const WebRtc_UWord32 streamId) = 0;
 227
 228     /*
 229      *   Set cropping of incoming stream
 230      */
 231     virtual WebRtc_Word32 SetStreamCropping(const WebRtc_UWord32 streamId,
 232                                             const float left, const float top,
 233                                             const float right,
 234                                             const float bottom) = 0;
 235
 236     /*
 237      * re-configure renderer
 238      */
 239     virtual WebRtc_Word32 ConfigureRenderer(const WebRtc_UWord32 streamId,
 240                                             const unsigned int zOrder,
 241                                             const float left, const float top,
 242                                             const float right,
 243                                             const float bottom) = 0;
 244
 245     virtual WebRtc_Word32 SetTransparentBackground(const bool enable) = 0;
 246
 247     virtual WebRtc_Word32 FullScreenRender(void* window, const bool enable) = 0;
 248
 249     virtual WebRtc_Word32 SetBitmap(const void* bitMap,
 250                                     const WebRtc_UWord8 pictureId,
 251                                     const void* colorKey, const float left,
 252                                     const float top, const float right,
 253                                     const float bottom) = 0;
 254
 255     virtual WebRtc_Word32 SetText(const WebRtc_UWord8 textId,
 256                                   const WebRtc_UWord8* text,
 257                                   const WebRtc_Word32 textLength,
 258                                   const WebRtc_UWord32 textColorRef,
 259                                   const WebRtc_UWord32 backgroundColorRef,
 260                                   const float left, const float top,
 261                                   const float right, const float bottom) = 0;
 262
 263     /*
 264      * Set a start image. The image is rendered before the first image has been delivered
 265      */
 266     virtual WebRtc_Word32
 267             SetStartImage(const WebRtc_UWord32 streamId,
 268                           const VideoFrame& videoFrame) = 0;
 269
 270     /*
 271      * Set a timout image. The image is rendered if no videoframe has been delivered
 272      */
 273     virtual WebRtc_Word32 SetTimeoutImage(const WebRtc_UWord32 streamId,
 274                                           const VideoFrame& videoFrame,
 275                                           const WebRtc_UWord32 timeout)= 0;
 276
 277     virtual WebRtc_Word32 MirrorRenderStream(const int renderId,
 278                                              const bool enable,
 279                                              const bool mirrorXAxis,
 280                                              const bool mirrorYAxis) = 0;
 281 };
 282 } //namespace webrtc
 283 #endif  // WEBRTC_MODULES_VIDEO_RENDER_MAIN_INTERFACE_VIDEO_RENDER_H_