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 "base/callback.h"
   9 #include "base/md5.h"
  10 #include "base/memory/shared_memory.h"
  11 #include "media/base/buffers.h"
  12 #include "ui/gfx/rect.h"
  13 #include "ui/gfx/size.h"
  14
  15 class SkBitmap;
  16
  17 namespace gpu {
  18 struct MailboxHolder;
  19 }  // namespace gpu
  20
  21 namespace media {
  22
  23 class MEDIA_EXPORT VideoFrame : public base::RefCountedThreadSafe<VideoFrame> {
  24  public:
  25   enum {
  26     kFrameSizeAlignment = 16,
  27     kFrameSizePadding = 16,
  28     kFrameAddressAlignment = 32
  29   };
  30
  31   enum {
  32     kMaxPlanes = 4,
  33
  34     kYPlane = 0,
  35     kUPlane = 1,
  36     kVPlane = 2,
  37     kAPlane = 3,
  38   };
  39
  40   // Surface formats roughly based on FOURCC labels, see:
  41   // http://www.fourcc.org/rgb.php
  42   // http://www.fourcc.org/yuv.php
  43   // Logged to UMA, so never reuse values.
  44   enum Format {
  45     UNKNOWN = 0,  // Unknown format value.
  46     YV12 = 1,  // 12bpp YVU planar 1x1 Y, 2x2 VU samples
  47     YV16 = 2,  // 16bpp YVU planar 1x1 Y, 2x1 VU samples
  48     I420 = 3,  // 12bpp YVU planar 1x1 Y, 2x2 UV samples.
  49     YV12A = 4,  // 20bpp YUVA planar 1x1 Y, 2x2 VU, 1x1 A samples.
  50 #if defined(VIDEO_HOLE)
  51     HOLE = 5,  // Hole frame.
  52 #endif  // defined(VIDEO_HOLE)
  53     NATIVE_TEXTURE = 6,  // Native texture.  Pixel-format agnostic.
  54     YV12J = 7,  // JPEG color range version of YV12
  55     HISTOGRAM_MAX,  // Must always be greatest.
  56   };
  57
  58   // Returns the name of a Format as a string.
  59   static std::string FormatToString(Format format);
  60
  61   // Creates a new frame in system memory with given parameters. Buffers for
  62   // the frame are allocated but not initialized.
  63   // |coded_size| is the width and height of the frame data in pixels.
  64   // |visible_rect| is the visible portion of |coded_size|, after cropping (if
  65   // any) is applied.
  66   // |natural_size| is the width and height of the frame when the frame's aspect
  67   // ratio is applied to |visible_rect|.
  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 gpu::MailboxHolder*)> 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   // |coded_size| is the width and height of the frame data in pixels.
  95   // |visible_rect| is the visible portion of |coded_size|, after cropping (if
  96   // any) is applied.
  97   // |natural_size| is the width and height of the frame when the frame's aspect
  98   // ratio is applied to |visible_rect|.
  99
 100   // |read_pixels_cb| may be used to do (slow!) readbacks from the
 101   // texture to main memory.
 102   static scoped_refptr<VideoFrame> WrapNativeTexture(
 103       scoped_ptr<gpu::MailboxHolder> mailbox_holder,
 104       const ReleaseMailboxCB& mailbox_holder_release_cb,
 105       const gfx::Size& coded_size,
 106       const gfx::Rect& visible_rect,
 107       const gfx::Size& natural_size,
 108       base::TimeDelta timestamp,
 109       const ReadPixelsCB& read_pixels_cb);
 110
 111   // Read pixels from the native texture backing |*this| and write
 112   // them to |pixels| as BGRA.  |pixels| must point to a buffer at
 113   // least as large as 4*visible_rect().width()*visible_rect().height().
 114   void ReadPixelsFromNativeTexture(const SkBitmap& pixels);
 115
 116   // Wraps packed image data residing in a memory buffer with a VideoFrame.
 117   // The image data resides in |data| and is assumed to be packed tightly in a
 118   // buffer of logical dimensions |coded_size| with the appropriate bit depth
 119   // and plane count as given by |format|.  The shared memory handle of the
 120   // backing allocation, if present, can be passed in with |handle|.  When the
 121   // frame is destroyed, |no_longer_needed_cb.Run()| will be called.
 122   static scoped_refptr<VideoFrame> WrapExternalPackedMemory(
 123       Format format,
 124       const gfx::Size& coded_size,
 125       const gfx::Rect& visible_rect,
 126       const gfx::Size& natural_size,
 127       uint8* data,
 128       size_t data_size,
 129       base::SharedMemoryHandle handle,
 130       base::TimeDelta timestamp,
 131       const base::Closure& no_longer_needed_cb);
 132
 133   // Wraps external YUV data of the given parameters with a VideoFrame.
 134   // The returned VideoFrame does not own the data passed in. When the frame
 135   // is destroyed |no_longer_needed_cb.Run()| will be called.
 136   // TODO(sheu): merge this into WrapExternalSharedMemory().
 137   // http://crbug.com/270217
 138   static scoped_refptr<VideoFrame> WrapExternalYuvData(
 139       Format format,
 140       const gfx::Size& coded_size,
 141       const gfx::Rect& visible_rect,
 142       const gfx::Size& natural_size,
 143       int32 y_stride,
 144       int32 u_stride,
 145       int32 v_stride,
 146       uint8* y_data,
 147       uint8* u_data,
 148       uint8* v_data,
 149       base::TimeDelta timestamp,
 150       const base::Closure& no_longer_needed_cb);
 151
 152   // Wraps |frame| and calls |no_longer_needed_cb| when the wrapper VideoFrame
 153   // gets destroyed.
 154   static scoped_refptr<VideoFrame> WrapVideoFrame(
 155       const scoped_refptr<VideoFrame>& frame,
 156       const base::Closure& no_longer_needed_cb);
 157
 158   // Creates a frame which indicates end-of-stream.
 159   static scoped_refptr<VideoFrame> CreateEOSFrame();
 160
 161   // Allocates YV12 frame based on |size|, and sets its data to the YUV(y,u,v).
 162   static scoped_refptr<VideoFrame> CreateColorFrame(
 163       const gfx::Size& size,
 164       uint8 y, uint8 u, uint8 v,
 165       base::TimeDelta timestamp);
 166
 167   // Allocates YV12 frame based on |size|, and sets its data to the YUV
 168   // equivalent of RGB(0,0,0).
 169   static scoped_refptr<VideoFrame> CreateBlackFrame(const gfx::Size& size);
 170
 171 #if defined(VIDEO_HOLE)
 172   // Allocates a hole frame.
 173   static scoped_refptr<VideoFrame> CreateHoleFrame(const gfx::Size& size);
 174 #endif  // defined(VIDEO_HOLE)
 175
 176   static size_t NumPlanes(Format format);
 177
 178   // Returns the required allocation size for a (tightly packed) frame of the
 179   // given coded size and format.
 180   static size_t AllocationSize(Format format, const gfx::Size& coded_size);
 181
 182   // Returns the required allocation size for a (tightly packed) plane of the
 183   // given coded size and format.
 184   static size_t PlaneAllocationSize(Format format,
 185                                     size_t plane,
 186                                     const gfx::Size& coded_size);
 187
 188   Format format() const { return format_; }
 189
 190   const gfx::Size& coded_size() const { return coded_size_; }
 191   const gfx::Rect& visible_rect() const { return visible_rect_; }
 192   const gfx::Size& natural_size() const { return natural_size_; }
 193
 194   int stride(size_t plane) const;
 195
 196   // Returns the number of bytes per row and number of rows for a given plane.
 197   //
 198   // As opposed to stride(), row_bytes() refers to the bytes representing
 199   // frame data scanlines (coded_size.width() pixels, without stride padding).
 200   int row_bytes(size_t plane) const;
 201   int rows(size_t plane) const;
 202
 203   // Returns pointer to the buffer for a given plane. The memory is owned by
 204   // VideoFrame object and must not be freed by the caller.
 205   uint8* data(size_t plane) const;
 206
 207   // Returns the mailbox holder of the native texture wrapped by this frame.
 208   // Only valid to call if this is a NATIVE_TEXTURE frame. Before using the
 209   // mailbox, the caller must wait for the included sync point.
 210   gpu::MailboxHolder* mailbox_holder() const;
 211
 212   // Returns the shared-memory handle, if present
 213   base::SharedMemoryHandle shared_memory_handle() const;
 214
 215   // Returns true if this VideoFrame represents the end of the stream.
 216   bool end_of_stream() const { return end_of_stream_; }
 217
 218   base::TimeDelta GetTimestamp() const {
 219     return timestamp_;
 220   }
 221   void SetTimestamp(const base::TimeDelta& timestamp) {
 222     timestamp_ = timestamp;
 223   }
 224
 225   // Used to keep a running hash of seen frames.  Expects an initialized MD5
 226   // context.  Calls MD5Update with the context and the contents of the frame.
 227   void HashFrameForTesting(base::MD5Context* context);
 228
 229  private:
 230   friend class base::RefCountedThreadSafe<VideoFrame>;
 231   // Clients must use the static CreateFrame() method to create a new frame.
 232   VideoFrame(Format format,
 233              const gfx::Size& coded_size,
 234              const gfx::Rect& visible_rect,
 235              const gfx::Size& natural_size,
 236              base::TimeDelta timestamp,
 237              bool end_of_stream);
 238   virtual ~VideoFrame();
 239
 240   void AllocateYUV();
 241
 242   // Used to DCHECK() plane parameters.
 243   bool IsValidPlane(size_t plane) const;
 244
 245   // Frame format.
 246   Format format_;
 247
 248   // Width and height of the video frame.
 249   gfx::Size coded_size_;
 250
 251   // Width, height, and offsets of the visible portion of the video frame.
 252   gfx::Rect visible_rect_;
 253
 254   // Width and height of the visible portion of the video frame with aspect
 255   // ratio taken into account.
 256   gfx::Size natural_size_;
 257
 258   // Array of strides for each plane, typically greater or equal to the width
 259   // of the surface divided by the horizontal sampling period.  Note that
 260   // strides can be negative.
 261   int32 strides_[kMaxPlanes];
 262
 263   // Array of data pointers to each plane.
 264   uint8* data_[kMaxPlanes];
 265
 266   // Native texture mailbox, if this is a NATIVE_TEXTURE frame.
 267   scoped_ptr<gpu::MailboxHolder> mailbox_holder_;
 268   ReleaseMailboxCB mailbox_holder_release_cb_;
 269   ReadPixelsCB read_pixels_cb_;
 270
 271   // Shared memory handle, if this frame was allocated from shared memory.
 272   base::SharedMemoryHandle shared_memory_handle_;
 273
 274   base::Closure no_longer_needed_cb_;
 275
 276   base::TimeDelta timestamp_;
 277
 278   const bool end_of_stream_;
 279
 280   DISALLOW_IMPLICIT_CONSTRUCTORS(VideoFrame);
 281 };
 282
 283 }  // namespace media
 284
 285 #endif  // MEDIA_BASE_VIDEO_FRAME_H_