QUIC - cleanup changes to sync chromium tree with internal source.
[chromium-blink-merge.git] / ppapi / cpp / video_encoder.h
blobe3b3d3e60a4ef4bef64e6a431ae11ca055777c31
1 // Copyright 2015 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_ENCODER_H_
6 #define PPAPI_CPP_VIDEO_ENCODER_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/resource.h"
12 #include "ppapi/cpp/size.h"
13 #include "ppapi/cpp/video_frame.h"
15 /// @file
16 /// This file defines the API to create and use a VideoEncoder resource.
18 namespace pp {
20 class InstanceHandle;
22 /// Video encoder interface.
23 ///
24 /// Typical usage:
25 /// - Call Create() to create a new video encoder resource.
26 /// - Call GetSupportedFormats() to determine which codecs and profiles are
27 /// available.
28 /// - Call Initialize() to initialize the encoder for a supported profile.
29 /// - Call GetVideoFrame() to get a blank frame and fill it in, or get a video
30 /// frame from another resource, e.g. <code>PPB_MediaStreamVideoTrack</code>.
31 /// - Call Encode() to push the video frame to the encoder. If an external frame
32 /// is pushed, wait for completion to recycle the frame.
33 /// - Call GetBitstreamBuffer() continuously (waiting for each previous call to
34 /// complete) to pull encoded pictures from the encoder.
35 /// - Call RecycleBitstreamBuffer() after consuming the data in the bitstream
36 /// buffer.
37 /// - To destroy the encoder, the plugin should release all of its references to
38 /// it. Any pending callbacks will abort before the encoder is destroyed.
39 ///
40 /// Available video codecs vary by platform.
41 /// All: vp8 (software).
42 /// ChromeOS, depending on your device: h264 (hardware), vp8 (hardware)
43 class VideoEncoder : public Resource {
44 public:
45 /// Default constructor for creating an is_null() <code>VideoEncoder</code>
46 /// object.
47 VideoEncoder();
49 /// A constructor used to create a <code>VideoEncoder</code> and associate it
50 /// with the provided <code>Instance</code>.
51 /// @param[in] instance The instance with which this resource will be
52 /// associated.
53 explicit VideoEncoder(const InstanceHandle& instance);
55 /// The copy constructor for <code>VideoEncoder</code>.
56 /// @param[in] other A reference to a <code>VideoEncoder</code>.
57 VideoEncoder(const VideoEncoder& other);
59 /// Gets an array of supported video encoder profiles.
60 /// These can be used to choose a profile before calling Initialize().
61 ///
62 /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
63 /// called upon completion with the PP_VideoProfileDescription structs.
64 ///
65 /// @return If >= 0, the number of supported profiles returned, otherwise an
66 /// error code from <code>pp_errors.h</code>.
67 int32_t GetSupportedProfiles(const CompletionCallbackWithOutput<
68 std::vector<PP_VideoProfileDescription> >& cc);
70 /// Initializes a video encoder resource. This should be called after
71 /// GetSupportedProfiles() and before any functions below.
72 ///
73 /// @param[in] input_format The <code>PP_VideoFrame_Format</code> of the
74 /// frames which will be encoded.
75 /// @param[in] input_visible_size A <code>Size</code> specifying the
76 /// dimensions of the visible part of the input frames.
77 /// @param[in] output_profile A <code>PP_VideoProfile</code> specifying the
78 /// codec profile of the encoded output stream.
79 /// @param[in] acceleration A <code>PP_HardwareAcceleration</code> specifying
80 /// whether to use a hardware accelerated or a software implementation.
81 /// @param[in] callback A <code>CompletionCallback</code> to be called upon
82 /// completion.
83 ///
84 /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
85 /// Returns PP_ERROR_NOTSUPPORTED if video encoding is not available, or the
86 /// requested codec profile is not supported.
87 /// Returns PP_ERROR_NOMEMORY if frame and bitstream buffers can't be created.
88 int32_t Initialize(const PP_VideoFrame_Format& input_format,
89 const Size& input_visible_size,
90 const PP_VideoProfile& output_profile,
91 const uint32_t initial_bitrate,
92 PP_HardwareAcceleration acceleration,
93 const CompletionCallback& cc);
95 /// Gets the number of input video frames that the encoder may hold while
96 /// encoding. If the plugin is providing the video frames, it should have at
97 /// least this many available.
98 ///
99 /// @return An int32_t containing the number of frames required, or an error
100 /// code from <code>pp_errors.h</code>.
101 /// Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
102 int32_t GetFramesRequired();
104 /// Gets the coded size of the video frames required by the encoder. Coded
105 /// size is the logical size of the input frames, in pixels. The encoder may
106 /// have hardware alignment requirements that make this different from
107 /// |input_visible_size|, as requested in the call to Initialize().
109 /// @param[in] coded_size A <code>Size</code> to hold the coded size.
111 /// @return An int32_t containing a result code from <code>pp_errors.h</code>.
112 /// Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
113 int32_t GetFrameCodedSize(Size* coded_size);
115 /// Gets a blank video frame which can be filled with video data and passed
116 /// to the encoder.
118 /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
119 /// called upon completion with the blank <code>VideoFrame</code> resource.
121 /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
122 int32_t GetVideoFrame(const CompletionCallbackWithOutput<VideoFrame>& cc);
124 /// Encodes a video frame.
126 /// @param[in] video_frame The <code>VideoFrame</code> to be encoded.
127 /// @param[in] force_keyframe A <code>PP_Bool> specifying whether the encoder
128 /// should emit a key frame for this video frame.
129 /// @param[in] callback A <code>CompletionCallback</code> to be called upon
130 /// completion. Plugins that pass <code>VideoFrame</code> resources owned
131 /// by other resources should wait for completion before reusing them.
133 /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
134 /// Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
135 int32_t Encode(const VideoFrame& video_frame,
136 bool force_keyframe,
137 const CompletionCallback& cc);
139 /// Gets the next encoded bitstream buffer from the encoder.
141 /// @param[out] bitstream_buffer A <code>PP_BitstreamBuffer</code> containing
142 /// encoded video data.
143 /// @param[in] callback A <code>CompletionCallbackWithOutput</code> to be
144 /// called upon completion with the next bitstream buffer. The plugin can call
145 /// GetBitstreamBuffer from the callback in order to continuously "pull"
146 /// bitstream buffers from the encoder.
148 /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
149 /// Returns PP_ERROR_FAILED if Initialize() has not successfully completed.
150 /// Returns PP_ERROR_INPROGRESS if a prior call to GetBitstreamBuffer() has
151 /// not completed.
152 int32_t GetBitstreamBuffer(
153 const CompletionCallbackWithOutput<PP_BitstreamBuffer>& cc);
155 /// Recycles a bitstream buffer back to the encoder.
157 /// @param[in] bitstream_buffer A <code>PP_BitstreamBuffer</code> that is no
158 /// longer needed by the plugin.
159 void RecycleBitstreamBuffer(const PP_BitstreamBuffer& bitstream_buffer);
161 /// Requests a change to encoding parameters. This is only a request,
162 /// fulfilled on a best-effort basis.
164 /// @param[in] bitrate The requested new bitrate, in bits per second.
165 /// @param[in] framerate The requested new framerate, in frames per second.
166 void RequestEncodingParametersChange(uint32_t bitrate, uint32_t framerate);
168 /// Closes the video encoder, and cancels any pending encodes. Any pending
169 /// callbacks will still run, reporting <code>PP_ERROR_ABORTED</code> . It is
170 /// not valid to call any encoder functions after a call to this method.
171 /// <strong>Note:</strong> Destroying the video encoder closes it implicitly,
172 /// so you are not required to call Close().
173 void Close();
176 } // namespace pp
178 #endif // PPAPI_CPP_VIDEO_ENCODER_H_