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 16 namespace 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. 21 class 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 154 namespace base { 155 156 template <class T> 157 struct DefaultDeleter; 158 159 // Specialize DefaultDeleter so that scoped_ptr<VideoDecodeAccelerator> always 160 // uses "Destroy()" instead of trying to use the destructor. 161 template <> 162 struct 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
