Updated docstrings for TextureContents (#167221)
fixes https://github.com/flutter/flutter/issues/139527
## 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].
<!-- Links -->
[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
diff --git a/engine/src/flutter/impeller/entity/contents/texture_contents.h b/engine/src/flutter/impeller/entity/contents/texture_contents.h
index f57f531..9b540e1 100644
--- a/engine/src/flutter/impeller/entity/contents/texture_contents.h
+++ b/engine/src/flutter/impeller/entity/contents/texture_contents.h
@@ -14,19 +14,47 @@
class Texture;
+/// Represents the contents of a texture to be rendered.
+///
+/// This class encapsulates a texture along with parameters defining how it
+/// should be drawn, such as the source rectangle within the texture, the
+/// destination rectangle on the render target, opacity, and sampler settings.
+/// It's used by the rendering system to draw textured quads.
+///
+/// @see `TiledTextureContents` for a tiled version.
class TextureContents final : public Contents {
public:
TextureContents();
~TextureContents() override;
- /// @brief A common case factory that marks the texture contents as having a
- /// destination rectangle. In this situation, a subpass can be avoided
- /// when image filters are applied.
+ /// A common case factory that marks the texture contents as having a
+ /// destination rectangle.
+ ///
+ /// In this situation, a subpass can be avoided when image filters are
+ /// applied.
+ ///
+ /// @param destination The destination rectangle in the Entity's local
+ /// coordinate space.
static std::shared_ptr<TextureContents> MakeRect(Rect destination);
+ /// Sets a debug label for this contents object.
+ ///
+ /// This label is used for debugging purposes, for example, in graphics
+ /// debuggers or logs.
+ ///
+ /// @param label The debug label string.
void SetLabel(std::string_view label);
+ /// Sets the destination rectangle within the current render target
+ /// where the texture will be drawn.
+ ///
+ /// The texture, potentially clipped by the `source_rect_`, will be mapped to
+ /// this rectangle. The coordinates are in the local coordinate space of the
+ /// Entity.
+ ///
+ /// @param rect The destination rectangle in the Entity's local coordinate
+ /// space.
void SetDestinationRect(Rect rect);
void SetTexture(std::shared_ptr<Texture> texture);
@@ -37,10 +65,25 @@
const SamplerDescriptor& GetSamplerDescriptor() const;
+ /// Sets the source rectangle within the texture to sample from.
+ ///
+ /// This rectangle defines the portion of the texture that will be mapped to
+ /// the `destination_rect_`. The coordinates are in the coordinate space of
+ /// the texture (texels), with the top-left corner being (0, 0).
+ ///
+ /// @param source_rect The rectangle defining the area of the texture to use.
void SetSourceRect(const Rect& source_rect);
const Rect& GetSourceRect() const;
+ /// Sets whether strict source rect sampling should be used.
+ ///
+ /// When enabled, the texture coordinates are adjusted slightly (typically by
+ /// half a texel) to ensure that linear filtering does not sample pixels
+ /// outside the specified `source_rect_`. This is useful for preventing
+ /// edge artifacts when rendering sub-sections of a texture atlas.
+ ///
+ /// @param strict True to enable strict source rect sampling, false otherwise.
void SetStrictSourceRect(bool strict);
bool GetStrictSourceRect() const;
@@ -72,6 +115,18 @@
// |Contents|
void SetInheritedOpacity(Scalar opacity) override;
+ /// Sets whether applying the opacity should be deferred.
+ ///
+ /// When true, the opacity value (`GetOpacity()`) might not be applied
+ /// directly during rendering operations like `RenderToSnapshot`. Instead, the
+ /// opacity might be stored in the resulting `Snapshot` to be applied later
+ /// when the snapshot is drawn. This is typically used as an optimization when
+ /// the texture covers its destination rectangle completely and has near-full
+ /// opacity, allowing the original texture to be used directly in the
+ /// snapshot.
+ ///
+ /// @param defer_applying_opacity True to defer applying opacity, false to
+ /// apply it during rendering.
void SetDeferApplyingOpacity(bool defer_applying_opacity);
private:
