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.
5 #ifndef MEDIA_VIDEO_VIDEO_DECODE_ACCELERATOR_H_
6 #define MEDIA_VIDEO_VIDEO_DECODE_ACCELERATOR_H_
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"
18 // Video decoder interface.
19 // This interface is extended by the various components that ultimately
20 // implement the backend of PPB_VideoDecode_Dev.
21 class MEDIA_EXPORT VideoDecodeAccelerator
{
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
28 // An operation was attempted during an incompatible decoder state.
30 // Invalid argument was passed to an API method.
32 // Encoded input is unreadable.
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.
38 // Largest used enum. This should be adjusted when new errors are added.
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
48 class MEDIA_EXPORT Client
{
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;
55 // Callback to dismiss picture buffer that was assigned earlier.
56 virtual void DismissPictureBuffer(int32 picture_buffer_id
) = 0;
58 // Callback to deliver decoded pictures ready to be displayed.
59 virtual void PictureReady(const Picture
& picture
) = 0;
61 // Callback to notify that decoded has decoded the end of the current
63 virtual void NotifyEndOfBitstreamBuffer(int32 bitstream_buffer_id
) = 0;
65 // Flush completion callback.
66 virtual void NotifyFlushDone() = 0;
68 // Reset completion callback.
69 virtual void NotifyResetDone() = 0;
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;
80 // Video decoder functions.
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.
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;
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.
95 // |bitstream_buffer| is the input bitstream that is sent for decoding.
96 virtual void Decode(const BitstreamBuffer
& bitstream_buffer
) = 0;
98 // Assigns a set of texture-backed picture buffers to the video decoder.
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.
105 // |buffers| contains the allocated picture buffers for the output.
106 virtual void AssignPictureBuffers(
107 const std::vector
<PictureBuffer
>& buffers
) = 0;
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.
114 // |picture_buffer_id| id of the picture buffer that is to be reused.
115 virtual void ReusePictureBuffer(int32 picture_buffer_id
) = 0;
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;
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
126 virtual void Reset() = 0;
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;
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();
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();
157 struct DefaultDeleter
;
159 // Specialize DefaultDeleter so that scoped_ptr<VideoDecodeAccelerator> always
160 // uses "Destroy()" instead of trying to use the destructor.
162 struct MEDIA_EXPORT DefaultDeleter
<media::VideoDecodeAccelerator
> {
164 void operator()(void* video_decode_accelerator
) const;
169 #endif // MEDIA_VIDEO_VIDEO_DECODE_ACCELERATOR_H_