| Flutter Impeller |

Public Member Functions | Static Public Member Functions | List of all members
impeller::TextureContents Class Referencefinal

`#include <texture_contents.h>`

Inheritance diagram for impeller::TextureContents:

## Public Member Functions
| TextureContents ()
| ~TextureContents () override
void | SetLabel (std::string_view label)
void | SetDestinationRect (Rect rect)
void | SetTexture (std::shared_ptr< Texture > texture)
std::shared_ptr< Texture > | GetTexture () const
void | SetSamplerDescriptor (const SamplerDescriptor &desc)
const SamplerDescriptor & | GetSamplerDescriptor () const
void | SetSourceRect (const Rect &source_rect)
const Rect & | GetSourceRect () const
void | SetStrictSourceRect (bool strict)
bool | GetStrictSourceRect () const
void | SetOpacity (Scalar opacity)
Scalar | GetOpacity () const
void | SetStencilEnabled (bool enabled)
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. More...
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, and blend mode. The result texture size is always the size of `GetCoverage(entity)`. More...
bool | Render (const ContentContext &renderer, const Entity &entity, RenderPass &pass) const override
void | SetInheritedOpacity (Scalar opacity) override
| Inherit the provided opacity. More...
void | SetDeferApplyingOpacity (bool defer_applying_opacity)
Public Member Functions inherited from impeller::Contents
| Contents ()
virtual | ~Contents ()
void | SetCoverageHint (std::optional< Rect > coverage_hint)
| Hint that specifies the coverage area of this Contents that will actually be used during rendering. This is for optimization purposes only and can not be relied on as a clip. May optionally affect the result of `GetCoverage()`. More...
const std::optional< Rect > & | GetCoverageHint () const
virtual bool | IsOpaque (const Matrix &transform) const
| Whether this Contents only emits opaque source colors from the fragment stage. This value does not account for any entity properties (e.g. the blend mode), clips/visibility culling, or inherited opacity. More...
std::optional< Size > | GetColorSourceSize () const
| Return the color source's intrinsic size, if available. More...
void | SetColorSourceSize (Size size)
virtual std::optional< Color > | AsBackgroundColor (const Entity &entity, ISize target_size) const
| Returns a color if this Contents will flood the given `target_size` with a color. This output color is the "Source" color that will be used for the Entity's blend operation. More...
virtual bool | ApplyColorFilter (const ColorFilterProc &color_filter_proc)
| If possible, applies a color filter to this contents inputs on the CPU. More...

## Static Public Member Functions
static std::shared_ptr< TextureContents > | MakeRect (Rect destination)
Static Public Member Functions inherited from impeller::Contents
static std::shared_ptr< Contents > | MakeAnonymous (RenderProc render_proc, CoverageProc coverage_proc)

## Additional Inherited Members
Public Types inherited from impeller::Contents
using | ColorFilterProc = std::function< Color(Color)>
using | RenderProc = std::function< bool(const ContentContext &renderer, const Entity &entity, RenderPass &pass)>
using | CoverageProc = std::function< std::optional< Rect >(const Entity &entity)>

## Detailed Description

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 also
  `TiledTextureContents` for a tiled version.

Definition at line 25 of file texture_contents.h.

## Constructor & Destructor Documentation

## ◆ TextureContents()

impeller::TextureContents::TextureContents | ( |  | ) |
| default

## ◆ ~TextureContents()

impeller::TextureContents::~TextureContents | ( |  | ) |
| override default

## Member Function Documentation

## ◆ GetCoverage()

std::optional< Rect > impeller::TextureContents::GetCoverage | ( | const Entity & | entity | ) | const
| override virtual

Get the area of the render pass that will be affected when this contents is rendered.

During rendering, coverage coordinates count pixels from the top left corner of the framebuffer.

Returns
  The coverage rectangle. An `std::nullopt` result means that rendering this contents has no effect on the output color.

Implements impeller::Contents.

Definition at line 66 of file texture_contents.cc.

66 {
67 if (GetOpacity() == 0) {
68 return std::nullopt;
69 }
70 return destination_rect_.TransformBounds(entity.GetTransform());
71 };
impeller::TextureContents::GetOpacity
Scalar GetOpacity() const
Definition: texture_contents.cc:62
impeller::TRect::TransformBounds
constexpr TRect TransformBounds(const Matrix &transform) const
Creates a new bounding box that contains this transformed rectangle.
Definition: rect.h:472

References GetOpacity(), impeller::Entity::GetTransform(), and impeller::TRect< T >::TransformBounds().

