Flutter Impeller
text_frame.h
Go to the documentation of this file.
1 // Copyright 2013 The Flutter Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
4 
5 #ifndef FLUTTER_IMPELLER_TYPOGRAPHER_TEXT_FRAME_H_
6 #define FLUTTER_IMPELLER_TYPOGRAPHER_TEXT_FRAME_H_
7 
8 #include <cstdint>
9 
10 #include "flutter/display_list/geometry/dl_path.h"
11 #include "fml/status_or.h"
16 
17 namespace impeller {
18 
19 using PathCreator = std::function<fml::StatusOr<flutter::DlPath>()>;
20 
21 //------------------------------------------------------------------------------
22 /// @brief Represents a collection of shaped text runs.
23 ///
24 /// This object is typically the entrypoint in the Impeller type
25 /// rendering subsystem.
26 ///
27 /// A text frame should not be reused in multiple places within a single frame,
28 /// as internally it is used as a cache for various glyph properties.
29 class TextFrame {
30  public:
32 
33  TextFrame(std::vector<TextRun>& runs,
34  Rect bounds,
35  bool has_color,
36  const PathCreator& path_creator = {});
37 
39 
41  const TextRun::GlyphPosition& glyph_position,
42  AxisAlignment alignment,
43  const Matrix& transform);
44 
45  static Rational RoundScaledFontSize(Scalar scale);
47 
48  //----------------------------------------------------------------------------
49  /// @brief The conservative bounding box for this text frame.
50  ///
51  /// @return The bounds rectangle. If there are no glyphs in this text
52  /// frame and empty Rectangle is returned instead.
53  ///
54  Rect GetBounds() const;
55 
56  //----------------------------------------------------------------------------
57  /// @brief The number of runs in this text frame.
58  ///
59  /// @return The run count.
60  ///
61  size_t GetRunCount() const;
62 
63  //----------------------------------------------------------------------------
64  /// @brief Returns a reference to all the text runs in this frame.
65  ///
66  /// @return The runs in this frame.
67  ///
68  const std::vector<TextRun>& GetRuns() const;
69 
70  //----------------------------------------------------------------------------
71  /// @brief Returns the paint color this text frame was recorded with.
72  ///
73  /// Non-bitmap/COLR fonts always use a black text color here, but
74  /// COLR fonts can potentially use the paint color in the glyph
75  /// atlas, so this color must be considered as part of the cache
76  /// key.
77  bool HasColor() const;
78 
79  //----------------------------------------------------------------------------
80  /// @brief The type of atlas this run should be place in.
82 
83  /// @brief Verifies that all glyphs in this text frame have computed bounds
84  /// information.
85  bool IsFrameComplete() const;
86 
87  /// @brief Retrieve the frame bounds for the glyph at [index].
88  ///
89  /// This method is only valid if [IsFrameComplete] returns true.
90  const FrameBounds& GetFrameBounds(size_t index) const;
91 
92  /// @brief If this text frame contains a single glyph (such as for an Icon),
93  /// then return it, otherwise std::nullopt.
94  std::optional<Glyph> AsSingleGlyph() const;
95 
96  /// @brief Return the font of the first glyph run.
97  const Font& GetFont() const;
98 
99  /// @brief Store text frame scale, offset, and properties for hashing in th
100  /// glyph atlas.
101  void SetPerFrameData(Rational scale,
102  Point offset,
103  const Matrix& transform,
104  std::optional<GlyphProperties> properties);
105 
106  // A generation id for the glyph atlas this text run was associated
107  // with. As long as the frame generation matches the atlas generation,
108  // the contents are guaranteed to be populated and do not need to be
109  // processed.
110  std::pair<size_t, intptr_t> GetAtlasGenerationAndID() const;
111 
112  Rational GetScale() const;
113 
114  const Matrix& GetTransform() const { return transform_; }
115 
116  fml::StatusOr<flutter::DlPath> GetPath() const;
117 
118  Point GetOffset() const;
119 
120  Matrix GetOffsetTransform() const;
121 
122  private:
124  friend class LazyGlyphAtlas;
125 
126  std::optional<GlyphProperties> GetProperties() const;
127 
128  void AppendFrameBounds(const FrameBounds& frame_bounds);
129 
130  void ClearFrameBounds();
131 
132  void SetAtlasGeneration(size_t value, intptr_t atlas_id);
133 
134  std::vector<TextRun> runs_;
135  Rect bounds_;
136  bool has_color_;
137  const PathCreator path_creator_;
138 
139  // Data that is cached when rendering the text frame and is only
140  // valid for the current atlas generation.
141  std::vector<FrameBounds> bound_values_;
142  Rational scale_ = Rational(0, 1);
143  size_t generation_ = 0;
144  intptr_t atlas_id_ = 0;
145  Point offset_;
146  std::optional<GlyphProperties> properties_;
147  Matrix transform_;
148 };
149 
150 } // namespace impeller
151 
152 #endif // FLUTTER_IMPELLER_TYPOGRAPHER_TEXT_FRAME_H_
Describes a typeface along with any modifications to its intrinsic properties.
Definition: font.h:35
Type
Describes how the glyphs are represented in the texture.
Definition: glyph_atlas.h:74
Represents a collection of shaped text runs.
Definition: text_frame.h:29
static Rational RoundScaledFontSize(Scalar scale)
Definition: text_frame.cc:55
Rect GetBounds() const
The conservative bounding box for this text frame.
Definition: text_frame.cc:27
bool IsFrameComplete() const
Verifies that all glyphs in this text frame have computed bounds information.
Definition: text_frame.cc:156
GlyphAtlas::Type GetAtlasType() const
The type of atlas this run should be place in.
Definition: text_frame.cc:39
std::optional< Glyph > AsSingleGlyph() const
If this text frame contains a single glyph (such as for an Icon), then return it, otherwise std::null...
Definition: text_frame.cc:168
bool HasColor() const
Returns the paint color this text frame was recorded with.
Definition: text_frame.cc:44
Rational GetScale() const
Definition: text_frame.cc:129
const FrameBounds & GetFrameBounds(size_t index) const
Retrieve the frame bounds for the glyph at [index].
Definition: text_frame.cc:175
const Matrix & GetTransform() const
Definition: text_frame.h:114
const Font & GetFont() const
Return the font of the first glyph run.
Definition: text_frame.cc:164
std::pair< size_t, intptr_t > GetAtlasGenerationAndID() const
Definition: text_frame.cc:180
size_t GetRunCount() const
The number of runs in this text frame.
Definition: text_frame.cc:31
Point GetOffset() const
Definition: text_frame.cc:133
void SetPerFrameData(Rational scale, Point offset, const Matrix &transform, std::optional< GlyphProperties > properties)
Store text frame scale, offset, and properties for hashing in th glyph atlas.
Definition: text_frame.cc:118
Matrix GetOffsetTransform() const
Definition: text_frame.cc:114
fml::StatusOr< flutter::DlPath > GetPath() const
Definition: text_frame.cc:149
static SubpixelPosition ComputeSubpixelPosition(const TextRun::GlyphPosition &glyph_position, AxisAlignment alignment, const Matrix &transform)
Definition: text_frame.cc:94
const std::vector< TextRun > & GetRuns() const
Returns a reference to all the text runs in this frame.
Definition: text_frame.cc:35
int32_t value
float Scalar
Definition: scalar.h:19
AxisAlignment
Determines the axis along which there is subpixel positioning.
Definition: font.h:20
std::function< fml::StatusOr< flutter::DlPath >()> PathCreator
Definition: text_frame.h:19
A 4x4 matrix using column-major storage.
Definition: matrix.h:37