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