impeller::TextContents Class Reference

#include <text_contents.h>

Inheritance diagram for impeller::TextContents:

Public Member Functions
	TextContents ()
	~TextContents ()
void	SetTextFrame (const std::shared_ptr< TextFrame > &frame)
void	SetColor (Color color)
void	SetForceTextColor (bool value)
	Force the text color to apply to the rendered glyphs, even if those glyphs are bitmaps. More...
void	SetTextProperties (Color color, const std::optional< StrokeParameters > &stroke)
	Must be set after text frame. More...
Color	GetColor () const
void	SetInheritedOpacity (Scalar opacity) override
	Inherit the provided opacity. More...
void	SetPosition (Point position)
void	SetScreenTransform (const Matrix &transform)
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...
bool	Render (const ContentContext &renderer, const Entity &entity, RenderPass &pass) const override
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...
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, and blend mode. The result texture size is always the size of GetCoverage(entity). 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 void	ComputeVertexData (GlyphAtlasPipeline::VertexShader::PerVertexData *vtx_contents, const Matrix &entity_transform, const std::shared_ptr< TextFrame > &frame, Point position, const Matrix &screen_transform, GlyphProperties glyph_properties, const std::shared_ptr< GlyphAtlas > &atlas)
	Computes the vertex data for the render operation from a collection of data drawn from the DrawTextFrame call itself and the entity environment. More...
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

Definition at line 23 of file text_contents.h.

Constructor & Destructor Documentation

TextContents()

impeller::TextContents::TextContents

(

)

Definition at line 45 of file text_contents.cc.

{}

~TextContents()

impeller::TextContents::~TextContents ( )

default

Member Function Documentation

ComputeVertexData()

void impeller::TextContents::ComputeVertexData ( GlyphAtlasPipeline::VertexShader::PerVertexData *  vtx_contents, const Matrix &  entity_transform, const std::shared_ptr< TextFrame > &  frame, Point  position, const Matrix &  screen_transform, GlyphProperties  glyph_properties, const std::shared_ptr< GlyphAtlas > &  atlas  )

static

Computes the vertex data for the render operation from a collection of data drawn from the DrawTextFrame call itself and the entity environment.

vtx_contents A pointer to the array of PerVertexData to fill. entity_transform The transform from the entity which might include offsets due to an intermediate temporary rendering target. This transform is used for final placement of glyphs on the screen. frame The TextFrame object from the DrawTextFrame call. position The position from the DrawTextFrame call. screen_transform The value of Canvas::GetCurrentTransform() from the DrawTextFrame call. It is the full transform of the text relative to screen space and is not adjusted relative to the origin of an intermidate buffer as the entity_transform may be. This transform is used to retrieve metrics and glyph information from the atlas so that the data matches what was stored in the atlas when the global DisplayList did a pre-pass to collect the glyph information. glyph_properties The GlyphProperties providing the color and stroke information from the Paint object used in the DrawTextFrame call, optionally and only if they should come into play for rendering the glyphs. atlas The glyph atlas containing the glyph texture and placement metrics for all of the glyphs that appear in the TextFrame.

