Flutter Impeller
impeller::ColorSourceContents Class Reference

#include <color_source_contents.h>

Inheritance diagram for impeller::ColorSourceContents:
impeller::Contents impeller::ConicalGradientContents impeller::FramebufferBlendContents impeller::LinearGradientContents impeller::RadialGradientContents impeller::RuntimeEffectContents impeller::SolidColorContents impeller::SweepGradientContents impeller::TiledTextureContents

Public Types

using BindFragmentCallback = std::function< bool(RenderPass &pass)>
 
using PipelineBuilderCallback = std::function< PipelineRef(ContentContextOptions)>
 
using CreateGeometryCallback = std::function< GeometryResult(const ContentContext &renderer, const Entity &entity, RenderPass &pass, const Geometry *geom)>
 
- 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)>
 

Public Member Functions

 ColorSourceContents ()
 
 ~ColorSourceContents () override
 
void SetGeometry (const Geometry *geometry)
 Set the geometry that this contents will use to render. More...
 
const GeometryGetGeometry () const
 Get the geometry that this contents will use to render. More...
 
void SetEffectTransform (Matrix matrix)
 Set the effect transform for this color source. More...
 
const MatrixGetInverseEffectTransform () const
 Set the inverted effect transform for this color source. More...
 
void SetOpacityFactor (Scalar opacity)
 Set the opacity factor for this color source. More...
 
Scalar GetOpacityFactor () const
 Get the opacity factor for this color source. More...
 
virtual bool IsSolidColor () const
 
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...
 
void SetInheritedOpacity (Scalar opacity) override
 Inherit the provided opacity. More...
 
- Public Member Functions inherited from impeller::Contents
 Contents ()
 
virtual ~Contents ()
 
virtual bool Render (const ContentContext &renderer, const Entity &entity, RenderPass &pass) const =0
 
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...
 
virtual 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="Snapshot") const
 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...
 
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

template<typename VertexShaderT >
static bool DrawGeometry (const Contents *contents, const Geometry *geometry, const ContentContext &renderer, const Entity &entity, RenderPass &pass, const PipelineBuilderCallback &pipeline_callback, typename VertexShaderT::FrameInfo frame_info, const BindFragmentCallback &bind_fragment_callback, bool force_stencil=false, const CreateGeometryCallback &create_geom_callback=DefaultCreateGeometryCallback)
 
- Static Public Member Functions inherited from impeller::Contents
static std::shared_ptr< ContentsMakeAnonymous (RenderProc render_proc, CoverageProc coverage_proc)
 

Protected Member Functions

bool AppliesAlphaForStrokeCoverage (const Matrix &transform) const
 Whether the entity should be treated as non-opaque due to stroke geometry requiring alpha for coverage. More...
 
template<typename VertexShaderT >
bool DrawGeometry (const ContentContext &renderer, const Entity &entity, RenderPass &pass, const PipelineBuilderCallback &pipeline_callback, typename VertexShaderT::FrameInfo frame_info, const BindFragmentCallback &bind_fragment_callback, bool force_stencil=false, const CreateGeometryCallback &create_geom_callback=DefaultCreateGeometryCallback) const
 

Static Protected Member Functions

static GeometryResult DefaultCreateGeometryCallback (const ContentContext &renderer, const Entity &entity, RenderPass &pass, const Geometry *geom)
 

Detailed Description

Color sources are geometry-ignostic Contents capable of shading any area defined by an impeller::Geometry. Conceptually, impeller::ColorSourceContents implement a particular color shading behavior.

This separation of concerns between geometry and color source output allows Impeller to handle most possible draw combinations in a consistent way. For example: There are color sources for handling solid colors, gradients, textures, custom runtime effects, and even 3D scenes.

There are some special rendering exceptions that deviate from this pattern and cross geometry and color source concerns, such as text atlas and image atlas rendering. Special Contents exist for rendering these behaviors which don't implement ColorSourceContents.

See also
impeller::Geometry

Definition at line 38 of file color_source_contents.h.

Member Typedef Documentation

◆ BindFragmentCallback

Definition at line 40 of file color_source_contents.h.

◆ CreateGeometryCallback

using impeller::ColorSourceContents::CreateGeometryCallback = std::function<GeometryResult(const ContentContext& renderer, const Entity& entity, RenderPass& pass, const Geometry* geom)>

Definition at line 43 of file color_source_contents.h.

◆ PipelineBuilderCallback

Constructor & Destructor Documentation

◆ ColorSourceContents()

impeller::ColorSourceContents::ColorSourceContents ( )
default

