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
5#ifndef MEDIA_VIDEO_VIDEO_DECODE_ACCELERATOR_H_
6#define MEDIA_VIDEO_VIDEO_DECODE_ACCELERATOR_H_
7
8#include <vector>
9
10#include "base/basictypes.h"
11#include "media/base/bitstream_buffer.h"
12#include "media/base/video_decoder_config.h"
13#include "media/video/picture.h"
14#include "ui/gfx/size.h"
15
16namespace media {
17
18// Video decoder interface.
19// This interface is extended by the various components that ultimately
20// implement the backend of PPB_VideoDecode_Dev.
21class MEDIA_EXPORT VideoDecodeAccelerator {
22 public:
23  // Enumeration of potential errors generated by the API.
24  // Note: Keep these in sync with PP_VideoDecodeError_Dev. Also do not
25  // rearrange, reuse or remove values as they are used for gathering UMA
26  // statistics.
27  enum Error {
28    // An operation was attempted during an incompatible decoder state.
29    ILLEGAL_STATE = 1,
30    // Invalid argument was passed to an API method.
31    INVALID_ARGUMENT,
32    // Encoded input is unreadable.
33    UNREADABLE_INPUT,
34    // A failure occurred at the browser layer or one of its dependencies.
35    // Examples of such failures include GPU hardware failures, GPU driver
36    // failures, GPU library failures, browser programming errors, and so on.
37    PLATFORM_FAILURE,
38    // Largest used enum. This should be adjusted when new errors are added.
39    LARGEST_ERROR_ENUM,
40  };
41
42  // Interface for collaborating with picture interface to provide memory for
43  // output picture and blitting them. These callbacks will not be made unless
44  // Initialize() has returned successfully.
45  // This interface is extended by the various layers that relay messages back
46  // to the plugin, through the PPP_VideoDecode_Dev interface the plugin
47  // implements.
48  class MEDIA_EXPORT Client {
49   public:
50    // Callback to tell client how many and what size of buffers to provide.
51    virtual void ProvidePictureBuffers(uint32 requested_num_of_buffers,
52                                       const gfx::Size& dimensions,
53                                       uint32 texture_target) = 0;
54
55    // Callback to dismiss picture buffer that was assigned earlier.
56    virtual void DismissPictureBuffer(int32 picture_buffer_id) = 0;
57
58    // Callback to deliver decoded pictures ready to be displayed.
59    virtual void PictureReady(const Picture& picture) = 0;
60
61    // Callback to notify that decoded has decoded the end of the current
62    // bitstream buffer.
63    virtual void NotifyEndOfBitstreamBuffer(int32 bitstream_buffer_id) = 0;
64
65    // Flush completion callback.
66    virtual void NotifyFlushDone() = 0;
67
68    // Reset completion callback.
69    virtual void NotifyResetDone() = 0;
70
71    // Callback to notify about decoding errors. Note that errors in
72    // Initialize() will not be reported here, but will instead be indicated by
73    // a false return value there.
74    virtual void NotifyError(Error error) = 0;
75
76   protected:
77    virtual ~Client() {}
78  };
79
80  // Video decoder functions.
81
82  // Initializes the video decoder with specific configuration.  Called once per
83  // decoder construction.  This call is synchronous and returns true iff
84  // initialization is successful.
85  // Parameters:
86  //  |profile| is the video stream's format profile.
87  //  |client| is the client of this video decoder.  The provided pointer must
88  //  be valid until Destroy() is called.
89  virtual bool Initialize(VideoCodecProfile profile, Client* client) = 0;
90
91  // Decodes given bitstream buffer that contains at most one frame.  Once
92  // decoder is done with processing |bitstream_buffer| it will call
93  // NotifyEndOfBitstreamBuffer() with the bitstream buffer id.
94  // Parameters:
95  //  |bitstream_buffer| is the input bitstream that is sent for decoding.
96  virtual void Decode(const BitstreamBuffer& bitstream_buffer) = 0;
97
98  // Assigns a set of texture-backed picture buffers to the video decoder.
99  //
100  // Ownership of each picture buffer remains with the client, but the client
101  // is not allowed to deallocate the buffer before the DismissPictureBuffer
102  // callback has been initiated for a given buffer.
103  //
104  // Parameters:
105  //  |buffers| contains the allocated picture buffers for the output.
106  virtual void AssignPictureBuffers(
107      const std::vector<PictureBuffer>& buffers) = 0;
108
109  // Sends picture buffers to be reused by the decoder. This needs to be called
110  // for each buffer that has been processed so that decoder may know onto which
111  // picture buffers it can write the output to.
112  //
113  // Parameters:
114  //  |picture_buffer_id| id of the picture buffer that is to be reused.
115  virtual void ReusePictureBuffer(int32 picture_buffer_id) = 0;
116
117  // Flushes the decoder: all pending inputs will be decoded and pictures handed
118  // back to the client, followed by NotifyFlushDone() being called on the
119  // client.  Can be used to implement "end of stream" notification.
120  virtual void Flush() = 0;
121
122  // Resets the decoder: all pending inputs are dropped immediately and the
123  // decoder returned to a state ready for further Decode()s, followed by
124  // NotifyResetDone() being called on the client.  Can be used to implement
125  // "seek".
126  virtual void Reset() = 0;
127
128  // Destroys the decoder: all pending inputs are dropped immediately and the
129  // component is freed.  This call may asynchornously free system resources,
130  // but its client-visible effects are synchronous.  After this method returns
131  // no more callbacks will be made on the client.  Deletes |this|
132  // unconditionally, so make sure to drop all pointers to it!
133  virtual void Destroy() = 0;
134
135  // GPU PROCESS ONLY.  Implementations of this interface in the
136  // content/common/gpu/media should implement this, and implementations in
137  // other processes should not override the default implementation.
138  // Returns true if VDA::Decode and VDA::Client callbacks can run on the IO
139  // thread. Otherwise they will run on the GPU child thread. The purpose of
140  // running Decode on the IO thread is to reduce decode latency. Note Decode
141  // should return as soon as possible and not block on the IO thread. Also,
142  // PictureReady should be run on the child thread if a picture is delivered
143  // the first time so it can be cleared.
144  virtual bool CanDecodeOnIOThread();
145
146 protected:
147  // Do not delete directly; use Destroy() or own it with a scoped_ptr, which
148  // will Destroy() it properly by default.
149  virtual ~VideoDecodeAccelerator();
150};
151
152}  // namespace media
153
154namespace base {
155
156template <class T>
157struct DefaultDeleter;
158
159// Specialize DefaultDeleter so that scoped_ptr<VideoDecodeAccelerator> always
160// uses "Destroy()" instead of trying to use the destructor.
161template <>
162struct MEDIA_EXPORT DefaultDeleter<media::VideoDecodeAccelerator> {
163 public:
164  void operator()(void* video_decode_accelerator) const;
165};
166
167}  // namespace base
168
169#endif  // MEDIA_VIDEO_VIDEO_DECODE_ACCELERATOR_H_
170