Relanding 1143663007: VideoFrame: Separate Pixel Format from Storage Type.

media/base/video_frame.h

 // Copyright (c) 2012 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_BASE_VIDEO_FRAME_H_
 #define MEDIA_BASE_VIDEO_FRAME_H_
 
 #include <vector>
 
 #include "base/callback.h"
@@ skipping 30 matching lines @@
     kUVPlane = kUPlane,
     kVPlane = 2,
     kAPlane = 3,
   };
 
   // Pixel formats roughly based on FOURCC labels, see:
   // http://www.fourcc.org/rgb.php
   // http://www.fourcc.org/yuv.php
   // Logged to UMA, so never reuse values. Leave gaps if necessary.
   enum Format {
-    UNKNOWN = 0,  // Unknown format value.
+    UNKNOWN = 0,  // Unknown or unspecified format value.
     YV12 = 1,  // 12bpp YVU planar 1x1 Y, 2x2 VU samples.
-    I420 = 2,  // 12bpp YVU planar 1x1 Y, 2x2 UV samples, a.k.a. YU12.
+    I420 = 2,  // 12bpp YUV planar 1x1 Y, 2x2 UV samples, a.k.a. YU12.
     YV16 = 3,  // 16bpp YVU planar 1x1 Y, 2x1 VU samples.
-    YV12A = 4,   // 20bpp YUVA planar 1x1 Y, 2x2 VU, 1x1 A samples.
+    YV12A = 4,  // 20bpp YUVA planar 1x1 Y, 2x2 VU, 1x1 A samples.
     YV24 = 5,  // 24bpp YUV planar, no subsampling.
-    NV12 = 6,  // 12bpp 1x1 Y plane followed by an interleaved 2x2 UV plane.
+#if defined(OS_MACOSX) || defined(OS_CHROMEOS)
+    NV12 = 6,  // 12bpp with Y plane followed by a 2x2 interleaved UV plane.
+#endif
     ARGB = 7,  // 32bpp ARGB, 1 plane.
-#if defined(VIDEO_HOLE)
-    HOLE = 8,  // Hole frame.
-#endif
-    NATIVE_TEXTURE = 9,  // Native texture.  Pixel-format agnostic.
+    XRGB = 8,  // 24bpp XRGB, 1 plane.
     // Please update UMA histogram enumeration when adding new formats here.
-    // Must always be equal to largest entry logged.
-    FORMAT_MAX = NATIVE_TEXTURE,
-  };
-
-  // Defines the internal format and the number of the textures in the mailbox
-  // holders.
-  enum TextureFormat {
-    TEXTURE_RGBA,  // One RGBA texture.
-    TEXTURE_RGB,  // One RGB texture.
-    TEXTURE_YUV_420,  // 3 RED textures one per channel. UV are 2x2 subsampled.
+    FORMAT_MAX = XRGB,  // Must always be equal to largest entry logged.
   };
 
   // Color space or color range used for the pixels, in general this is left
-  // unspecified, meaning SD is assumed.
+  // unspecified, meaning Rec601 (SD) is assumed.
   enum ColorSpace {
     COLOR_SPACE_UNSPECIFIED = 0,  // In general this is Rec601.
     COLOR_SPACE_JPEG = 1,  // JPEG color range.
     COLOR_SPACE_HD_REC709 = 2,  // Rec709 "HD" color space.
     COLOR_SPACE_MAX = COLOR_SPACE_HD_REC709,
   };
 
+  // Defines the pixel storage type. STORAGE_{OWNED, UNOWNED}_MEMORY and
+  // STORAGE_SHMEM have in common that are mappable, i.e. can be accessed from
+  // the VideoFrame memory space, whereas the rest, in principle, can't.
+  enum StorageType {
+    STORAGE_UNKNOWN = 0,
+    STORAGE_UNOWNED_MEMORY = 1,  // External, non owned data pointers.
+    STORAGE_OWNED_MEMORY = 2,  // VideoFrame has allocated its own data buffer.
+    STORAGE_SHMEM = 3,  // Pixels are backed by Shared Memory.
+#if defined(OS_LINUX)
+    STORAGE_DMABUFS = 4,  // Each plane is stored into a DmaBuf.
+#endif
+#if defined(VIDEO_HOLE)
+    // Opaque storage.
+    STORAGE_HOLE = 5,
+#endif
+    // Pixels are stored in textures, one per plane, referred by MailboxHolders.
+    STORAGE_TEXTURE = 6,
+    STORAGE_MAX = STORAGE_TEXTURE,  // Always equal to the last StorageType.
+  };
+
+  // CB to be called on the mailbox backing this frame when the frame is
+  // destroyed.
+  typedef base::Callback<void(uint32)> ReleaseMailboxCB;
+
   // Returns the name of a Format as a string.
   static std::string FormatToString(Format format);
 
