media/base/video_frame.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_BASE_VIDEO_FRAME_H_
   6 #define MEDIA_BASE_VIDEO_FRAME_H_
   7
   8 #include <vector>
   9
  10 #include "base/callback.h"
  11 #include "base/md5.h"
  12 #include "base/memory/shared_memory.h"
  13 #include "base/synchronization/lock.h"
  14 #include "media/base/buffers.h"
  15 #include "ui/gfx/rect.h"
  16 #include "ui/gfx/size.h"
  17
  18 class SkBitmap;
  19
  20 namespace gpu {
  21 struct MailboxHolder;
  22 }  // namespace gpu
  23
  24 namespace media {
  25
  26 class MEDIA_EXPORT VideoFrame : public base::RefCountedThreadSafe<VideoFrame> {
  27  public:
  28   enum {
  29     kFrameSizeAlignment = 16,
  30     kFrameSizePadding = 16,
  31     kFrameAddressAlignment = 32
  32   };
  33
  34   enum {
  35     kMaxPlanes = 4,
  36
  37     kYPlane = 0,
  38     kUPlane = 1,
  39     kUVPlane = kUPlane,
  40     kVPlane = 2,
  41     kAPlane = 3,
  42   };
  43
  44   // Surface formats roughly based on FOURCC labels, see:
  45   // http://www.fourcc.org/rgb.php
  46   // http://www.fourcc.org/yuv.php
  47   // Logged to UMA, so never reuse values.
  48   enum Format {
  49     UNKNOWN = 0,  // Unknown format value.
  50     YV12 = 1,  // 12bpp YVU planar 1x1 Y, 2x2 VU samples
  51     YV16 = 2,  // 16bpp YVU planar 1x1 Y, 2x1 VU samples
  52     I420 = 3,  // 12bpp YVU planar 1x1 Y, 2x2 UV samples.
  53     YV12A = 4,  // 20bpp YUVA planar 1x1 Y, 2x2 VU, 1x1 A samples.
  54 #if defined(VIDEO_HOLE)
  55     HOLE = 5,  // Hole frame.
  56 #endif  // defined(VIDEO_HOLE)
  57     NATIVE_TEXTURE = 6,  // Native texture.  Pixel-format agnostic.
  58     YV12J = 7,  // JPEG color range version of YV12
  59     NV12 = 8,  // 12bpp 1x1 Y plane followed by an interleaved 2x2 UV plane.
  60     FORMAT_MAX = NV12,  // Must always be equal to largest entry logged.
  61   };
  62
  63   // Returns the name of a Format as a string.
  64   static std::string FormatToString(Format format);
  65
  66   // Creates a new frame in system memory with given parameters. Buffers for
  67   // the frame are allocated but not initialized.
  68   static scoped_refptr<VideoFrame> CreateFrame(
  69       Format format,
  70       const gfx::Size& coded_size,
  71       const gfx::Rect& visible_rect,
  72       const gfx::Size& natural_size,
  73       base::TimeDelta timestamp);
  74
  75   // Call prior to CreateFrame to ensure validity of frame configuration. Called
  76   // automatically by VideoDecoderConfig::IsValidConfig().
  77   // TODO(scherkus): VideoDecoderConfig shouldn't call this method
  78   static bool IsValidConfig(Format format, const gfx::Size& coded_size,
  79                             const gfx::Rect& visible_rect,
  80                             const gfx::Size& natural_size);
  81
  82   // CB to write pixels from the texture backing this frame into the
  83   // |const SkBitmap&| parameter.
  84   typedef base::Callback<void(const SkBitmap&)> ReadPixelsCB;
  85
  86   // CB to be called on the mailbox backing this frame when the frame is
  87   // destroyed.
  88   typedef base::Callback<void(const std::vector<uint32>&)> ReleaseMailboxCB;
  89
  90   // Wraps a native texture of the given parameters with a VideoFrame.  The
  91   // backing of the VideoFrame is held in the mailbox held by |mailbox_holder|,
  92   // and |mailbox_holder_release_cb| will be called with |mailbox_holder| as the
  93   // argument when the VideoFrame is to be destroyed.
  94   // |read_pixels_cb| may be used to do (slow!) readbacks from the
  95   // texture to main memory.
  96   static scoped_refptr<VideoFrame> WrapNativeTexture(
  97       scoped_ptr<gpu::MailboxHolder> mailbox_holder,
  98       const ReleaseMailboxCB& mailbox_holder_release_cb,
  99       const gfx::Size& coded_size,
 100       const gfx::Rect& visible_rect,
 101       const gfx::Size& natural_size,
 102       base::TimeDelta timestamp,
 103       const ReadPixelsCB& read_pixels_cb);
 104
 105   // Read pixels from the native texture backing |*this| and write
 106   // them to |pixels| as BGRA.  |pixels| must point to a buffer at
 107   // least as large as 4 * visible_rect().size().GetArea().
 108   void ReadPixelsFromNativeTexture(const SkBitmap& pixels);
 109
 110   // Wraps packed image data residing in a memory buffer with a VideoFrame.
 111   // The image data resides in |data| and is assumed to be packed tightly in a
 112   // buffer of logical dimensions |coded_size| with the appropriate bit depth
 113   // and plane count as given by |format|.  The shared memory handle of the
 114   // backing allocation, if present, can be passed in with |handle|.  When the
 115   // frame is destroyed, |no_longer_needed_cb.Run()| will be called.
 116   static scoped_refptr<VideoFrame> WrapExternalPackedMemory(
 117       Format format,
 118       const gfx::Size& coded_size,
 119       const gfx::Rect& visible_rect,
 120       const gfx::Size& natural_size,
 121       uint8* data,
 122       size_t data_size,
 123       base::SharedMemoryHandle handle,
 124       base::TimeDelta timestamp,
 125       const base::Closure& no_longer_needed_cb);
 126
 127 #if defined(OS_POSIX)
 128   // Wraps provided dmabufs
 129   // (https://www.kernel.org/doc/Documentation/dma-buf-sharing.txt) with a
 130   // VideoFrame. The dmabuf fds are dup()ed on creation, so that the VideoFrame
 131   // retains a reference to them, and are automatically close()d on destruction,
 132   // dropping the reference. The caller may safely close() its reference after
 133   // calling WrapExternalDmabufs().
 134   // The image data is only accessible via dmabuf fds, which are usually passed
 135   // directly to a hardware device and/or to another process, or can also be
 136   // mapped via mmap() for CPU access.
 137   // When the frame is destroyed, |no_longer_needed_cb.Run()| will be called.
 138   static scoped_refptr<VideoFrame> WrapExternalDmabufs(
 139       Format format,
 140       const gfx::Size& coded_size,
 141       const gfx::Rect& visible_rect,
 142       const gfx::Size& natural_size,
 143       const std::vector<int> dmabuf_fds,
 144       base::TimeDelta timestamp,
 145       const base::Closure& no_longer_needed_cb);
 146 #endif
 147
 148   // Wraps external YUV data of the given parameters with a VideoFrame.
 149   // The returned VideoFrame does not own the data passed in. When the frame
 150   // is destroyed |no_longer_needed_cb.Run()| will be called.
 151   // TODO(sheu): merge this into WrapExternalSharedMemory().
 152   // http://crbug.com/270217
 153   static scoped_refptr<VideoFrame> WrapExternalYuvData(
 154       Format format,
 155       const gfx::Size& coded_size,
 156       const gfx::Rect& visible_rect,
 157       const gfx::Size& natural_size,
 158       int32 y_stride,
 159       int32 u_stride,
 160       int32 v_stride,
 161       uint8* y_data,
 162       uint8* u_data,
 163       uint8* v_data,
 164       base::TimeDelta timestamp,
 165       const base::Closure& no_longer_needed_cb);
 166
 167   // Wraps |frame| and calls |no_longer_needed_cb| when the wrapper VideoFrame
 168   // gets destroyed. |visible_rect| must be a sub rect within
 169   // frame->visible_rect().
 170   static scoped_refptr<VideoFrame> WrapVideoFrame(
 171       const scoped_refptr<VideoFrame>& frame,
 172       const gfx::Rect& visible_rect,
 173       const gfx::Size& natural_size,
 174       const base::Closure& no_longer_needed_cb);
 175
 176   // Creates a frame which indicates end-of-stream.
 177   static scoped_refptr<VideoFrame> CreateEOSFrame();
 178
 179   // Allocates YV12 frame based on |size|, and sets its data to the YUV(y,u,v).
 180   static scoped_refptr<VideoFrame> CreateColorFrame(
 181       const gfx::Size& size,
 182       uint8 y, uint8 u, uint8 v,
 183       base::TimeDelta timestamp);
 184
 185   // Allocates YV12 frame based on |size|, and sets its data to the YUV
 186   // equivalent of RGB(0,0,0).
 187   static scoped_refptr<VideoFrame> CreateBlackFrame(const gfx::Size& size);
 188
 189 #if defined(VIDEO_HOLE)
 190   // Allocates a hole frame.
 191   static scoped_refptr<VideoFrame> CreateHoleFrame(const gfx::Size& size);
 192 #endif  // defined(VIDEO_HOLE)
 193
 194   static size_t NumPlanes(Format format);
 195
 196   // Returns the required allocation size for a (tightly packed) frame of the
 197   // given coded size and format.
 198   static size_t AllocationSize(Format format, const gfx::Size& coded_size);
 199
 200   // Returns the plane size for a plane of the given coded size and format.
 201   static gfx::Size PlaneSize(Format format,
 202                              size_t plane,
 203                              const gfx::Size& coded_size);
 204
 205   // Returns the required allocation size for a (tightly packed) plane of the
 206   // given coded size and format.
 207   static size_t PlaneAllocationSize(Format format,
 208                                     size_t plane,
 209                                     const gfx::Size& coded_size);
 210
 211   // Returns horizontal bits per pixel for given |plane| and |format|.
 212   static int PlaneHorizontalBitsPerPixel(Format format, size_t plane);
 213
 214   Format format() const { return format_; }
 215
 216   const gfx::Size& coded_size() const { return coded_size_; }
 217   const gfx::Rect& visible_rect() const { return visible_rect_; }
 218   const gfx::Size& natural_size() const { return natural_size_; }
 219
 220   int stride(size_t plane) const;
 221
 222   // Returns the number of bytes per row and number of rows for a given plane.
 223   //
 224   // As opposed to stride(), row_bytes() refers to the bytes representing
 225   // frame data scanlines (coded_size.width() pixels, without stride padding).
 226   int row_bytes(size_t plane) const;
 227   int rows(size_t plane) const;
 228
 229   // Returns pointer to the buffer for a given plane. The memory is owned by
 230   // VideoFrame object and must not be freed by the caller.
 231   uint8* data(size_t plane) const;
 232
 233   // Returns the mailbox holder of the native texture wrapped by this frame.
 234   // Only valid to call if this is a NATIVE_TEXTURE frame. Before using the
 235   // mailbox, the caller must wait for the included sync point.
 236   const gpu::MailboxHolder* mailbox_holder() const;
 237
 238   // Returns the shared-memory handle, if present
 239   base::SharedMemoryHandle shared_memory_handle() const;
 240
 241 #if defined(OS_POSIX)
 242   // Returns backing dmabuf file descriptor for given |plane|, if present.
 243   int dmabuf_fd(size_t plane) const;
 244 #endif
 245
 246   // Returns true if this VideoFrame represents the end of the stream.
 247   bool end_of_stream() const { return end_of_stream_; }
 248
 249   base::TimeDelta timestamp() const {
 250     return timestamp_;
 251   }
 252   void set_timestamp(const base::TimeDelta& timestamp) {
 253     timestamp_ = timestamp;
 254   }
 255
 256   // Append |sync_point| into |release_sync_points_| which will be passed to
 257   // the video decoder when |mailbox_holder_release_cb_| is called so that
 258   // the video decoder waits for the sync points before reusing the mailbox.
 259   // Multiple clients can append multiple sync points on one frame.
 260   // This method is thread safe. Both blink and compositor threads can call it.
 261   void AppendReleaseSyncPoint(uint32 sync_point);
 262
 263   // Used to keep a running hash of seen frames.  Expects an initialized MD5
 264   // context.  Calls MD5Update with the context and the contents of the frame.
 265   void HashFrameForTesting(base::MD5Context* context);
 266
 267  private:
 268   friend class base::RefCountedThreadSafe<VideoFrame>;
 269   // Clients must use the static CreateFrame() method to create a new frame.
 270   VideoFrame(Format format,
 271              const gfx::Size& coded_size,
 272              const gfx::Rect& visible_rect,
 273              const gfx::Size& natural_size,
 274              scoped_ptr<gpu::MailboxHolder> mailbox_holder,
 275              base::TimeDelta timestamp,
 276              bool end_of_stream);
 277   virtual ~VideoFrame();
 278
 279   void AllocateYUV();
 280
 281   // Used to DCHECK() plane parameters.
 282   bool IsValidPlane(size_t plane) const;
 283
 284   // Frame format.
 285   const Format format_;
 286
 287   // Width and height of the video frame, in pixels. This must include pixel
 288   // data for the whole image; i.e. for YUV formats with subsampled chroma
 289   // planes, in the case that the visible portion of the image does not line up
 290   // on a sample boundary, |coded_size_| must be rounded up appropriately and
 291   // the pixel data provided for the odd pixels.
 292   const gfx::Size coded_size_;
 293
 294   // Width, height, and offsets of the visible portion of the video frame. Must
 295   // be a subrect of |coded_size_|. Can be odd with respect to the sample
 296   // boundaries, e.g. for formats with subsampled chroma.
 297   const gfx::Rect visible_rect_;
 298
 299   // Width and height of the visible portion of the video frame
 300   // (|visible_rect_.size()|) with aspect ratio taken into account.
 301   const gfx::Size natural_size_;
 302
 303   // Array of strides for each plane, typically greater or equal to the width
 304   // of the surface divided by the horizontal sampling period.  Note that
 305   // strides can be negative.
 306   int32 strides_[kMaxPlanes];
 307
 308   // Array of data pointers to each plane.
 309   uint8* data_[kMaxPlanes];
 310
 311   // Native texture mailbox, if this is a NATIVE_TEXTURE frame.
 312   const scoped_ptr<gpu::MailboxHolder> mailbox_holder_;
 313   ReleaseMailboxCB mailbox_holder_release_cb_;
 314   ReadPixelsCB read_pixels_cb_;
 315
 316   // Shared memory handle, if this frame was allocated from shared memory.
 317   base::SharedMemoryHandle shared_memory_handle_;
 318
 319 #if defined(OS_POSIX)
 320   // Dmabufs for each plane, if this frame is wrapping memory
 321   // acquired via dmabuf.
 322   base::ScopedFD dmabuf_fds_[kMaxPlanes];
 323 #endif
 324
 325   base::Closure no_longer_needed_cb_;
 326
 327   base::TimeDelta timestamp_;
 328
 329   base::Lock release_sync_point_lock_;
 330   std::vector<uint32> release_sync_points_;
 331
 332   const bool end_of_stream_;
 333
 334   DISALLOW_IMPLICIT_CONSTRUCTORS(VideoFrame);
 335 };
 336
 337 }  // namespace media
 338
 339 #endif  // MEDIA_BASE_VIDEO_FRAME_H_