diff --git a/impeller/entity/contents/filters/filter_contents.h b/impeller/entity/contents/filters/filter_contents.h index f06c17c19364c..544080a6c5489 100644 --- a/impeller/entity/contents/filters/filter_contents.h +++ b/impeller/entity/contents/filters/filter_contents.h @@ -132,17 +132,36 @@ class FilterContents : public Contents { // |Contents| const FilterContents* AsFilter() const override; - /// @brief Determines the coverage of source pixels that will be needed - /// to apply this filter under the given transform and produce - /// results anywhere within the indicated coverage limit. + /// @brief Determines the coverage of source pixels that will be needed + /// to produce results for the specified |output_limit| under the + /// specified |effect_transform|. This is essentially a reverse of + /// the |GetCoverage| method computing a source coverage from + /// an intended |output_limit| coverage. /// - /// This is useful for subpass rendering scenarios where a filter - /// will be applied to the output of the subpass and we need to - /// determine how large of a render target to allocate in order - /// to collect all pixels that might affect the supplied output - /// coverage limit. While we might clip the rendering of the subpass, - /// we want to avoid clipping out any pixels that contribute to - /// the output limit via the filtering operation. + /// Both the |output_limit| and the return value are in the + /// transformed coordinate space, and so do not need to be + /// transformed or inverse transformed by the |effect_transform| + /// but individual parameters on the filter might be in the + /// untransformed space and should be transformed by the + /// |effect_transform| before applying them to the coverages. + /// + /// The method computes a result such that if the filter is applied + /// to a set of pixels filling the computed source coverage, it + /// should produce an output that covers the entire specified + /// |output_limit|. + /// + /// This is useful for subpass rendering scenarios where a filter + /// will be applied to the output of the subpass and we need to + /// determine how large of a render target to allocate in order + /// to collect all pixels that might affect the supplied output + /// coverage limit. While we might end up clipping the rendering + /// of the subpass to its destination, we want to avoid clipping + /// out any pixels that contribute to the output limit via the + /// filtering operation. + /// + /// @return The coverage bounds in the transformed space of any source pixel + /// that may be needed to produce output for the indicated filter + /// that covers the indicated |output_limit|. std::optional GetSourceCoverage(const Matrix& effect_transform, const Rect& output_limit) const; @@ -178,11 +197,18 @@ class FilterContents : public Contents { virtual void SetRenderingMode(Entity::RenderingMode rendering_mode); private: + /// @brief Internal utility method for |GetLocalCoverage| that computes + /// the output coverage of this filter across the specified inputs, + /// ignoring the coverage hint. virtual std::optional GetFilterCoverage( const FilterInput::Vector& inputs, const Entity& entity, const Matrix& effect_transform) const; + /// @brief Internal utility method for |GetSourceCoverage| that computes + /// the inverse effect of this transform on the specified output + /// coverage, ignoring the inputs which will be accommodated by + /// the caller. virtual std::optional GetFilterSourceCoverage( const Matrix& effect_transform, const Rect& output_limit) const = 0; @@ -196,6 +222,11 @@ class FilterContents : public Contents { const Rect& coverage, const std::optional& coverage_hint) const = 0; + /// @brief Internal utility method to compute the coverage of this + /// filter across its internally specified inputs and subject + /// to the coverage hint. + /// + /// Uses |GetFilterCoverage|. std::optional GetLocalCoverage(const Entity& local_entity) const; FilterInput::Vector inputs_;