◆ ~ColorSourceContents()

impeller::ColorSourceContents::~ColorSourceContents ( )
overridedefault

Member Function Documentation

◆ AppliesAlphaForStrokeCoverage()

bool impeller::ColorSourceContents::AppliesAlphaForStrokeCoverage ( const Matrix transform) const
protected

Whether the entity should be treated as non-opaque due to stroke geometry requiring alpha for coverage.

Definition at line 53 of file color_source_contents.cc.

54  {
56 }
const Geometry * GetGeometry() const
Get the geometry that this contents will use to render.
virtual Scalar ComputeAlphaCoverage(const Matrix &transform) const
Definition: geometry.h:125

References impeller::Geometry::ComputeAlphaCoverage(), GetGeometry(), and transform.

Referenced by impeller::LinearGradientContents::IsOpaque(), impeller::RadialGradientContents::IsOpaque(), impeller::SolidColorContents::IsOpaque(), impeller::SweepGradientContents::IsOpaque(), and impeller::TiledTextureContents::IsOpaque().

◆ DefaultCreateGeometryCallback()

static GeometryResult impeller::ColorSourceContents::DefaultCreateGeometryCallback ( const ContentContext renderer,
const Entity entity,
RenderPass pass,
const Geometry geom 
)
inlinestaticprotected

Definition at line 259 of file color_source_contents.h.

263  {
264  return geom->GetPositionBuffer(renderer, entity, pass);
265  }

References impeller::Geometry::GetPositionBuffer().

◆ DrawGeometry() [1/2]

template<typename VertexShaderT >
bool impeller::ColorSourceContents::DrawGeometry ( const ContentContext renderer,
const Entity entity,
RenderPass pass,
const PipelineBuilderCallback pipeline_callback,
typename VertexShaderT::FrameInfo  frame_info,
const BindFragmentCallback bind_fragment_callback,
bool  force_stencil = false,
const CreateGeometryCallback create_geom_callback = DefaultCreateGeometryCallback 
) const
inlineprotected

Definition at line 272 of file color_source_contents.h.

280  {
281  //
282  return DrawGeometry<VertexShaderT>(this, //
283  GetGeometry(), //
284  renderer, //
285  entity, //
286  pass, //
287  pipeline_callback, //
288  frame_info, //
289  bind_fragment_callback, //
290  force_stencil, //
291  create_geom_callback);
292  }

References GetGeometry().

◆ DrawGeometry() [2/2]

template<typename VertexShaderT >
static bool impeller::ColorSourceContents::DrawGeometry ( const Contents contents,
const Geometry geometry,
const ContentContext renderer,
const Entity entity,
RenderPass pass,
const PipelineBuilderCallback pipeline_callback,
typename VertexShaderT::FrameInfo  frame_info,
const BindFragmentCallback bind_fragment_callback,
bool  force_stencil = false,
const CreateGeometryCallback create_geom_callback = DefaultCreateGeometryCallback 
)
inlinestatic

Stencil preparation draw.

Cover draw.

Definition at line 113 of file color_source_contents.h.

