From df5dfdba617a58aa228cd3a8e2d08133b86a3ad7 Mon Sep 17 00:00:00 2001 From: gaaclarke <30870216+gaaclarke@users.noreply.github.com> Date: Thu, 17 Apr 2025 14:38:52 -0700 Subject: [PATCH] adds Entity docstrings (#167228) fixes https://github.com/flutter/flutter/issues/144943 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md --- engine/src/flutter/impeller/entity/entity.h | 61 ++++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/engine/src/flutter/impeller/entity/entity.h b/engine/src/flutter/impeller/entity/entity.h index 1d8cd80e8c7..2952554b1ec 100644 --- a/engine/src/flutter/impeller/entity/entity.h +++ b/engine/src/flutter/impeller/entity/entity.h @@ -17,6 +17,12 @@ namespace impeller { class Renderer; class RenderPass; +/// Represents a renderable object within the Impeller scene. +/// +/// An Entity combines graphical content (`Contents`) with properties +/// like transformation (`Matrix`), blend mode (`BlendMode`), and stencil +/// clip depth. It serves as the primary unit for constructing and rendering +/// scenes. Entities can be created directly or from `Snapshot` objects. class Entity { public: static constexpr BlendMode kLastPipelineBlendMode = BlendMode::kModulate; @@ -78,7 +84,14 @@ class Entity { /// @brief Get the global transform matrix for this Entity. const Matrix& GetTransform() const; - /// @brief Get the vertex shader transform used for drawing this Entity. + /// Calculates the final transformation matrix for rendering in a shader. + /// + /// This combines the entity's transform with the render pass's orthographic + /// projection and applies the necessary adjustments based on the entity's + /// shader clip depth. + /// + /// @param[in] pass The current render pass. + /// @return The combined model-view-projection matrix for the shader. Matrix GetShaderTransform(const RenderPass& pass) const; /// @brief Static utility that computes the vertex shader transform used for @@ -90,18 +103,56 @@ class Entity { /// @brief Set the global transform matrix for this Entity. void SetTransform(const Matrix& transform); + /// Calculates the axis-aligned bounding box covering this entity after its + /// transformation is applied. + /// @return The coverage rectangle in the parent coordinate space, or + /// `std::nullopt` if the entity has no contents. std::optional GetCoverage() const; void SetContents(std::shared_ptr contents); const std::shared_ptr& GetContents() const; + /// Sets the stencil clip depth for this entity. + /// + /// The clip depth determines the entity's level within a stack of stencil + /// clips. Higher values indicate the entity is nested deeper within clips. + /// This value is used during rendering to configure stencil buffer + /// operations. + /// + /// @param[in] clip_depth The integer clip depth level. void SetClipDepth(uint32_t clip_depth); + /// Gets the stencil clip depth level for this entity. + /// + /// @see SetClipDepth(uint32_t) + /// @see GetShaderClipDepth() + /// + /// @return The current integer clip depth level. uint32_t GetClipDepth() const; + /// Gets the shader-compatible depth value based on the entity's current clip + /// depth level (`clip_depth_`). + /// + /// @see GetShaderClipDepth(uint32_t) for details on the conversion logic. + /// + /// @return The floating-point depth value for shaders corresponding to the + /// entity's `clip_depth_`. float GetShaderClipDepth() const; + /// Converts an integer clip depth level into a floating-point depth value + /// suitable for use in shaders. + /// + /// The integer `clip_depth` represents discrete layers used for stencil + /// clipping. This function maps that integer to a depth value within the [0, + /// 1) range for the depth buffer. Each increment in `clip_depth` corresponds + /// to a small step (`kDepthEpsilon`) in the shader depth. + /// + /// The result is clamped to ensure it stays within the valid depth range and + /// slightly below 1.0 to avoid potential issues with the maximum depth value. + /// + /// @param[in] clip_depth The integer clip depth level. + /// @return The corresponding floating-point depth value for shaders. static float GetShaderClipDepth(uint32_t clip_depth); void SetBlendMode(BlendMode blend_mode); @@ -114,6 +165,14 @@ class Entity { bool SetInheritedOpacity(Scalar alpha); + /// Attempts to represent this entity as a solid background color. + /// + /// This is an optimization. If the entity's contents can be represented as a + /// solid color covering the entire target area, this method returns that + /// color. + /// + /// @param[in] target_size The size of the render target. + /// @return The background color if representable, otherwise `std::nullopt`. std::optional AsBackgroundColor(ISize target_size) const; Entity Clone() const;