Torne (Richard Coles) | 010d83a | 2014-05-14 12:12:37 +0100 | [diff] [blame] | 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 |
Torne (Richard Coles) | cedac22 | 2014-06-03 10:58:34 +0100 | [diff] [blame] | 84 | /// |buffer|. The plugin should wait until the decoder signals completion by |
| 85 | /// returning PP_OK or by running |callback| before calling Decode() again. |
Torne (Richard Coles) | 010d83a | 2014-05-14 12:12:37 +0100 | [diff] [blame] | 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>. |
Torne (Richard Coles) | cedac22 | 2014-06-03 10:58:34 +0100 | [diff] [blame] | 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. |
Torne (Richard Coles) | 010d83a | 2014-05-14 12:12:37 +0100 | [diff] [blame] | 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>. |
Torne (Richard Coles) | cedac22 | 2014-06-03 10:58:34 +0100 | [diff] [blame] | 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. |
Torne (Richard Coles) | 010d83a | 2014-05-14 12:12:37 +0100 | [diff] [blame] | 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 | |
Torne (Richard Coles) | cedac22 | 2014-06-03 10:58:34 +0100 | [diff] [blame] | 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 |
Ben Murdoch | 116680a | 2014-07-20 18:25:52 -0700 | [diff] [blame] | 152 | /// available. Any pictures held by the plugin remain valid during and after |
| 153 | /// the flush and should be recycled back to the decoder. |
Torne (Richard Coles) | 010d83a | 2014-05-14 12:12:37 +0100 | [diff] [blame] | 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>. |
Torne (Richard Coles) | cedac22 | 2014-06-03 10:58:34 +0100 | [diff] [blame] | 159 | /// Returns PP_ERROR_FAILED if the decoder isn't initialized. |
Torne (Richard Coles) | 010d83a | 2014-05-14 12:12:37 +0100 | [diff] [blame] | 160 | int32_t Flush(const CompletionCallback& callback); |
| 161 | |
| 162 | /// Resets the decoder as quickly as possible. The plugin can call Reset() to |
Torne (Richard Coles) | cedac22 | 2014-06-03 10:58:34 +0100 | [diff] [blame] | 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 |
Ben Murdoch | 116680a | 2014-07-20 18:25:52 -0700 | [diff] [blame] | 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. |
Torne (Richard Coles) | 010d83a | 2014-05-14 12:12:37 +0100 | [diff] [blame] | 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>. |
Torne (Richard Coles) | cedac22 | 2014-06-03 10:58:34 +0100 | [diff] [blame] | 175 | /// Returns PP_ERROR_FAILED if the decoder isn't initialized. |
| 176 | int32_t Reset(const CompletionCallback& callback); |
Torne (Richard Coles) | 010d83a | 2014-05-14 12:12:37 +0100 | [diff] [blame] | 177 | }; |
| 178 | |
| 179 | } // namespace pp |
| 180 | |
| 181 | #endif // PPAPI_CPP_VIDEO_DECODER_H_ |