• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Copyright (c) 2012 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 // Note: ported from Chromium commit head: 85fdf90
5 
6 #ifndef VIDEO_DECODE_ACCELERATOR_H_
7 #define VIDEO_DECODE_ACCELERATOR_H_
8 
9 #include <vector>
10 
11 #include "base/memory/ref_counted.h"
12 #include "base/memory/weak_ptr.h"
13 
14 #include "bitstream_buffer.h"
15 #include "native_pixmap_handle.h"
16 #include "picture.h"
17 #include "size.h"
18 #include "video_codecs.h"
19 #include "video_pixel_format.h"
20 
21 namespace base {
22 class SingleThreadTaskRunner;
23 }
24 
25 namespace media {
26 
27 // Video decoder interface.
28 // This interface is extended by the various components that ultimately
29 // implement the backend of PPB_VideoDecoder_Dev.
30 class VideoDecodeAccelerator {
31  public:
32   // Specification of a decoding profile supported by an decoder.
33   // |max_resolution| and |min_resolution| are inclusive.
34   struct SupportedProfile {
35     SupportedProfile();
36     ~SupportedProfile();
37     VideoCodecProfile profile;
38     Size max_resolution;
39     Size min_resolution;
40     bool encrypted_only;
41   };
42   using SupportedProfiles = std::vector<SupportedProfile>;
43 
44   struct Capabilities {
45     Capabilities();
46     Capabilities(const Capabilities& other);
47     ~Capabilities();
48 
49     std::string AsHumanReadableString() const;
50 
51     // Flags that can be associated with a VDA.
52     enum Flags {
53       NO_FLAGS = 0,
54 
55       // Normally, the VDA is required to be able to provide all PictureBuffers
56       // to the client via PictureReady(), even if the client does not return
57       // any of them via ReusePictureBuffer().  The client is only required to
58       // return PictureBuffers when it holds all of them, if it wants to get
59       // more decoded output.  See VideoDecoder::CanReadWithoutStalling for
60       // more context.
61       // If this flag is set, then the VDA does not make this guarantee.  The
62       // client must return PictureBuffers to be sure that new frames will be
63       // provided via PictureReady.
64       NEEDS_ALL_PICTURE_BUFFERS_TO_DECODE = 1 << 0,
65 
66       // Whether the VDA supports being configured with an output surface for
67       // it to render frames to. For example, SurfaceViews on Android.
68       SUPPORTS_EXTERNAL_OUTPUT_SURFACE = 1 << 1,
69 
70       // If set, the VDA will use deferred initialization if the config
71       // indicates that the client supports it as well.  Refer to
72       // NotifyInitializationComplete for more details.
73       SUPPORTS_DEFERRED_INITIALIZATION = 1 << 2,
74 
75       // If set, video frames will have COPY_REQUIRED flag which will cause
76       // an extra texture copy during composition.
77       REQUIRES_TEXTURE_COPY = 1 << 3,
78 
79       // Whether the VDA supports encrypted streams or not.
80       SUPPORTS_ENCRYPTED_STREAMS = 1 << 4,
81 
82       // If set the decoder does not require a restart in order to switch to
83       // using an external output surface.
84       SUPPORTS_SET_EXTERNAL_OUTPUT_SURFACE = 1 << 5,
85     };
86 
87     SupportedProfiles supported_profiles;
88     uint32_t flags;
89   };
90 
91   // Enumeration of potential errors generated by the API.
92   // Note: Keep these in sync with PP_VideoDecodeError_Dev. Also do not
93   // rearrange, reuse or remove values as they are used for gathering UMA
94   // statistics.
95   enum Error {
96     // An operation was attempted during an incompatible decoder state.
97     ILLEGAL_STATE = 1,
98     // Invalid argument was passed to an API method.
99     INVALID_ARGUMENT,
100     // Encoded input is unreadable.
101     UNREADABLE_INPUT,
102     // A failure occurred at the browser layer or one of its dependencies.
103     // Examples of such failures include GPU hardware failures, GPU driver
104     // failures, GPU library failures, browser programming errors, and so on.
105     PLATFORM_FAILURE,
106     // Largest used enum. This should be adjusted when new errors are added.
107     ERROR_MAX = PLATFORM_FAILURE,
108   };
109 
110   // Config structure contains parameters required for the VDA initialization.
111   struct Config {
112     // Specifies the allocation and handling mode for output PictureBuffers.
113     // When set to ALLOCATE, the VDA is expected to allocate backing memory
114     // for PictureBuffers at the time of AssignPictureBuffers() call.
115     // When set to IMPORT, the VDA will not allocate, but after receiving
116     // AssignPictureBuffers() call, it will expect a call to
117     // ImportBufferForPicture() for each PictureBuffer before use.
118     enum class OutputMode {
119       ALLOCATE,
120       IMPORT,
121     };
122 
123     Config();
124     Config(const Config& config);
125 
126     explicit Config(VideoCodecProfile profile);
127 
128     ~Config();
129 
130     std::string AsHumanReadableString() const;
131 
132     // The video codec and profile.
133     VideoCodecProfile profile = VIDEO_CODEC_PROFILE_UNKNOWN;
134 
135     // Whether the client supports deferred initialization.
136     bool is_deferred_initialization_allowed = false;
137 
138     // Coded size of the video frame hint, subject to change.
139     Size initial_expected_coded_size = Size(320, 240);
140 
141     OutputMode output_mode = OutputMode::ALLOCATE;
142 
143     // The list of picture buffer formats that the client knows how to use. An
144     // empty list means any format is supported.
145     std::vector<VideoPixelFormat> supported_output_formats;
146 
147     // The H264 SPS and PPS configuration data. Not all clients populate these
148     // fields, so they should be parsed from the bitstream instead, if required.
149     // Each SPS and PPS is prefixed with the Annex B framing bytes: 0, 0, 0, 1.
150     std::vector<uint8_t> sps;
151     std::vector<uint8_t> pps;
152   };
153 
154   // Interface for collaborating with picture interface to provide memory for
155   // output picture and blitting them. These callbacks will not be made unless
156   // Initialize() has returned successfully.
157   // This interface is extended by the various layers that relay messages back
158   // to the plugin, through the PPP_VideoDecoder_Dev interface the plugin
159   // implements.
160   class Client {
161    public:
162     // Notify the client that deferred initialization has completed successfully
163     // or not.  This is required if and only if deferred initialization is
164     // supported by the VDA (see Capabilities), and it is supported by the
165     // client (see Config::is_deferred_initialization_allowed), and the initial
166     // call to VDA::Initialize returns true.
167     // The default implementation is a NOTREACHED, since deferred initialization
168     // is not supported by default.
169     virtual void NotifyInitializationComplete(bool success);
170 
171     // Callback to tell client how many and what size of buffers to provide.
172     // Note that the actual count provided through AssignPictureBuffers() can be
173     // larger than the value requested.
174     // |format| indicates what format the decoded frames will be produced in
175     // by the VDA, or PIXEL_FORMAT_UNKNOWN if the underlying platform handles
176     // this transparently.
177     virtual void ProvidePictureBuffers(uint32_t requested_num_of_buffers,
178                                        VideoPixelFormat format,
179                                        const Size& dimensions) = 0;
180 
181     // Callback to dismiss picture buffer that was assigned earlier.
182     virtual void DismissPictureBuffer(int32_t picture_buffer_id) = 0;
183 
184     // Callback to deliver decoded pictures ready to be displayed.
185     virtual void PictureReady(const Picture& picture) = 0;
186 
187     // Callback to notify that decoded has decoded the end of the current
188     // bitstream buffer.
189     virtual void NotifyEndOfBitstreamBuffer(int32_t bitstream_buffer_id) = 0;
190 
191     // Flush completion callback.
192     virtual void NotifyFlushDone() = 0;
193 
194     // Reset completion callback.
195     virtual void NotifyResetDone() = 0;
196 
197     // Callback to notify about decoding errors. Note that errors in
198     // Initialize() will not be reported here, but will instead be indicated by
199     // a false return value there.
200     virtual void NotifyError(Error error) = 0;
201 
202    protected:
~Client()203     virtual ~Client() {}
204   };
205 
206   // Video decoder functions.
207 
208   // Initializes the video decoder with specific configuration.  Called once per
209   // decoder construction.  This call is synchronous and returns true iff
210   // initialization is successful, unless deferred initialization is used.
211   //
212   // By default, deferred initialization is not used.  However, if Config::
213   // is_deferred_initialization_allowed is set by the client, and if
214   // Capabilities::Flags::SUPPORTS_DEFERRED_INITIALIZATION is set by the VDA,
215   // and if VDA::Initialize returns true, then the client can expect a call to
216   // NotifyInitializationComplete with the actual success / failure of
217   // initialization.  Note that a return value of false from VDA::Initialize
218   // indicates that initialization definitely failed, and no callback is needed.
219   //
220   // For encrypted video, only deferred initialization is supported and |config|
221   // must contain a valid |cdm_id|.
222   //
223   // Parameters:
224   //  |config| contains the initialization parameters.
225   //  |client| is the client of this video decoder. Does not take ownership of
226   //  |client| which must be valid until Destroy() is called.
227   virtual bool Initialize(const Config& config, Client* client) = 0;
228 
229   // Decodes given bitstream buffer that contains at most one frame.  Once
230   // decoder is done with processing |bitstream_buffer| it will call
231   // NotifyEndOfBitstreamBuffer() with the bitstream buffer id.
232   // Parameters:
233   //  |bitstream_buffer| is the input bitstream that is sent for decoding.
234   virtual void Decode(const BitstreamBuffer& bitstream_buffer) = 0;
235 
236   // Assigns a set of texture-backed picture buffers to the video decoder.
237   //
238   // Ownership of each picture buffer remains with the client, but the client
239   // is not allowed to deallocate the buffer before the DismissPictureBuffer
240   // callback has been initiated for a given buffer.
241   //
242   // Parameters:
243   //  |buffers| contains the allocated picture buffers for the output.  Note
244   //  that the count of buffers may be larger than the count requested through
245   //  the call to Client::ProvidePictureBuffers().
246   virtual void AssignPictureBuffers(
247       const std::vector<PictureBuffer>& buffers) = 0;
248 
249   // Imports |gpu_memory_buffer_handle|, pointing to a buffer in |pixel_format|,
250   // as backing memory for picture buffer associated with |picture_buffer_id|.
251   // This can only be be used if the VDA has been Initialize()d with
252   // config.output_mode = IMPORT, and should be preceded by a call to
253   // AssignPictureBuffers() to set up the number of PictureBuffers and their
254   // details.
255   // The |pixel_format| used here may be different from the |pixel_format|
256   // required in ProvidePictureBuffers(). If the buffer cannot be imported an
257   // error should be notified via NotifyError().
258   // After this call, the VDA becomes the owner of those file descriptors,
259   // and is responsible for closing it after use, also on import failure.
260   virtual void ImportBufferForPicture(
261       int32_t picture_buffer_id,
262       VideoPixelFormat pixel_format,
263       const NativePixmapHandle& native_pixmap_handle);
264 
265   // Sends picture buffers to be reused by the decoder. This needs to be called
266   // for each buffer that has been processed so that decoder may know onto which
267   // picture buffers it can write the output to.
268   //
269   // Parameters:
270   //  |picture_buffer_id| id of the picture buffer that is to be reused.
271   virtual void ReusePictureBuffer(int32_t picture_buffer_id) = 0;
272 
273   // Flushes the decoder: all pending inputs will be decoded and pictures handed
274   // back to the client, followed by NotifyFlushDone() being called on the
275   // client.  Can be used to implement "end of stream" notification.
276   virtual void Flush() = 0;
277 
278   // Resets the decoder: all pending inputs are dropped immediately and the
279   // decoder returned to a state ready for further Decode()s, followed by
280   // NotifyResetDone() being called on the client.  Can be used to implement
281   // "seek". After Flush is called, it is OK to call Reset before receiving
282   // NotifyFlushDone() and VDA should cancel the flush. Note NotifyFlushDone()
283   // may be on the way to the client. If client gets NotifyFlushDone(), it
284   // should be before NotifyResetDone().
285   virtual void Reset() = 0;
286 
287   // Destroys the decoder: all pending inputs are dropped immediately and the
288   // component is freed.  This call may asynchornously free system resources,
289   // but its client-visible effects are synchronous.  After this method returns
290   // no more callbacks will be made on the client.  Deletes |this|
291   // unconditionally, so make sure to drop all pointers to it!
292   virtual void Destroy() = 0;
293 
294   // TO BE CALLED IN THE SAME PROCESS AS THE VDA IMPLEMENTATION ONLY.
295   //
296   // A decode "task" is a sequence that includes a Decode() call from Client,
297   // as well as corresponding callbacks to return the input BitstreamBuffer
298   // after use, and the resulting output Picture(s).
299   //
300   // If the Client can support running these three calls on a separate thread,
301   // it may call this method to try to set up the VDA implementation to do so.
302   // If the VDA can support this as well, return true, otherwise return false.
303   // If true is returned, the client may submit each Decode() call (but no other
304   // calls) on |decode_task_runner|, and should then expect that
305   // NotifyEndOfBitstreamBuffer() and PictureReady() callbacks may come on
306   // |decode_task_runner| as well, called on |decode_client|, instead of client
307   // provided to Initialize().
308   //
309   // This method may be called at any time.
310   //
311   // NOTE 1: some callbacks may still have to come on the main thread and the
312   // Client should handle both callbacks coming on main and |decode_task_runner|
313   // thread.
314   //
315   // NOTE 2: VDA implementations of Decode() must return as soon as possible and
316   // never block, as |decode_task_runner| may be a latency critical thread
317   // (such as the GPU IO thread).
318   //
319   // One application of this is offloading the GPU Child thread. In general,
320   // calls to VDA in GPU process have to be done on the GPU Child thread, as
321   // they may require GL context to be current. However, some VDAs may be able
322   // to run decode operations without GL context, which helps reduce latency and
323   // offloads the GPU Child thread.
324   virtual bool TryToSetupDecodeOnSeparateThread(
325       const base::WeakPtr<Client>& decode_client,
326       const scoped_refptr<base::SingleThreadTaskRunner>& decode_task_runner);
327 
328  protected:
329   // Do not delete directly; use Destroy() or own it with a scoped_ptr, which
330   // will Destroy() it properly by default.
331   virtual ~VideoDecodeAccelerator();
332 };
333 
334 }  // namespace media
335 
336 namespace std {
337 
338 // Specialize std::default_delete so that
339 // std::unique_ptr<VideoDecodeAccelerator> uses "Destroy()" instead of trying to
340 // use the destructor.
341 template <>
342 struct default_delete<media::VideoDecodeAccelerator> {
343   void operator()(media::VideoDecodeAccelerator* vda) const;
344 };
345 
346 }  // namespace std
347 
348 #endif  // VIDEO_DECODE_ACCELERATOR_H_
349