| 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, const SnapshotOptions &options) 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 248 of file texture_contents.cc.

248 {
249 return sampler_descriptor_;
250 }

## ◆ GetSourceRect()

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

Definition at line 232 of file texture_contents.cc.

232 {
233 return source_rect_;
234 }

## ◆ GetStrictSourceRect()

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

Definition at line 240 of file texture_contents.cc.

240 {
241 return strict_source_rect_enabled_;
242 }

## ◆ 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 103 of file texture_contents.cc.

105 {
106 using VS = TextureFillVertexShader;
107 using FS = TextureFillFragmentShader;
108 using FSStrict = TextureFillStrictSrcFragmentShader;
109
110 if (destination_rect_.IsEmpty() || source_rect_.IsEmpty() ||
111 texture_ == nullptr || texture_->GetSize().IsEmpty()) {
112 return true; // Nothing to render.
113 }
114
115 #ifdef IMPELLER_ENABLE_OPENGLES
116 using FSExternal = TiledTextureFillExternalFragmentShader;
117 bool is_external_texture =
118 texture_->GetTextureDescriptor().type == TextureType::kTextureExternalOES;
119 #endif // IMPELLER_ENABLE_OPENGLES
120
121 auto texture_coords =
122 Rect::MakeSize(texture_->GetSize()).Project(source_rect_);
123 auto& data_host_buffer = renderer.GetTransientsDataBuffer();
124
125 std::array<VS::PerVertexData, 4> vertices = {
126 VS::PerVertexData{destination_rect_.GetLeftTop(),
127 texture_coords.GetLeftTop()},
128 VS::PerVertexData{destination_rect_.GetRightTop(),
129 texture_coords.GetRightTop()},
130 VS::PerVertexData{destination_rect_.GetLeftBottom(),
131 texture_coords.GetLeftBottom()},
132 VS::PerVertexData{destination_rect_.GetRightBottom(),
133 texture_coords.GetRightBottom()},
134 };
135 auto vertex_buffer = CreateVertexBuffer(vertices, data_host_buffer);
136
137 VS::FrameInfo frame_info;
138 frame_info.mvp = entity.GetShaderTransform(pass);
139 frame_info.texture_sampler_y_coord_scale = texture_->GetYCoordScale();
140
141 #ifdef IMPELLER_DEBUG
142 if (label_.empty()) {
143 pass.SetCommandLabel("Texture Fill");
144 } else {
145 pass.SetCommandLabel("Texture Fill: " + label_);
146 }
147 #endif // IMPELLER_DEBUG
148
149 auto pipeline_options = OptionsFromPassAndEntity(pass, entity);
150 if (!stencil_enabled_) {
151 pipeline_options.stencil_mode = ContentContextOptions::StencilMode::kIgnore;
152 }
153 pipeline_options.primitive_type = PrimitiveType::kTriangleStrip;
154
155 pipeline_options.depth_write_enabled =
156 stencil_enabled_ && pipeline_options.blend_mode == BlendMode::kSrc;
157
158 #ifdef IMPELLER_ENABLE_OPENGLES
159 if (is_external_texture) {
160 pass.SetPipeline(
161 renderer.GetTiledTextureExternalPipeline(pipeline_options));
162 } else {
163 pass.SetPipeline(
164 strict_source_rect_enabled_
165 ? renderer.GetTextureStrictSrcPipeline(pipeline_options)
166 : renderer.GetTexturePipeline(pipeline_options));
167 }
168 #else
169 pass.SetPipeline(strict_source_rect_enabled_
170 ? renderer.GetTextureStrictSrcPipeline(pipeline_options)
171 : renderer.GetTexturePipeline(pipeline_options));
172 #endif // IMPELLER_ENABLE_OPENGLES
173
174 pass.SetVertexBuffer(vertex_buffer);
175 VS::BindFrameInfo(pass, data_host_buffer.EmplaceUniform(frame_info));
176
177 if (strict_source_rect_enabled_) {
178 // For a strict source rect, shrink the texture coordinate range by half a
179 // texel to ensure that linear filtering does not sample anything outside
180 // the source rect bounds.
181 auto strict_texture_coords =
182 Rect::MakeSize(texture_->GetSize()).Project(source_rect_.Expand(-0.5));
183
184 FSStrict::FragInfo frag_info;
185 frag_info.source_rect = Vector4(strict_texture_coords.GetLTRB());
186 frag_info.alpha = GetOpacity();
187 FSStrict::BindFragInfo(pass, data_host_buffer.EmplaceUniform((frag_info)));
188 FSStrict::BindTextureSampler(
189 pass, texture_,
190 renderer.GetContext()->GetSamplerLibrary()->GetSampler(
191 sampler_descriptor_));
192 #ifdef IMPELLER_ENABLE_OPENGLES
193 } else if (is_external_texture) {
194 FSExternal::FragInfo frag_info;
195 frag_info.x_tile_mode =
196 static_cast<Scalar>(sampler_descriptor_.width_address_mode);
197 frag_info.y_tile_mode =
198 static_cast<Scalar>(sampler_descriptor_.height_address_mode);
199 frag_info.alpha = GetOpacity();
200 FSExternal::BindFragInfo(pass, data_host_buffer.EmplaceUniform(frag_info));
201
202 SamplerDescriptor sampler_desc;
203 // OES_EGL_image_external states that only CLAMP_TO_EDGE is valid, so
204 // we emulate all other tile modes here by remapping the texture
205 // coordinates.
206 sampler_desc.width_address_mode = SamplerAddressMode::kClampToEdge;
207 sampler_desc.height_address_mode = SamplerAddressMode::kClampToEdge;
208 sampler_desc.min_filter = sampler_descriptor_.min_filter;
209 sampler_desc.mag_filter = sampler_descriptor_.mag_filter;
210 sampler_desc.mip_filter = MipFilter::kBase;
211
212 FSExternal::BindSAMPLEREXTERNALOESTextureSampler(
213 pass, texture_,
214 renderer.GetContext()->GetSamplerLibrary()->GetSampler(sampler_desc));
215 #endif // IMPELLER_ENABLE_OPENGLES
216 } else {
217 FS::FragInfo frag_info;
218 frag_info.alpha = GetOpacity();
219 FS::BindFragInfo(pass, data_host_buffer.EmplaceUniform((frag_info)));
220 FS::BindTextureSampler(
221 pass, texture_,
222 renderer.GetContext()->GetSamplerLibrary()->GetSampler(
223 sampler_descriptor_));
224 }
225 return pass.Draw().ok();
226 }
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,
|  | const SnapshotOptions & | options
| ) |  | 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.

