copy_output_request.h 8.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183
  1. // Copyright 2013 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef COMPONENTS_VIZ_COMMON_FRAME_SINKS_COPY_OUTPUT_REQUEST_H_
  5. #define COMPONENTS_VIZ_COMMON_FRAME_SINKS_COPY_OUTPUT_REQUEST_H_
  6. #include <memory>
  7. #include <string>
  8. #include <utility>
  9. #include "base/callback.h"
  10. #include "base/task/sequenced_task_runner.h"
  11. #include "base/unguessable_token.h"
  12. #include "components/viz/common/frame_sinks/blit_request.h"
  13. #include "components/viz/common/frame_sinks/copy_output_result.h"
  14. #include "components/viz/common/viz_common_export.h"
  15. #include "gpu/command_buffer/common/mailbox.h"
  16. #include "gpu/command_buffer/common/sync_token.h"
  17. #include "mojo/public/cpp/bindings/struct_traits.h"
  18. #include "third_party/abseil-cpp/absl/types/optional.h"
  19. #include "ui/gfx/geometry/rect.h"
  20. #include "ui/gfx/geometry/vector2d.h"
  21. namespace viz {
  22. namespace mojom {
  23. class CopyOutputRequestDataView;
  24. }
  25. // Holds all the properties pertaining to a copy of a surface or layer.
  26. // Implementations that execute these requests must provide the requested
  27. // ResultFormat or else an "empty" result. Likewise, this means that any
  28. // transient or permanent errors preventing the successful execution of a
  29. // copy request will result in an "empty" result.
  30. //
  31. // Usage: Client code creates a CopyOutputRequest, optionally sets some/all of
  32. // its properties, and then submits it to the compositing pipeline via one of a
  33. // number of possible entry points (usually methods named RequestCopyOfOutput()
  34. // or RequestCopyOfSurface()). Then, some time later, the given result callback
  35. // will be run and the client processes the CopyOutputResult containing the
  36. // image.
  37. //
  38. // Note: This should be used for one-off screen capture only, and NOT for video
  39. // screen capture use cases (please use FrameSinkVideoCapturer instead).
  40. class VIZ_COMMON_EXPORT CopyOutputRequest {
  41. public:
  42. using ResultFormat = CopyOutputResult::Format;
  43. // Specifies intended destination for the results. For software compositing,
  44. // only the system-memory results are supported - even if the
  45. // CopyOutputRequest is issued with ResultDestination::kNativeTextures, the
  46. // results will still be returned via ResultDestination::kSystemMemory.
  47. using ResultDestination = CopyOutputResult::Destination;
  48. using CopyOutputRequestCallback =
  49. base::OnceCallback<void(std::unique_ptr<CopyOutputResult> result)>;
  50. // Creates new CopyOutputRequest. I420_PLANES format returned via
  51. // kNativeTextures is currently not supported.
  52. CopyOutputRequest(ResultFormat result_format,
  53. ResultDestination result_destination,
  54. CopyOutputRequestCallback result_callback);
  55. CopyOutputRequest(const CopyOutputRequest&) = delete;
  56. CopyOutputRequest& operator=(const CopyOutputRequest&) = delete;
  57. virtual ~CopyOutputRequest();
  58. // Returns the requested result format.
  59. ResultFormat result_format() const { return result_format_; }
  60. // Returns the requested result destination.
  61. ResultDestination result_destination() const { return result_destination_; }
  62. // Requests that the result callback be run as a task posted to the given
  63. // |task_runner|. If this is not set, the result callback could be run from
  64. // any context.
  65. void set_result_task_runner(
  66. scoped_refptr<base::SequencedTaskRunner> task_runner) {
  67. result_task_runner_ = std::move(task_runner);
  68. }
  69. bool has_result_task_runner() const { return !!result_task_runner_; }
  70. // Optionally specify that the result should be scaled. |scale_from| and
  71. // |scale_to| describe the scale ratio in terms of relative sizes: Downscale
  72. // if |scale_from| > |scale_to|, upscale if |scale_from| < |scale_to|, and
  73. // no scaling if |scale_from| == |scale_to|. Neither argument may be zero.
  74. //
  75. // There are two setters: SetScaleRatio() allows for requesting an arbitrary
  76. // scale in each dimension, which is sometimes useful for minor "tweaks" that
  77. // optimize visual quality. SetUniformScaleRatio() scales both dimensions by
  78. // the same amount.
  79. void SetScaleRatio(const gfx::Vector2d& scale_from,
  80. const gfx::Vector2d& scale_to);
  81. void SetUniformScaleRatio(int scale_from, int scale_to);
  82. const gfx::Vector2d& scale_from() const { return scale_from_; }
  83. const gfx::Vector2d& scale_to() const { return scale_to_; }
  84. bool is_scaled() const { return scale_from_ != scale_to_; }
  85. // Optionally specify the source of this copy request. This is used when the
  86. // client plans to make many similar copy requests over short periods of time.
  87. // It is used to: 1) auto-abort prior uncommitted copy requests to avoid
  88. // duplicate copies of the same frame; and 2) hint to the implementation to
  89. // cache resources for more-efficient execution of later copy requests.
  90. void set_source(const base::UnguessableToken& source) { source_ = source; }
  91. bool has_source() const { return source_.has_value(); }
  92. const base::UnguessableToken& source() const { return *source_; }
  93. // Optionally specify the clip rect; meaning that just a portion of the entire
  94. // surface (or layer's subtree output) should be scanned to produce a result.
  95. // This rect is in the same space as the RenderPass output rect, pre-scaling.
  96. // This is related to set_result_selection() (see below).
  97. void set_area(const gfx::Rect& area) { area_ = area; }
  98. bool has_area() const { return area_.has_value(); }
  99. const gfx::Rect& area() const { return *area_; }
  100. // Optionally specify that only a portion of the result be generated. The
  101. // selection rect will be clamped to the result bounds, which always starts at
  102. // 0,0 and spans the post-scaling size of the copy area (see set_area()
  103. // above). Only RGBA format supports odd-sized result selection. Can only be
  104. // called before blit request was set on the copy request.
  105. void set_result_selection(const gfx::Rect& selection) {
  106. DCHECK(result_format_ == ResultFormat::RGBA ||
  107. (selection.width() % 2 == 0 && selection.height() % 2 == 0))
  108. << "CopyOutputRequest supports odd-sized result_selection() only for "
  109. "RGBA!";
  110. DCHECK(!has_blit_request());
  111. result_selection_ = selection;
  112. }
  113. bool has_result_selection() const { return result_selection_.has_value(); }
  114. const gfx::Rect& result_selection() const { return *result_selection_; }
  115. // Requests that the region copied by the CopyOutputRequest be blitted into
  116. // the caller's textures. Can be called only for CopyOutputRequests that
  117. // target native textures. Requires that result selection was set, in which
  118. // case the caller's textures will be populated with the results of the
  119. // copy request. The region in the caller's textures that will be populated
  120. // is specified by `gfx::Rect(blit_request.destination_region_offset(),
  121. // result_selection().size())`. If blit request is configured to perform
  122. // letterboxing, all contents outside of that region will be overwritten with
  123. // black, otherwise they will be unchanged. If the copy request's result would
  124. // be smaller than `result_selection().size()`, the request will fail (i.e.
  125. // empty result will be sent).
  126. void set_blit_request(BlitRequest blit_request);
  127. bool has_blit_request() const { return blit_request_.has_value(); }
  128. const BlitRequest& blit_request() const { return *blit_request_; }
  129. // Sends the result from executing this request. Called by the internal
  130. // implementation, usually a DirectRenderer.
  131. void SendResult(std::unique_ptr<CopyOutputResult> result);
  132. // Returns true if SendResult() will deliver the CopyOutputResult using the
  133. // same TaskRunner as that to which the current task was posted.
  134. bool SendsResultsInCurrentSequence() const;
  135. // Creates a RGBA request with ResultDestination::kSystemMemory that ignores
  136. // results, for testing purposes.
  137. static std::unique_ptr<CopyOutputRequest> CreateStubForTesting();
  138. std::string ToString() const;
  139. private:
  140. // Note: The StructTraits may "steal" the |result_callback_|, to allow it to
  141. // outlive this CopyOutputRequest (and wait for the result from another
  142. // process).
  143. friend struct mojo::StructTraits<mojom::CopyOutputRequestDataView,
  144. std::unique_ptr<CopyOutputRequest>>;
  145. const ResultFormat result_format_;
  146. const ResultDestination result_destination_;
  147. CopyOutputRequestCallback result_callback_;
  148. scoped_refptr<base::SequencedTaskRunner> result_task_runner_;
  149. gfx::Vector2d scale_from_;
  150. gfx::Vector2d scale_to_;
  151. absl::optional<base::UnguessableToken> source_;
  152. absl::optional<gfx::Rect> area_;
  153. absl::optional<gfx::Rect> result_selection_;
  154. absl::optional<BlitRequest> blit_request_;
  155. };
  156. } // namespace viz
  157. #endif // COMPONENTS_VIZ_COMMON_FRAME_SINKS_COPY_OUTPUT_REQUEST_H_