123  {
124  auto options = OptionsFromPassAndEntity(pass, entity);
125 
126  GeometryResult::Mode geometry_mode = geometry->GetResultMode();
127  bool do_cover_draw = false;
128  Rect cover_area = {};
129 
130  bool is_stencil_then_cover =
131  geometry_mode == GeometryResult::Mode::kNonZero ||
132  geometry_mode == GeometryResult::Mode::kEvenOdd;
133  if (!is_stencil_then_cover && force_stencil) {
134  geometry_mode = GeometryResult::Mode::kNonZero;
135  is_stencil_then_cover = true;
136  }
137 
138  if (is_stencil_then_cover) {
139  pass.SetStencilReference(0);
140 
141  /// Stencil preparation draw.
142 
143  GeometryResult stencil_geometry_result =
144  geometry->GetPositionBuffer(renderer, entity, pass);
145  if (stencil_geometry_result.vertex_buffer.vertex_count == 0u) {
146  return true;
147  }
148  pass.SetVertexBuffer(std::move(stencil_geometry_result.vertex_buffer));
149  options.primitive_type = stencil_geometry_result.type;
150 
151  options.blend_mode = BlendMode::kDst;
152  switch (stencil_geometry_result.mode) {
154  pass.SetCommandLabel("Stencil preparation (NonZero)");
155  options.stencil_mode =
157  break;
159  pass.SetCommandLabel("Stencil preparation (EvenOdd)");
160  options.stencil_mode =
162  break;
163  default:
164  if (force_stencil) {
165  pass.SetCommandLabel("Stencil preparation (NonZero)");
166  options.stencil_mode =
168  break;
169  }
170  FML_UNREACHABLE();
171  }
172  pass.SetPipeline(renderer.GetClipPipeline(options));
173  ClipPipeline::VertexShader::FrameInfo clip_frame_info;
174  clip_frame_info.depth = entity.GetShaderClipDepth();
175  clip_frame_info.mvp = stencil_geometry_result.transform;
176  ClipPipeline::VertexShader::BindFrameInfo(
177  pass, renderer.GetTransientsBuffer().EmplaceUniform(clip_frame_info));
178 
179  if (!pass.Draw().ok()) {
180  return false;
181  }
182 
183  /// Cover draw.
184 
185  options.blend_mode = entity.GetBlendMode();
187  std::optional<Rect> maybe_cover_area = geometry->GetCoverage({});
188  if (!maybe_cover_area.has_value()) {
189  return true;
190  }
191  do_cover_draw = true;
192  cover_area = maybe_cover_area.value();
193  }
194 
195  GeometryResult geometry_result;
196  if (do_cover_draw) {
197  FillRectGeometry geom(cover_area);
198  geometry_result = create_geom_callback(renderer, entity, pass, &geom);
199  } else {
200  geometry_result = create_geom_callback(renderer, entity, pass, geometry);
201  }
202 
203  if (geometry_result.vertex_buffer.vertex_count == 0u) {
204  return true;
205  }
206  pass.SetVertexBuffer(std::move(geometry_result.vertex_buffer));
207  options.primitive_type = geometry_result.type;
208 
209  // Enable depth writing for all opaque entities in order to allow
210  // reordering. Opaque entities are coerced to source blending by
211  // `EntityPass::AddEntity`.
212  options.depth_write_enabled = options.blend_mode == BlendMode::kSrc;
213 
214  // Take the pre-populated vertex shader uniform struct and set managed
215  // values.
216  frame_info.mvp = geometry_result.transform;
217 
218  // If overdraw prevention is enabled (like when drawing stroke paths), we
219  // increment the stencil buffer as we draw, preventing overlapping fragments
220  // from drawing. Afterwards, we need to append another draw call to clean up
221  // the stencil buffer (happens below in this method). This can be skipped
222  // for draws that are fully opaque or use src blend mode.
223  if (geometry_result.mode == GeometryResult::Mode::kPreventOverdraw &&
224  options.blend_mode != BlendMode::kSrc) {
225  options.stencil_mode =
227  }
228  pass.SetStencilReference(0);
229 
230  VertexShaderT::BindFrameInfo(
231  pass, renderer.GetTransientsBuffer().EmplaceUniform(frame_info));
232 
233  // The reason we need to have a callback mechanism here is that this routine
234  // may insert draw calls before the main draw call below. For example, for
235  // sufficiently complex paths we may opt to use stencil-then-cover to avoid
236  // tessellation.
237  if (!bind_fragment_callback(pass)) {
238  return false;
239  }
240 
241  pass.SetPipeline(pipeline_callback(options));
242 
243  if (!pass.Draw().ok()) {
244  return false;
245  }
246 
247  // If we performed overdraw prevention, a subsection of the clip heightmap
248  // was incremented by 1 in order to self-clip. So simply append a clip
249  // restore to clean it up.
250  if (geometry_result.mode == GeometryResult::Mode::kPreventOverdraw &&
251  options.blend_mode != BlendMode::kSrc) {
252  return RenderClipRestore(renderer, pass, entity.GetClipDepth(),
253  contents->GetCoverage(entity));
254  }
255  return true;
256  }
TRect< Scalar > Rect
Definition: rect.h:792
bool RenderClipRestore(const ContentContext &renderer, RenderPass &pass, uint32_t clip_depth, std::optional< Rect > restore_coverage)
Render a restore clip.
ContentContextOptions OptionsFromPassAndEntity(const RenderPass &pass, const Entity &entity)
Definition: contents.cc:34

