| Flutter Impeller |

texture_contents.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_TEXTURE_CONTENTS_H_
6 #define FLUTTER_IMPELLER_ENTITY_CONTENTS_TEXTURE_CONTENTS_H_
7
8 #include <memory>
9
10 #include "impeller/core/sampler_descriptor.h"
11 #include "impeller/entity/contents/contents.h"
12
13 namespace impeller {
14
15 class Texture;
16
17 /// Represents the contents of a texture to be rendered.
18 ///
19 /// This class encapsulates a texture along with parameters defining how it
20 /// should be drawn, such as the source rectangle within the texture, the
21 /// destination rectangle on the render target, opacity, and sampler settings.
22 /// It's used by the rendering system to draw textured quads.
23 ///
24 /// @see `TiledTextureContents` for a tiled version.
25 class TextureContents final : public Contents {
26 public:
27 TextureContents();
28
29 ~TextureContents() override;
30
31 /// A common case factory that marks the texture contents as having a
32 /// destination rectangle.
33 ///
34 /// In this situation, a subpass can be avoided when image filters are
35 /// applied.
36 ///
37 /// @param destination The destination rectangle in the Entity's local
38 /// coordinate space.
39 static std::shared_ptr<TextureContents> MakeRect(Rect destination);
40
41 /// Sets a debug label for this contents object.
42 ///
43 /// This label is used for debugging purposes, for example, in graphics
44 /// debuggers or logs.
45 ///
46 /// @param label The debug label string.
47 void SetLabel(std::string_view label);
48
49 /// Sets the destination rectangle within the current render target
50 /// where the texture will be drawn.
51 ///
52 /// The texture, potentially clipped by the `source_rect_`, will be mapped to
53 /// this rectangle. The coordinates are in the local coordinate space of the
54 /// Entity.
55 ///
56 /// @param rect The destination rectangle in the Entity's local coordinate
57 /// space.
58 void SetDestinationRect(Rect rect);
59
60 void SetTexture(std::shared_ptr<Texture> texture);
61
62 std::shared_ptr<Texture> GetTexture() const;
63
64 void SetSamplerDescriptor(const SamplerDescriptor& desc);
65
66 const SamplerDescriptor& GetSamplerDescriptor() const;
67
68 /// Sets the source rectangle within the texture to sample from.
69 ///
70 /// This rectangle defines the portion of the texture that will be mapped to
71 /// the `destination_rect_`. The coordinates are in the coordinate space of
72 /// the texture (texels), with the top-left corner being (0, 0).
73 ///
74 /// @param source_rect The rectangle defining the area of the texture to use.
75 void SetSourceRect(const Rect& source_rect);
76
77 const Rect& GetSourceRect() const;
78
79 /// Sets whether strict source rect sampling should be used.
80 ///
81 /// When enabled, the texture coordinates are adjusted slightly (typically by
82 /// half a texel) to ensure that linear filtering does not sample pixels
83 /// outside the specified `source_rect_`. This is useful for preventing
84 /// edge artifacts when rendering sub-sections of a texture atlas.
85 ///
86 /// @param strict True to enable strict source rect sampling, false otherwise.
87 void SetStrictSourceRect(bool strict);
88
89 bool GetStrictSourceRect() const;
90
91 void SetOpacity(Scalar opacity);
92
93 Scalar GetOpacity() const;
94
95 void SetStencilEnabled(bool enabled);
96
97 // |Contents|
98 std::optional<Rect> GetCoverage(const Entity& entity) const override;
99
100 // |Contents|
101 std::optional<Snapshot> RenderToSnapshot(
102 const ContentContext& renderer,
103 const Entity& entity,
104 std::optional<Rect> coverage_limit = std::nullopt,
105 const std::optional<SamplerDescriptor>& sampler_descriptor = std::nullopt,
106 bool msaa_enabled = true,
107 int32_t mip_count = 1,
108 std::string_view label = "Texture Snapshot") const override;
109
110 // |Contents|
111 bool Render(const ContentContext& renderer,
112 const Entity& entity,
113 RenderPass& pass) const override;
114
115 // |Contents|
116 void SetInheritedOpacity(Scalar opacity) override;
117
118 /// Sets whether applying the opacity should be deferred.
119 ///
120 /// When true, the opacity value (`GetOpacity()`) might not be applied
121 /// directly during rendering operations like `RenderToSnapshot`. Instead, the
122 /// opacity might be stored in the resulting `Snapshot` to be applied later
123 /// when the snapshot is drawn. This is typically used as an optimization when
124 /// the texture covers its destination rectangle completely and has near-full
125 /// opacity, allowing the original texture to be used directly in the
126 /// snapshot.
127 ///
128 /// @param defer_applying_opacity True to defer applying opacity, false to
129 /// apply it during rendering.
130 void SetDeferApplyingOpacity(bool defer_applying_opacity);
131
132 private:
133 std::string label_;
134
135 Rect destination_rect_;
136 bool stencil_enabled_ = true;
137
138 std::shared_ptr<Texture> texture_;
139 SamplerDescriptor sampler_descriptor_ = {};
140 Rect source_rect_;
141 bool strict_source_rect_enabled_ = false;
142 Scalar opacity_ = 1.0f;
143 Scalar inherited_opacity_ = 1.0f;
144 bool defer_applying_opacity_ = false;
145
146 TextureContents(const TextureContents&) = delete;
147
148 TextureContents& operator=(const TextureContents&) = delete;
149 };
150
151 } // namespace impeller
152
153 #endif // FLUTTER_IMPELLER_ENTITY_CONTENTS_TEXTURE_CONTENTS_H_
impeller::ContentContext
Definition: content_context.h:138
impeller::Contents
Definition: contents.h:31
impeller::Entity
Definition: entity.h:26
impeller::RenderPass
Render passes encode render commands directed as one specific render target into an underlying comman...
Definition: render_pass.h:30
impeller::TextureContents
Definition: texture_contents.h:25
impeller::TextureContents::GetTexture
std::shared_ptr< Texture > GetTexture() const
Definition: texture_contents.cc:46
impeller::TextureContents::SetSourceRect
void SetSourceRect(const Rect &source_rect)
Definition: texture_contents.cc:231
impeller::TextureContents::Render
bool Render(const ContentContext &renderer, const Entity &entity, RenderPass &pass) const override
Definition: texture_contents.cc:106
impeller::TextureContents::SetSamplerDescriptor
void SetSamplerDescriptor(const SamplerDescriptor &desc)
Definition: texture_contents.cc:247
impeller::TextureContents::GetOpacity
Scalar GetOpacity() const
Definition: texture_contents.cc:62
impeller::TextureContents::SetStrictSourceRect
void SetStrictSourceRect(bool strict)
Definition: texture_contents.cc:239
impeller::TextureContents::SetDeferApplyingOpacity
void SetDeferApplyingOpacity(bool defer_applying_opacity)
Definition: texture_contents.cc:255
impeller::TextureContents::GetSamplerDescriptor
const SamplerDescriptor & GetSamplerDescriptor() const
Definition: texture_contents.cc:251
impeller::TextureContents::SetOpacity
void SetOpacity(Scalar opacity)
Definition: texture_contents.cc:50
impeller::TextureContents::RenderToSnapshot
std::optional< Snapshot > RenderToSnapshot(const ContentContext &renderer, const Entity &entity, std::optional< Rect > coverage_limit=std::nullopt, const std::optional< SamplerDescriptor > &sampler_descriptor=std::nullopt, bool msaa_enabled=true, int32_t mip_count=1, std::string_view label="Texture Snapshot") const override
Render this contents to a snapshot, respecting the entity's transform, path, clip depth,...
Definition: texture_contents.cc:73
impeller::TextureContents::GetStrictSourceRect
bool GetStrictSourceRect() const
Definition: texture_contents.cc:243
impeller::TextureContents::MakeRect
static std::shared_ptr< TextureContents > MakeRect(Rect destination)
Definition: texture_contents.cc:28
impeller::TextureContents::GetSourceRect
const Rect & GetSourceRect() const
Definition: texture_contents.cc:235
impeller::TextureContents::SetInheritedOpacity
void SetInheritedOpacity(Scalar opacity) override
Inherit the provided opacity.
Definition: texture_contents.cc:58
impeller::TextureContents::TextureContents
TextureContents()
impeller::TextureContents::GetCoverage
std::optional< Rect > GetCoverage(const Entity &entity) const override
Get the area of the render pass that will be affected when this contents is rendered.
Definition: texture_contents.cc:66
impeller::TextureContents::SetTexture
void SetTexture(std::shared_ptr< Texture > texture)
Definition: texture_contents.cc:42
impeller::TextureContents::~TextureContents
~TextureContents() override
impeller::TextureContents::SetLabel
void SetLabel(std::string_view label)
Definition: texture_contents.cc:34
impeller::TextureContents::SetStencilEnabled
void SetStencilEnabled(bool enabled)
Definition: texture_contents.cc:54
impeller::TextureContents::SetDestinationRect
void SetDestinationRect(Rect rect)
Definition: texture_contents.cc:38
contents.h
impeller
Definition: allocation.cc:12
impeller::Scalar
float Scalar
Definition: scalar.h:19
sampler_descriptor.h
impeller::SamplerDescriptor
Definition: sampler_descriptor.h:14
impeller::TRect< Scalar >