-  // Creates a new frame in system memory with given parameters. Buffers for
-  // the frame are allocated but not initialized.
+  // Returns true if |format| is a YUV non interleaved format.
+  static bool IsYuvPlanar(Format format);
+
+  // Returns true if |storage_type| is mappable in the VideoFrame memory space.
+  static bool IsMappable(StorageType storage_type);
+
+  // Returns true if |plane| is a valid plane number for the given format.
+  static bool IsValidPlane(size_t plane, VideoFrame::Format format);
+
+  // Call prior to CreateFrame to ensure validity of frame configuration. Called
+  // automatically by VideoDecoderConfig::IsValidConfig().
+  // TODO(scherkus): VideoDecoderConfig shouldn't call this method
+  static bool IsValidConfig(Format format,
+                            StorageType storage_type,
+                            const gfx::Size& coded_size,
+                            const gfx::Rect& visible_rect,
+                            const gfx::Size& natural_size);
+
+  // Creates a new YUV frame in system memory with given parameters (|format|
+  // must be YUV). Buffers for the frame are allocated but not initialized. The
+  // caller most not make assumptions about the actual underlying size(s), but
+  // check the returned VideoFrame instead.
+  // TODO(mcasas): implement the RGB version of this factory method.
   static scoped_refptr<VideoFrame> CreateFrame(
       Format format,
       const gfx::Size& coded_size,
       const gfx::Rect& visible_rect,
       const gfx::Size& natural_size,
       base::TimeDelta timestamp);
 
-  // Returns true if |plane| is a valid plane number for the given format. This
-  // can be used to DCHECK() plane parameters.
-  static bool IsValidPlane(size_t plane, VideoFrame::Format format);
-
-  // Call prior to CreateFrame to ensure validity of frame configuration. Called
-  // automatically by VideoDecoderConfig::IsValidConfig().
-  // TODO(scherkus): VideoDecoderConfig shouldn't call this method
-  static bool IsValidConfig(Format format,
-                            const gfx::Size& coded_size,
-                            const gfx::Rect& visible_rect,
-                            const gfx::Size& natural_size);
-
-  // CB to be called on the mailbox backing this frame when the frame is
-  // destroyed.
-  typedef base::Callback<void(uint32)> ReleaseMailboxCB;
-
   // Wraps a native texture of the given parameters with a VideoFrame.
   // The backing of the VideoFrame is held in the mailbox held by
   // |mailbox_holder|, and |mailbox_holder_release_cb| will be called with
   // a syncpoint as the argument when the VideoFrame is to be destroyed.
   static scoped_refptr<VideoFrame> WrapNativeTexture(
       const gpu::MailboxHolder& mailbox_holder,
       const ReleaseMailboxCB& mailbox_holder_release_cb,
       const gfx::Size& coded_size,
       const gfx::Rect& visible_rect,
       const gfx::Size& natural_size,
@@ skipping 11 matching lines @@
       const ReleaseMailboxCB& mailbox_holders_release_cb,
       const gfx::Size& coded_size,
       const gfx::Rect& visible_rect,
       const gfx::Size& natural_size,
       base::TimeDelta timestamp,
       bool allow_overlay);
 
   // Wraps packed image data residing in a memory buffer with a VideoFrame.
   // The image data resides in |data| and is assumed to be packed tightly in a
   // buffer of logical dimensions |coded_size| with the appropriate bit depth
