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