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