Definition at line 110 of file text_contents.cc.

                                                                             {
  // Common vertex information for all glyphs.
  // All glyphs are given the same vertex information in the form of a
  // unit-sized quad. The size of the glyph is specified in per instance data
  // and the vertex shader uses this to size the glyph correctly. The
  // interpolated vertex information is also used in the fragment shader to
  // sample from the glyph atlas.
 
  constexpr std::array<Point, 4> unit_points = {Point{0, 0}, Point{1, 0},
                                                Point{0, 1}, Point{1, 1}};
 
  ISize atlas_size = atlas->GetTexture()->GetSize();
  bool is_translation_scale = entity_offset_transform.IsTranslationScaleOnly();
  Matrix basis_transform = entity_offset_transform.Basis();
 
  VS::PerVertexData vtx;
  size_t i = 0u;
 
  const Matrix frame_transform =
      screen_transform * Matrix::MakeTranslation(position);
  Rational rounded_scale =
      TextFrame::RoundScaledFontSize(frame_transform.GetMaxBasisLengthXY());
  Scalar inverted_rounded_scale = static_cast<Scalar>(rounded_scale.Invert());
  Matrix unscaled_basis =
      basis_transform *
      Matrix::MakeScale({inverted_rounded_scale, inverted_rounded_scale, 1});
 
  // In typical scales < 48x these values should be -1 or 1. We round to
  // those to avoid inaccuracies.
  unscaled_basis.m[0] = AttractToOne(unscaled_basis.m[0]);
  unscaled_basis.m[5] = AttractToOne(unscaled_basis.m[5]);
 
  // Compute the device origin of the entire frame.
  Point screen_offset = (entity_offset_transform * Point(0, 0));
 
  for (const TextRun& run : frame->GetRuns()) {
    const Font& font = run.GetFont();
    const ScaledFont scaled_font{.font = font, .scale = rounded_scale};
    const FontGlyphAtlas* font_atlas = atlas->GetFontGlyphAtlas(scaled_font);
 
    if (!font_atlas) {
      VALIDATION_LOG << "Could not find font in the atlas.";
      // We will not find glyph bounds data for any characters in this run.
      break;
    }
 
    // Adjust glyph position based on the subpixel rounding used by the font.
    //
    // This value is really only used in the is_translation_scale case below,
    // but that usage appears inside a pair of nested loops so we compute it
    // once here for the common case for use many times below.
    // For the other case, this is a fairly quick computation if we are
    // only doing it just once.
    Point subpixel_adjustment(0.5, 0.5);
    switch (font.GetAxisAlignment()) {
      case AxisAlignment::kNone:
        break;
      case AxisAlignment::kX:
        subpixel_adjustment.x = 0.125;
        break;
      case AxisAlignment::kY:
        subpixel_adjustment.y = 0.125;
        break;
      case AxisAlignment::kAll:
        subpixel_adjustment.x = 0.125;
        subpixel_adjustment.y = 0.125;
        break;
    }
 
    for (const TextRun::GlyphPosition& glyph_position :
         run.GetGlyphPositions()) {
      SubpixelPosition subpixel = TextFrame::ComputeSubpixelPosition(
          glyph_position, font.GetAxisAlignment(), frame_transform);
      SubpixelGlyph subpixel_glyph(glyph_position.glyph, subpixel,
                                   glyph_properties);
      FrameBounds frame_bounds =
          font_atlas->FindGlyphBounds(subpixel_glyph).value_or(FrameBounds{});
 
      // If frame_bounds.is_placeholder is true, either this set of attributes
      // were not captured by the FirstPass dispatcher or this is the first
      // frame the glyph has been rendered and so its atlas position was not
      // known when the glyph was recorded. Perform a slow lookup into the
      // glyph atlas hash table.
      if (frame_bounds.is_placeholder) {
        VALIDATION_LOG << "Frame bounds are not present in the atlas "
                       << font_atlas;
        continue;
      }
 
      // For each glyph, we compute two rectangles. One for the vertex
      // positions and one for the texture coordinates (UVs). The atlas
      // glyph bounds are used to compute UVs in cases where the
      // destination and source sizes may differ due to clamping the sizes
      // of large glyphs.
      Point uv_origin = frame_bounds.atlas_bounds.GetLeftTop() / atlas_size;
      Point uv_size =
          SizeToPoint(frame_bounds.atlas_bounds.GetSize()) / atlas_size;
 
      for (const Point& point : unit_points) {
        Point position;
        if (is_translation_scale) {
          Point unrounded_glyph_position =
              // This is for RTL text.
              unscaled_basis * frame_bounds.glyph_bounds.GetLeftTop() +
              (basis_transform * glyph_position.position);
 
          Point screen_glyph_position =
              (screen_offset + unrounded_glyph_position + subpixel_adjustment)
                  .Floor();
          position =
              (screen_glyph_position +
               (unscaled_basis * point * frame_bounds.glyph_bounds.GetSize()))
                  .Round();
        } else {
          Rect scaled_bounds =
              frame_bounds.glyph_bounds.Scale(inverted_rounded_scale);
          position = entity_offset_transform *
                     (glyph_position.position + scaled_bounds.GetLeftTop() +
                      point * scaled_bounds.GetSize());
        }
        vtx.uv = uv_origin + (uv_size * point);
        vtx.position = position;
        vtx_contents[i++] = vtx;
      }
    }
  }
}

