Checking in media common header file and buffer pure interfaces.

media/base/buffers.h

 // Copyright (c) 2006-2008 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.
 
+// Defines various types of timestamped media buffers used for transporting

[darin (slow to review), 2008/12/08 20:40:47]

nice!

+// data between filters.  Every buffer contains a timestamp in microseconds
+// describing the relative position of the buffer within the media stream, and
+// the duration in microseconds for the length of time the buffer will be
+// rendered.
+//
+// Timestamps are derived directly from the encoded media file and are commonly
+// known as the presentation timestamp (PTS).  Durations are a best-guess and
+// are usually derived from the sample/frame rate of the media file.
+//
+// Due to encoding and transmission errors, it is not guaranteed that timestamps
+// arrive in a monotonically increasing order nor that the next timestamp will
+// be equal to the previous timestamp plus the duration.
+//
+// In the ideal scenario for a 25fps movie, buffers are timestamped as followed:
+//
+//               Buffer0      Buffer1      Buffer2      ...      BufferN
+// Timestamp:        0us      40000us      80000us      ...   (N*40000)us
+// Duration*:    40000us      40000us      40000us      ...       40000us
+//
+//  *25fps = 0.04s per frame = 40000us per frame
+
 #ifndef MEDIA_BASE_BUFFERS_H_
 #define MEDIA_BASE_BUFFERS_H_
 
-#include "base/basictypes.h"
 #include "base/ref_counted.h"
 
 namespace media {
 
-// NOTE: this isn't a true interface since RefCountedThreadSafe has non-virtual
-// members, therefore implementors should NOT subclass RefCountedThreadSafe.
-//
-// If you do, AddRef/Release will have different outcomes depending on the
-// current type of the pointer (StreamSampleInterface vs. SomeImplementation).
 class StreamSampleInterface :
     public base::RefCountedThreadSafe<StreamSampleInterface> {
  public:
+  // Returns the timestamp of this buffer in microseconds.
+  virtual int64 GetTimestamp() = 0;
+
+  // Returns the duration of this buffer in microseconds.
+  virtual int64 GetDuration() = 0;
+
+  // Sets the timestamp of this buffer in microseconds.
+  virtual void SetTimestamp(int64 timestamp) = 0;
+
+  // Sets the duration of this buffer in microseconds.
+  virtual void SetDuration(int64 duration) = 0;
+
+ protected:
+  friend class base::RefCountedThreadSafe<StreamSampleInterface>;
   virtual ~StreamSampleInterface() {}
-
-  virtual int64 GetTimestamp() = 0;
-  virtual int64 GetDuration() = 0;
-  virtual void SetTimestamp(int64 timestamp) = 0;
-  virtual void SetDuration(int64 duration) = 0;
 };
 
 
 class BufferInterface : public StreamSampleInterface {
  public:
-  virtual ~BufferInterface() {}
-
   // Returns a read only pointer to the buffer data.
   virtual const char* GetData() = 0;
 
   // Returns the size of valid data in bytes.
   virtual size_t GetDataSize() = 0;
 };
 
 
 class WritableBufferInterface : public BufferInterface  {
  public:
-  virtual ~WritableBufferInterface() {}
-
   // Returns a read-write pointer to the buffer data.
   virtual char* GetWritableData() = 0;
 
   // Updates the size of valid data in bytes, which must be less than or equal
   // to GetBufferSize.
   virtual void SetDataSize(size_t data_size) = 0;
 
   // Returns the maximum allocated size for this buffer.
   virtual size_t GetBufferSize() = 0;
 };
@@ skipping 30 matching lines @@
   // of the surface divided by the horizontal sampling period.
   size_t strides[kMaxPlanes];
 
   // Array of data pointers to each plane.
   char* data[kMaxPlanes];
 };
 
 
 class VideoFrameInterface : public StreamSampleInterface {
  public:
-  virtual ~VideoFrameInterface() {}
-
   // Locks the underlying surface and fills out the given VideoSurface and
-  // returns true if successful, false otherwise.
+  // returns true if successful, false otherwise.  Any additional calls to Lock
+  // will fail.
   virtual bool Lock(VideoSurface* surface) = 0;
 
-  // Unlocks the underlying surface, any previous VideoSurfaces are no longer
-  // guaranteed to be valid.
+  // Unlocks the underlying surface, the VideoSurface acquired from Lock is no
+  // longer guaranteed to be valid.
   virtual void Unlock() = 0;
 };
 
 
 template <class BufferType>
 class AssignableInterface {
  public:
-  virtual ~AssignableInterface() {}
-
   // Assigns a buffer to the owner.
   virtual void SetBuffer(BufferType* buffer) = 0;
 
   // Notifies the owner that an assignment has been completed.
   virtual void OnAssignment() = 0;
 };
 
 
 // Template for easily creating AssignableInterface buffers.  Pass in the
 // pointer of the object to receive the OnAssignment callback.
 template <class OwnerType, class BufferType>
 class AssignableBuffer : public AssignableInterface<BufferType>,
     public base::RefCountedThreadSafe<AssignableBuffer<OwnerType, BufferType> > {
  public:
   explicit AssignableBuffer(OwnerType* owner)
     : owner_(owner),
       buffer_(NULL) {
     DCHECK(owner_);
   }
-  virtual ~AssignableBuffer() {}
 
   // AssignableBufferInterface<BufferType>
   virtual void SetBuffer(BufferType* buffer) {
     buffer_ = buffer;
   }
 
   virtual void OnAssignment() {
     owner_->OnAssignment(buffer_.get());
   }
 
  private:
   OwnerType* owner_;
   scoped_refptr<BufferType> buffer_;
 
   DISALLOW_COPY_AND_ASSIGN(AssignableBuffer);
 };
 
 } // namespace media
 
 #endif // MEDIA_BASE_BUFFERS_H_