## ◆ GetOpacity()

Scalar impeller::TextureContents::GetOpacity | ( |  | ) | const

Definition at line 62 of file texture_contents.cc.

62 {
63 return opacity_ * inherited_opacity_;
64 }

Referenced by GetCoverage(), Render(), and RenderToSnapshot().

## ◆ GetSamplerDescriptor()

const SamplerDescriptor & impeller::TextureContents::GetSamplerDescriptor | ( |  | ) | const

Definition at line 251 of file texture_contents.cc.

251 {
252 return sampler_descriptor_;
253 }

## ◆ GetSourceRect()

const Rect & impeller::TextureContents::GetSourceRect | ( |  | ) | const

Definition at line 235 of file texture_contents.cc.

235 {
236 return source_rect_;
237 }

## ◆ GetStrictSourceRect()

bool impeller::TextureContents::GetStrictSourceRect | ( |  | ) | const

Definition at line 243 of file texture_contents.cc.

243 {
244 return strict_source_rect_enabled_;
245 }

## ◆ GetTexture()

std::shared_ptr< Texture > impeller::TextureContents::GetTexture | ( |  | ) | const

Definition at line 46 of file texture_contents.cc.

46 {
47 return texture_;
48 }

## ◆ MakeRect()

std::shared_ptr< TextureContents > impeller::TextureContents::MakeRect | ( | Rect | destination | ) |
| static

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.

Parameters

  destination | The destination rectangle in the Entity's local coordinate space.

Definition at line 28 of file texture_contents.cc.

28 {
29 auto contents = std::make_shared<TextureContents>();
30 contents->destination_rect_ = destination;
31 return contents;
32 }

Referenced by impeller::Canvas::DrawImageRect(), impeller::Entity::FromSnapshot(), impeller::Canvas::SaveLayer(), and impeller::testing::TEST_P().

## ◆ Render()

bool impeller::TextureContents::Render | ( | const ContentContext & | renderer,
|  | const Entity & | entity,
|  | RenderPass & | pass
| ) |  | const
| override virtual

Implements impeller::Contents.

Definition at line 106 of file texture_contents.cc.

108 {
109 using VS = TextureFillVertexShader;
110 using FS = TextureFillFragmentShader;
111 using FSStrict = TextureFillStrictSrcFragmentShader;
112
113 if (destination_rect_.IsEmpty() || source_rect_.IsEmpty() ||
114 texture_ == nullptr || texture_->GetSize().IsEmpty()) {
115 return true; // Nothing to render.
116 }
117
118 #ifdef IMPELLER_ENABLE_OPENGLES
119 using FSExternal = TiledTextureFillExternalFragmentShader;
120 bool is_external_texture =
121 texture_->GetTextureDescriptor().type == TextureType::kTextureExternalOES;
122 #endif // IMPELLER_ENABLE_OPENGLES
123
124 auto texture_coords =
125 Rect::MakeSize(texture_->GetSize()).Project(source_rect_);
126 auto& data_host_buffer = renderer.GetTransientsDataBuffer();
127
128 std::array<VS::PerVertexData, 4> vertices = {
129 VS::PerVertexData{destination_rect_.GetLeftTop(),
130 texture_coords.GetLeftTop()},
131 VS::PerVertexData{destination_rect_.GetRightTop(),
132 texture_coords.GetRightTop()},
133 VS::PerVertexData{destination_rect_.GetLeftBottom(),
134 texture_coords.GetLeftBottom()},
135 VS::PerVertexData{destination_rect_.GetRightBottom(),
136 texture_coords.GetRightBottom()},
137 };
138 auto vertex_buffer = CreateVertexBuffer(vertices, data_host_buffer);
139
140 VS::FrameInfo frame_info;
141 frame_info.mvp = entity.GetShaderTransform(pass);
142 frame_info.texture_sampler_y_coord_scale = texture_->GetYCoordScale();
143
144 #ifdef IMPELLER_DEBUG
145 if (label_.empty()) {
146 pass.SetCommandLabel("Texture Fill");
147 } else {
148 pass.SetCommandLabel("Texture Fill: " + label_);
149 }
150 #endif // IMPELLER_DEBUG
151
152 auto pipeline_options = OptionsFromPassAndEntity(pass, entity);
153 if (!stencil_enabled_) {
154 pipeline_options.stencil_mode = ContentContextOptions::StencilMode::kIgnore;
155 }
156 pipeline_options.primitive_type = PrimitiveType::kTriangleStrip;
157
158 pipeline_options.depth_write_enabled =
159 stencil_enabled_ && pipeline_options.blend_mode == BlendMode::kSrc;
160
161 #ifdef IMPELLER_ENABLE_OPENGLES
162 if (is_external_texture) {
163 pass.SetPipeline(
164 renderer.GetTiledTextureExternalPipeline(pipeline_options));
165 } else {
166 pass.SetPipeline(
167 strict_source_rect_enabled_
168 ? renderer.GetTextureStrictSrcPipeline(pipeline_options)
169 : renderer.GetTexturePipeline(pipeline_options));
170 }
171 #else
172 pass.SetPipeline(strict_source_rect_enabled_
173 ? renderer.GetTextureStrictSrcPipeline(pipeline_options)
174 : renderer.GetTexturePipeline(pipeline_options));
175 #endif // IMPELLER_ENABLE_OPENGLES
176
177 pass.SetVertexBuffer(vertex_buffer);
178 VS::BindFrameInfo(pass, data_host_buffer.EmplaceUniform(frame_info));
179
180 if (strict_source_rect_enabled_) {
181 // For a strict source rect, shrink the texture coordinate range by half a
182 // texel to ensure that linear filtering does not sample anything outside
183 // the source rect bounds.
184 auto strict_texture_coords =
185 Rect::MakeSize(texture_->GetSize()).Project(source_rect_.Expand(-0.5));
186
187 FSStrict::FragInfo frag_info;
188 frag_info.source_rect = Vector4(strict_texture_coords.GetLTRB());
189 frag_info.alpha = GetOpacity();
190 FSStrict::BindFragInfo(pass, data_host_buffer.EmplaceUniform((frag_info)));
191 FSStrict::BindTextureSampler(
192 pass, texture_,
193 renderer.GetContext()->GetSamplerLibrary()->GetSampler(
194 sampler_descriptor_));
195 #ifdef IMPELLER_ENABLE_OPENGLES
196 } else if (is_external_texture) {
197 FSExternal::FragInfo frag_info;
198 frag_info.x_tile_mode =
199 static_cast<Scalar>(sampler_descriptor_.width_address_mode);
200 frag_info.y_tile_mode =
201 static_cast<Scalar>(sampler_descriptor_.height_address_mode);
202 frag_info.alpha = GetOpacity();
203 FSExternal::BindFragInfo(pass, data_host_buffer.EmplaceUniform(frag_info));
204
205 SamplerDescriptor sampler_desc;
206 // OES_EGL_image_external states that only CLAMP_TO_EDGE is valid, so
207 // we emulate all other tile modes here by remapping the texture
208 // coordinates.
209 sampler_desc.width_address_mode = SamplerAddressMode::kClampToEdge;
210 sampler_desc.height_address_mode = SamplerAddressMode::kClampToEdge;
211 sampler_desc.min_filter = sampler_descriptor_.min_filter;
212 sampler_desc.mag_filter = sampler_descriptor_.mag_filter;
213 sampler_desc.mip_filter = MipFilter::kBase;
214
215 FSExternal::BindSAMPLEREXTERNALOESTextureSampler(
216 pass, texture_,
217 renderer.GetContext()->GetSamplerLibrary()->GetSampler(sampler_desc));
218 #endif // IMPELLER_ENABLE_OPENGLES
219 } else {
220 FS::FragInfo frag_info;
221 frag_info.alpha = GetOpacity();
222 FS::BindFragInfo(pass, data_host_buffer.EmplaceUniform((frag_info)));
223 FS::BindTextureSampler(
224 pass, texture_,
225 renderer.GetContext()->GetSamplerLibrary()->GetSampler(
226 sampler_descriptor_));
227 }
228 return pass.Draw().ok();
229 }
impeller::PrimitiveType::kTriangleStrip
@ kTriangleStrip
impeller::Scalar
float Scalar
Definition: scalar.h:19
impeller::SamplerAddressMode::kClampToEdge
@ kClampToEdge
impeller::FS
LinePipeline::FragmentShader FS
Definition: line_contents.cc:14
impeller::CreateVertexBuffer
VertexBuffer CreateVertexBuffer(std::array< VertexType, size > input, HostBuffer &data_host_buffer)
Create an index-less vertex buffer from a fixed size array.
Definition: vertex_buffer_builder.h:24
impeller::MipFilter::kBase
@ kBase
The texture is sampled as if it only had a single mipmap level.
impeller::TextureType::kTextureExternalOES
@ kTextureExternalOES
impeller::BlendMode::kSrc
@ kSrc
impeller::VS
LinePipeline::VertexShader VS
Definition: line_contents.cc:13
impeller::OptionsFromPassAndEntity
ContentContextOptions OptionsFromPassAndEntity(const RenderPass &pass, const Entity &entity)
Definition: contents.cc:34
impeller::ContentContextOptions::StencilMode::kIgnore
@ kIgnore
impeller::SamplerDescriptor::width_address_mode
SamplerAddressMode width_address_mode
Definition: sampler_descriptor.h:19
impeller::SamplerDescriptor::height_address_mode
SamplerAddressMode height_address_mode
Definition: sampler_descriptor.h:20
impeller::SamplerDescriptor::mag_filter
MinMagFilter mag_filter
Definition: sampler_descriptor.h:16
impeller::SamplerDescriptor::min_filter
MinMagFilter min_filter
Definition: sampler_descriptor.h:15
impeller::TRect::Expand
constexpr TRect< T > Expand(T left, T top, T right, T bottom) const
Returns a rectangle with expanded edges. Negative expansion results in shrinking.
Definition: rect.h:618
impeller::TRect::Project
constexpr TRect< T > Project(TRect< T > source) const
Returns a new rectangle that represents the projection of the source rectangle onto this rectangle....
Definition: rect.h:669
impeller::TRect::IsEmpty
constexpr bool IsEmpty() const
Returns true if either of the width or height are 0, negative, or NaN.
Definition: rect.h:297
impeller::TRect::GetLeftBottom
constexpr TPoint< T > GetLeftBottom() const
Definition: rect.h:367
impeller::TRect::GetRightTop
constexpr TPoint< T > GetRightTop() const
Definition: rect.h:363
impeller::TRect< Scalar >::MakeSize
constexpr static TRect MakeSize(const TSize< U > &size)
Definition: rect.h:150
impeller::TRect::GetRightBottom
constexpr TPoint< T > GetRightBottom() const
Definition: rect.h:371
impeller::TRect::GetLeftTop
constexpr TPoint< T > GetLeftTop() const
Definition: rect.h:359

