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.
5 #ifndef PPAPI_CPP_VIDEO_DECODER_H_
6 #define PPAPI_CPP_VIDEO_DECODER_H_
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"
16 /// This file defines the API to create and use a VideoDecoder resource.
24 /// Video decoder interface.
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.
41 /// Available video codecs vary by platform.
42 /// All: theora, vorbis, vp8.
43 /// Chrome and ChromeOS: aac, h264.
45 class VideoDecoder : public Resource {
47 /// Default constructor for creating an is_null() <code>VideoDecoder</code>
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
55 explicit VideoDecoder(const InstanceHandle& instance);
57 /// The copy constructor for <code>VideoDecoder</code>.
58 /// @param[in] other A reference to a <code>VideoDecoder</code>.
59 VideoDecoder(const VideoDecoder& other);
61 /// Initializes a video decoder resource. This should be called after Create()
62 /// and before any other functions.
64 /// @param[in] video_decoder A <code>PP_Resource</code> identifying the video
66 /// @param[in] profile A <code>PP_VideoProfile</code> specifying the video
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
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);
83 /// Decodes a bitstream buffer. Copies |size| bytes of data from the plugin's
84 /// |buffer|. The plugin should maintain the buffer and not call Decode()
85 /// again until the decoder signals completion by returning PP_OK or by
86 /// running |callback|.
88 /// In general, each bitstream buffer should contain a demuxed bitstream frame
89 /// for the selected video codec. For example, H264 decoders expect to receive
90 /// one AnnexB NAL unit, including the 4 byte start code prefix, while VP8
91 /// decoders expect to receive a bitstream frame without the IVF frame header.
93 /// If the call to Decode() eventually results in a picture, the |decode_id|
94 /// parameter is copied into the returned picture. The plugin can use this to
95 /// associate decoded pictures with Decode() calls (e.g. to assign timestamps
96 /// or frame numbers to pictures.) This value is opaque to the API so the
97 /// plugin is free to pass any value.
99 /// @param[in] decode_id An optional value, chosen by the plugin, that can be
100 /// used to associate calls to Decode() with decoded pictures returned by
102 /// @param[in] size Buffer size in bytes.
103 /// @param[in] buffer Starting address of buffer.
104 /// @param[in] callback A <code>CompletionCallback</code> to be called on
107 /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
108 int32_t Decode(uint32_t decode_id,
111 const CompletionCallback& callback);
113 /// Gets the next picture from the decoder. The picture is valid after the
114 /// decoder signals completion by returning PP_OK or running |callback|. The
115 /// plugin can call GetPicture() again after the decoder signals completion.
116 /// When the plugin is finished using the picture, it should return it to the
117 /// system by calling RecyclePicture().
119 /// @param[in] video_decoder A <code>PP_Resource</code> identifying the video
121 /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
122 /// called on completion, and on success, to hold the picture descriptor.
124 /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
125 /// Returns PP_OK if a picture is available.
126 /// Returns PP_ERROR_ABORTED when Reset() is called, or if a call to Flush()
127 /// completes while GetPicture() is pending.
129 const CompletionCallbackWithOutput<PP_VideoPicture>& callback);
131 /// Recycles a picture that the plugin has received from the decoder.
132 /// The plugin should call this as soon as it has finished using the texture
133 /// so the decoder can decode more pictures.
135 /// @param[in] picture A <code>PP_VideoPicture</code> to return to the
137 void RecyclePicture(const PP_VideoPicture& picture);
139 /// Flushes the decoder. The plugin should call this when it reaches the end
140 /// of its video stream in order to stop cleanly. The decoder will run all
141 /// pending calls to completion. The plugin should make no further calls to
142 /// the decoder other than GetPicture() and RecyclePicture() until the decoder
143 /// signals completion by running the callback. Just before completion, any
144 /// pending GetPicture() call will complete by running the callback with
145 /// result PP_ERROR_ABORTED to signal that no more pictures are available.
147 /// @param[in] callback A <code>CompletionCallback</code> to be called on
150 /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
151 int32_t Flush(const CompletionCallback& callback);
153 /// Resets the decoder as quickly as possible. The plugin can call Reset() to
154 /// skip to another position in the video stream. Pending calls to Decode()
155 /// and GetPicture()) are immediately aborted, causing their callbacks to run
156 /// with PP_ERROR_ABORTED. The plugin should not make any further calls to the
157 /// decoder until the decoder signals completion by running |callback|.
159 /// @param[in] callback A <code>CompletionCallback</code> to be called on
162 /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
163 int32_t Reset(const CompletionCallback& callback);
168 #endif // PPAPI_CPP_VIDEO_DECODER_H_