video_frame.h revision effb81e5f8246d0db0270817048dc992db66e9fb
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 FORMAT_MAX = YV12J, // Must always be equal to largest entry logged. 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 static scoped_refptr<VideoFrame> CreateFrame( 64 Format format, 65 const gfx::Size& coded_size, 66 const gfx::Rect& visible_rect, 67 const gfx::Size& natural_size, 68 base::TimeDelta timestamp); 69 70 // Call prior to CreateFrame to ensure validity of frame configuration. Called 71 // automatically by VideoDecoderConfig::IsValidConfig(). 72 // TODO(scherkus): VideoDecoderConfig shouldn't call this method 73 static bool IsValidConfig(Format format, const gfx::Size& coded_size, 74 const gfx::Rect& visible_rect, 75 const gfx::Size& natural_size); 76 77 // CB to write pixels from the texture backing this frame into the 78 // |const SkBitmap&| parameter. 79 typedef base::Callback<void(const SkBitmap&)> ReadPixelsCB; 80 81 // CB to be called on the mailbox backing this frame when the frame is 82 // destroyed. 83 typedef base::Callback<void(scoped_ptr<gpu::MailboxHolder>)> ReleaseMailboxCB; 84 85 // Wraps a native texture of the given parameters with a VideoFrame. The 86 // backing of the VideoFrame is held in the mailbox held by |mailbox_holder|, 87 // and |mailbox_holder_release_cb| will be called with |mailbox_holder| as the 88 // argument when the VideoFrame is to be destroyed. 89 // |read_pixels_cb| may be used to do (slow!) readbacks from the 90 // texture to main memory. 91 static scoped_refptr<VideoFrame> WrapNativeTexture( 92 scoped_ptr<gpu::MailboxHolder> mailbox_holder, 93 const ReleaseMailboxCB& mailbox_holder_release_cb, 94 const gfx::Size& coded_size, 95 const gfx::Rect& visible_rect, 96 const gfx::Size& natural_size, 97 base::TimeDelta timestamp, 98 const ReadPixelsCB& read_pixels_cb); 99 100 // Read pixels from the native texture backing |*this| and write 101 // them to |pixels| as BGRA. |pixels| must point to a buffer at 102 // least as large as 4 * visible_rect().size().GetArea(). 103 void ReadPixelsFromNativeTexture(const SkBitmap& pixels); 104 105 // Wraps packed image data residing in a memory buffer with a VideoFrame. 106 // The image data resides in |data| and is assumed to be packed tightly in a 107 // buffer of logical dimensions |coded_size| with the appropriate bit depth 108 // and plane count as given by |format|. The shared memory handle of the 109 // backing allocation, if present, can be passed in with |handle|. When the 110 // frame is destroyed, |no_longer_needed_cb.Run()| will be called. 111 static scoped_refptr<VideoFrame> WrapExternalPackedMemory( 112 Format format, 113 const gfx::Size& coded_size, 114 const gfx::Rect& visible_rect, 115 const gfx::Size& natural_size, 116 uint8* data, 117 size_t data_size, 118 base::SharedMemoryHandle handle, 119 base::TimeDelta timestamp, 120 const base::Closure& no_longer_needed_cb); 121 122 // Wraps external YUV data of the given parameters with a VideoFrame. 123 // The returned VideoFrame does not own the data passed in. When the frame 124 // is destroyed |no_longer_needed_cb.Run()| will be called. 125 // TODO(sheu): merge this into WrapExternalSharedMemory(). 126 // http://crbug.com/270217 127 static scoped_refptr<VideoFrame> WrapExternalYuvData( 128 Format format, 129 const gfx::Size& coded_size, 130 const gfx::Rect& visible_rect, 131 const gfx::Size& natural_size, 132 int32 y_stride, 133 int32 u_stride, 134 int32 v_stride, 135 uint8* y_data, 136 uint8* u_data, 137 uint8* v_data, 138 base::TimeDelta timestamp, 139 const base::Closure& no_longer_needed_cb); 140 141 // Wraps |frame| and calls |no_longer_needed_cb| when the wrapper VideoFrame 142 // gets destroyed. |visible_rect| must be a sub rect within 143 // frame->visible_rect(). 144 static scoped_refptr<VideoFrame> WrapVideoFrame( 145 const scoped_refptr<VideoFrame>& frame, 146 const gfx::Rect& visible_rect, 147 const gfx::Size& natural_size, 148 const base::Closure& no_longer_needed_cb); 149 150 // Creates a frame which indicates end-of-stream. 151 static scoped_refptr<VideoFrame> CreateEOSFrame(); 152 153 // Allocates YV12 frame based on |size|, and sets its data to the YUV(y,u,v). 154 static scoped_refptr<VideoFrame> CreateColorFrame( 155 const gfx::Size& size, 156 uint8 y, uint8 u, uint8 v, 157 base::TimeDelta timestamp); 158 159 // Allocates YV12 frame based on |size|, and sets its data to the YUV 160 // equivalent of RGB(0,0,0). 161 static scoped_refptr<VideoFrame> CreateBlackFrame(const gfx::Size& size); 162 163#if defined(VIDEO_HOLE) 164 // Allocates a hole frame. 165 static scoped_refptr<VideoFrame> CreateHoleFrame(const gfx::Size& size); 166#endif // defined(VIDEO_HOLE) 167 168 static size_t NumPlanes(Format format); 169 170 // Returns the required allocation size for a (tightly packed) frame of the 171 // given coded size and format. 172 static size_t AllocationSize(Format format, const gfx::Size& coded_size); 173 174 // Returns the plane size for a plane of the given coded size and format. 175 static gfx::Size PlaneSize(Format format, 176 size_t plane, 177 const gfx::Size& coded_size); 178 179 // Returns the required allocation size for a (tightly packed) plane of the 180 // given coded size and format. 181 static size_t PlaneAllocationSize(Format format, 182 size_t plane, 183 const gfx::Size& coded_size); 184 185 Format format() const { return format_; } 186 187 const gfx::Size& coded_size() const { return coded_size_; } 188 const gfx::Rect& visible_rect() const { return visible_rect_; } 189 const gfx::Size& natural_size() const { return natural_size_; } 190 191 int stride(size_t plane) const; 192 193 // Returns the number of bytes per row and number of rows for a given plane. 194 // 195 // As opposed to stride(), row_bytes() refers to the bytes representing 196 // frame data scanlines (coded_size.width() pixels, without stride padding). 197 int row_bytes(size_t plane) const; 198 int rows(size_t plane) const; 199 200 // Returns pointer to the buffer for a given plane. The memory is owned by 201 // VideoFrame object and must not be freed by the caller. 202 uint8* data(size_t plane) const; 203 204 // Returns the mailbox holder of the native texture wrapped by this frame. 205 // Only valid to call if this is a NATIVE_TEXTURE frame. Before using the 206 // mailbox, the caller must wait for the included sync point. 207 gpu::MailboxHolder* mailbox_holder() const; 208 209 // Returns the shared-memory handle, if present 210 base::SharedMemoryHandle shared_memory_handle() const; 211 212 // Returns true if this VideoFrame represents the end of the stream. 213 bool end_of_stream() const { return end_of_stream_; } 214 215 base::TimeDelta GetTimestamp() const { 216 return timestamp_; 217 } 218 void SetTimestamp(const base::TimeDelta& timestamp) { 219 timestamp_ = timestamp; 220 } 221 222 // Used to keep a running hash of seen frames. Expects an initialized MD5 223 // context. Calls MD5Update with the context and the contents of the frame. 224 void HashFrameForTesting(base::MD5Context* context); 225 226 private: 227 friend class base::RefCountedThreadSafe<VideoFrame>; 228 // Clients must use the static CreateFrame() method to create a new frame. 229 VideoFrame(Format format, 230 const gfx::Size& coded_size, 231 const gfx::Rect& visible_rect, 232 const gfx::Size& natural_size, 233 base::TimeDelta timestamp, 234 bool end_of_stream); 235 virtual ~VideoFrame(); 236 237 void AllocateYUV(); 238 239 // Used to DCHECK() plane parameters. 240 bool IsValidPlane(size_t plane) const; 241 242 // Frame format. 243 const Format format_; 244 245 // Width and height of the video frame, in pixels. This must include pixel 246 // data for the whole image; i.e. for YUV formats with subsampled chroma 247 // planes, in the case that the visible portion of the image does not line up 248 // on a sample boundary, |coded_size_| must be rounded up appropriately and 249 // the pixel data provided for the odd pixels. 250 const gfx::Size coded_size_; 251 252 // Width, height, and offsets of the visible portion of the video frame. Must 253 // be a subrect of |coded_size_|. Can be odd with respect to the sample 254 // boundaries, e.g. for formats with subsampled chroma. 255 const gfx::Rect visible_rect_; 256 257 // Width and height of the visible portion of the video frame 258 // (|visible_rect_.size()|) with aspect ratio taken into account. 259 const gfx::Size natural_size_; 260 261 // Array of strides for each plane, typically greater or equal to the width 262 // of the surface divided by the horizontal sampling period. Note that 263 // strides can be negative. 264 int32 strides_[kMaxPlanes]; 265 266 // Array of data pointers to each plane. 267 uint8* data_[kMaxPlanes]; 268 269 // Native texture mailbox, if this is a NATIVE_TEXTURE frame. 270 scoped_ptr<gpu::MailboxHolder> mailbox_holder_; 271 ReleaseMailboxCB mailbox_holder_release_cb_; 272 ReadPixelsCB read_pixels_cb_; 273 274 // Shared memory handle, if this frame was allocated from shared memory. 275 base::SharedMemoryHandle shared_memory_handle_; 276 277 base::Closure no_longer_needed_cb_; 278 279 base::TimeDelta timestamp_; 280 281 const bool end_of_stream_; 282 283 DISALLOW_IMPLICIT_CONSTRUCTORS(VideoFrame); 284}; 285 286} // namespace media 287 288#endif // MEDIA_BASE_VIDEO_FRAME_H_ 289