media/video/video_decode_accelerator.h

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