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 "media/base/buffers.h"
  11
  12 namespace media {
  13
  14 class MEDIA_EXPORT VideoFrame : public base::RefCountedThreadSafe<VideoFrame> {
  15  public:
  16   enum {
  17     kMaxPlanes = 3,
  18
  19     kRGBPlane = 0,
  20
  21     kYPlane = 0,
  22     kUPlane = 1,
  23     kVPlane = 2,
  24   };
  25
  26   // Surface formats roughly based on FOURCC labels, see:
  27   // http://www.fourcc.org/rgb.php
  28   // http://www.fourcc.org/yuv.php
  29   // Keep in sync with WebKit::WebVideoFrame!
  30   enum Format {
  31     INVALID = 0,  // Invalid format value.  Used for error reporting.
  32     RGB32 = 4,  // 32bpp RGB packed with extra byte 8:8:8
  33     YV12 = 6,  // 12bpp YVU planar 1x1 Y, 2x2 VU samples
  34     YV16 = 7,  // 16bpp YVU planar 1x1 Y, 2x1 VU samples
  35     EMPTY = 9,  // An empty frame.
  36     I420 = 11,  // 12bpp YVU planar 1x1 Y, 2x2 UV samples.
  37     NATIVE_TEXTURE = 12,  // Native texture.  Pixel-format agnostic.
  38   };
  39
  40   // Creates a new frame in system memory with given parameters. Buffers for
  41   // the frame are allocated but not initialized.
  42   static scoped_refptr<VideoFrame> CreateFrame(
  43       Format format,
  44       size_t width,
  45       size_t height,
  46       base::TimeDelta timestamp,
  47       base::TimeDelta duration);
  48
  49   // Call prior to CreateFrame to ensure validity of frame configuration. Called
  50   // automatically by VideoDecoderConfig::IsValidConfig().
  51   static bool IsValidConfig(
  52       Format format,
  53       size_t width,
  54       size_t height);
  55
  56   // Wraps a native texture of the given parameters with a VideoFrame.  When the
  57   // frame is destroyed |no_longer_needed.Run()| will be called.
  58   static scoped_refptr<VideoFrame> WrapNativeTexture(
  59       uint32 texture_id,
  60       uint32 texture_target,
  61       size_t width,
  62       size_t height,
  63       base::TimeDelta timestamp,
  64       base::TimeDelta duration,
  65       const base::Closure& no_longer_needed);
  66
  67   // Creates a frame with format equals to VideoFrame::EMPTY, width, height
  68   // timestamp and duration are all 0.
  69   static scoped_refptr<VideoFrame> CreateEmptyFrame();
  70
  71   // Allocates YV12 frame based on |width| and |height|, and sets its data to
  72   // the YUV equivalent of RGB(0,0,0).
  73   static scoped_refptr<VideoFrame> CreateBlackFrame(int width, int height);
  74
  75   Format format() const { return format_; }
  76
  77   size_t width() const { return width_; }
  78
  79   size_t height() const { return height_; }
  80
  81   int stride(size_t plane) const;
  82
  83   // Returns the number of bytes per row and number of rows for a given plane.
  84   //
  85   // As opposed to stride(), row_bytes() refers to the bytes representing
  86   // visible pixels.
  87   int row_bytes(size_t plane) const;
  88   int rows(size_t plane) const;
  89
  90   // Returns pointer to the buffer for a given plane. The memory is owned by
  91   // VideoFrame object and must not be freed by the caller.
  92   uint8* data(size_t plane) const;
  93
  94   // Returns the ID of the native texture wrapped by this frame.  Only valid to
  95   // call if this is a NATIVE_TEXTURE frame.
  96   uint32 texture_id() const;
  97
  98   // Returns the texture target. Only valid for NATIVE_TEXTURE frames.
  99   uint32 texture_target() const;
 100
 101   // Returns true if this VideoFrame represents the end of the stream.
 102   bool IsEndOfStream() const;
 103
 104   base::TimeDelta GetTimestamp() const {
 105     return timestamp_;
 106   }
 107   void SetTimestamp(const base::TimeDelta& timestamp) {
 108     timestamp_ = timestamp;
 109   }
 110
 111   base::TimeDelta GetDuration() const {
 112     return duration_;
 113   }
 114   void SetDuration(const base::TimeDelta& duration) {
 115     duration_ = duration;
 116   }
 117
 118   // Used to keep a running hash of seen frames.  Expects an initialized MD5
 119   // context.  Calls MD5Update with the context and the contents of the frame.
 120   void HashFrameForTesting(base::MD5Context* context);
 121
 122  private:
 123   friend class base::RefCountedThreadSafe<VideoFrame>;
 124   // Clients must use the static CreateFrame() method to create a new frame.
 125   VideoFrame(Format format,
 126              size_t video_width,
 127              size_t video_height,
 128              base::TimeDelta timestamp,
 129              base::TimeDelta duration);
 130   virtual ~VideoFrame();
 131
 132   // Used internally by CreateFrame().
 133   void AllocateRGB(size_t bytes_per_pixel);
 134   void AllocateYUV();
 135
 136   // Used to DCHECK() plane parameters.
 137   bool IsValidPlane(size_t plane) const;
 138
 139   // Frame format.
 140   Format format_;
 141
 142   // Width and height of surface.
 143   size_t width_;
 144   size_t height_;
 145
 146   // Array of strides for each plane, typically greater or equal to the width
 147   // of the surface divided by the horizontal sampling period.  Note that
 148   // strides can be negative.
 149   int32 strides_[kMaxPlanes];
 150
 151   // Array of data pointers to each plane.
 152   uint8* data_[kMaxPlanes];
 153
 154   // Native texture ID, if this is a NATIVE_TEXTURE frame.
 155   uint32 texture_id_;
 156   uint32 texture_target_;
 157   base::Closure texture_no_longer_needed_;
 158
 159   base::TimeDelta timestamp_;
 160   base::TimeDelta duration_;
 161
 162   DISALLOW_IMPLICIT_CONSTRUCTORS(VideoFrame);
 163 };
 164
 165 }  // namespace media
 166
 167 #endif  // MEDIA_BASE_VIDEO_FRAME_H_