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