videoframe.h revision 00c509ad1c94805b3332f2ce876c04705abf8ef5 
1/*
2 * libjingle
3 * Copyright 2004 Google Inc.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are met:
7 *
8 *  1. Redistributions of source code must retain the above copyright notice,
9 *     this list of conditions and the following disclaimer.
10 *  2. Redistributions in binary form must reproduce the above copyright notice,
11 *     this list of conditions and the following disclaimer in the documentation
12 *     and/or other materials provided with the distribution.
13 *  3. The name of the author may not be used to endorse or promote products
14 *     derived from this software without specific prior written permission.
15 *
16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
18 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
19 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
20 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27
28#ifndef TALK_MEDIA_BASE_VIDEOFRAME_H_
29#define TALK_MEDIA_BASE_VIDEOFRAME_H_
30
31#include "webrtc/base/basictypes.h"
32#include "webrtc/base/stream.h"
33#include "webrtc/common_video/interface/video_frame_buffer.h"
34#include "webrtc/common_video/rotation.h"
35
36namespace cricket {
37
38// Represents a YUV420 (a.k.a. I420) video frame.
39class VideoFrame {
40 public:
41  VideoFrame() {}
42  virtual ~VideoFrame() {}
43
44  virtual bool InitToBlack(int w, int h, size_t pixel_width,
45                           size_t pixel_height, int64_t elapsed_time,
46                           int64_t time_stamp) = 0;
47  // Creates a frame from a raw sample with FourCC |format| and size |w| x |h|.
48  // |h| can be negative indicating a vertically flipped image.
49  // |dw| is destination width; can be less than |w| if cropping is desired.
50  // |dh| is destination height, like |dw|, but must be a positive number.
51  // Returns whether the function succeeded or failed.
52
53  // TODO(guoweis): remove the implementation and the next Reset once chrome
54  // gets the code.
55  virtual bool Reset(uint32 fourcc,
56                     int w,
57                     int h,
58                     int dw,
59                     int dh,
60                     uint8* sample,
61                     size_t sample_size,
62                     size_t pixel_width,
63                     size_t pixel_height,
64                     int64_t elapsed_time,
65                     int64_t time_stamp,
66                     webrtc::VideoRotation rotation,
67                     bool apply_rotation) {
68    return false;
69  }
70
71  virtual bool Reset(uint32 fourcc,
72                     int w,
73                     int h,
74                     int dw,
75                     int dh,
76                     uint8* sample,
77                     size_t sample_size,
78                     size_t pixel_width,
79                     size_t pixel_height,
80                     int64_t elapsed_time,
81                     int64_t time_stamp,
82                     int rotation) {
83    return Reset(fourcc, w, h, dw, dh, sample, sample_size, pixel_width,
84                 pixel_height, elapsed_time, time_stamp,
85                 static_cast<webrtc::VideoRotation>(rotation), true);
86  }
87
88  // Basic accessors.
89  virtual size_t GetWidth() const = 0;
90  virtual size_t GetHeight() const = 0;
91  size_t GetChromaWidth() const { return (GetWidth() + 1) / 2; }
92  size_t GetChromaHeight() const { return (GetHeight() + 1) / 2; }
93  size_t GetChromaSize() const { return GetUPitch() * GetChromaHeight(); }
94  // These can return NULL if the object is not backed by a buffer.
95  virtual const uint8 *GetYPlane() const = 0;
96  virtual const uint8 *GetUPlane() const = 0;
97  virtual const uint8 *GetVPlane() const = 0;
98  virtual uint8 *GetYPlane() = 0;
99  virtual uint8 *GetUPlane() = 0;
100  virtual uint8 *GetVPlane() = 0;
101
102  virtual int32 GetYPitch() const = 0;
103  virtual int32 GetUPitch() const = 0;
104  virtual int32 GetVPitch() const = 0;
105
106  // Returns the handle of the underlying video frame. This is used when the
107  // frame is backed by a texture. The object should be destroyed when it is no
108  // longer in use, so the underlying resource can be freed.
109  virtual void* GetNativeHandle() const = 0;
110
111  // Returns the underlying video frame buffer. The default implementation
112  // returns a shallow wrapper, converting itself into a
113  // webrtc::VideoFrameBuffer. This function is ok to call multiple times, but
114  // the returned object will refer to the same memory.
115  // TODO(magjed): Make pure virtual when all subclasses implement this.
116  virtual rtc::scoped_refptr<webrtc::VideoFrameBuffer> GetVideoFrameBuffer()
117      const;
118
119  // For retrieving the aspect ratio of each pixel. Usually this is 1x1, but
120  // the aspect_ratio_idc parameter of H.264 can specify non-square pixels.
121  virtual size_t GetPixelWidth() const = 0;
122  virtual size_t GetPixelHeight() const = 0;
123
124  virtual int64_t GetElapsedTime() const = 0;
125  virtual int64_t GetTimeStamp() const = 0;
126  virtual void SetElapsedTime(int64_t elapsed_time) = 0;
127  virtual void SetTimeStamp(int64_t time_stamp) = 0;
128
129  // Indicates the rotation angle in degrees.
130  // TODO(guoweis): Remove this function, rename GetVideoRotation and remove the
131  // skeleton implementation of GetRotation once chrome is updated.
132  virtual int GetRotation() const { return GetVideoRotation(); }
133  virtual webrtc::VideoRotation GetVideoRotation() const {
134    return webrtc::kVideoRotation_0;
135  }
136
137  // Make a shallow copy of the frame. The frame buffer itself is not copied.
138  // Both the current and new VideoFrame will share a single reference-counted
139  // frame buffer.
140  virtual VideoFrame *Copy() const = 0;
141
142  // Since VideoFrame supports shallow copy and the internal frame buffer might
143  // be shared, this function can be used to check exclusive ownership. The
144  // default implementation is conservative and returns false. Subclasses with
145  // knowledge of implementation specific details can override this.
146  virtual bool IsExclusive() const { return false; }
147
148  // In case VideoFrame needs exclusive access of the frame buffer, user can
149  // call MakeExclusive() to make sure the frame buffer is exclusively
150  // accessible to the current object.  This might mean a deep copy of the frame
151  // buffer if it is currently shared by other objects.
152  virtual bool MakeExclusive() = 0;
153
154  // Writes the frame into the given frame buffer, provided that it is of
155  // sufficient size. Returns the frame's actual size, regardless of whether
156  // it was written or not (like snprintf). If there is insufficient space,
157  // nothing is written.
158  virtual size_t CopyToBuffer(uint8 *buffer, size_t size) const;
159
160  // Writes the frame into the given planes, stretched to the given width and
161  // height. The parameter "interpolate" controls whether to interpolate or just
162  // take the nearest-point. The parameter "crop" controls whether to crop this
163  // frame to the aspect ratio of the given dimensions before stretching.
164  virtual bool CopyToPlanes(
165      uint8* dst_y, uint8* dst_u, uint8* dst_v,
166      int32 dst_pitch_y, int32 dst_pitch_u, int32 dst_pitch_v) const;
167
168  // Writes the frame into the target VideoFrame.
169  virtual void CopyToFrame(VideoFrame* target) const;
170
171  // Return a copy of frame which has its pending rotation applied. The
172  // ownership of the returned frame is held by this frame.
173  virtual const VideoFrame* GetCopyWithRotationApplied() const {
174    return nullptr;
175  }
176
177  // Writes the frame into the given stream and returns the StreamResult.
178  // See webrtc/base/stream.h for a description of StreamResult and error.
179  // Error may be NULL. If a non-success value is returned from
180  // StreamInterface::Write(), we immediately return with that value.
181  virtual rtc::StreamResult Write(rtc::StreamInterface* stream,
182                                  int* error) const;
183
184  // Converts the I420 data to RGB of a certain type such as ARGB and ABGR.
185  // Returns the frame's actual size, regardless of whether it was written or
186  // not (like snprintf). Parameters size and stride_rgb are in units of bytes.
187  // If there is insufficient space, nothing is written.
188  virtual size_t ConvertToRgbBuffer(uint32 to_fourcc, uint8 *buffer,
189                                    size_t size, int stride_rgb) const;
190
191  // Writes the frame into the given planes, stretched to the given width and
192  // height. The parameter "interpolate" controls whether to interpolate or just
193  // take the nearest-point. The parameter "crop" controls whether to crop this
194  // frame to the aspect ratio of the given dimensions before stretching.
195  virtual void StretchToPlanes(
196      uint8 *y, uint8 *u, uint8 *v, int32 pitchY, int32 pitchU, int32 pitchV,
197      size_t width, size_t height, bool interpolate, bool crop) const;
198
199  // Writes the frame into the given frame buffer, stretched to the given width
200  // and height, provided that it is of sufficient size. Returns the frame's
201  // actual size, regardless of whether it was written or not (like snprintf).
202  // If there is insufficient space, nothing is written. The parameter
203  // "interpolate" controls whether to interpolate or just take the
204  // nearest-point. The parameter "crop" controls whether to crop this frame to
205  // the aspect ratio of the given dimensions before stretching.
206  virtual size_t StretchToBuffer(size_t w, size_t h, uint8 *buffer, size_t size,
207                                 bool interpolate, bool crop) const;
208
209  // Writes the frame into the target VideoFrame, stretched to the size of that
210  // frame. The parameter "interpolate" controls whether to interpolate or just
211  // take the nearest-point. The parameter "crop" controls whether to crop this
212  // frame to the aspect ratio of the target frame before stretching.
213  virtual void StretchToFrame(VideoFrame *target, bool interpolate,
214                              bool crop) const;
215
216  // Stretches the frame to the given size, creating a new VideoFrame object to
217  // hold it. The parameter "interpolate" controls whether to interpolate or
218  // just take the nearest-point. The parameter "crop" controls whether to crop
219  // this frame to the aspect ratio of the given dimensions before stretching.
220  virtual VideoFrame *Stretch(size_t w, size_t h, bool interpolate,
221                              bool crop) const;
222
223  // Sets the video frame to black.
224  virtual bool SetToBlack();
225
226  // Tests if sample is valid.  Returns true if valid.
227  static bool Validate(uint32 fourcc, int w, int h, const uint8 *sample,
228                       size_t sample_size);
229
230  // Size of an I420 image of given dimensions when stored as a frame buffer.
231  static size_t SizeOf(size_t w, size_t h) {
232    return w * h + ((w + 1) / 2) * ((h + 1) / 2) * 2;
233  }
234
235 protected:
236  // Creates an empty frame.
237  virtual VideoFrame *CreateEmptyFrame(int w, int h, size_t pixel_width,
238                                       size_t pixel_height,
239                                       int64_t elapsed_time,
240                                       int64_t time_stamp) const = 0;
241};
242
243}  // namespace cricket
244
245#endif  // TALK_MEDIA_BASE_VIDEOFRAME_H_
246