ppb_video_decoder.idl revision 010d83a9304c5a91596085d917d248abff47903a
1010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles)/* Copyright (c) 2014 The Chromium Authors. All rights reserved. 2010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Use of this source code is governed by a BSD-style license that can be 3010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * found in the LICENSE file. 4010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) */ 5010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) 6010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles)/** 7010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * This file defines the <code>PPB_VideoDecoder</code> interface. 8010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) */ 9010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) 10010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles)[generate_thunk] 11010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) 12010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles)label Chrome { 13010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [channel=dev] M36 = 0.1 14010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles)}; 15010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) 16010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles)/** 17010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Video decoder interface. 18010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 19010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Typical usage: 20010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * - Call Create() to create a new video decoder resource. 21010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * - Call Initialize() to initialize it with a 3d graphics context and the 22010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * desired codec profile. 23010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * - Call Decode() continuously (waiting for each previous call to complete) to 24010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * push bitstream buffers to the decoder. 25010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * - Call GetPicture() continuously (waiting for each previous call to complete) 26010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * to pull decoded pictures from the decoder. 27010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * - Call Flush() to signal end of stream to the decoder and perform shutdown 28010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * when it completes. 29010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * - Call Reset() to quickly stop the decoder (e.g. to implement Seek) and wait 30010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * for the callback before restarting decoding at another point. 31010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * - To destroy the decoder, the plugin should release all of its references to 32010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * it. Any pending callbacks will abort before the decoder is destroyed. 33010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 34010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Available video codecs vary by platform. 35010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * All: theora, vorbis, vp8. 36010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Chrome and ChromeOS: aac, h264. 37010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * ChromeOS: mpeg4. 38010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) */ 39010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles)interface PPB_VideoDecoder { 40010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) /** 41010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Creates a new video decoder resource. 42010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 43010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] instance A <code>PP_Instance</code> identifying the instance 44010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * with the video decoder. 45010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 46010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @return A <code>PP_Resource</code> corresponding to a video decoder if 47010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * successful or 0 otherwise. 48010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) */ 49010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) PP_Resource Create( 50010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_Instance instance); 51010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) 52010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) /** 53010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Determines if the given resource is a video decoder. 54010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 55010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] resource A <code>PP_Resource</code> identifying a resource. 56010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 57010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @return <code>PP_TRUE</code> if the resource is a 58010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * <code>PPB_VideoDecoder</code>, <code>PP_FALSE</code> if the resource is 59010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * invalid or some other type. 60010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) */ 61010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) PP_Bool IsVideoDecoder( 62010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_Resource resource); 63010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) 64010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) /** 65010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Initializes a video decoder resource. This should be called after Create() 66010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * and before any other functions. 67010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 68010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] video_decoder A <code>PP_Resource</code> identifying the video 69010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * decoder. 70010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] graphics3d_context A <code>PPB_Graphics3D</code> resource to use 71010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * during decoding. 72010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] profile A <code>PP_VideoProfile</code> specifying the video 73010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * codec profile. 74010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] allow_software_fallback A <code>PP_Bool</code> specifying 75010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * whether the decoder can fall back to software decoding if a suitable 76010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * hardware decoder isn't available. 77010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 78010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * completion. 79010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 80010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @return An int32_t containing an error code from <code>pp_errors.h</code>. 81010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Returns PP_ERROR_NOTSUPPORTED if video decoding is not available, or the 82010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * requested profile is not supported. In this case, the client may call 83010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Initialize() again with different parameters to find a good configuration. 84010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) */ 85010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) int32_t Initialize( 86010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_Resource video_decoder, 87010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_Resource graphics3d_context, 88010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_VideoProfile profile, 89010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_Bool allow_software_fallback, 90010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_CompletionCallback callback); 91010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) 92010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) /** 93010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Decodes a bitstream buffer. Copies |size| bytes of data from the plugin's 94010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * |buffer|. The plugin should maintain the buffer and not call Decode() again 95010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * until the decoder signals completion by returning PP_OK or by running 96010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * |callback|. 97010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 98010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * In general, each bitstream buffer should contain a demuxed bitstream frame 99010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * for the selected video codec. For example, H264 decoders expect to receive 100010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * one AnnexB NAL unit, including the 4 byte start code prefix, while VP8 101010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * decoders expect to receive a bitstream frame without the IVF frame header. 102010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 103010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * If the call to Decode() eventually results in a picture, the |decode_id| 104010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * parameter is copied into the returned picture. The plugin can use this to 105010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * associate decoded pictures with Decode() calls (e.g. to assign timestamps 106010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * or frame numbers to pictures.) This value is opaque to the API so the 107010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * plugin is free to pass any value. 108010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 109010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] video_decoder A <code>PP_Resource</code> identifying the video 110010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * decoder. 111010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] decode_id An optional value, chosen by the plugin, that can be 112010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * used to associate calls to Decode() with decoded pictures returned by 113010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * GetPicture(). 114010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] size Buffer size in bytes. 115010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] buffer Starting address of buffer. 116010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] callback A <code>PP_CompletionCallback</code> to be called on 117010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * completion. 118010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 119010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @return An int32_t containing an error code from <code>pp_errors.h</code>. 120010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) */ 121010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) int32_t Decode( 122010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_Resource video_decoder, 123010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] uint32_t decode_id, 124010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] uint32_t size, 125010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] mem_t buffer, 126010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_CompletionCallback callback); 127010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) 128010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) /** 129010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Gets the next picture from the decoder. The picture is valid after the 130010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * decoder signals completion by returning PP_OK or running |callback|. The 131010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * plugin can call GetPicture() again after the decoder signals completion. 132010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * When the plugin is finished using the picture, it should return it to the 133010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * system by calling RecyclePicture(). 134010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 135010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] video_decoder A <code>PP_Resource</code> identifying the video 136010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * decoder. 137010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[out] picture A <code>PP_VideoPicture</code> to hold the decoded 138010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * picture. 139010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] callback A <code>PP_CompletionCallback</code> to be called on 140010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * completion. 141010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 142010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @return An int32_t containing an error code from <code>pp_errors.h</code>. 143010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Returns PP_OK if a picture is available. 144010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Returns PP_ERROR_ABORTED when Reset() is called, or if a call to Flush() 145010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * completes while GetPicture() is pending. 146010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) */ 147010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) int32_t GetPicture( 148010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_Resource video_decoder, 149010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [out] PP_VideoPicture picture, 150010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_CompletionCallback callback); 151010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) 152010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) /** 153010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Recycles a picture that the plugin has received from the decoder. 154010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * The plugin should call this as soon as it has finished using the texture so 155010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * the decoder can decode more pictures. 156010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 157010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] video_decoder A <code>PP_Resource</code> identifying the video 158010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * decoder. 159010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] picture A <code>PP_VideoPicture</code> to return to 160010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * the decoder. 161010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) */ 162010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) void RecyclePicture( 163010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_Resource video_decoder, 164010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_VideoPicture picture); 165010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) 166010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) /** 167010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Flushes the decoder. The plugin should call this when it reaches the end of 168010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * its video stream in order to stop cleanly. The decoder will run all pending 169010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * calls to completion. The plugin should make no further calls to the decoder 170010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * other than GetPicture() and RecyclePicture() until the decoder signals 171010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * completion by running the callback. Just before completion, any pending 172010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * GetPicture() call will complete by running the callback with result 173010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * PP_ERROR_ABORTED to signal that no more pictures are available. 174010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 175010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] video_decoder A <code>PP_Resource</code> identifying the video 176010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * decoder. 177010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] callback A <code>PP_CompletionCallback</code> to be called on 178010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * completion. 179010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 180010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @return An int32_t containing an error code from <code>pp_errors.h</code>. 181010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) */ 182010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) int32_t Flush( 183010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_Resource video_decoder, 184010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_CompletionCallback callback); 185010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) 186010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) /** 187010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * Resets the decoder as quickly as possible. The plugin can call Reset() to 188010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * skip to another position in the video stream. Pending calls to Decode() and 189010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * GetPicture()) are immediately aborted, causing their callbacks to run with 190010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * PP_ERROR_ABORTED. The plugin should not make any further calls to the 191010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * decoder until the decoder signals completion by running |callback|. 192010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 193010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] video_decoder A <code>PP_Resource</code> identifying the video 194010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * decoder. 195010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @param[in] callback A <code>PP_CompletionCallback</code> to be called on 196010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * completion. 197010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * 198010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) * @return An int32_t containing an error code from <code>pp_errors.h</code>. 199010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) */ 200010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) int32_t Reset( 201010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_Resource video_decoder, 202010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles) [in] PP_CompletionCallback callback); 203010d83a9304c5a91596085d917d248abff47903aTorne (Richard Coles)}; 204