video_frame.h revision 2a99a7e74a7f215066514fe81d2bfa6639d9eddd
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#include "ui/gfx/rect.h" 12#include "ui/gfx/size.h" 13 14namespace media { 15 16class MEDIA_EXPORT VideoFrame : public base::RefCountedThreadSafe<VideoFrame> { 17 public: 18 enum { 19 kFrameSizeAlignment = 16, 20 kFrameSizePadding = 16, 21 kFrameAddressAlignment = 32 22 }; 23 24 enum { 25 kMaxPlanes = 3, 26 27 kRGBPlane = 0, 28 29 kYPlane = 0, 30 kUPlane = 1, 31 kVPlane = 2, 32 }; 33 34 // Surface formats roughly based on FOURCC labels, see: 35 // http://www.fourcc.org/rgb.php 36 // http://www.fourcc.org/yuv.php 37 // Keep in sync with WebKit::WebVideoFrame! 38 enum Format { 39 INVALID = 0, // Invalid format value. Used for error reporting. 40 RGB32 = 4, // 32bpp RGB packed with extra byte 8:8:8 41 YV12 = 6, // 12bpp YVU planar 1x1 Y, 2x2 VU samples 42 YV16 = 7, // 16bpp YVU planar 1x1 Y, 2x1 VU samples 43 EMPTY = 9, // An empty frame. 44 I420 = 11, // 12bpp YVU planar 1x1 Y, 2x2 UV samples. 45 NATIVE_TEXTURE = 12, // Native texture. Pixel-format agnostic. 46#if defined(GOOGLE_TV) 47 HOLE = 13, // Hole frame. 48#endif 49 }; 50 51 // Creates a new frame in system memory with given parameters. Buffers for 52 // the frame are allocated but not initialized. 53 // |coded_size| is the width and height of the frame data in pixels. 54 // |visible_rect| is the visible portion of |coded_size|, after cropping (if 55 // any) is applied. 56 // |natural_size| is the width and height of the frame when the frame's aspect 57 // ratio is applied to |visible_rect|. 58 static scoped_refptr<VideoFrame> CreateFrame( 59 Format format, 60 const gfx::Size& coded_size, 61 const gfx::Rect& visible_rect, 62 const gfx::Size& natural_size, 63 base::TimeDelta timestamp); 64 65 // Call prior to CreateFrame to ensure validity of frame configuration. Called 66 // automatically by VideoDecoderConfig::IsValidConfig(). 67 // TODO(scherkus): VideoDecoderConfig shouldn't call this method 68 static bool IsValidConfig(Format format, const gfx::Size& coded_size, 69 const gfx::Rect& visible_rect, 70 const gfx::Size& natural_size); 71 72 // CB to write pixels from the texture backing this frame into the 73 // |void*| parameter. 74 typedef base::Callback<void(void*)> ReadPixelsCB; 75 76 // Wraps a native texture of the given parameters with a VideoFrame. When the 77 // frame is destroyed |no_longer_needed_cb.Run()| will be called. 78 // |coded_size| is the width and height of the frame data in pixels. 79 // |visible_rect| is the visible portion of |coded_size|, after cropping (if 80 // any) is applied. 81 // |natural_size| is the width and height of the frame when the frame's aspect 82 // ratio is applied to |visible_rect|. 83 // |read_pixels_cb| may be used to do (slow!) readbacks from the 84 // texture to main memory. 85 static scoped_refptr<VideoFrame> WrapNativeTexture( 86 uint32 texture_id, 87 uint32 texture_target, 88 const gfx::Size& coded_size, 89 const gfx::Rect& visible_rect, 90 const gfx::Size& natural_size, 91 base::TimeDelta timestamp, 92 const ReadPixelsCB& read_pixels_cb, 93 const base::Closure& no_longer_needed_cb); 94 95 // Read pixels from the native texture backing |*this| and write 96 // them to |*pixels| as BGRA. |pixels| must point to a buffer at 97 // least as large as 4*visible_rect().width()*visible_rect().height(). 98 void ReadPixelsFromNativeTexture(void* pixels); 99 100 // Wraps external YUV data of the given parameters with a VideoFrame. 101 // The returned VideoFrame does not own the data passed in. When the frame 102 // is destroyed |no_longer_needed_cb.Run()| will be called. 103 static scoped_refptr<VideoFrame> WrapExternalYuvData( 104 Format format, 105 const gfx::Size& coded_size, 106 const gfx::Rect& visible_rect, 107 const gfx::Size& natural_size, 108 int32 y_stride, 109 int32 u_stride, 110 int32 v_stride, 111 uint8* y_data, 112 uint8* u_data, 113 uint8* v_data, 114 base::TimeDelta timestamp, 115 const base::Closure& no_longer_needed_cb); 116 117 // Creates a frame with format equals to VideoFrame::EMPTY, width, height, 118 // and timestamp are all 0. 119 static scoped_refptr<VideoFrame> CreateEmptyFrame(); 120 121 // Allocates YV12 frame based on |size|, and sets its data to the YUV(y,u,v). 122 static scoped_refptr<VideoFrame> CreateColorFrame( 123 const gfx::Size& size, 124 uint8 y, uint8 u, uint8 v, 125 base::TimeDelta timestamp); 126 127 // Allocates YV12 frame based on |size|, and sets its data to the YUV 128 // equivalent of RGB(0,0,0). 129 static scoped_refptr<VideoFrame> CreateBlackFrame(const gfx::Size& size); 130 131#if defined(GOOGLE_TV) 132 // Allocates a hole frame. 133 static scoped_refptr<VideoFrame> CreateHoleFrame(const gfx::Size& size); 134#endif 135 136 static size_t NumPlanes(Format format); 137 138 Format format() const { return format_; } 139 140 const gfx::Size& coded_size() const { return coded_size_; } 141 const gfx::Rect& visible_rect() const { return visible_rect_; } 142 const gfx::Size& natural_size() const { return natural_size_; } 143 144 int stride(size_t plane) const; 145 146 // Returns the number of bytes per row and number of rows for a given plane. 147 // 148 // As opposed to stride(), row_bytes() refers to the bytes representing 149 // frame data scanlines (coded_size.width() pixels, without stride padding). 150 int row_bytes(size_t plane) const; 151 int rows(size_t plane) const; 152 153 // Returns pointer to the buffer for a given plane. The memory is owned by 154 // VideoFrame object and must not be freed by the caller. 155 uint8* data(size_t plane) const; 156 157 // Returns the ID of the native texture wrapped by this frame. Only valid to 158 // call if this is a NATIVE_TEXTURE frame. 159 uint32 texture_id() const; 160 161 // Returns the texture target. Only valid for NATIVE_TEXTURE frames. 162 uint32 texture_target() const; 163 164 // Returns true if this VideoFrame represents the end of the stream. 165 bool IsEndOfStream() const; 166 167 base::TimeDelta GetTimestamp() const { 168 return timestamp_; 169 } 170 void SetTimestamp(const base::TimeDelta& timestamp) { 171 timestamp_ = timestamp; 172 } 173 174 // Used to keep a running hash of seen frames. Expects an initialized MD5 175 // context. Calls MD5Update with the context and the contents of the frame. 176 void HashFrameForTesting(base::MD5Context* context); 177 178 private: 179 friend class base::RefCountedThreadSafe<VideoFrame>; 180 // Clients must use the static CreateFrame() method to create a new frame. 181 VideoFrame(Format format, 182 const gfx::Size& coded_size, 183 const gfx::Rect& visible_rect, 184 const gfx::Size& natural_size, 185 base::TimeDelta timestamp); 186 virtual ~VideoFrame(); 187 188 // Used internally by CreateFrame(). 189 void AllocateRGB(size_t bytes_per_pixel); 190 void AllocateYUV(); 191 192 // Used to DCHECK() plane parameters. 193 bool IsValidPlane(size_t plane) const; 194 195 // Frame format. 196 Format format_; 197 198 // Width and height of the video frame. 199 gfx::Size coded_size_; 200 201 // Width, height, and offsets of the visible portion of the video frame. 202 gfx::Rect visible_rect_; 203 204 // Width and height of the visible portion of the video frame with aspect 205 // ratio taken into account. 206 gfx::Size natural_size_; 207 208 // Array of strides for each plane, typically greater or equal to the width 209 // of the surface divided by the horizontal sampling period. Note that 210 // strides can be negative. 211 int32 strides_[kMaxPlanes]; 212 213 // Array of data pointers to each plane. 214 uint8* data_[kMaxPlanes]; 215 216 // Native texture ID, if this is a NATIVE_TEXTURE frame. 217 uint32 texture_id_; 218 uint32 texture_target_; 219 ReadPixelsCB read_pixels_cb_; 220 221 base::Closure no_longer_needed_cb_; 222 223 base::TimeDelta timestamp_; 224 225 DISALLOW_IMPLICIT_CONSTRUCTORS(VideoFrame); 226}; 227 228} // namespace media 229 230#endif // MEDIA_BASE_VIDEO_FRAME_H_ 231