diff --git a/webrtc/media/base/videoframe.h b/webrtc/media/base/videoframe.h index 4015f906f9..1f282c5f29 100644 --- a/webrtc/media/base/videoframe.h +++ b/webrtc/media/base/videoframe.h @@ -19,6 +19,10 @@ namespace cricket { // Represents a YUV420 (a.k.a. I420) video frame. + +// TODO(nisse): This class duplicates webrtc::VideoFrame. There's +// ongoing work to merge the classes. See +// https://bugs.chromium.org/p/webrtc/issues/detail?id=5682. class VideoFrame { public: VideoFrame() {} @@ -54,22 +58,40 @@ class VideoFrame { // Make a shallow copy of the frame. The frame buffer itself is not copied. // Both the current and new VideoFrame will share a single reference-counted // frame buffer. + + // TODO(nisse): Deprecated, to be deleted in the cricket::VideoFrame and + // webrtc::VideoFrame merge. To make a copy, use the cricket::WebRtcVideoFrame + // constructor passing video_frame_buffer(), rotation() and timestamp_us() as + // arguments. virtual VideoFrame *Copy() const = 0; // Return a copy of frame which has its pending rotation applied. The // ownership of the returned frame is held by this frame. + + // TODO(nisse): Deprecated. Should be moved or deleted in the + // cricket::VideoFrame and webrtc::VideoFrame merge, possibly with a helper + // method on VideoFrameBuffer. virtual const VideoFrame* GetCopyWithRotationApplied() const = 0; // Converts the I420 data to RGB of a certain type such as ARGB and ABGR. // Returns the frame's actual size, regardless of whether it was written or // not (like snprintf). Parameters size and stride_rgb are in units of bytes. // If there is insufficient space, nothing is written. + + // TODO(nisse): Deprecated. Should be moved or deleted in the + // cricket::VideoFrame and webrtc::VideoFrame merge. Use + // libyuv::ConvertFromI420 directly instead. virtual size_t ConvertToRgbBuffer(uint32_t to_fourcc, uint8_t* buffer, size_t size, int stride_rgb) const; - // Tests if sample is valid. Returns true if valid. + // Tests if sample is valid. Returns true if valid. + + // TODO(nisse): Deprecated. Should be deleted in the cricket::VideoFrame and + // webrtc::VideoFrame merge. Validation of sample_size possibly moved to + // libyuv::ConvertToI420. As an initial step, demote this method to protected + // status. Used only by WebRtcVideoFrame::Reset. static bool Validate(uint32_t fourcc, int w, int h, diff --git a/webrtc/media/engine/webrtcvideoframe.h b/webrtc/media/engine/webrtcvideoframe.h index 487e32ef9a..29bdb32f2b 100644 --- a/webrtc/media/engine/webrtcvideoframe.h +++ b/webrtc/media/engine/webrtcvideoframe.h @@ -24,16 +24,24 @@ namespace cricket { struct CapturedFrame; +// TODO(nisse): This class will be deleted when the cricket::VideoFrame and +// webrtc::VideoFrame classes are merged. See +// https://bugs.chromium.org/p/webrtc/issues/detail?id=5682. Try to use only the +// preferred constructor, and the non-deprecated methods of the VideoFrame base +// class. class WebRtcVideoFrame : public VideoFrame { public: + // TODO(nisse): Deprecated. Using the default constructor violates the + // reasonable assumption that video_frame_buffer() returns a valid buffer. WebRtcVideoFrame(); - // Preferred construction, with microsecond timestamp. + // Preferred constructor. WebRtcVideoFrame(const rtc::scoped_refptr& buffer, webrtc::VideoRotation rotation, int64_t timestamp_us); - // TODO(nisse): Deprecate/delete. + // TODO(nisse): Deprecated, delete as soon as all callers have switched to the + // above constructor with microsecond timestamp. WebRtcVideoFrame(const rtc::scoped_refptr& buffer, int64_t time_stamp_ns, webrtc::VideoRotation rotation); @@ -54,10 +62,13 @@ class WebRtcVideoFrame : public VideoFrame { int64_t time_stamp_ns, webrtc::VideoRotation rotation); - // The timestamp of the captured frame is expected to use the same - // timescale and epoch as rtc::Time. - // TODO(nisse): Consider adding a warning message, or even an RTC_DCHECK, if - // the time is too far off. + // TODO(nisse): We're moving to have all timestamps use the same + // time scale as rtc::TimeMicros. However, this method is used by + // WebRtcVideoFrameFactory::CreateAliasedFrame this code path + // currently does not conform to the new timestamp conventions and + // may use the camera's own clock instead. It's unclear if this + // should be fixed, or if instead all of the VideoFrameFactory + // abstraction should be eliminated. bool Init(const CapturedFrame* frame, int dw, int dh, bool apply_rotation); void InitToEmptyBuffer(int w, int h); diff --git a/webrtc/video_frame.h b/webrtc/video_frame.h index 0f2b9a68af..ab8e37b0ed 100644 --- a/webrtc/video_frame.h +++ b/webrtc/video_frame.h @@ -19,9 +19,16 @@ namespace webrtc { +// TODO(nisse): This class duplicates cricket::VideoFrame. There's +// ongoing work to merge the classes. See +// https://bugs.chromium.org/p/webrtc/issues/detail?id=5682. class VideoFrame { public: + // TODO(nisse): Deprecated. Using the default constructor violates the + // reasonable assumption that video_frame_buffer() returns a valid buffer. VideoFrame(); + + // Preferred constructor. VideoFrame(const rtc::scoped_refptr& buffer, uint32_t timestamp, int64_t render_time_ms, @@ -31,6 +38,12 @@ class VideoFrame { // on set dimensions - height and plane stride. // If required size is bigger than the allocated one, new buffers of adequate // size will be allocated. + + // TODO(nisse): Deprecated. Should be deleted in the cricket::VideoFrame and + // webrtc::VideoFrame merge. If you need to write into the frame, create a + // VideoFrameBuffer of the desired size, e.g, using I420Buffer::Create and + // write to that. And if you need to wrap it into a VideoFrame, pass it to the + // constructor. void CreateEmptyFrame(int width, int height, int stride_y, @@ -39,6 +52,10 @@ class VideoFrame { // CreateFrame: Sets the frame's members and buffers. If required size is // bigger than allocated one, new buffers of adequate size will be allocated. + + // TODO(nisse): Deprecated. Should be deleted in the cricket::VideoFrame and + // webrtc::VideoFrame merge. Instead, create a VideoFrameBuffer and pass to + // the constructor. E.g, use I420Buffer::Copy(WrappedI420Buffer(...)). void CreateFrame(const uint8_t* buffer_y, const uint8_t* buffer_u, const uint8_t* buffer_v, @@ -52,6 +69,8 @@ class VideoFrame { // CreateFrame: Sets the frame's members and buffers. If required size is // bigger than allocated one, new buffers of adequate size will be allocated. // |buffer| must be a packed I420 buffer. + + // TODO(nisse): Deprecated, see above method for advice. void CreateFrame(const uint8_t* buffer, int width, int height, @@ -59,13 +78,23 @@ class VideoFrame { // Deep copy frame: If required size is bigger than allocated one, new // buffers of adequate size will be allocated. + // TODO(nisse): Should be deleted in the cricket::VideoFrame and + // webrtc::VideoFrame merge. Instead, use I420Buffer::Copy to make a copy of + // the pixel data, and use the constructor to wrap it into a VideoFrame. void CopyFrame(const VideoFrame& videoFrame); // Creates a shallow copy of |videoFrame|, i.e, the this object will retain a // reference to the video buffer also retained by |videoFrame|. + // TODO(nisse): Deprecated. Should be deleted in the cricket::VideoFrame and + // webrtc::VideoFrame merge. Instead, pass video_frame_buffer() and timestamps + // to the constructor. void ShallowCopy(const VideoFrame& videoFrame); // Get allocated size per plane. + + // TODO(nisse): Deprecated. Should be deleted in the cricket::VideoFrame and + // webrtc::VideoFrame merge. When used with memset, consider using + // libyuv::I420Rect instead. int allocated_size(PlaneType type) const; // Get frame width. @@ -74,18 +103,22 @@ class VideoFrame { // Get frame height. int height() const; + // TODO(nisse): After the cricket::VideoFrame and webrtc::VideoFrame + // merge, we'll have methods timestamp_us and set_timestamp_us, all + // other frame timestamps will likely be deprecated. + // Set frame timestamp (90kHz). void set_timestamp(uint32_t timestamp) { timestamp_ = timestamp; } // Get frame timestamp (90kHz). uint32_t timestamp() const { return timestamp_; } - // Set capture ntp time in miliseconds. + // Set capture ntp time in milliseconds. void set_ntp_time_ms(int64_t ntp_time_ms) { ntp_time_ms_ = ntp_time_ms; } - // Get capture ntp time in miliseconds. + // Get capture ntp time in milliseconds. int64_t ntp_time_ms() const { return ntp_time_ms_; } // Naming convention for Coordination of Video Orientation. Please see @@ -103,15 +136,21 @@ class VideoFrame { rotation_ = rotation; } - // Set render time in miliseconds. + // Set render time in milliseconds. void set_render_time_ms(int64_t render_time_ms) { render_time_ms_ = render_time_ms; } - // Get render time in miliseconds. + // Get render time in milliseconds. int64_t render_time_ms() const { return render_time_ms_; } - // Return true if underlying plane buffers are of zero size, false if not. + // Return true if and only if video_frame_buffer() is null. Which is possible + // only if the object was default-constructed. + // TODO(nisse): Deprecated. Should be deleted in the cricket::VideoFrame and + // webrtc::VideoFrame merge. The intention is that video_frame_buffer() never + // should return nullptr. To handle potentially uninitialized or non-existent + // frames, consider using rtc::Optional. Otherwise, IsZeroSize() can be + // replaced by video_frame_buffer() == nullptr. bool IsZeroSize() const; // Return the underlying buffer. Never nullptr for a properly