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 "base/memory/weak_ptr.h"
  12 #include "media/base/bitstream_buffer.h"
  13 #include "media/base/video_decoder_config.h"
  14 #include "media/video/picture.h"
  15 #include "ui/gfx/size.h"
  16
  17 namespace media {
  18
  19 // Video decoder interface.
  20 // This interface is extended by the various components that ultimately
  21 // implement the backend of PPB_VideoDecode_Dev.
  22 class MEDIA_EXPORT VideoDecodeAccelerator
  23     : public base::SupportsWeakPtr<VideoDecodeAccelerator> {
  24  public:
  25   virtual ~VideoDecodeAccelerator();
  26
  27   // Enumeration of potential errors generated by the API.
  28   // Note: Keep these in sync with PP_VideoDecodeError_Dev. Also do not
  29   // rearrange, reuse or remove values as they are used for gathering UMA
  30   // statistics.
  31   enum Error {
  32     // An operation was attempted during an incompatible decoder state.
  33     ILLEGAL_STATE = 1,
  34     // Invalid argument was passed to an API method.
  35     INVALID_ARGUMENT,
  36     // Encoded input is unreadable.
  37     UNREADABLE_INPUT,
  38     // A failure occurred at the browser layer or one of its dependencies.
  39     // Examples of such failures include GPU hardware failures, GPU driver
  40     // failures, GPU library failures, browser programming errors, and so on.
  41     PLATFORM_FAILURE,
  42     // Largest used enum. This should be adjusted when new errors are added.
  43     LARGEST_ERROR_ENUM,
  44   };
  45
  46   // Interface for collaborating with picture interface to provide memory for
  47   // output picture and blitting them.
  48   // This interface is extended by the various layers that relay messages back
  49   // to the plugin, through the PPP_VideoDecode_Dev interface the plugin
  50   // implements.
  51   class MEDIA_EXPORT Client {
  52    public:
  53     // Callback to notify client that decoder has been initialized.
  54     virtual void NotifyInitializeDone() = 0;
  55
  56     // Callback to tell client how many and what size of buffers to provide.
  57     virtual void ProvidePictureBuffers(uint32 requested_num_of_buffers,
  58                                        const gfx::Size& dimensions,
  59                                        uint32 texture_target) = 0;
  60
  61     // Callback to dismiss picture buffer that was assigned earlier.
  62     virtual void DismissPictureBuffer(int32 picture_buffer_id) = 0;
  63
  64     // Callback to deliver decoded pictures ready to be displayed.
  65     virtual void PictureReady(const Picture& picture) = 0;
  66
  67     // Callback to notify that decoded has decoded the end of the current
  68     // bitstream buffer.
  69     virtual void NotifyEndOfBitstreamBuffer(int32 bitstream_buffer_id) = 0;
  70
  71     // Flush completion callback.
  72     virtual void NotifyFlushDone() = 0;
  73
  74     // Reset completion callback.
  75     virtual void NotifyResetDone() = 0;
  76
  77     // Callback to notify about decoding errors.
  78     virtual void NotifyError(Error error) = 0;
  79
  80    protected:
  81     virtual ~Client() {}
  82   };
  83
  84   // Video decoder functions.
  85
  86   // Initializes the video decoder with specific configuration.
  87   // Parameters:
  88   //  |profile| is the video stream's format profile.
  89   //
  90   // Returns true when command successfully accepted. Otherwise false.
  91   virtual bool Initialize(VideoCodecProfile profile) = 0;
  92
  93   // Decodes given bitstream buffer. Once decoder is done with processing
  94   // |bitstream_buffer| it will call NotifyEndOfBitstreamBuffer() with the
  95   // bitstream buffer id.
  96   // Parameters:
  97   //  |bitstream_buffer| is the input bitstream that is sent for decoding.
  98   virtual void Decode(const BitstreamBuffer& bitstream_buffer) = 0;
  99
 100   // Assigns a set of texture-backed picture buffers to the video decoder.
 101   //
 102   // Ownership of each picture buffer remains with the client, but the client
 103   // is not allowed to deallocate the buffer before the DismissPictureBuffer
 104   // callback has been initiated for a given buffer.
 105   //
 106   // Parameters:
 107   //  |buffers| contains the allocated picture buffers for the output.
 108   virtual void AssignPictureBuffers(
 109       const std::vector<PictureBuffer>& buffers) = 0;
 110
 111   // Sends picture buffers to be reused by the decoder. This needs to be called
 112   // for each buffer that has been processed so that decoder may know onto which
 113   // picture buffers it can write the output to.
 114   //
 115   // Parameters:
 116   //  |picture_buffer_id| id of the picture buffer that is to be reused.
 117   virtual void ReusePictureBuffer(int32 picture_buffer_id) = 0;
 118
 119   // Flushes the decoder: all pending inputs will be decoded and pictures handed
 120   // back to the client, followed by NotifyFlushDone() being called on the
 121   // client.  Can be used to implement "end of stream" notification.
 122   virtual void Flush() = 0;
 123
 124   // Resets the decoder: all pending inputs are dropped immediately and the
 125   // decoder returned to a state ready for further Decode()s, followed by
 126   // NotifyResetDone() being called on the client.  Can be used to implement
 127   // "seek".
 128   virtual void Reset() = 0;
 129
 130   // Destroys the decoder: all pending inputs are dropped immediately and the
 131   // component is freed.  This call may asynchornously free system resources,
 132   // but its client-visible effects are synchronous.  After this method returns
 133   // no more callbacks will be made on the client.  Deletes |this|
 134   // unconditionally, so make sure to drop all pointers to it!
 135   virtual void Destroy() = 0;
 136 };
 137
 138 }  // namespace media
 139
 140 #endif  // MEDIA_VIDEO_VIDEO_DECODE_ACCELERATOR_H_