-  // and plane count as given by |format|.  The shared memory handle of the
-  // backing allocation, if present, can be passed in with |handle|.
-  // Returns NULL on failure.
-  static scoped_refptr<VideoFrame> WrapExternalPackedMemory(
+  // and plane count as given by |format|. Returns NULL on failure.
+  static scoped_refptr<VideoFrame> WrapExternalData(
       Format format,
       const gfx::Size& coded_size,
       const gfx::Rect& visible_rect,
+      const gfx::Size& natural_size,
+      uint8* data,
+      size_t data_size,
+      base::TimeDelta timestamp);
+
+  // Same as WrapExternalData() with SharedMemoryHandle and its offset.
+  static scoped_refptr<VideoFrame> WrapExternalSharedMemory(
+      Format format,
+      const gfx::Size& coded_size,
+      const gfx::Rect& visible_rect,
       const gfx::Size& natural_size,
       uint8* data,
       size_t data_size,
       base::SharedMemoryHandle handle,
       size_t shared_memory_offset,
       base::TimeDelta timestamp);
 
   // Wraps external YUV data of the given parameters with a VideoFrame.
   // The returned VideoFrame does not own the data passed in.
   static scoped_refptr<VideoFrame> WrapExternalYuvData(
       Format format,
       const gfx::Size& coded_size,
       const gfx::Rect& visible_rect,
       const gfx::Size& natural_size,
       int32 y_stride,
       int32 u_stride,
       int32 v_stride,
       uint8* y_data,
       uint8* u_data,
       uint8* v_data,
       base::TimeDelta timestamp);
 
-#if defined(OS_POSIX)
+#if defined(OS_LINUX)
   // Wraps provided dmabufs
   // (https://www.kernel.org/doc/Documentation/dma-buf-sharing.txt) with a
   // VideoFrame. The dmabuf fds are dup()ed on creation, so that the VideoFrame
   // retains a reference to them, and are automatically close()d on destruction,
   // dropping the reference. The caller may safely close() its reference after
   // calling WrapExternalDmabufs().
   // The image data is only accessible via dmabuf fds, which are usually passed
   // directly to a hardware device and/or to another process, or can also be
   // mapped via mmap() for CPU access.
   // Returns NULL on failure.
@@ skipping 45 matching lines @@
   static scoped_refptr<VideoFrame> CreateTransparentFrame(
       const gfx::Size& size);
 
 #if defined(VIDEO_HOLE)
   // Allocates a hole frame.
   static scoped_refptr<VideoFrame> CreateHoleFrame(const gfx::Size& size);
 #endif  // defined(VIDEO_HOLE)
 
   static size_t NumPlanes(Format format);
 
-  static size_t NumTextures(TextureFormat texture_format);
-
   // Returns the required allocation size for a (tightly packed) frame of the
   // given coded size and format.
   static size_t AllocationSize(Format format, const gfx::Size& coded_size);
 
   // Returns the plane size (in bytes) for a plane of the given coded size and
   // format.
   static gfx::Size PlaneSize(Format format,
                              size_t plane,
                              const gfx::Size& coded_size);
 
@@ skipping 16 matching lines @@
   // Returns the number of rows for the given plane, format, and height.
   // The height may be aligned to format requirements.
   static size_t Rows(size_t plane, Format format, int height);
 
   // Returns the number of columns for the given plane, format, and width.
   // The width may be aligned to format requirements.
   static size_t Columns(size_t plane, Format format, int width);
 
   Format format() const { return format_; }
 
-  TextureFormat texture_format() const { return texture_format_; }
+  StorageType storage_type() const { return storage_type_; }
 
   const gfx::Size& coded_size() const { return coded_size_; }
   const gfx::Rect& visible_rect() const { return visible_rect_; }
   const gfx::Size& natural_size() const { return natural_size_; }
 
   int stride(size_t plane) const;
 
   // Returns the number of bytes per row and number of rows for a given plane.
   //
   // As opposed to stride(), row_bytes() refers to the bytes representing
   // frame data scanlines (coded_size.width() pixels, without stride padding).
   int row_bytes(size_t plane) const;
   int rows(size_t plane) const;
 
-  // Returns pointer to the buffer for a given plane. The memory is owned by
-  // VideoFrame object and must not be freed by the caller.
+  // Returns pointer to the buffer for a given plane, if this is an IsMappable()
+  // frame type. The memory is owned by VideoFrame object and must not be freed
+  // by the caller.
   const uint8* data(size_t plane) const;
   uint8* data(size_t plane);
 
-  // Returns pointer to the data in the visible region of the frame. I.e. the
-  // returned pointer is offsetted into the plane buffer specified by
-  // visible_rect().origin(). Memory is owned by VideoFrame object and must not
-  // be freed by the caller.
+  // Returns pointer to the data in the visible region of the frame, for
+  // IsMappable() storage types. The returned pointer is offsetted into the
+  // plane buffer specified by visible_rect().origin(). Memory is owned by
+  // VideoFrame object and must not be freed by the caller.
   const uint8* visible_data(size_t plane) const;
   uint8* visible_data(size_t plane);
 
   // Returns a mailbox holder for a given texture.
   // Only valid to call if this is a NATIVE_TEXTURE frame. Before using the
   // mailbox, the caller must wait for the included sync point.
-  const gpu::MailboxHolder& mailbox_holder(size_t texture) const;
+  const gpu::MailboxHolder& mailbox_holder(size_t texture_index) const;
 
   // Returns the shared-memory handle, if present
   base::SharedMemoryHandle shared_memory_handle() const;
 
   // Returns the offset into the shared memory where the frame data begins.
   size_t shared_memory_offset() const;
 
   // Adds a callback to be run when the VideoFrame is about to be destroyed.
   // The callback may be run from ANY THREAD, and so it is up to the client to
   // ensure thread safety.  Although read-only access to the members of this
   // VideoFrame is permitted while the callback executes (including
   // VideoFrameMetadata), clients should not assume the data pointers are
   // valid.
   void AddDestructionObserver(const base::Closure& callback);
 
   // Returns a dictionary of optional metadata.  This contains information
   // associated with the frame that downstream clients might use for frame-level
   // logging, quality/performance optimizations, signaling, etc.
   //
   // TODO(miu): Move some of the "extra" members of VideoFrame (below) into
   // here as a later clean-up step.
   const VideoFrameMetadata* metadata() const { return &metadata_; }
   VideoFrameMetadata* metadata() { return &metadata_; }
 
   bool allow_overlay() const { return allow_overlay_; }
 
-#if defined(OS_POSIX)
+#if defined(OS_LINUX)
   // Returns backing dmabuf file descriptor for given |plane|, if present.
   int dmabuf_fd(size_t plane) const;
 #endif
 
 #if defined(OS_MACOSX)
   // Returns the backing CVPixelBuffer, if present.
   CVPixelBufferRef cv_pixel_buffer() const;
 #endif
 
   // Returns true if this VideoFrame represents the end of the stream.
   bool end_of_stream() const { return end_of_stream_; }
 
-  base::TimeDelta timestamp() const {
-    return timestamp_;
-  }
-  void set_timestamp(const base::TimeDelta& timestamp) {
+  base::TimeDelta timestamp() const { return timestamp_; }
+  void set_timestamp(base::TimeDelta timestamp) {
     timestamp_ = timestamp;
   }
 
   class SyncPointClient {
    public:
     SyncPointClient() {}
     virtual uint32 InsertSyncPoint() = 0;
     virtual void WaitSyncPoint(uint32 sync_point) = 0;
 
    protected:
     virtual ~SyncPointClient() {}
 
     DISALLOW_COPY_AND_ASSIGN(SyncPointClient);
   };
   // It uses |client| to insert a new sync point and potentially waits on a
   // older sync point. The final sync point will be used to release this
   // VideoFrame.
   // This method is thread safe. Both blink and compositor threads can call it.
   void UpdateReleaseSyncPoint(SyncPointClient* client);
 
   // Used to keep a running hash of seen frames.  Expects an initialized MD5
   // context.  Calls MD5Update with the context and the contents of the frame.
   void HashFrameForTesting(base::MD5Context* context);
 
  private:
   friend class base::RefCountedThreadSafe<VideoFrame>;
 
   // Clients must use the static CreateFrame() method to create a new frame.
   VideoFrame(Format format,
+             StorageType storage_type,
+             const gfx::Size& coded_size,
+             const gfx::Rect& visible_rect,
+             const gfx::Size& natural_size,
+             base::TimeDelta timestamp,
+             bool end_of_stream);
+  VideoFrame(Format format,
+             StorageType storage_type,
+             const gfx::Size& coded_size,
+             const gfx::Rect& visible_rect,
+             const gfx::Size& natural_size,
+             base::TimeDelta timestamp,
+             bool end_of_stream,
+             base::SharedMemoryHandle handle,
+             size_t shared_memory_offset);
+  VideoFrame(Format format,
+             StorageType storage_type,
              const gfx::Size& coded_size,
              const gfx::Rect& visible_rect,
              const gfx::Size& natural_size,
              const gpu::MailboxHolder(&mailbox_holders)[kMaxPlanes],
-             TextureFormat texture_format,
              base::TimeDelta timestamp,
              bool end_of_stream);
   virtual ~VideoFrame();
 
+  static scoped_refptr<VideoFrame> WrapExternalStorage(
+      Format format,
+      StorageType storage_type,
+      const gfx::Size& coded_size,
+      const gfx::Rect& visible_rect,
+      const gfx::Size& natural_size,
+      uint8* data,
+      size_t data_size,
+      base::TimeDelta timestamp,
+      base::SharedMemoryHandle handle,
+      size_t data_offset);
+
   void AllocateYUV();
 
   // Frame format.
   const Format format_;
 
-  // Format of the native textures associated with this frame.
-  const TextureFormat texture_format_;
+  // Storage type for the different planes.
+  const StorageType storage_type_;
 
   // Width and height of the video frame, in pixels. This must include pixel
   // data for the whole image; i.e. for YUV formats with subsampled chroma
   // planes, in the case that the visible portion of the image does not line up
   // on a sample boundary, |coded_size_| must be rounded up appropriately and
   // the pixel data provided for the odd pixels.
   const gfx::Size coded_size_;
 
   // Width, height, and offsets of the visible portion of the video frame. Must
   // be a subrect of |coded_size_|. Can be odd with respect to the sample
   // boundaries, e.g. for formats with subsampled chroma.
   const gfx::Rect visible_rect_;
 
   // Width and height of the visible portion of the video frame
   // (|visible_rect_.size()|) with aspect ratio taken into account.
   const gfx::Size natural_size_;
 
   // Array of strides for each plane, typically greater or equal to the width
   // of the surface divided by the horizontal sampling period.  Note that
   // strides can be negative.
   int32 strides_[kMaxPlanes];
 
   // Array of data pointers to each plane.
+  // TODO(mcasas): we don't know on ctor if we own |data_| or not. After
+  // refactoring VideoFrame, change to scoped_ptr<uint8, AlignedFreeDeleter>.
   uint8* data_[kMaxPlanes];
 
-  // Native texture mailboxes, if this is a NATIVE_TEXTURE frame.
+  // Native texture mailboxes, if this is a STORAGE_TEXTURE frame.
   gpu::MailboxHolder mailbox_holders_[kMaxPlanes];
   ReleaseMailboxCB mailbox_holders_release_cb_;
 
-  // Shared memory handle, if this frame was allocated from shared memory.
+  // Shared memory handle and associated offset inside it, if this frame was
+  // constructed as STORAGE_SHMEM.
   base::SharedMemoryHandle shared_memory_handle_;
-
-  // Offset in shared memory buffer.
   size_t shared_memory_offset_;
 
-#if defined(OS_POSIX)
+#if defined(OS_LINUX)
   // Dmabufs for each plane, if this frame is wrapping memory
   // acquired via dmabuf.
   base::ScopedFD dmabuf_fds_[kMaxPlanes];
 #endif
 
 #if defined(OS_MACOSX)
   // CVPixelBuffer, if this frame is wrapping one.
   base::ScopedCFTypeRef<CVPixelBufferRef> cv_pixel_buffer_;
 #endif
 
   std::vector<base::Closure> done_callbacks_;
 
   base::TimeDelta timestamp_;
 
   base::Lock release_sync_point_lock_;
   uint32 release_sync_point_;
 
   const bool end_of_stream_;
 
   VideoFrameMetadata metadata_;
 
   bool allow_overlay_;
 
   DISALLOW_IMPLICIT_CONSTRUCTORS(VideoFrame);
 };
 
 }  // namespace media
 
 #endif  // MEDIA_BASE_VIDEO_FRAME_H_