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