References impeller::CreateVertexBuffer(), impeller::RenderPass::Draw(), impeller::TRect< T >::Expand(), impeller::ContentContext::GetContext(), impeller::TRect< T >::GetLeftBottom(), impeller::TRect< T >::GetLeftTop(), GetOpacity(), impeller::TRect< T >::GetRightBottom(), impeller::TRect< T >::GetRightTop(), impeller::Entity::GetShaderTransform(), impeller::ContentContext::GetTexturePipeline(), impeller::ContentContext::GetTextureStrictSrcPipeline(), impeller::ContentContext::GetTransientsDataBuffer(), impeller::SamplerDescriptor::height_address_mode, impeller::TRect< T >::IsEmpty(), impeller::kBase, impeller::kClampToEdge, impeller::ContentContextOptions::kIgnore, impeller::kSrc, impeller::kTextureExternalOES, impeller::kTriangleStrip, impeller::SamplerDescriptor::mag_filter, impeller::TRect< Scalar >::MakeSize(), impeller::SamplerDescriptor::min_filter, impeller::SamplerDescriptor::mip_filter, impeller::OptionsFromPassAndEntity(), impeller::TRect< T >::Project(), impeller::RenderPass::SetCommandLabel(), impeller::RenderPass::SetPipeline(), impeller::RenderPass::SetVertexBuffer(), and impeller::SamplerDescriptor::width_address_mode.

## ◆ RenderToSnapshot()

std::optional< Snapshot > impeller::TextureContents::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 virtual

Render this contents to a snapshot, respecting the entity's transform, path, clip depth, and blend mode. The result texture size is always the size of `GetCoverage(entity)`.

Reimplemented from impeller::Contents.

Definition at line 73 of file texture_contents.cc.

