Flutter Impeller
impeller::TextureContents Class Referencefinal

#include <texture_contents.h>

Inheritance diagram for impeller::TextureContents:
impeller::Contents

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< TextureGetTexture () const
 
void SetSamplerDescriptor (const SamplerDescriptor &desc)
 
const SamplerDescriptorGetSamplerDescriptor () const
 
void SetSourceRect (const Rect &source_rect)
 
const RectGetSourceRect () const
 
void SetStrictSourceRect (bool strict)
 
bool GetStrictSourceRect () const
 
void SetOpacity (Scalar opacity)
 
Scalar GetOpacity () const
 
void SetStencilEnabled (bool enabled)
 
std::optional< RectGetCoverage (const Entity &entity) const override
 Get the area of the render pass that will be affected when this contents is rendered. More...
 
std::optional< SnapshotRenderToSnapshot (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< SizeGetColorSourceSize () const
 Return the color source's intrinsic size, if available. More...
 
void SetColorSourceSize (Size size)
 
virtual std::optional< ColorAsBackgroundColor (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< TextureContentsMakeRect (Rect destination)
 
- Static Public Member Functions inherited from impeller::Contents
static std::shared_ptr< ContentsMakeAnonymous (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 ( )
overridedefault

Member Function Documentation

◆ GetCoverage()

std::optional< Rect > impeller::TextureContents::GetCoverage ( const Entity entity) const
overridevirtual

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 };
constexpr TRect TransformBounds(const Matrix &transform) const
Creates a new bounding box that contains this transformed rectangle.
Definition: rect.h:476

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
destinationThe 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
overridevirtual

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& host_buffer = renderer.GetTransientsBuffer();
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, 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, 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, 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, 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, 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 }
float Scalar
Definition: scalar.h:19
LinePipeline::FragmentShader FS
@ kBase
The texture is sampled as if it only had a single mipmap level.
VertexBuffer CreateVertexBuffer(std::array< VertexType, size > input, HostBuffer &host_buffer)
Create an index-less vertex buffer from a fixed size array.
LinePipeline::VertexShader VS
ContentContextOptions OptionsFromPassAndEntity(const RenderPass &pass, const Entity &entity)
Definition: contents.cc:34
SamplerAddressMode width_address_mode
SamplerAddressMode height_address_mode
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:622
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:673
constexpr bool IsEmpty() const
Returns true if either of the width or height are 0, negative, or NaN.
Definition: rect.h:301
constexpr TPoint< T > GetLeftBottom() const
Definition: rect.h:371
constexpr TPoint< T > GetRightTop() const
Definition: rect.h:367
constexpr static TRect MakeSize(const TSize< U > &size)
Definition: rect.h:150
constexpr TPoint< T > GetRightBottom() const
Definition: rect.h:375
constexpr TPoint< T > GetLeftTop() const
Definition: rect.h:363

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::GetTransientsBuffer(), 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
overridevirtual

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  }
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 }
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
Point Vector2
Definition: point.h:331
constexpr float kEhCloseEnough
Definition: constants.h:57
TSize< Scalar > Size
Definition: size.h:159
static constexpr Matrix MakeTranslation(const Vector3 &t)
Definition: matrix.h:95
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_opacityTrue 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
rectThe 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)
overridevirtual

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
labelThe 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_rectThe 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
strictTrue 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: