modules/desktop_capture/desktop_frame.h - src - Git at Google

 /*
  *  Copyright (c) 2013 The WebRTC project authors. All Rights Reserved.
  *
  *  Use of this source code is governed by a BSD-style license
  *  that can be found in the LICENSE file in the root of the source
  *  tree. An additional intellectual property rights grant can be found
  *  in the file PATENTS.  All contributing project authors may
  *  be found in the AUTHORS file in the root of the source tree.
  */

 #ifndef MODULES_DESKTOP_CAPTURE_DESKTOP_FRAME_H_
 #define MODULES_DESKTOP_CAPTURE_DESKTOP_FRAME_H_

 #include <stdint.h>

 #include <memory>
 #include <optional>
 #include <vector>

 #include "media/base/video_common.h"
 #include "modules/desktop_capture/desktop_geometry.h"
 #include "modules/desktop_capture/desktop_region.h"
 #include "modules/desktop_capture/shared_memory.h"
 #include "rtc_base/system/rtc_export.h"

 namespace webrtc {

 const float kStandardDPI = 96.0f;

 // DesktopFrame represents a video frame captured from the screen.
 class RTC_EXPORT DesktopFrame {
  public:
   // DesktopFrame objects always hold BGRA data.
   static const int kBytesPerPixel = 4;

   virtual ~DesktopFrame();

   DesktopFrame(const DesktopFrame&) = delete;
   DesktopFrame& operator=(const DesktopFrame&) = delete;

   // Returns the rectangle in full desktop coordinates to indicate it covers
   // the area of top_left() to top_letf() + size() / scale_factor().
   DesktopRect rect() const;

   // Returns the scale factor from DIPs to physical pixels of the frame.
   // Assumes same scale in both X and Y directions at present.
   float scale_factor() const;

   // Size of the frame. In physical coordinates, mapping directly from the
   // underlying buffer.
   const DesktopSize& size() const { return size_; }

   // The top-left of the frame in full desktop coordinates. E.g. the top left
   // monitor should start from (0, 0). The desktop coordinates may be scaled by
   // OS, but this is always consistent with the MouseCursorMonitor.
   const DesktopVector& top_left() const { return top_left_; }
   void set_top_left(const DesktopVector& top_left) { top_left_ = top_left; }

   // Distance in the buffer between two neighboring rows in bytes.
   int stride() const { return stride_; }

   // The pixel format the `DesktopFrame` is stored in.
   FourCC pixel_format() const { return pixel_format_; }

   // Data buffer used for the frame.
   uint8_t* data() const { return data_; }

   // SharedMemory used for the buffer or NULL if memory is allocated on the
   // heap. The result is guaranteed to be deleted only after the frame is
   // deleted (classes that inherit from DesktopFrame must ensure it).
   SharedMemory* shared_memory() const { return shared_memory_; }

   // Indicates region of the screen that has changed since the previous frame.
   const DesktopRegion& updated_region() const { return updated_region_; }
   DesktopRegion* mutable_updated_region() { return &updated_region_; }

   // DPI of the screen being captured. May be set to zero, e.g. if DPI is
   // unknown.
   const DesktopVector& dpi() const { return dpi_; }
   void set_dpi(const DesktopVector& dpi) { dpi_ = dpi; }

   std::optional<float> device_scale_factor() const {
     return device_scale_factor_;
   }
   void set_device_scale_factor(std::optional<float> device_scale_factor) {
     device_scale_factor_ = device_scale_factor;
   }
   // Indicates if this frame may have the mouse cursor in it. Capturers that
   // support cursor capture may set this to true. If the cursor was
   // outside of the captured area, this may be true even though the cursor is
   // not in the image.
   bool may_contain_cursor() const { return may_contain_cursor_; }
   void set_may_contain_cursor(bool may_contain_cursor) {
     may_contain_cursor_ = may_contain_cursor;
   }

   // Time taken to capture the frame in milliseconds.
   int64_t capture_time_ms() const { return capture_time_ms_; }
   void set_capture_time_ms(int64_t time_ms) { capture_time_ms_ = time_ms; }

   // Copies pixels from a buffer or another frame. `dest_rect` rect must lay
   // within bounds of this frame.
   void CopyPixelsFrom(const uint8_t* src_buffer,
                       int src_stride,
                       const DesktopRect& dest_rect);
   void CopyPixelsFrom(const DesktopFrame& src_frame,
                       const DesktopVector& src_pos,
                       const DesktopRect& dest_rect);

   // Copies pixels from another frame, with the copied & overwritten regions
   // representing the intersection between the two frames. Returns true if
   // pixels were copied, or false if there's no intersection. The scale factors
   // represent the ratios between pixel space & offset coordinate space (e.g.
   // 2.0 would indicate the frames are scaled down by 50% for display, so any
   // offset between their origins should be doubled).
   bool CopyIntersectingPixelsFrom(const DesktopFrame& src_frame,
                                   double horizontal_scale,
                                   double vertical_scale);

   // A helper to return the data pointer of a frame at the specified position.
   uint8_t* GetFrameDataAtPos(const DesktopVector& pos) const;

   // The DesktopCapturer implementation which generates current DesktopFrame.
   // Not all DesktopCapturer implementations set this field; it's set to
   // kUnknown by default.
   uint32_t capturer_id() const { return capturer_id_; }
   void set_capturer_id(uint32_t capturer_id) { capturer_id_ = capturer_id; }

   // Copies various information from `other`. Anything initialized in
   // constructor are not copied.
   // This function is usually used when sharing a source DesktopFrame with
   // several clients: the original DesktopFrame should be kept unchanged. For
   // example, BasicDesktopFrame::CopyOf() and SharedDesktopFrame::Share().
   void CopyFrameInfoFrom(const DesktopFrame& other);

   // Copies various information from `other`. Anything initialized in
   // constructor are not copied. Not like CopyFrameInfoFrom() function, this
   // function uses swap or move constructor to avoid data copy. It won't break
   // the `other`, but some of its information may be missing after this
   // operation. E.g. other->updated_region_;
   // This function is usually used when wrapping a DesktopFrame: the wrapper
   // instance takes the ownership of `other`, so other components cannot access
   // `other` anymore. For example, CroppedDesktopFrame and
   // DesktopFrameWithCursor.
   void MoveFrameInfoFrom(DesktopFrame* other);

   // Set and get the ICC profile of the frame data pixels. Useful to build the
   // a ColorSpace object from clients of webrtc library like chromium. The
   // format of an ICC profile is defined in the following specification
   // http://www.color.org/specification/ICC1v43_2010-12.pdf.
   const std::vector<uint8_t>& icc_profile() const { return icc_profile_; }
   void set_icc_profile(const std::vector<uint8_t>& icc_profile) {
     icc_profile_ = icc_profile;
   }

   // Sets all pixel values in the data buffer to zero.
   void SetFrameDataToBlack();

   // Returns true if all pixel values in the data buffer are zero or false
   // otherwise. Also returns false if the frame is empty.
   bool FrameDataIsBlack() const;

  protected:
   // TODO(bugs.webrtc.org/436974448): Remove.
   // Deprecated, use the next constructor.
   DesktopFrame(DesktopSize size,
                int stride,
                uint8_t* data,
                SharedMemory* shared_memory);

   DesktopFrame(DesktopSize size,
                int stride,
                FourCC pixel_format,
                uint8_t* data,
                SharedMemory* shared_memory);

   // Ownership of the buffers is defined by the classes that inherit from this
   // class. They must guarantee that the buffer is not deleted before the frame
   // is deleted.
   uint8_t* const data_;
   SharedMemory* const shared_memory_;

  private:
   const DesktopSize size_;
   const int stride_;

   // The pixel format for the data stored. Currently, only 4 byte per pixel
   // formats are supported.
   const FourCC pixel_format_;

   DesktopRegion updated_region_;
   DesktopVector top_left_;
   DesktopVector dpi_;
   bool may_contain_cursor_ = false;
   int64_t capture_time_ms_;
   uint32_t capturer_id_;
   std::vector<uint8_t> icc_profile_;
   // Currently only used on Windows. It stores the device scale factor of the
   // captured surface and has distinct values possible in the range of
   // [1,5].
   std::optional<float> device_scale_factor_;
 };

 // A DesktopFrame that stores data in the heap.
 class RTC_EXPORT BasicDesktopFrame : public DesktopFrame {
  public:
   // TODO(bugs.webrtc.org/436974448): Remove.
   // Deprecated, use the last constructor.
   explicit BasicDesktopFrame(DesktopSize size);

   // The entire data buffer used for the frame is initialized with zeros.
   BasicDesktopFrame(DesktopSize size, FourCC pixel_format);

   ~BasicDesktopFrame() override;

   BasicDesktopFrame(const BasicDesktopFrame&) = delete;
   BasicDesktopFrame& operator=(const BasicDesktopFrame&) = delete;

   // Creates a BasicDesktopFrame that contains copy of `frame`.
   // TODO(zijiehe): Return std::unique_ptr<DesktopFrame>
   static DesktopFrame* CopyOf(const DesktopFrame& frame);
 };

 // A DesktopFrame that stores data in shared memory.
 class RTC_EXPORT SharedMemoryDesktopFrame : public DesktopFrame {
  public:
   // May return nullptr if `shared_memory_factory` failed to create a
   // SharedMemory instance.
   // `shared_memory_factory` should not be nullptr.
   static std::unique_ptr<DesktopFrame> Create(
       DesktopSize size,
       FourCC pixel_format,
       SharedMemoryFactory* shared_memory_factory);

   // TODO(bugs.webrtc.org/436974448): Remove.
   // Deprecated, use the last constructor.
   SharedMemoryDesktopFrame(DesktopSize size,
                            int stride,
                            std::unique_ptr<SharedMemory> shared_memory);

   // Takes ownership of `shared_memory`.
   // Deprecated, use the last constructor.
   SharedMemoryDesktopFrame(DesktopSize size,
                            int stride,
                            FourCC pixel_format,
                            SharedMemory* shared_memory);

   // Preferred.
   SharedMemoryDesktopFrame(DesktopSize size,
                            int stride,
                            FourCC pixel_format,
                            std::unique_ptr<SharedMemory> shared_memory);

   ~SharedMemoryDesktopFrame() override;

   SharedMemoryDesktopFrame(const SharedMemoryDesktopFrame&) = delete;
   SharedMemoryDesktopFrame& operator=(const SharedMemoryDesktopFrame&) = delete;

  private:
   // Avoid unexpected order of parameter evaluation.
   // Executing both std::unique_ptr<T>::operator->() and
   // std::unique_ptr<T>::release() in the member initializer list is not safe.
   // Depends on the order of parameter evaluation,
   // std::unique_ptr<T>::operator->() may trigger assertion failure if it has
   // been evaluated after std::unique_ptr<T>::release(). By using this
   // constructor, std::unique_ptr<T>::operator->() won't be involved anymore.
   SharedMemoryDesktopFrame(DesktopRect rect,
                            int stride,
                            FourCC pixel_format,
                            SharedMemory* shared_memory);
 };

 }  // namespace webrtc

 #endif  // MODULES_DESKTOP_CAPTURE_DESKTOP_FRAME_H_
	/*
	* Copyright (c) 2013 The WebRTC project authors. All Rights Reserved.
	*
	* Use of this source code is governed by a BSD-style license
	* that can be found in the LICENSE file in the root of the source
	* tree. An additional intellectual property rights grant can be found
	* in the file PATENTS. All contributing project authors may
	* be found in the AUTHORS file in the root of the source tree.
	*/

	#ifndef MODULES_DESKTOP_CAPTURE_DESKTOP_FRAME_H_
	#define MODULES_DESKTOP_CAPTURE_DESKTOP_FRAME_H_

	#include <stdint.h>

	#include <memory>
	#include <optional>
	#include <vector>

	#include "media/base/video_common.h"
	#include "modules/desktop_capture/desktop_geometry.h"
	#include "modules/desktop_capture/desktop_region.h"
	#include "modules/desktop_capture/shared_memory.h"
	#include "rtc_base/system/rtc_export.h"

	namespace webrtc {

	const float kStandardDPI = 96.0f;

	// DesktopFrame represents a video frame captured from the screen.
	class RTC_EXPORT DesktopFrame {
	public:
	// DesktopFrame objects always hold BGRA data.
	static const int kBytesPerPixel = 4;

	virtual ~DesktopFrame();

	DesktopFrame(const DesktopFrame&) = delete;
	DesktopFrame& operator=(const DesktopFrame&) = delete;

	// Returns the rectangle in full desktop coordinates to indicate it covers
	// the area of top_left() to top_letf() + size() / scale_factor().
	DesktopRect rect() const;

	// Returns the scale factor from DIPs to physical pixels of the frame.
	// Assumes same scale in both X and Y directions at present.
	float scale_factor() const;

	// Size of the frame. In physical coordinates, mapping directly from the
	// underlying buffer.
	const DesktopSize& size() const { return size_; }

	// The top-left of the frame in full desktop coordinates. E.g. the top left
	// monitor should start from (0, 0). The desktop coordinates may be scaled by
	// OS, but this is always consistent with the MouseCursorMonitor.
	const DesktopVector& top_left() const { return top_left_; }
	void set_top_left(const DesktopVector& top_left) { top_left_ = top_left; }

	// Distance in the buffer between two neighboring rows in bytes.
	int stride() const { return stride_; }

	// The pixel format the `DesktopFrame` is stored in.
	FourCC pixel_format() const { return pixel_format_; }

	// Data buffer used for the frame.
	uint8_t* data() const { return data_; }

	// SharedMemory used for the buffer or NULL if memory is allocated on the
	// heap. The result is guaranteed to be deleted only after the frame is
	// deleted (classes that inherit from DesktopFrame must ensure it).
	SharedMemory* shared_memory() const { return shared_memory_; }

	// Indicates region of the screen that has changed since the previous frame.
	const DesktopRegion& updated_region() const { return updated_region_; }
	DesktopRegion* mutable_updated_region() { return &updated_region_; }

	// DPI of the screen being captured. May be set to zero, e.g. if DPI is
	// unknown.
	const DesktopVector& dpi() const { return dpi_; }
	void set_dpi(const DesktopVector& dpi) { dpi_ = dpi; }

	std::optional<float> device_scale_factor() const {
	return device_scale_factor_;
	}
	void set_device_scale_factor(std::optional<float> device_scale_factor) {
	device_scale_factor_ = device_scale_factor;
	}
	// Indicates if this frame may have the mouse cursor in it. Capturers that
	// support cursor capture may set this to true. If the cursor was
	// outside of the captured area, this may be true even though the cursor is
	// not in the image.
	bool may_contain_cursor() const { return may_contain_cursor_; }
	void set_may_contain_cursor(bool may_contain_cursor) {
	may_contain_cursor_ = may_contain_cursor;
	}

	// Time taken to capture the frame in milliseconds.
	int64_t capture_time_ms() const { return capture_time_ms_; }
	void set_capture_time_ms(int64_t time_ms) { capture_time_ms_ = time_ms; }

	// Copies pixels from a buffer or another frame. `dest_rect` rect must lay
	// within bounds of this frame.
	void CopyPixelsFrom(const uint8_t* src_buffer,
	int src_stride,
	const DesktopRect& dest_rect);
	void CopyPixelsFrom(const DesktopFrame& src_frame,
	const DesktopVector& src_pos,
	const DesktopRect& dest_rect);

	// Copies pixels from another frame, with the copied & overwritten regions
	// representing the intersection between the two frames. Returns true if
	// pixels were copied, or false if there's no intersection. The scale factors
	// represent the ratios between pixel space & offset coordinate space (e.g.
	// 2.0 would indicate the frames are scaled down by 50% for display, so any
	// offset between their origins should be doubled).
	bool CopyIntersectingPixelsFrom(const DesktopFrame& src_frame,
	double horizontal_scale,
	double vertical_scale);

	// A helper to return the data pointer of a frame at the specified position.
	uint8_t* GetFrameDataAtPos(const DesktopVector& pos) const;

	// The DesktopCapturer implementation which generates current DesktopFrame.
	// Not all DesktopCapturer implementations set this field; it's set to
	// kUnknown by default.
	uint32_t capturer_id() const { return capturer_id_; }
	void set_capturer_id(uint32_t capturer_id) { capturer_id_ = capturer_id; }

	// Copies various information from `other`. Anything initialized in
	// constructor are not copied.
	// This function is usually used when sharing a source DesktopFrame with
	// several clients: the original DesktopFrame should be kept unchanged. For
	// example, BasicDesktopFrame::CopyOf() and SharedDesktopFrame::Share().
	void CopyFrameInfoFrom(const DesktopFrame& other);

	// Copies various information from `other`. Anything initialized in
	// constructor are not copied. Not like CopyFrameInfoFrom() function, this
	// function uses swap or move constructor to avoid data copy. It won't break
	// the `other`, but some of its information may be missing after this
	// operation. E.g. other->updated_region_;
	// This function is usually used when wrapping a DesktopFrame: the wrapper
	// instance takes the ownership of `other`, so other components cannot access
	// `other` anymore. For example, CroppedDesktopFrame and
	// DesktopFrameWithCursor.
	void MoveFrameInfoFrom(DesktopFrame* other);

	// Set and get the ICC profile of the frame data pixels. Useful to build the
	// a ColorSpace object from clients of webrtc library like chromium. The
	// format of an ICC profile is defined in the following specification
	// http://www.color.org/specification/ICC1v43_2010-12.pdf.
	const std::vector<uint8_t>& icc_profile() const { return icc_profile_; }
	void set_icc_profile(const std::vector<uint8_t>& icc_profile) {
	icc_profile_ = icc_profile;
	}

	// Sets all pixel values in the data buffer to zero.
	void SetFrameDataToBlack();

	// Returns true if all pixel values in the data buffer are zero or false
	// otherwise. Also returns false if the frame is empty.
	bool FrameDataIsBlack() const;

	protected:
	// TODO(bugs.webrtc.org/436974448): Remove.
	// Deprecated, use the next constructor.
	DesktopFrame(DesktopSize size,
	int stride,
	uint8_t* data,
	SharedMemory* shared_memory);

	DesktopFrame(DesktopSize size,
	int stride,
	FourCC pixel_format,
	uint8_t* data,
	SharedMemory* shared_memory);

	// Ownership of the buffers is defined by the classes that inherit from this
	// class. They must guarantee that the buffer is not deleted before the frame
	// is deleted.
	uint8_t* const data_;
	SharedMemory* const shared_memory_;

	private:
	const DesktopSize size_;
	const int stride_;

	// The pixel format for the data stored. Currently, only 4 byte per pixel
	// formats are supported.
	const FourCC pixel_format_;

	DesktopRegion updated_region_;
	DesktopVector top_left_;
	DesktopVector dpi_;
	bool may_contain_cursor_ = false;
	int64_t capture_time_ms_;
	uint32_t capturer_id_;
	std::vector<uint8_t> icc_profile_;
	// Currently only used on Windows. It stores the device scale factor of the
	// captured surface and has distinct values possible in the range of
	// [1,5].
	std::optional<float> device_scale_factor_;
	};

	// A DesktopFrame that stores data in the heap.
	class RTC_EXPORT BasicDesktopFrame : public DesktopFrame {
	public:
	// TODO(bugs.webrtc.org/436974448): Remove.
	// Deprecated, use the last constructor.
	explicit BasicDesktopFrame(DesktopSize size);

	// The entire data buffer used for the frame is initialized with zeros.
	BasicDesktopFrame(DesktopSize size, FourCC pixel_format);

	~BasicDesktopFrame() override;

	BasicDesktopFrame(const BasicDesktopFrame&) = delete;
	BasicDesktopFrame& operator=(const BasicDesktopFrame&) = delete;

	// Creates a BasicDesktopFrame that contains copy of `frame`.
	// TODO(zijiehe): Return std::unique_ptr<DesktopFrame>
	static DesktopFrame* CopyOf(const DesktopFrame& frame);
	};

	// A DesktopFrame that stores data in shared memory.
	class RTC_EXPORT SharedMemoryDesktopFrame : public DesktopFrame {
	public:
	// May return nullptr if `shared_memory_factory` failed to create a
	// SharedMemory instance.
	// `shared_memory_factory` should not be nullptr.
	static std::unique_ptr<DesktopFrame> Create(
	DesktopSize size,
	FourCC pixel_format,
	SharedMemoryFactory* shared_memory_factory);

	// TODO(bugs.webrtc.org/436974448): Remove.
	// Deprecated, use the last constructor.
	SharedMemoryDesktopFrame(DesktopSize size,
	int stride,
	std::unique_ptr<SharedMemory> shared_memory);

	// Takes ownership of `shared_memory`.
	// Deprecated, use the last constructor.
	SharedMemoryDesktopFrame(DesktopSize size,
	int stride,
	FourCC pixel_format,
	SharedMemory* shared_memory);

	// Preferred.
	SharedMemoryDesktopFrame(DesktopSize size,
	int stride,
	FourCC pixel_format,
	std::unique_ptr<SharedMemory> shared_memory);

	~SharedMemoryDesktopFrame() override;

	SharedMemoryDesktopFrame(const SharedMemoryDesktopFrame&) = delete;
	SharedMemoryDesktopFrame& operator=(const SharedMemoryDesktopFrame&) = delete;

	private:
	// Avoid unexpected order of parameter evaluation.
	// Executing both std::unique_ptr<T>::operator->() and
	// std::unique_ptr<T>::release() in the member initializer list is not safe.
	// Depends on the order of parameter evaluation,
	// std::unique_ptr<T>::operator->() may trigger assertion failure if it has
	// been evaluated after std::unique_ptr<T>::release(). By using this
	// constructor, std::unique_ptr<T>::operator->() won't be involved anymore.
	SharedMemoryDesktopFrame(DesktopRect rect,
	int stride,
	FourCC pixel_format,
	SharedMemory* shared_memory);
	};

	} // namespace webrtc

	#endif // MODULES_DESKTOP_CAPTURE_DESKTOP_FRAME_H_