video_frame.h revision 5f1c94371a64b3196d4be9466099bb892df9b88e
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 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 class SyncPointClient { 265 public: 266 SyncPointClient() {} 267 virtual uint32 InsertSyncPoint() = 0; 268 virtual void WaitSyncPoint(uint32 sync_point) = 0; 269 270 protected: 271 virtual ~SyncPointClient() {} 272 273 DISALLOW_COPY_AND_ASSIGN(SyncPointClient); 274 }; 275 // It uses |client| to insert a new sync point and potentially waits on a 276 // older sync point. The final sync point will be used to release this 277 // VideoFrame. 278 // This method is thread safe. Both blink and compositor threads can call it. 279 void UpdateReleaseSyncPoint(SyncPointClient* client); 280 281 // Used to keep a running hash of seen frames. Expects an initialized MD5 282 // context. Calls MD5Update with the context and the contents of the frame. 283 void HashFrameForTesting(base::MD5Context* context); 284 285 private: 286 friend class base::RefCountedThreadSafe<VideoFrame>; 287 // Clients must use the static CreateFrame() method to create a new frame. 288 VideoFrame(Format format, 289 const gfx::Size& coded_size, 290 const gfx::Rect& visible_rect, 291 const gfx::Size& natural_size, 292 scoped_ptr<gpu::MailboxHolder> mailbox_holder, 293 base::TimeDelta timestamp, 294 bool end_of_stream); 295 virtual ~VideoFrame(); 296 297 void AllocateYUV(); 298 299 // Used to DCHECK() plane parameters. 300 bool IsValidPlane(size_t plane) const; 301 302 // Frame format. 303 const Format format_; 304 305 // Width and height of the video frame, in pixels. This must include pixel 306 // data for the whole image; i.e. for YUV formats with subsampled chroma 307 // planes, in the case that the visible portion of the image does not line up 308 // on a sample boundary, |coded_size_| must be rounded up appropriately and 309 // the pixel data provided for the odd pixels. 310 const gfx::Size coded_size_; 311 312 // Width, height, and offsets of the visible portion of the video frame. Must 313 // be a subrect of |coded_size_|. Can be odd with respect to the sample 314 // boundaries, e.g. for formats with subsampled chroma. 315 const gfx::Rect visible_rect_; 316 317 // Width and height of the visible portion of the video frame 318 // (|visible_rect_.size()|) with aspect ratio taken into account. 319 const gfx::Size natural_size_; 320 321 // Array of strides for each plane, typically greater or equal to the width 322 // of the surface divided by the horizontal sampling period. Note that 323 // strides can be negative. 324 int32 strides_[kMaxPlanes]; 325 326 // Array of data pointers to each plane. 327 uint8* data_[kMaxPlanes]; 328 329 // Native texture mailbox, if this is a NATIVE_TEXTURE frame. 330 const scoped_ptr<gpu::MailboxHolder> mailbox_holder_; 331 ReleaseMailboxCB mailbox_holder_release_cb_; 332 ReadPixelsCB read_pixels_cb_; 333 334 // Shared memory handle, if this frame was allocated from shared memory. 335 base::SharedMemoryHandle shared_memory_handle_; 336 337#if defined(OS_POSIX) 338 // Dmabufs for each plane, if this frame is wrapping memory 339 // acquired via dmabuf. 340 base::ScopedFD dmabuf_fds_[kMaxPlanes]; 341#endif 342 343 base::Closure no_longer_needed_cb_; 344 345 base::TimeDelta timestamp_; 346 347 base::Lock release_sync_point_lock_; 348 uint32 release_sync_point_; 349 350 const bool end_of_stream_; 351 352 DISALLOW_IMPLICIT_CONSTRUCTORS(VideoFrame); 353}; 354 355} // namespace media 356 357#endif // MEDIA_BASE_VIDEO_FRAME_H_ 358