video_frame.h revision 03b57e008b61dfcb1fbad3aea950ae0e001748b0
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(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 // Returns the number of bytes per row for the given plane, format, and width. 223 // The width may be aligned to format requirements. 224 static int RowBytes(size_t plane, Format format, int width); 225 226 Format format() const { return format_; } 227 228 const gfx::Size& coded_size() const { return coded_size_; } 229 const gfx::Rect& visible_rect() const { return visible_rect_; } 230 const gfx::Size& natural_size() const { return natural_size_; } 231 232 int stride(size_t plane) const; 233 234 // Returns the number of bytes per row and number of rows for a given plane. 235 // 236 // As opposed to stride(), row_bytes() refers to the bytes representing 237 // frame data scanlines (coded_size.width() pixels, without stride padding). 238 int row_bytes(size_t plane) const; 239 int rows(size_t plane) const; 240 241 // Returns pointer to the buffer for a given plane. The memory is owned by 242 // VideoFrame object and must not be freed by the caller. 243 uint8* data(size_t plane) const; 244 245 // Returns the mailbox holder of the native texture wrapped by this frame. 246 // Only valid to call if this is a NATIVE_TEXTURE frame. Before using the 247 // mailbox, the caller must wait for the included sync point. 248 const gpu::MailboxHolder* mailbox_holder() const; 249 250 // Returns the shared-memory handle, if present 251 base::SharedMemoryHandle shared_memory_handle() const; 252 253#if defined(OS_POSIX) 254 // Returns backing dmabuf file descriptor for given |plane|, if present. 255 int dmabuf_fd(size_t plane) const; 256#endif 257 258 // Returns true if this VideoFrame represents the end of the stream. 259 bool end_of_stream() const { return end_of_stream_; } 260 261 base::TimeDelta timestamp() const { 262 return timestamp_; 263 } 264 void set_timestamp(const base::TimeDelta& timestamp) { 265 timestamp_ = timestamp; 266 } 267 268 class SyncPointClient { 269 public: 270 SyncPointClient() {} 271 virtual uint32 InsertSyncPoint() = 0; 272 virtual void WaitSyncPoint(uint32 sync_point) = 0; 273 274 protected: 275 virtual ~SyncPointClient() {} 276 277 DISALLOW_COPY_AND_ASSIGN(SyncPointClient); 278 }; 279 // It uses |client| to insert a new sync point and potentially waits on a 280 // older sync point. The final sync point will be used to release this 281 // VideoFrame. 282 // This method is thread safe. Both blink and compositor threads can call it. 283 void UpdateReleaseSyncPoint(SyncPointClient* client); 284 285 // Used to keep a running hash of seen frames. Expects an initialized MD5 286 // context. Calls MD5Update with the context and the contents of the frame. 287 void HashFrameForTesting(base::MD5Context* context); 288 289 private: 290 friend class base::RefCountedThreadSafe<VideoFrame>; 291 292 // Returns true if |plane| is a valid plane number for the given format. This 293 // can be used to DCHECK() plane parameters. 294 static bool IsValidPlane(size_t plane, VideoFrame::Format format); 295 296 // Clients must use the static CreateFrame() method to create a new frame. 297 VideoFrame(Format format, 298 const gfx::Size& coded_size, 299 const gfx::Rect& visible_rect, 300 const gfx::Size& natural_size, 301 scoped_ptr<gpu::MailboxHolder> mailbox_holder, 302 base::TimeDelta timestamp, 303 bool end_of_stream); 304 virtual ~VideoFrame(); 305 306 void AllocateYUV(); 307 308 // Frame format. 309 const Format format_; 310 311 // Width and height of the video frame, in pixels. This must include pixel 312 // data for the whole image; i.e. for YUV formats with subsampled chroma 313 // planes, in the case that the visible portion of the image does not line up 314 // on a sample boundary, |coded_size_| must be rounded up appropriately and 315 // the pixel data provided for the odd pixels. 316 const gfx::Size coded_size_; 317 318 // Width, height, and offsets of the visible portion of the video frame. Must 319 // be a subrect of |coded_size_|. Can be odd with respect to the sample 320 // boundaries, e.g. for formats with subsampled chroma. 321 const gfx::Rect visible_rect_; 322 323 // Width and height of the visible portion of the video frame 324 // (|visible_rect_.size()|) with aspect ratio taken into account. 325 const gfx::Size natural_size_; 326 327 // Array of strides for each plane, typically greater or equal to the width 328 // of the surface divided by the horizontal sampling period. Note that 329 // strides can be negative. 330 int32 strides_[kMaxPlanes]; 331 332 // Array of data pointers to each plane. 333 uint8* data_[kMaxPlanes]; 334 335 // Native texture mailbox, if this is a NATIVE_TEXTURE frame. 336 const scoped_ptr<gpu::MailboxHolder> mailbox_holder_; 337 ReleaseMailboxCB mailbox_holder_release_cb_; 338 ReadPixelsCB read_pixels_cb_; 339 340 // Shared memory handle, if this frame was allocated from shared memory. 341 base::SharedMemoryHandle shared_memory_handle_; 342 343#if defined(OS_POSIX) 344 // Dmabufs for each plane, if this frame is wrapping memory 345 // acquired via dmabuf. 346 base::ScopedFD dmabuf_fds_[kMaxPlanes]; 347#endif 348 349 base::Closure no_longer_needed_cb_; 350 351 base::TimeDelta timestamp_; 352 353 base::Lock release_sync_point_lock_; 354 uint32 release_sync_point_; 355 356 const bool end_of_stream_; 357 358 DISALLOW_IMPLICIT_CONSTRUCTORS(VideoFrame); 359}; 360 361} // namespace media 362 363#endif // MEDIA_BASE_VIDEO_FRAME_H_ 364