ppapi/c/ppb_media_stream_video_track.h

   1 /* Copyright 2014 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /* From ppb_media_stream_video_track.idl modified Fri Mar 28 10:13:52 2014. */
   7
   8 #ifndef PPAPI_C_PPB_MEDIA_STREAM_VIDEO_TRACK_H_
   9 #define PPAPI_C_PPB_MEDIA_STREAM_VIDEO_TRACK_H_
  10
  11 #include "ppapi/c/pp_bool.h"
  12 #include "ppapi/c/pp_completion_callback.h"
  13 #include "ppapi/c/pp_macros.h"
  14 #include "ppapi/c/pp_resource.h"
  15 #include "ppapi/c/pp_stdint.h"
  16 #include "ppapi/c/pp_var.h"
  17
  18 #define PPB_MEDIASTREAMVIDEOTRACK_INTERFACE_0_1 "PPB_MediaStreamVideoTrack;0.1"
  19 #define PPB_MEDIASTREAMVIDEOTRACK_INTERFACE \
  20     PPB_MEDIASTREAMVIDEOTRACK_INTERFACE_0_1
  21
  22 /**
  23  * @file
  24  * Defines the <code>PPB_MediaStreamVideoTrack</code> interface. Used for
  25  * receiving video frames from a MediaStream video track in the browser.
  26  */
  27
  28
  29 /**
  30  * @addtogroup Enums
  31  * @{
  32  */
  33 /**
  34  * This enumeration contains video track attributes which are used by
  35  * <code>Configure()</code>.
  36  */
  37 typedef enum {
  38   /**
  39    * Attribute list terminator.
  40    */
  41   PP_MEDIASTREAMVIDEOTRACK_ATTRIB_NONE = 0,
  42   /**
  43    * The maximum number of frames to hold in the input buffer.
  44    * Note: this is only used as advisory; the browser may allocate more or fewer
  45    * based on available resources. How many frames to buffer depends on usage -
  46    * request at least 2 to make sure latency doesn't cause lost frames. If
  47    * the plugin expects to hold on to more than one frame at a time (e.g. to do
  48    * multi-frame processing), it should request that many more.
  49    * If this attribute is not specified or value 0 is specified for this
  50    * attribute, the default value will be used.
  51    */
  52   PP_MEDIASTREAMVIDEOTRACK_ATTRIB_BUFFERED_FRAMES = 1,
  53   /**
  54    * The width of video frames in pixels. It should be a multiple of 4.
  55    * If the specified size is different from the video source (webcam),
  56    * frames will be scaled to specified size.
  57    * If this attribute is not specified or value 0 is specified, the original
  58    * frame size of the video track will be used.
  59    *
  60    * Maximum value: 4096 (4K resolution).
  61    */
  62   PP_MEDIASTREAMVIDEOTRACK_ATTRIB_WIDTH = 2,
  63   /**
  64    * The height of video frames in pixels. It should be a multiple of 4.
  65    * If the specified size is different from the video source (webcam),
  66    * frames will be scaled to specified size.
  67    * If this attribute is not specified or value 0 is specified, the original
  68    * frame size of the video track will be used.
  69    *
  70    * Maximum value: 4096 (4K resolution).
  71    */
  72   PP_MEDIASTREAMVIDEOTRACK_ATTRIB_HEIGHT = 3,
  73   /**
  74    * The format of video frames. The attribute value is
  75    * a <code>PP_VideoFrame_Format</code>. If the specified format is different
  76    * from the video source (webcam), frames will be converted to specified
  77    * format.
  78    * If this attribute is not specified or value
  79    * <code>PP_VIDEOFRAME_FORMAT_UNKNOWN</code> is specified, the orignal frame
  80    * format of the video track will be used.
  81    */
  82   PP_MEDIASTREAMVIDEOTRACK_ATTRIB_FORMAT = 4
  83 } PP_MediaStreamVideoTrack_Attrib;
  84 /**
  85  * @}
  86  */
  87
  88 /**
  89  * @addtogroup Interfaces
  90  * @{
  91  */
  92 struct PPB_MediaStreamVideoTrack_0_1 {
  93   /**
  94    * Determines if a resource is a MediaStream video track resource.
  95    *
  96    * @param[in] resource The <code>PP_Resource</code> to test.
  97    *
  98    * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
  99    * resource is a Mediastream video track resource or <code>PP_FALSE</code>
 100    * otherwise.
 101    */
 102   PP_Bool (*IsMediaStreamVideoTrack)(PP_Resource resource);
 103   /**
 104    * Configures underlying frame buffers for incoming frames.
 105    * If the application doesn't want to drop frames, then the
 106    * <code>PP_MEDIASTREAMVIDEOTRACK_ATTRIB_BUFFERED_FRAMES</code> should be
 107    * chosen such that inter-frame processing time variability won't overrun the
 108    * input buffer. If the buffer is overfilled, then frames will be dropped.
 109    * The application can detect this by examining the timestamp on returned
 110    * frames. If some attributes are not specified, default values will be used
 111    * for those unspecified attributes. If <code>Configure()</code> is not
 112    * called, default settings will be used.
 113    * Example usage from plugin code:
 114    * @code
 115    * int32_t attribs[] = {
 116    *     PP_MEDIASTREAMVIDEOTRACK_ATTRIB_BUFFERED_FRAMES, 4,
 117    *     PP_MEDIASTREAMVIDEOTRACK_ATTRIB_NONE};
 118    * track_if->Configure(track, attribs, callback);
 119    * @endcode
 120    *
 121    * @param[in] video_track A <code>PP_Resource</code> corresponding to a video
 122    * resource.
 123    * @param[in] attrib_list A list of attribute name-value pairs in which each
 124    * attribute is immediately followed by the corresponding desired value.
 125    * The list is terminated by
 126    * <code>PP_MEDIASTREAMVIDEOTRACK_ATTRIB_NONE</code>.
 127    * @param[in] callback <code>PP_CompletionCallback</code> to be called upon
 128    * completion of <code>Configure()</code>.
 129    *
 130    * @return An int32_t containing a result code from <code>pp_errors.h</code>.
 131    * Returns <code>PP_ERROR_INPROGRESS</code> if there is a pending call of
 132    * <code>Configure()</code> or <code>GetFrame()</code>, or the plugin
 133    * holds some frames which are not recycled with <code>RecycleFrame()</code>.
 134    * If an error is returned, all attributes and the underlying buffer will not
 135    * be changed.
 136    */
 137   int32_t (*Configure)(PP_Resource video_track,
 138                        const int32_t attrib_list[],
 139                        struct PP_CompletionCallback callback);
 140   /**
 141    * Gets attribute value for a given attribute name.
 142    *
 143    * @param[in] video_track A <code>PP_Resource</code> corresponding to a video
 144    * resource.
 145    * @param[in] attrib A <code>PP_MediaStreamVideoTrack_Attrib</code> for
 146    * querying.
 147    * @param[out] value A int32_t for storing the attribute value on success.
 148    * Otherwise, the value will not be changed.
 149    *
 150    * @return An int32_t containing a result code from <code>pp_errors.h</code>.
 151    */
 152   int32_t (*GetAttrib)(PP_Resource video_track,
 153                        PP_MediaStreamVideoTrack_Attrib attrib,
 154                        int32_t* value);
 155   /**
 156    * Returns the track ID of the underlying MediaStream video track.
 157    *
 158    * @param[in] video_track The <code>PP_Resource</code> to check.
 159    *
 160    * @return A <code>PP_Var</code> containing the MediaStream track ID as
 161    * a string.
 162    */
 163   struct PP_Var (*GetId)(PP_Resource video_track);
 164   /**
 165    * Checks whether the underlying MediaStream track has ended.
 166    * Calls to GetFrame while the track has ended are safe to make and will
 167    * complete, but will fail.
 168    *
 169    * @param[in] video_track The <code>PP_Resource</code> to check.
 170    *
 171    * @return A <code>PP_Bool</code> with <code>PP_TRUE</code> if the given
 172    * MediaStream track has ended or <code>PP_FALSE</code> otherwise.
 173    */
 174   PP_Bool (*HasEnded)(PP_Resource video_track);
 175   /**
 176    * Gets the next video frame from the MediaStream track.
 177    * If internal processing is slower than the incoming frame rate, new frames
 178    * will be dropped from the incoming stream. Once the input buffer is full,
 179    * frames will be dropped until <code>RecycleFrame()</code> is called to free
 180    * a spot for another frame to be buffered.
 181    * If there are no frames in the input buffer,
 182    * <code>PP_OK_COMPLETIONPENDING</code> will be returned immediately and the
 183    * <code>callback</code> will be called when a new frame is received or an
 184    * error happens.
 185    *
 186    * @param[in] video_track A <code>PP_Resource</code> corresponding to a video
 187    * resource.
 188    * @param[out] frame A <code>PP_Resource</code> corresponding to a VideoFrame
 189    * resource.
 190    * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
 191    * completion of GetFrame().
 192    *
 193    * @return An int32_t containing a result code from <code>pp_errors.h</code>.
 194    * Returns PP_ERROR_NOMEMORY if <code>max_buffered_frames</code> frames buffer
 195    * was not allocated successfully.
 196    */
 197   int32_t (*GetFrame)(PP_Resource video_track,
 198                       PP_Resource* frame,
 199                       struct PP_CompletionCallback callback);
 200   /**
 201    * Recycles a frame returned by <code>GetFrame()</code>, so the track can
 202    * reuse the underlying buffer of this frame. And the frame will become
 203    * invalid. The caller should release all references it holds to
 204    * <code>frame</code> and not use it anymore.
 205    *
 206    * @param[in] video_track A <code>PP_Resource</code> corresponding to a video
 207    * resource.
 208    * @param[in] frame A <code>PP_Resource</code> corresponding to a VideoFrame
 209    * resource returned by <code>GetFrame()</code>.
 210    *
 211    * @return An int32_t containing a result code from <code>pp_errors.h</code>.
 212    */
 213   int32_t (*RecycleFrame)(PP_Resource video_track, PP_Resource frame);
 214   /**
 215    * Closes the MediaStream video track and disconnects it from video source.
 216    * After calling <code>Close()</code>, no new frames will be received.
 217    *
 218    * @param[in] video_track A <code>PP_Resource</code> corresponding to a
 219    * MediaStream video track resource.
 220    */
 221   void (*Close)(PP_Resource video_track);
 222 };
 223
 224 typedef struct PPB_MediaStreamVideoTrack_0_1 PPB_MediaStreamVideoTrack;
 225 /**
 226  * @}
 227  */
 228
 229 #endif  /* PPAPI_C_PPB_MEDIA_STREAM_VIDEO_TRACK_H_ */
 230