Flutter Impeller
filter_input.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter 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 
5 #ifndef FLUTTER_IMPELLER_ENTITY_CONTENTS_FILTERS_INPUTS_FILTER_INPUT_H_
6 #define FLUTTER_IMPELLER_ENTITY_CONTENTS_FILTERS_INPUTS_FILTER_INPUT_H_
7 
8 #include <memory>
9 #include <optional>
10 #include <variant>
11 #include <vector>
12 
14 #include "impeller/entity/entity.h"
15 #include "impeller/geometry/rect.h"
16 
17 namespace impeller {
18 
19 class ContentContext;
20 class FilterContents;
21 
22 /// `FilterInput` is a lazy/single eval `Snapshot` which may be shared across
23 /// filter parameters and used to evaluate input coverage.
24 ///
25 /// A `FilterInput` can be re-used for any filter inputs across an entity's
26 /// filter graph without repeating subpasses unnecessarily.
27 ///
28 /// Filters may decide to not evaluate inputs in situations where they won't
29 /// contribute to the filter's output texture.
30 class FilterInput {
31  public:
32  using Ref = std::shared_ptr<FilterInput>;
33  using Vector = std::vector<FilterInput::Ref>;
34  using Variant = std::variant<std::shared_ptr<FilterContents>,
35  std::shared_ptr<Contents>,
36  std::shared_ptr<Texture>,
37  Rect>;
38 
39  virtual ~FilterInput();
40 
41  static FilterInput::Ref Make(Variant input, bool msaa_enabled = true);
42 
43  static FilterInput::Ref Make(std::shared_ptr<Texture> input,
44  Matrix local_transform);
45 
46  static FilterInput::Vector Make(std::initializer_list<Variant> inputs);
47 
48  /// Evaluates the filter input and returns a snapshot of the result.
49  ///
50  /// This method renders the input (which could be another filter, contents,
51  /// or a texture) into a `Snapshot` object, which contains the resulting
52  /// texture and its transform relative to the current render target.
53  ///
54  /// Implementations are typically lazy and may cache the result, ensuring
55  /// that the input is only rendered once even if `GetSnapshot` is called
56  /// multiple times.
57  ///
58  /// @param[in] label A debug label for the rendering operation and the
59  /// resulting snapshot texture.
60  /// @param[in] renderer The content context providing rendering resources.
61  /// @param[in] entity The entity associated with this filter input, providing
62  /// transform and other contextual information.
63  /// @param[in] coverage_limit An optional rectangle to limit the area of the
64  /// input that needs to be rendered. This can be used as an optimization.
65  /// @param[in] mip_count The number of mip levels to generate for the snapshot
66  /// texture. Defaults to 1 (no mips).
67  ///
68  /// @return A `Snapshot` containing the rendered texture and its transform, or
69  /// `std::nullopt` if the input cannot be rendered or results in an empty
70  /// output.
71  virtual std::optional<Snapshot> GetSnapshot(
72  std::string_view label,
73  const ContentContext& renderer,
74  const Entity& entity,
75  std::optional<Rect> coverage_limit = std::nullopt,
76  int32_t mip_count = 1) const = 0;
77 
78  std::optional<Rect> GetLocalCoverage(const Entity& entity) const;
79 
80  virtual std::optional<Rect> GetCoverage(const Entity& entity) const = 0;
81 
82  virtual std::optional<Rect> GetSourceCoverage(const Matrix& effect_transform,
83  const Rect& output_limit) const;
84 
85  /// @brief Get the local transform of this filter input. This transform is
86  /// relative to the `Entity` transform space.
87  virtual Matrix GetLocalTransform(const Entity& entity) const;
88 
89  /// @brief Get the transform of this `FilterInput`. This is equivalent to
90  /// calling `entity.GetTransform() * GetLocalTransform()`.
91  virtual Matrix GetTransform(const Entity& entity) const;
92 
93  /// @brief Sets the effect transform of filter inputs.
94  virtual void SetEffectTransform(const Matrix& matrix);
95 
96  /// @brief Turns on subpass mode for filter inputs.
97  virtual void SetRenderingMode(Entity::RenderingMode rendering_mode);
98 };
99 
100 } // namespace impeller
101 
102 #endif // FLUTTER_IMPELLER_ENTITY_CONTENTS_FILTERS_INPUTS_FILTER_INPUT_H_
virtual std::optional< Rect > GetSourceCoverage(const Matrix &effect_transform, const Rect &output_limit) const
Definition: filter_input.cc:69
virtual void SetEffectTransform(const Matrix &matrix)
Sets the effect transform of filter inputs.
Definition: filter_input.cc:81
std::shared_ptr< FilterInput > Ref
Definition: filter_input.h:32
virtual Matrix GetTransform(const Entity &entity) const
Get the transform of this FilterInput. This is equivalent to calling entity.GetTransform() * GetLocal...
Definition: filter_input.cc:75
std::optional< Rect > GetLocalCoverage(const Entity &entity) const
Definition: filter_input.cc:63
std::variant< std::shared_ptr< FilterContents >, std::shared_ptr< Contents >, std::shared_ptr< Texture >, Rect > Variant
Definition: filter_input.h:37
virtual std::optional< Rect > GetCoverage(const Entity &entity) const =0
static FilterInput::Ref Make(Variant input, bool msaa_enabled=true)
Definition: filter_input.cc:19
virtual Matrix GetLocalTransform(const Entity &entity) const
Get the local transform of this filter input. This transform is relative to the Entity transform spac...
Definition: filter_input.cc:59
std::vector< FilterInput::Ref > Vector
Definition: filter_input.h:33
virtual void SetRenderingMode(Entity::RenderingMode rendering_mode)
Turns on subpass mode for filter inputs.
Definition: filter_input.cc:83
virtual std::optional< Snapshot > GetSnapshot(std::string_view label, const ContentContext &renderer, const Entity &entity, std::optional< Rect > coverage_limit=std::nullopt, int32_t mip_count=1) const =0
A 4x4 matrix using column-major storage.
Definition: matrix.h:37