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] graphics3d_context A <code>PPB_Graphics3D</code> resource to 65 /// use during decoding. 66 /// @param[in] profile A <code>PP_VideoProfile</code> specifying the video 67 /// codec profile. 68 /// @param[in] acceleration A <code>PP_HardwareAcceleration</code> specifying 69 /// whether to use a hardware accelerated or a software implementation. 70 /// @param[in] callback A <code>PP_CompletionCallback</code> to be called upon 71 /// completion. 72 /// 73 /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 74 /// Returns PP_ERROR_NOTSUPPORTED if video decoding is not available, or the 75 /// requested profile is not supported. In this case, the client may call 76 /// Initialize() again with different parameters to find a good configuration. 77 int32_t Initialize(const Graphics3D& graphics3d_context, 78 PP_VideoProfile profile, 79 PP_HardwareAcceleration acceleration, 80 const CompletionCallback& callback); 81 82 /// Decodes a bitstream buffer. Copies |size| bytes of data from the plugin's 83 /// |buffer|. The plugin should wait until the decoder signals completion by 84 /// returning PP_OK or by running |callback| before calling Decode() again. 85 /// 86 /// In general, each bitstream buffer should contain a demuxed bitstream frame 87 /// for the selected video codec. For example, H264 decoders expect to receive 88 /// one AnnexB NAL unit, including the 4 byte start code prefix, while VP8 89 /// decoders expect to receive a bitstream frame without the IVF frame header. 90 /// 91 /// If the call to Decode() eventually results in a picture, the |decode_id| 92 /// parameter is copied into the returned picture. The plugin can use this to 93 /// associate decoded pictures with Decode() calls (e.g. to assign timestamps 94 /// or frame numbers to pictures.) This value is opaque to the API so the 95 /// plugin is free to pass any value. 96 /// 97 /// @param[in] decode_id An optional value, chosen by the plugin, that can be 98 /// used to associate calls to Decode() with decoded pictures returned by 99 /// GetPicture(). 100 /// @param[in] size Buffer size in bytes. 101 /// @param[in] buffer Starting address of buffer. 102 /// @param[in] callback A <code>CompletionCallback</code> to be called on 103 /// completion. 104 /// 105 /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 106 /// Returns PP_ERROR_FAILED if the decoder isn't initialized or if a Flush() 107 /// or Reset() call is pending. 108 /// Returns PP_ERROR_INPROGRESS if there is another Decode() call pending. 109 /// Returns PP_ERROR_NOMEMORY if a bitstream buffer can't be created. 110 /// Returns PP_ERROR_ABORTED when Reset() is called while Decode() is pending. 111 int32_t Decode(uint32_t decode_id, 112 uint32_t size, 113 const void* buffer, 114 const CompletionCallback& callback); 115 116 /// Gets the next picture from the decoder. The picture is valid after the 117 /// decoder signals completion by returning PP_OK or running |callback|. The 118 /// plugin can call GetPicture() again after the decoder signals completion. 119 /// When the plugin is finished using the picture, it should return it to the 120 /// system by calling RecyclePicture(). 121 /// 122 /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be 123 /// called on completion, and on success, to hold the picture descriptor. 124 /// 125 /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 126 /// Returns PP_ERROR_FAILED if the decoder isn't initialized or if a Reset() 127 /// call is pending. 128 /// Returns PP_ERROR_INPROGRESS if there is another GetPicture() call pending. 129 /// Returns PP_ERROR_ABORTED when Reset() is called, or if a call to Flush() 130 /// completes while GetPicture() is pending. 131 int32_t GetPicture( 132 const CompletionCallbackWithOutput<PP_VideoPicture>& callback); 133 134 /// Recycles a picture that the plugin has received from the decoder. 135 /// The plugin should call this as soon as it has finished using the texture 136 /// so the decoder can decode more pictures. 137 /// 138 /// @param[in] picture A <code>PP_VideoPicture</code> to return to the 139 /// decoder. 140 void RecyclePicture(const PP_VideoPicture& picture); 141 142 /// Flushes the decoder. The plugin should call Flush() when it reaches the 143 /// end of its video stream in order to stop cleanly. The decoder will run any 144 /// pending Decode() call to completion. The plugin should make no further 145 /// calls to the decoder other than GetPicture() and RecyclePicture() until 146 /// the decoder signals completion by running |callback|. Just before 147 /// completion, any pending GetPicture() call will complete by running its 148 /// callback with result PP_ERROR_ABORTED to signal that no more pictures are 149 /// available. Any pictures held by the plugin remain valid during and after 150 /// the flush and should be recycled back to the decoder. 151 /// 152 /// @param[in] callback A <code>CompletionCallback</code> to be called on 153 /// completion. 154 /// 155 /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 156 /// Returns PP_ERROR_FAILED if the decoder isn't initialized. 157 int32_t Flush(const CompletionCallback& callback); 158 159 /// Resets the decoder as quickly as possible. The plugin can call Reset() to 160 /// skip to another position in the video stream. After Reset() returns, any 161 /// pending calls to Decode() and GetPicture()) abort, causing their callbacks 162 /// to run with PP_ERROR_ABORTED. The plugin should not make further calls to 163 /// the decoder other than RecyclePicture() until the decoder signals 164 /// completion by running |callback|. Any pictures held by the plugin remain 165 /// valid during and after the reset and should be recycled back to the 166 /// decoder. 167 /// 168 /// @param[in] callback A <code>CompletionCallback</code> to be called on 169 /// completion. 170 /// 171 /// @return An int32_t containing an error code from <code>pp_errors.h</code>. 172 /// Returns PP_ERROR_FAILED if the decoder isn't initialized. 173 int32_t Reset(const CompletionCallback& callback); 174 }; 175 176 } // namespace pp 177 178 #endif // PPAPI_CPP_VIDEO_DECODER_H_ 179