References impeller::RenderPass::Draw(), impeller::HostBuffer::EmplaceUniform(), impeller::Entity::GetBlendMode(), impeller::Entity::GetClipDepth(), impeller::ContentContext::GetClipPipeline(), impeller::Contents::GetCoverage(), impeller::Geometry::GetCoverage(), impeller::Geometry::GetPositionBuffer(), impeller::Geometry::GetResultMode(), impeller::Entity::GetShaderClipDepth(), impeller::ContentContext::GetTransientsBuffer(), impeller::ContentContextOptions::kCoverCompare, impeller::kDst, impeller::GeometryResult::kEvenOdd, impeller::GeometryResult::kNonZero, impeller::ContentContextOptions::kOverdrawPreventionIncrement, impeller::GeometryResult::kPreventOverdraw, impeller::kSrc, impeller::ContentContextOptions::kStencilEvenOddFill, impeller::ContentContextOptions::kStencilNonZeroFill, impeller::GeometryResult::mode, impeller::OptionsFromPassAndEntity(), impeller::RenderClipRestore(), impeller::RenderPass::SetCommandLabel(), impeller::RenderPass::SetPipeline(), impeller::RenderPass::SetStencilReference(), impeller::RenderPass::SetVertexBuffer(), impeller::GeometryResult::transform, impeller::GeometryResult::type, impeller::GeometryResult::vertex_buffer, and impeller::VertexBuffer::vertex_count.

◆ GetCoverage()

std::optional< Rect > impeller::ColorSourceContents::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.

Reimplemented in impeller::SolidColorContents.

Definition at line 44 of file color_source_contents.cc.

45  {
46  return geometry_->GetCoverage(entity.GetTransform());
47 };
virtual std::optional< Rect > GetCoverage(const Matrix &transform) const =0

References impeller::Geometry::GetCoverage(), and impeller::Entity::GetTransform().

Referenced by impeller::TiledTextureContents::RenderToSnapshot().

◆ GetGeometry()

const Geometry * impeller::ColorSourceContents::GetGeometry ( ) const

◆ GetInverseEffectTransform()

const Matrix & impeller::ColorSourceContents::GetInverseEffectTransform ( ) const

Set the inverted effect transform for this color source.

     When the effect transform is set via `SetEffectTransform`, the
     value is inverted upon storage. The reason for this is that most
     color sources internally use the inverted transform.
Returns
The inverse of the transform set by SetEffectTransform.
See also
SetEffectTransform

Definition at line 36 of file color_source_contents.cc.

36  {
37  return inverse_matrix_;
38 }

Referenced by impeller::TiledTextureContents::Render(), and impeller::TiledTextureContents::RenderToSnapshot().

◆ GetOpacityFactor()

Scalar impeller::ColorSourceContents::GetOpacityFactor ( ) const

Get the opacity factor for this color source.

    This value is is factored into the output of the color source in
    addition to opacity information that may be supplied any other
    inputs.
Note
If set, the output of this method factors factors in the inherited opacity of this Contents.

Definition at line 28 of file color_source_contents.cc.

28  {
29  return opacity_ * inherited_opacity_;
30 }

Referenced by impeller::SolidColorContents::GetColor(), impeller::LinearGradientContents::IsOpaque(), impeller::RadialGradientContents::IsOpaque(), impeller::SweepGradientContents::IsOpaque(), impeller::TiledTextureContents::IsOpaque(), impeller::TiledTextureContents::Render(), and impeller::TiledTextureContents::RenderToSnapshot().

◆ IsSolidColor()

bool impeller::ColorSourceContents::IsSolidColor ( ) const
virtual

Reimplemented in impeller::SolidColorContents.

Definition at line 40 of file color_source_contents.cc.

40  {
41  return false;
42 }

◆ SetEffectTransform()

void impeller::ColorSourceContents::SetEffectTransform ( Matrix  matrix)

Set the effect transform for this color source.

    The effect transform is a transform matrix that is applied to
    the shaded color output and does not impact geometry in any way.

    For example: With repeat tiling, any gradient or
    `TiledTextureContents` could be used with an effect transform to
    inexpensively draw an infinite scrolling background pattern.

Definition at line 32 of file color_source_contents.cc.

32  {
33  inverse_matrix_ = matrix.Invert();
34 }
Matrix Invert() const
Definition: matrix.cc:97

References impeller::Matrix::Invert().

◆ SetGeometry()

void impeller::ColorSourceContents::SetGeometry ( const Geometry geometry)

Set the geometry that this contents will use to render.

Definition at line 16 of file color_source_contents.cc.

16  {
17  geometry_ = geometry;
18 }

Referenced by impeller::testing::TEST_P().

◆ SetInheritedOpacity()

void impeller::ColorSourceContents::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 49 of file color_source_contents.cc.

49  {
50  inherited_opacity_ = opacity;
51 }

◆ SetOpacityFactor()

void impeller::ColorSourceContents::SetOpacityFactor ( Scalar  opacity)

Set the opacity factor for this color source.

Definition at line 24 of file color_source_contents.cc.

24  {
25  opacity_ = alpha;
26 }

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