80 {
81 // Passthrough textures that have simple rectangle paths and complete source
82 // rects.
83 auto bounds = destination_rect_;
84 auto opacity = GetOpacity();
85 if (source_rect_ == Rect::MakeSize(texture_->GetSize()) &&
86 (opacity >= 1 - kEhCloseEnough || defer_applying_opacity_)) {
87 auto scale = Vector2(bounds.GetSize() / Size(texture_->GetSize()));
88 return Snapshot{
89 .texture = texture_,
90 .transform = entity.GetTransform() *
91 Matrix::MakeTranslation(bounds.GetOrigin()) *
92 Matrix::MakeScale(scale),
93 .sampler_descriptor = sampler_descriptor.value_or(sampler_descriptor_),
94 .opacity = opacity};
95 }
96 return Contents::RenderToSnapshot(
97 renderer, // renderer
98 entity, // entity
99 std::nullopt, // coverage_limit
100 sampler_descriptor.value_or(sampler_descriptor_), // sampler_descriptor
101 true, // msaa_enabled
102 /*mip_count=*/mip_count,
103 label); // label
104 }
impeller::Contents::RenderToSnapshot
virtual 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="Snapshot") const
Render this contents to a snapshot, respecting the entity's transform, path, clip depth,...
Definition: contents.cc:56
impeller::Vector2
Point Vector2
Definition: point.h:331
impeller::kEhCloseEnough
constexpr float kEhCloseEnough
Definition: constants.h:57
impeller::Size
TSize< Scalar > Size
Definition: size.h:159
impeller::Matrix::MakeTranslation
static constexpr Matrix MakeTranslation(const Vector3 &t)
Definition: matrix.h:95
impeller::Matrix::MakeScale
static constexpr Matrix MakeScale(const Vector3 &s)
Definition: matrix.h:104

References GetOpacity(), impeller::Entity::GetTransform(), impeller::kEhCloseEnough, impeller::Matrix::MakeScale(), impeller::TRect< Scalar >::MakeSize(), impeller::Matrix::MakeTranslation(), impeller::Contents::RenderToSnapshot(), and impeller::Snapshot::texture.

## ◆ SetDeferApplyingOpacity()

void impeller::TextureContents::SetDeferApplyingOpacity | ( | bool | defer_applying_opacity | ) |

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.

Parameters

  defer_applying_opacity | True to defer applying opacity, false to apply it during rendering.

Definition at line 255 of file texture_contents.cc.

255 {
256 defer_applying_opacity_ = defer_applying_opacity;
257 }

## ◆ SetDestinationRect()

void impeller::TextureContents::SetDestinationRect | ( | Rect | rect | ) |

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.

Parameters

  rect | The destination rectangle in the Entity's local coordinate space.

Definition at line 38 of file texture_contents.cc.

38 {
39 destination_rect_ = rect;
40 }

## ◆ SetInheritedOpacity()

void impeller::TextureContents::SetInheritedOpacity | ( | Scalar | opacity | ) |
| override virtual

Inherit the provided opacity.

       Use of this method is invalid if CanAcceptOpacity returns false.

Reimplemented from impeller::Contents.

Definition at line 58 of file texture_contents.cc.

58 {
59 inherited_opacity_ = opacity;
60 }

## ◆ SetLabel()

void impeller::TextureContents::SetLabel | ( | std::string_view | label | ) |

Sets a debug label for this contents object.

This label is used for debugging purposes, for example, in graphics debuggers or logs.

Parameters

  label | The debug label string.

Definition at line 34 of file texture_contents.cc.

34 {
35 label_ = label;
36 }

## ◆ SetOpacity()

void impeller::TextureContents::SetOpacity | ( | Scalar | opacity | ) |

Definition at line 50 of file texture_contents.cc.

50 {
51 opacity_ = opacity;
52 }

## ◆ SetSamplerDescriptor()

void impeller::TextureContents::SetSamplerDescriptor | ( | const SamplerDescriptor & | desc | ) |

Definition at line 247 of file texture_contents.cc.

247 {
248 sampler_descriptor_ = desc;
249 }

## ◆ SetSourceRect()

void impeller::TextureContents::SetSourceRect | ( | const Rect & | source_rect | ) |

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).

Parameters

  source_rect | The rectangle defining the area of the texture to use.

Definition at line 231 of file texture_contents.cc.

231 {
232 source_rect_ = source_rect;
233 }

## ◆ SetStencilEnabled()

void impeller::TextureContents::SetStencilEnabled | ( | bool | enabled | ) |

Definition at line 54 of file texture_contents.cc.

54 {
55 stencil_enabled_ = enabled;
56 }

## ◆ SetStrictSourceRect()

void impeller::TextureContents::SetStrictSourceRect | ( | bool | strict | ) |

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.

Parameters

  strict | True to enable strict source rect sampling, false otherwise.

Definition at line 239 of file texture_contents.cc.

239 {
240 strict_source_rect_enabled_ = strict;
241 }

## ◆ SetTexture()

void impeller::TextureContents::SetTexture | ( | std::shared_ptr< Texture > | texture | ) |

Definition at line 42 of file texture_contents.cc.

42 {
43 texture_ = std::move(texture);
44 }

The documentation for this class was generated from the following files:

- impeller/entity/contents/texture_contents.h
- impeller/entity/contents/texture_contents.cc