76 {
77 // Passthrough textures that have simple rectangle paths and complete source
78 // rects.
79 auto bounds = destination_rect_;
80 auto opacity = GetOpacity();
81 if (source_rect_ == Rect::MakeSize(texture_->GetSize()) &&
82 (opacity >= 1 - kEhCloseEnough || defer_applying_opacity_)) {
83 auto scale = Vector2(bounds.GetSize() / Size(texture_->GetSize()));
84 return Snapshot{.texture = texture_,
85 .transform = entity.GetTransform() *
86 Matrix::MakeTranslation(bounds.GetOrigin()) *
87 Matrix::MakeScale(scale),
88 .sampler_descriptor = options.sampler_descriptor.value_or(
89 sampler_descriptor_),
90 .opacity = opacity};
91 }
92 return Contents::RenderToSnapshot(
93 renderer, entity,
94 {.coverage_limit = std::nullopt,
95 .sampler_descriptor =
96 options.sampler_descriptor.value_or(sampler_descriptor_),
97 .msaa_enabled = true,
98 .mip_count = options.mip_count,
99 .label = options.label,
100 .coverage_expansion = options.coverage_expansion});
101 }
impeller::Contents::RenderToSnapshot
virtual std::optional< Snapshot > RenderToSnapshot(const ContentContext &renderer, const Entity &entity, const SnapshotOptions &options) 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 impeller::Contents::SnapshotOptions::coverage_expansion, GetOpacity(), impeller::Entity::GetTransform(), impeller::kEhCloseEnough, impeller::Contents::SnapshotOptions::label, impeller::Matrix::MakeScale(), impeller::TRect< Scalar >::MakeSize(), impeller::Matrix::MakeTranslation(), impeller::Contents::SnapshotOptions::mip_count, impeller::Contents::RenderToSnapshot(), impeller::Contents::SnapshotOptions::sampler_descriptor, 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 252 of file texture_contents.cc.

252 {
253 defer_applying_opacity_ = defer_applying_opacity;
254 }

## ◆ 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 244 of file texture_contents.cc.

244 {
245 sampler_descriptor_ = desc;
246 }

## ◆ 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 228 of file texture_contents.cc.

228 {
229 source_rect_ = source_rect;
230 }

## ◆ 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 236 of file texture_contents.cc.

236 {
237 strict_source_rect_enabled_ = strict;
238 }

## ◆ 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