Add a VideoDecodeContext that provides resources for a VideoDecodeEngine

media/video/video_decode_context.h

+// Copyright (c) 2010 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef MEDIA_VIDEO_VIDEO_DECODE_CONTEXT_H_
+#define MEDIA_VIDEO_VIDEO_DECODE_CONTEXT_H_
+
+#include "base/callback.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.
+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
+  // handle is a contract between the implementation of VideoDecodeContext and
+  // VideoDecodeEngine.
+  //
+  // 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|
+  // is called when allocation has completed.
+  virtual void AllocateVideoFrames(int n, size_t width, size_t height,
+                                   AllocationCompleteCallback* callback) = 0;
+
+  // Release 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;

[scherkus (not reviewing), 2010/09/03 17:50:14]

this is still a bit clumsy

so AllocateVideoFrames returns an array of VideoFrame* (basically a
VideoFrame**).  Do I copy the array of pointers or do I now own the array of
pointers?

What am I passing in here?  The pointer to the array returned from
AllocateVideoFrames?  if I copied the array of pointers, is the implementor
looking for and releasing each element, or is the implementor looking for the
just the start of the array (the one passed back from AllocateVideoFrames)?

Also why are we passing in n?  If I allocated 3 frames, what happens when I pass
in 2?

I'm wondering if this would be easier to understand if it worked like calloc():
  - AllocateVideoFrame(n) -> a single VideoFrame* that can be accessed at
indices [0-2]
  - ReleaseVideoFrame(VideoFrame*) -> pass back in original pointer from
AllocateVideoFrame

Also the documentation still hasn't be updated to explain whether we're allow to
call Allocate() as much as we want.  If we are.. then I'm wondering if perhaps
we should stick with just single Allocate/Release.  If you want three frames,
fire off 3 allocs + callbacks and wait for them all to finish.  This might be
over pedantic, but what if we only allocate 2/3 frames -- is it all/nothing? 
Will the implementor have to free whatever it allocated and return failure
somehow?

+
+  // Destroy this context asynchronously. When the operation is done |callback|
+  // is called.
+  //
+  // ReleaseVideoFrames() need to be called with all the video frames allocated
+  // before making this call.
+  virtual void Destroy(DestructionCompleteCallback* callback) = 0;
+};
+
+}  // namespace media
+
+#endif  // MEDIA_VIDEO_VIDEO_DECODE_CONTEXT_H_