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