References impeller::FrameBounds::atlas_bounds, impeller::Matrix::Basis(), impeller::TextFrame::ComputeSubpixelPosition(), impeller::FontGlyphAtlas::FindGlyphBounds(), impeller::ScaledFont::font, impeller::Font::GetAxisAlignment(), impeller::TRect< T >::GetLeftTop(), impeller::Matrix::GetMaxBasisLengthXY(), impeller::TRect< T >::GetSize(), impeller::FrameBounds::glyph_bounds, impeller::Rational::Invert(), impeller::FrameBounds::is_placeholder, impeller::Matrix::IsTranslationScaleOnly(), impeller::kAll, impeller::kNone, impeller::kX, impeller::kY, impeller::Matrix::m, impeller::Matrix::MakeScale(), impeller::Matrix::MakeTranslation(), impeller::TPoint< T >::Round(), impeller::TextFrame::RoundScaledFontSize(), impeller::TRect< T >::Scale(), VALIDATION_LOG, impeller::TPoint< T >::x, and impeller::TPoint< T >::y.

Referenced by Render(), and impeller::testing::TEST_P().

GetColor()

Color impeller::TextContents::GetColor

(

)

const

Definition at line 57 of file text_contents.cc.

                                   {
  return color_.WithAlpha(color_.alpha * inherited_opacity_);
}

References impeller::Color::alpha, and impeller::Color::WithAlpha().

Referenced by Render().

GetCoverage()

std::optional< Rect > impeller::TextContents::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 77 of file text_contents.cc.

                                                                      {
  return frame_->GetBounds().TransformBounds(entity.GetTransform());
}

References impeller::Entity::GetTransform().

Render()

bool impeller::TextContents::Render ( const ContentContext &  renderer, const Entity &  entity, RenderPass &  pass  ) const

overridevirtual

Implements impeller::Contents.

