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