1 /* 2 * Copyright (c) 2015 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 #ifndef API_VIDEO_VIDEO_FRAME_BUFFER_H_ 12 #define API_VIDEO_VIDEO_FRAME_BUFFER_H_ 13 14 #include <stdint.h> 15 16 #include "api/scoped_refptr.h" 17 #include "rtc_base/ref_count.h" 18 #include "rtc_base/system/rtc_export.h" 19 20 namespace webrtc { 21 22 class I420BufferInterface; 23 class I420ABufferInterface; 24 class I444BufferInterface; 25 class I010BufferInterface; 26 27 // Base class for frame buffers of different types of pixel format and storage. 28 // The tag in type() indicates how the data is represented, and each type is 29 // implemented as a subclass. To access the pixel data, call the appropriate 30 // GetXXX() function, where XXX represents the type. There is also a function 31 // ToI420() that returns a frame buffer in I420 format, converting from the 32 // underlying representation if necessary. I420 is the most widely accepted 33 // format and serves as a fallback for video sinks that can only handle I420, 34 // e.g. the internal WebRTC software encoders. A special enum value 'kNative' is 35 // provided for external clients to implement their own frame buffer 36 // representations, e.g. as textures. The external client can produce such 37 // native frame buffers from custom video sources, and then cast it back to the 38 // correct subclass in custom video sinks. The purpose of this is to improve 39 // performance by providing an optimized path without intermediate conversions. 40 // Frame metadata such as rotation and timestamp are stored in 41 // webrtc::VideoFrame, and not here. 42 class RTC_EXPORT VideoFrameBuffer : public rtc::RefCountInterface { 43 public: 44 // New frame buffer types will be added conservatively when there is an 45 // opportunity to optimize the path between some pair of video source and 46 // video sink. 47 enum class Type { 48 kNative, 49 kI420, 50 kI420A, 51 kI444, 52 kI010, 53 }; 54 55 // This function specifies in what pixel format the data is stored in. 56 virtual Type type() const = 0; 57 58 // The resolution of the frame in pixels. For formats where some planes are 59 // subsampled, this is the highest-resolution plane. 60 virtual int width() const = 0; 61 virtual int height() const = 0; 62 63 // Returns a memory-backed frame buffer in I420 format. If the pixel data is 64 // in another format, a conversion will take place. All implementations must 65 // provide a fallback to I420 for compatibility with e.g. the internal WebRTC 66 // software encoders. 67 virtual rtc::scoped_refptr<I420BufferInterface> ToI420() = 0; 68 69 // GetI420() methods should return I420 buffer if conversion is trivial, i.e 70 // no change for binary data is needed. Otherwise these methods should return 71 // nullptr. One example of buffer with that property is 72 // WebrtcVideoFrameAdapter in Chrome - it's I420 buffer backed by a shared 73 // memory buffer. Therefore it must have type kNative. Yet, ToI420() 74 // doesn't affect binary data at all. Another example is any I420A buffer. 75 virtual const I420BufferInterface* GetI420() const; 76 77 // These functions should only be called if type() is of the correct type. 78 // Calling with a different type will result in a crash. 79 const I420ABufferInterface* GetI420A() const; 80 const I444BufferInterface* GetI444() const; 81 const I010BufferInterface* GetI010() const; 82 83 protected: ~VideoFrameBuffer()84 ~VideoFrameBuffer() override {} 85 }; 86 87 // This interface represents planar formats. 88 class PlanarYuvBuffer : public VideoFrameBuffer { 89 public: 90 virtual int ChromaWidth() const = 0; 91 virtual int ChromaHeight() const = 0; 92 93 // Returns the number of steps(in terms of Data*() return type) between 94 // successive rows for a given plane. 95 virtual int StrideY() const = 0; 96 virtual int StrideU() const = 0; 97 virtual int StrideV() const = 0; 98 99 protected: ~PlanarYuvBuffer()100 ~PlanarYuvBuffer() override {} 101 }; 102 103 // This interface represents 8-bit color depth formats: Type::kI420, 104 // Type::kI420A and Type::kI444. 105 class PlanarYuv8Buffer : public PlanarYuvBuffer { 106 public: 107 // Returns pointer to the pixel data for a given plane. The memory is owned by 108 // the VideoFrameBuffer object and must not be freed by the caller. 109 virtual const uint8_t* DataY() const = 0; 110 virtual const uint8_t* DataU() const = 0; 111 virtual const uint8_t* DataV() const = 0; 112 113 protected: ~PlanarYuv8Buffer()114 ~PlanarYuv8Buffer() override {} 115 }; 116 117 class RTC_EXPORT I420BufferInterface : public PlanarYuv8Buffer { 118 public: 119 Type type() const override; 120 121 int ChromaWidth() const final; 122 int ChromaHeight() const final; 123 124 rtc::scoped_refptr<I420BufferInterface> ToI420() final; 125 const I420BufferInterface* GetI420() const final; 126 127 protected: ~I420BufferInterface()128 ~I420BufferInterface() override {} 129 }; 130 131 class RTC_EXPORT I420ABufferInterface : public I420BufferInterface { 132 public: 133 Type type() const final; 134 virtual const uint8_t* DataA() const = 0; 135 virtual int StrideA() const = 0; 136 137 protected: ~I420ABufferInterface()138 ~I420ABufferInterface() override {} 139 }; 140 141 class I444BufferInterface : public PlanarYuv8Buffer { 142 public: 143 Type type() const final; 144 145 int ChromaWidth() const final; 146 int ChromaHeight() const final; 147 148 protected: ~I444BufferInterface()149 ~I444BufferInterface() override {} 150 }; 151 152 // This interface represents 8-bit to 16-bit color depth formats: Type::kI010. 153 class PlanarYuv16BBuffer : public PlanarYuvBuffer { 154 public: 155 // Returns pointer to the pixel data for a given plane. The memory is owned by 156 // the VideoFrameBuffer object and must not be freed by the caller. 157 virtual const uint16_t* DataY() const = 0; 158 virtual const uint16_t* DataU() const = 0; 159 virtual const uint16_t* DataV() const = 0; 160 161 protected: ~PlanarYuv16BBuffer()162 ~PlanarYuv16BBuffer() override {} 163 }; 164 165 // Represents Type::kI010, allocates 16 bits per pixel and fills 10 least 166 // significant bits with color information. 167 class I010BufferInterface : public PlanarYuv16BBuffer { 168 public: 169 Type type() const override; 170 171 int ChromaWidth() const final; 172 int ChromaHeight() const final; 173 174 protected: ~I010BufferInterface()175 ~I010BufferInterface() override {} 176 }; 177 178 } // namespace webrtc 179 180 #endif // API_VIDEO_VIDEO_FRAME_BUFFER_H_ 181