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