Definition at line 244 of file text_contents.cc.

                                                  {
  Color color = GetColor();
  if (color.IsTransparent()) {
    return true;
  }
 
  GlyphAtlas::Type type = frame_->GetAtlasType();
  const std::shared_ptr<GlyphAtlas>& atlas =
      renderer.GetLazyGlyphAtlas()->CreateOrGetGlyphAtlas(
          *renderer.GetContext(), renderer.GetTransientsDataBuffer(), type);
 
  if (!atlas || !atlas->IsValid()) {
    VALIDATION_LOG << "Cannot render glyphs without prepared atlas.";
    return false;
  }
 
  // Information shared by all glyph draw calls.
  pass.SetCommandLabel("TextFrame");
  auto opts = OptionsFromPassAndEntity(pass, entity);
  opts.primitive_type = PrimitiveType::kTriangle;
  pass.SetPipeline(renderer.GetGlyphAtlasPipeline(opts));
 
  // Common vertex uniforms for all glyphs.
  VS::FrameInfo frame_info;
  frame_info.mvp =
      Entity::GetShaderTransform(entity.GetShaderClipDepth(), pass, Matrix());
  const Matrix& entity_transform = entity.GetTransform();
  bool is_translation_scale = entity_transform.IsTranslationScaleOnly();
 
  VS::BindFrameInfo(
      pass, renderer.GetTransientsDataBuffer().EmplaceUniform(frame_info));
 
  FS::FragInfo frag_info;
  frag_info.use_text_color = force_text_color_ ? 1.0 : 0.0;
  frag_info.text_color = ToVector(color.Premultiply());
  frag_info.is_color_glyph = type == GlyphAtlas::Type::kColorBitmap;
  bool enable_gamma_correction = frame_->GetEnableGammaCorrection().value_or(
      kPlatformGammaCorrectionDefault);
  if (enable_gamma_correction) {
    // Calculate relative luminance using Rec. 709 luma coefficients.
    Scalar luma =
        color.red * 0.2126f + color.green * 0.7152f + color.blue * 0.0722f;
    // The contrast/gamma exponent applied in the shader ranges from 1.0 for
    // black text to 2.2 (standard sRGB gamma) for white text. This interpolates
    // the exponent based on the text color's luminance.
    constexpr Scalar kMaxGammaCorrection = 1.2f;
    frag_info.text_contrast = 1.0f + luma * kMaxGammaCorrection;
  } else {
    frag_info.text_contrast = 1.0f;
  }
 
  FS::BindFragInfo(
      pass, renderer.GetTransientsDataBuffer().EmplaceUniform(frag_info));
 
  SamplerDescriptor sampler_desc;
  if (is_translation_scale) {
    // When the transform is translation+scale only, we normally use nearest-
    // neighbor sampling for pixel-perfect text. However, if the X and Y
    // scales differ significantly (non-uniform / anisotropic scaling, e.g.
    // Transform.scale(scaleY: 2)), the glyph atlas entry is rasterized at
    // max(|scaleX|,|scaleY|) uniformly and the compensating unscaled_basis
    // squeezes one axis, causing a minification. Nearest-neighbor during
    // minification discards texel columns/rows, producing jagged diagonals
    // and varying stroke weights. Fall back to bilinear in that case.
    // See https://github.com/flutter/flutter/issues/182143
    constexpr Scalar kMinScaleForRatio = 0.001f;
    constexpr Scalar kAnisotropicScaleThreshold = 1.15f;
    const Scalar sx = entity_transform.GetBasisX().GetLength();
    const Scalar sy = entity_transform.GetBasisY().GetLength();
    const Scalar ratio = (sx > sy) ? sx / std::max(sy, kMinScaleForRatio)
                                   : sy / std::max(sx, kMinScaleForRatio);
    if (ratio > kAnisotropicScaleThreshold) {
      // Non-uniform scale — use bilinear to avoid aliasing.
      sampler_desc.min_filter = MinMagFilter::kLinear;
      sampler_desc.mag_filter = MinMagFilter::kLinear;
    } else {
      sampler_desc.min_filter = MinMagFilter::kNearest;
      sampler_desc.mag_filter = MinMagFilter::kNearest;
    }
  } else {
    // Currently, we only propagate the scale of the transform to the atlas
    // renderer, so if the transform has more than just a translation, we turn
    // on linear sampling to prevent crunchiness caused by the pixel grid not
    // being perfectly aligned.
    // The downside is that this slightly over-blurs rotated/skewed text.
    sampler_desc.min_filter = MinMagFilter::kLinear;
    sampler_desc.mag_filter = MinMagFilter::kLinear;
  }
 
  // No mipmaps for glyph atlas (glyphs are generated at exact scales).
  sampler_desc.mip_filter = MipFilter::kBase;
 
  FS::BindGlyphAtlasSampler(
      pass,                 // command
      atlas->GetTexture(),  // texture
      renderer.GetContext()->GetSamplerLibrary()->GetSampler(
          sampler_desc)  // sampler
  );
 
  HostBuffer& data_host_buffer = renderer.GetTransientsDataBuffer();
  HostBuffer& indexes_host_buffer = renderer.GetTransientsIndexesBuffer();
  size_t glyph_count = 0;
  for (const auto& run : frame_->GetRuns()) {
    glyph_count += run.GetGlyphPositions().size();
  }
  size_t vertex_count = glyph_count * 4;
  size_t index_count = glyph_count * 6;
 
  BufferView buffer_view = data_host_buffer.Emplace(
      vertex_count * sizeof(VS::PerVertexData), alignof(VS::PerVertexData),
      [&](uint8_t* data) {
        VS::PerVertexData* vtx_contents =
            reinterpret_cast<VS::PerVertexData*>(data);
        ComputeVertexData(/*vtx_contents=*/vtx_contents,
                          /*entity_transform=*/entity.GetTransform(),
                          /*frame=*/frame_,
                          /*position=*/position_,
                          /*screen_transform=*/screen_transform_,
                          /*glyph_properties=*/properties_,
                          /*atlas=*/atlas);
      });
  BufferView index_buffer_view = indexes_host_buffer.Emplace(
      index_count * sizeof(uint16_t), alignof(uint16_t), [&](uint8_t* data) {
        uint16_t* indices = reinterpret_cast<uint16_t*>(data);
        size_t j = 0;
        for (auto i = 0u; i < glyph_count; i++) {
          size_t base = i * 4;
          indices[j++] = base + 0;
          indices[j++] = base + 1;
          indices[j++] = base + 2;
          indices[j++] = base + 1;
          indices[j++] = base + 2;
          indices[j++] = base + 3;
        }
      });
 
  pass.SetVertexBuffer(std::move(buffer_view));
  pass.SetIndexBuffer(index_buffer_view, IndexType::k16bit);
  pass.SetElementCount(index_count);
 
  return pass.Draw().ok();
}

