video_frame.h revision 5d1f7b1de12d16ceb2c938c56701a3e8bfa558f7
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 15class SkBitmap; 16 17namespace gpu { 18struct MailboxHolder; 19} // namespace gpu 20 21namespace media { 22 23class 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(scoped_ptr<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_ 286