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/include/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 time_stamp) = 0;
46  // Creates a frame from a raw sample with FourCC |format| and size |w| x |h|.
47  // |h| can be negative indicating a vertically flipped image.
48  // |dw| is destination width; can be less than |w| if cropping is desired.
49  // |dh| is destination height, like |dw|, but must be a positive number.
50  // Returns whether the function succeeded or failed.
51
52  virtual bool Reset(uint32_t fourcc,
53                     int w,
54                     int h,
55                     int dw,
56                     int dh,
57                     uint8_t* sample,
58                     size_t sample_size,
59                     size_t pixel_width,
60                     size_t pixel_height,
61                     int64_t time_stamp,
62                     webrtc::VideoRotation rotation,
63                     bool apply_rotation) = 0;
64
65  // Basic accessors.
66  // Note this is the width and height without rotation applied.
67  virtual size_t GetWidth() const = 0;
68  virtual size_t GetHeight() const = 0;
69
70  size_t GetChromaWidth() const { return (GetWidth() + 1) / 2; }
71  size_t GetChromaHeight() const { return (GetHeight() + 1) / 2; }
72  size_t GetChromaSize() const { return GetUPitch() * GetChromaHeight(); }
73  // These can return NULL if the object is not backed by a buffer.
74  virtual const uint8_t* GetYPlane() const = 0;
75  virtual const uint8_t* GetUPlane() const = 0;
76  virtual const uint8_t* GetVPlane() const = 0;
77  virtual uint8_t* GetYPlane() = 0;
78  virtual uint8_t* GetUPlane() = 0;
79  virtual uint8_t* GetVPlane() = 0;
80
81  virtual int32_t GetYPitch() const = 0;
82  virtual int32_t GetUPitch() const = 0;
83  virtual int32_t GetVPitch() const = 0;
84
85  // Returns the handle of the underlying video frame. This is used when the
86  // frame is backed by a texture. The object should be destroyed when it is no
87  // longer in use, so the underlying resource can be freed.
88  virtual void* GetNativeHandle() const = 0;
89
90  // Returns the underlying video frame buffer. This function is ok to call
91  // multiple times, but the returned object will refer to the same memory.
92  virtual rtc::scoped_refptr<webrtc::VideoFrameBuffer> GetVideoFrameBuffer()
93      const = 0;
94
95  // For retrieving the aspect ratio of each pixel. Usually this is 1x1, but
96  // the aspect_ratio_idc parameter of H.264 can specify non-square pixels.
97  virtual size_t GetPixelWidth() const = 0;
98  virtual size_t GetPixelHeight() const = 0;
99
100  virtual int64_t GetTimeStamp() const = 0;
101  virtual void SetTimeStamp(int64_t time_stamp) = 0;
102
103  // Indicates the rotation angle in degrees.
104  // TODO(guoweis): Remove this function, rename GetVideoRotation and remove the
105  // skeleton implementation of GetRotation once chrome is updated.
106  virtual int GetRotation() const { return GetVideoRotation(); }
107  virtual webrtc::VideoRotation GetVideoRotation() const {
108    return webrtc::kVideoRotation_0;
109  }
110
111  // Make a shallow copy of the frame. The frame buffer itself is not copied.
112  // Both the current and new VideoFrame will share a single reference-counted
113  // frame buffer.
114  virtual VideoFrame *Copy() const = 0;
115
116  // Since VideoFrame supports shallow copy and the internal frame buffer might
117  // be shared, this function can be used to check exclusive ownership.
118  virtual bool IsExclusive() const = 0;
119
120  // In case VideoFrame needs exclusive access of the frame buffer, user can
121  // call MakeExclusive() to make sure the frame buffer is exclusively
122  // accessible to the current object.  This might mean a deep copy of the frame
123  // buffer if it is currently shared by other objects.
124  virtual bool MakeExclusive() = 0;
125
126  // Writes the frame into the given frame buffer, provided that it is of
127  // sufficient size. Returns the frame's actual size, regardless of whether
128  // it was written or not (like snprintf). If there is insufficient space,
129  // nothing is written.
130  virtual size_t CopyToBuffer(uint8_t* buffer, size_t size) const;
131
132  // Writes the frame into the given planes, stretched to the given width and
133  // height. The parameter "interpolate" controls whether to interpolate or just
134  // take the nearest-point. The parameter "crop" controls whether to crop this
135  // frame to the aspect ratio of the given dimensions before stretching.
136  virtual bool CopyToPlanes(uint8_t* dst_y,
137                            uint8_t* dst_u,
138                            uint8_t* dst_v,
139                            int32_t dst_pitch_y,
140                            int32_t dst_pitch_u,
141                            int32_t dst_pitch_v) const;
142
143  // Writes the frame into the target VideoFrame.
144  virtual void CopyToFrame(VideoFrame* target) const;
145
146  // Return a copy of frame which has its pending rotation applied. The
147  // ownership of the returned frame is held by this frame.
148  virtual const VideoFrame* GetCopyWithRotationApplied() const = 0;
149
150  // Writes the frame into the given stream and returns the StreamResult.
151  // See webrtc/base/stream.h for a description of StreamResult and error.
152  // Error may be NULL. If a non-success value is returned from
153  // StreamInterface::Write(), we immediately return with that value.
154  virtual rtc::StreamResult Write(rtc::StreamInterface* stream,
155                                  int* error) const;
156
157  // Converts the I420 data to RGB of a certain type such as ARGB and ABGR.
158  // Returns the frame's actual size, regardless of whether it was written or
159  // not (like snprintf). Parameters size and stride_rgb are in units of bytes.
160  // If there is insufficient space, nothing is written.
161  virtual size_t ConvertToRgbBuffer(uint32_t to_fourcc,
162                                    uint8_t* buffer,
163                                    size_t size,
164                                    int stride_rgb) const;
165
166  // Writes the frame into the given planes, stretched to the given width and
167  // height. The parameter "interpolate" controls whether to interpolate or just
168  // take the nearest-point. The parameter "crop" controls whether to crop this
169  // frame to the aspect ratio of the given dimensions before stretching.
170  virtual void StretchToPlanes(uint8_t* y,
171                               uint8_t* u,
172                               uint8_t* v,
173                               int32_t pitchY,
174                               int32_t pitchU,
175                               int32_t pitchV,
176                               size_t width,
177                               size_t height,
178                               bool interpolate,
179                               bool crop) const;
180
181  // Writes the frame into the target VideoFrame, stretched to the size of that
182  // frame. The parameter "interpolate" controls whether to interpolate or just
183  // take the nearest-point. The parameter "crop" controls whether to crop this
184  // frame to the aspect ratio of the target frame before stretching.
185  virtual void StretchToFrame(VideoFrame *target, bool interpolate,
186                              bool crop) const;
187
188  // Stretches the frame to the given size, creating a new VideoFrame object to
189  // hold it. The parameter "interpolate" controls whether to interpolate or
190  // just take the nearest-point. The parameter "crop" controls whether to crop
191  // this frame to the aspect ratio of the given dimensions before stretching.
192  virtual VideoFrame *Stretch(size_t w, size_t h, bool interpolate,
193                              bool crop) const;
194
195  // Sets the video frame to black.
196  virtual bool SetToBlack();
197
198  // Tests if sample is valid.  Returns true if valid.
199  static bool Validate(uint32_t fourcc,
200                       int w,
201                       int h,
202                       const uint8_t* sample,
203                       size_t sample_size);
204
205  // Size of an I420 image of given dimensions when stored as a frame buffer.
206  static size_t SizeOf(size_t w, size_t h) {
207    return w * h + ((w + 1) / 2) * ((h + 1) / 2) * 2;
208  }
209
210 protected:
211  // Creates an empty frame.
212  virtual VideoFrame *CreateEmptyFrame(int w, int h, size_t pixel_width,
213                                       size_t pixel_height,
214                                       int64_t time_stamp) const = 0;
215  virtual void SetRotation(webrtc::VideoRotation rotation) = 0;
216};
217
218}  // namespace cricket
219
220#endif  // TALK_MEDIA_BASE_VIDEOFRAME_H_
221