1 files changed, 48 insertions, 15 deletions

diff --git a/media/video/video_decode_context.h b/media/video/video_decode_context.h
index 0bea382..f768a0a 100644
--- a/media/video/video_decode_context.h
+++ b/media/video/video_decode_context.h
@@ -5,20 +5,30 @@
 #ifndef MEDIA_VIDEO_VIDEO_DECODE_CONTEXT_H_
 #define MEDIA_VIDEO_VIDEO_DECODE_CONTEXT_H_
 
-#include "base/callback.h"
+#include <vector>
+
+#include "base/task.h"
+#include "media/base/video_frame.h"
 
 namespace media {
 
 class VideoFrame;
 
-// A VideoDecodeContext provides resources like output video frame storage and
-// hardware decoder handle to a VideoDecodeEngine, it hides all the platform and
-// subsystem details from the decode engine.
+// A VideoDecodeContext is used by VideoDecodeEngine to provide the following
+// functions:
+//
+// 1. Provides access to hardware video decoding device.
+// 2. Allocate VideoFrame objects that are used to carry the decoded video
+//    frames.
+// 3. Upload a device specific buffer to some common VideoFrame storage types.
+//    In many cases a VideoDecodeEngine provides its own buffer, these buffer
+//    are usually device specific and a conversion step is needed. Instead of
+//    handling these many cases in the renderer a VideoDecodeContext is used
+//    to convert the device specific buffer to a common storage format, e.g.
+//    GL textures or system memory. This way we keep the device specific code
+//    in the VideoDecodeEngine and VideoDecodeContext pair.
 class VideoDecodeContext {
  public:
-  typedef Callback2<int, VideoFrame*[]>::Type AllocationCompleteCallback;
-  typedef Callback0::Type DestructionCompleteCallback;
-
   virtual ~VideoDecodeContext() {};
 
   // Obtain a handle to the hardware video decoder device. The type of the
@@ -28,22 +38,45 @@ class VideoDecodeContext {
   // If a hardware device is not needed this method should return NULL.
   virtual void* GetDevice() = 0;
 
-  // Allocate |n| video frames with dimension |width| and |height|. |callback|
+  // Allocate |n| video frames with dimension |width| and |height|. |task|
   // is called when allocation has completed.
-  virtual void AllocateVideoFrames(int n, size_t width, size_t height,
-                                   AllocationCompleteCallback* callback) = 0;
+  //
+  // |frames| is the output parameter for VideFrame(s) allocated.
+  virtual void AllocateVideoFrames(
+      int n, size_t width, size_t height, VideoFrame::Format format,
+      std::vector<scoped_refptr<VideoFrame> >* frames,
+      Task* task) = 0;
 
-  // Release video frames allocated by the context. After making this call
+  // Release all video frames allocated by the context. After making this call
   // VideoDecodeEngine should not use the VideoFrame allocated because they
   // could be destroyed.
-  virtual void ReleaseVideoFrames(int n, VideoFrame* frames) = 0;
+  virtual void ReleaseAllVideoFrames() = 0;
+
+  // Upload a device specific buffer to a video frame. The video frame was
+  // allocated via AllocateVideoFrames().
+  // This method is used if a VideoDecodeEngine cannot write directly to a
+  // VideoFrame, e.g. upload should be done on a different thread, the subsystem
+  // require some special treatment to generate a VideoFrame. The goal is to
+  // keep VideoDecodeEngine a reusable component and also adapt to different
+  // system by having a different VideoDecodeContext.
+  //
+  // |frame| is a VideoFrame allocated via AllocateVideoFrames().
+  //
+  // |buffer| is of type void*, it is of an internal type in VideoDecodeEngine
+  // that points to the buffer that contains the video frame.
+  // Implementor should know how to handle it.
+  //
+  // |task| is executed if the operation was completed successfully.
+  // TODO(hclam): Rename this to ConvertToVideoFrame().
+  virtual void UploadToVideoFrame(void* buffer, scoped_refptr<VideoFrame> frame,
+                                  Task* task) = 0;
 
-  // Destroy this context asynchronously. When the operation is done |callback|
+  // Destroy this context asynchronously. When the operation is done |task|
   // is called.
   //
   // ReleaseVideoFrames() need to be called with all the video frames allocated
-  // before making this call.
-  virtual void Destroy(DestructionCompleteCallback* callback) = 0;
+ // before making this call.
+  virtual void Destroy(Task* task) = 0;
 };
 
 }  // namespace media