References impeller::Color::blue, ComputeVertexData(), impeller::RenderPass::Draw(), impeller::HostBuffer::Emplace(), impeller::HostBuffer::EmplaceUniform(), impeller::Matrix::GetBasisX(), impeller::Matrix::GetBasisY(), GetColor(), impeller::ContentContext::GetContext(), impeller::ContentContext::GetGlyphAtlasPipeline(), impeller::ContentContext::GetLazyGlyphAtlas(), impeller::Vector3::GetLength(), impeller::Entity::GetShaderClipDepth(), impeller::Entity::GetShaderTransform(), impeller::Entity::GetTransform(), impeller::ContentContext::GetTransientsDataBuffer(), impeller::ContentContext::GetTransientsIndexesBuffer(), impeller::Color::green, impeller::Matrix::IsTranslationScaleOnly(), impeller::Color::IsTransparent(), impeller::k16bit, impeller::kBase, impeller::GlyphAtlas::kColorBitmap, impeller::kLinear, impeller::kNearest, impeller::kTriangle, impeller::SamplerDescriptor::mag_filter, impeller::SamplerDescriptor::min_filter, impeller::SamplerDescriptor::mip_filter, impeller::OptionsFromPassAndEntity(), impeller::Color::Premultiply(), impeller::Color::red, impeller::RenderPass::SetCommandLabel(), impeller::RenderPass::SetElementCount(), impeller::RenderPass::SetIndexBuffer(), impeller::RenderPass::SetPipeline(), impeller::RenderPass::SetVertexBuffer(), impeller::ToVector(), and VALIDATION_LOG.

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

SetColor()

void impeller::TextContents::SetColor

(

Color

color

)

Definition at line 53 of file text_contents.cc.

                                       {
  color_ = color;
}

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

SetForceTextColor()

void impeller::TextContents::SetForceTextColor

(

bool

value

)

Force the text color to apply to the rendered glyphs, even if those glyphs are bitmaps.

This is used to ensure that mask blurs work correctly on emoji.

Definition at line 73 of file text_contents.cc.

                                               {
  force_text_color_ = value;
}

References value.

SetInheritedOpacity()

void impeller::TextContents::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 61 of file text_contents.cc.

                                                     {
  inherited_opacity_ = opacity;
}

SetPosition()

void impeller::TextContents::SetPosition

(

Point

position

)

Definition at line 65 of file text_contents.cc.

                                             {
  position_ = position;
}

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

SetScreenTransform()

void impeller::TextContents::SetScreenTransform

(

const Matrix &

transform

)

Definition at line 69 of file text_contents.cc.

                                                             {
  screen_transform_ = transform;
}

References transform.

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

SetTextFrame()

void impeller::TextContents::SetTextFrame

(

const std::shared_ptr< TextFrame > &

frame

)

Definition at line 49 of file text_contents.cc.

                                                                     {
  frame_ = frame;
}

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

SetTextProperties()

void impeller::TextContents::SetTextProperties	(	Color	color,
		const std::optional< StrokeParameters > &	stroke
	)

Must be set after text frame.

Definition at line 81 of file text_contents.cc.

                                                 {
  if (frame_->HasColor()) {
    // Alpha is always applied when rendering, remove it here so
    // we do not double-apply the alpha.
    properties_.tone_or_color = color.WithAlpha(1.0);
  } else {
    properties_.tone_or_color = GlyphProperties::ComputeTone(color);
  }
  properties_.stroke = stroke;
}

References impeller::GlyphProperties::ComputeTone(), impeller::GlyphProperties::stroke, impeller::GlyphProperties::tone_or_color, and impeller::Color::WithAlpha().

---

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

• impeller/entity/contents/text_contents.h
• impeller/entity/contents/text_contents.cc