1 /* Copyright (c) 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 * This file defines the <code>PPB_VideoDecoder</code> interface. 8 */ 9 10 [generate_thunk] 11 12 label Chrome { 13 [channel=dev] M36 = 0.1 14 }; 15 16 /** 17 * Video decoder interface. 18 * 19 * Typical usage: 20 * - Call Create() to create a new video decoder resource. 21 * - Call Initialize() to initialize it with a 3d graphics context and the 22 * desired codec profile. 23 * - Call Decode() continuously (waiting for each previous call to complete) to 24 * push bitstream buffers to the decoder. 25 * - Call GetPicture() continuously (waiting for each previous call to complete) 26 * to pull decoded pictures from the decoder. 27 * - Call Flush() to signal end of stream to the decoder and perform shutdown 28 * when it completes. 29 * - Call Reset() to quickly stop the decoder (e.g. to implement Seek) and wait 30 * for the callback before restarting decoding at another point. 31 * - To destroy the decoder, the plugin should release all of its references to 32 * it. Any pending callbacks will abort before the decoder is destroyed. 33 * 34 * Available video codecs vary by platform. 35 * All: theora, vorbis, vp8. 36 * Chrome and ChromeOS: aac, h264. 37 * ChromeOS: mpeg4. 38 */ 39 interface PPB_VideoDecoder { 40 /** 41 * Creates a new video decoder resource. 42 * 43 * @param[in] instance A <code>PP_Instance</code> identifying the instance 44 * with the video decoder. 45 * 46 * @return A <code>PP_Resource</code> corresponding to a video decoder if 47 * successful or 0 otherwise. 48 */ 49 PP_Resource Create( 50 [in] PP_Instance instance); 51 52 /** 53 * Determines if the given resource is a video decoder. 54 * 55 * @param[in] resource A <code>PP_Resource</code> identifying a resource. 56 * 57 * @return <code>PP_TRUE</code> if the resource is a 58 * <code>PPB_VideoDecoder</code>, <code>PP_FALSE</code> if the resource is 59 * invalid or some other type. 60 */ 61 PP_Bool IsVideoDecoder( 62 [in] PP_Resource resource); 63 64 /** 65 * Initializes a video decoder resource. This should be called after Create() 66 * and before any other functions. 67 * 68 * @param[in] video_decoder A <code>PP_Resource</code> identifying the video 69 * decoder. 70 * @param[in] graphics3d_context A <code>PPB_Graphics3D</code> resource to use 71 * during decoding. 72 * @param[in] profile A <code>PP_VideoProfile</code> specifying the video 73 * codec profile. 74 * @param[in] allow_software_fallback A <code>PP_Bool</code> specifying 75 * whether the decoder can fall back to software decoding if a suitable 76 * hardware decoder isn't available. 77 * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 78 * completion. 79 * 80 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 81 * Returns PP_ERROR_NOTSUPPORTED if video decoding is not available, or the 82 * requested profile is not supported. In this case, the client may call 83 * Initialize() again with different parameters to find a good configuration. 84 */ 85 int32_t Initialize( 86 [in] PP_Resource video_decoder, 87 [in] PP_Resource graphics3d_context, 88 [in] PP_VideoProfile profile, 89 [in] PP_Bool allow_software_fallback, 90 [in] PP_CompletionCallback callback); 91 92 /** 93 * Decodes a bitstream buffer. Copies |size| bytes of data from the plugin's 94 * |buffer|. The plugin should wait until the decoder signals completion by 95 * returning PP_OK or by running |callback| before calling Decode() again. 96 * 97 * In general, each bitstream buffer should contain a demuxed bitstream frame 98 * for the selected video codec. For example, H264 decoders expect to receive 99 * one AnnexB NAL unit, including the 4 byte start code prefix, while VP8 100 * decoders expect to receive a bitstream frame without the IVF frame header. 101 * 102 * If the call to Decode() eventually results in a picture, the |decode_id| 103 * parameter is copied into the returned picture. The plugin can use this to 104 * associate decoded pictures with Decode() calls (e.g. to assign timestamps 105 * or frame numbers to pictures.) This value is opaque to the API so the 106 * plugin is free to pass any value. 107 * 108 * @param[in] video_decoder A <code>PP_Resource</code> identifying the video 109 * decoder. 110 * @param[in] decode_id An optional value, chosen by the plugin, that can be 111 * used to associate calls to Decode() with decoded pictures returned by 112 * GetPicture(). 113 * @param[in] size Buffer size in bytes. 114 * @param[in] buffer Starting address of buffer. 115 * @param[in] callback A <code>PP_CompletionCallback</code> to be called on 116 * completion. 117 * 118 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 119 * Returns PP_ERROR_FAILED if the decoder isn't initialized or if a Flush() 120 * or Reset() call is pending. 121 * Returns PP_ERROR_INPROGRESS if there is another Decode() call pending. 122 * Returns PP_ERROR_NOMEMORY if a bitstream buffer can't be created. 123 * Returns PP_ERROR_ABORTED when Reset() is called while Decode() is pending. 124 */ 125 int32_t Decode( 126 [in] PP_Resource video_decoder, 127 [in] uint32_t decode_id, 128 [in] uint32_t size, 129 [in] mem_t buffer, 130 [in] PP_CompletionCallback callback); 131 132 /** 133 * Gets the next picture from the decoder. The picture is valid after the 134 * decoder signals completion by returning PP_OK or running |callback|. The 135 * plugin can call GetPicture() again after the decoder signals completion. 136 * When the plugin is finished using the picture, it should return it to the 137 * system by calling RecyclePicture(). 138 * 139 * @param[in] video_decoder A <code>PP_Resource</code> identifying the video 140 * decoder. 141 * @param[out] picture A <code>PP_VideoPicture</code> to hold the decoded 142 * picture. 143 * @param[in] callback A <code>PP_CompletionCallback</code> to be called on 144 * completion. 145 * 146 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 147 * Returns PP_ERROR_FAILED if the decoder isn't initialized or if a Reset() 148 * call is pending. 149 * Returns PP_ERROR_INPROGRESS if there is another GetPicture() call pending. 150 * Returns PP_ERROR_ABORTED when Reset() is called, or if a call to Flush() 151 * completes while GetPicture() is pending. 152 */ 153 int32_t GetPicture( 154 [in] PP_Resource video_decoder, 155 [out] PP_VideoPicture picture, 156 [in] PP_CompletionCallback callback); 157 158 /** 159 * Recycles a picture that the plugin has received from the decoder. 160 * The plugin should call this as soon as it has finished using the texture so 161 * the decoder can decode more pictures. 162 * 163 * @param[in] video_decoder A <code>PP_Resource</code> identifying the video 164 * decoder. 165 * @param[in] picture A <code>PP_VideoPicture</code> to return to 166 * the decoder. 167 */ 168 void RecyclePicture( 169 [in] PP_Resource video_decoder, 170 [in] PP_VideoPicture picture); 171 172 /** 173 * Flushes the decoder. The plugin should call Flush() when it reaches the 174 * end of its video stream in order to stop cleanly. The decoder will run any 175 * pending Decode() call to completion. The plugin should make no further 176 * calls to the decoder other than GetPicture() and RecyclePicture() until 177 * the decoder signals completion by running |callback|. Just before 178 * completion, any pending GetPicture() call will complete by running its 179 * callback with result PP_ERROR_ABORTED to signal that no more pictures are 180 * available. Any pictures held by the plugin remain valid during and after 181 * the flush and should be recycled back to the decoder. 182 * 183 * @param[in] video_decoder A <code>PP_Resource</code> identifying the video 184 * decoder. 185 * @param[in] callback A <code>PP_CompletionCallback</code> to be called on 186 * completion. 187 * 188 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 189 * Returns PP_ERROR_FAILED if the decoder isn't initialized. 190 */ 191 int32_t Flush( 192 [in] PP_Resource video_decoder, 193 [in] PP_CompletionCallback callback); 194 195 /** 196 * Resets the decoder as quickly as possible. The plugin can call Reset() to 197 * skip to another position in the video stream. After Reset() returns, any 198 * pending calls to Decode() and GetPicture()) abort, causing their callbacks 199 * to run with PP_ERROR_ABORTED. The plugin should not make further calls to 200 * the decoder other than RecyclePicture() until the decoder signals 201 * completion by running |callback|. Any pictures held by the plugin remain 202 * valid during and after the reset and should be recycled back to the 203 * decoder. 204 * 205 * @param[in] video_decoder A <code>PP_Resource</code> identifying the video 206 * decoder. 207 * @param[in] callback A <code>PP_CompletionCallback</code> to be called on 208 * completion. 209 * 210 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 211 * Returns PP_ERROR_FAILED if the decoder isn't initialized. 212 */ 213 int32_t Reset( 214 [in] PP_Resource video_decoder, 215 [in] PP_CompletionCallback callback); 216 }; 217
