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