impeller::Tessellator Class Reference

A utility that generates triangles of the specified fill type given a polyline. This happens on the CPU. More...

#include <tessellator.h>

Classes
class	EllipticalVertexGenerator
	The |VertexGenerator| implementation common to all shapes that are based on a polygonal representation of an ellipse. More...
class	VertexGenerator
	An object which produces a list of vertices as |Point|s that tessellate a previously provided shape and delivers the vertices through a |TessellatedVertexProc| callback. More...

Public Types
enum	Result {   Result::kSuccess,   Result::kInputError,   Result::kTessellationError }
using	TessellatedVertexProc = std::function< void(const Point &p)>
	A callback function for a |VertexGenerator| to deliver the vertices it computes as |Point| objects. More...
using	BuilderCallback = std::function< bool(const float *vertices, size_t vertices_count, const uint16_t *indices, size_t indices_count)>
	A callback that returns the results of the tessellation. More...

Public Member Functions
	Tessellator ()
	~Tessellator ()
Tessellator::Result	Tessellate (const Path &path, Scalar tolerance, const BuilderCallback &callback)
	Generates filled triangles from the path. A callback is invoked once for the entire tessellation. More...
std::vector< Point >	TessellateConvex (const Path &path, Scalar tolerance)
	Given a convex path, create a triangle fan structure. More...
EllipticalVertexGenerator	FilledCircle (const Matrix &view_transform, const Point &center, Scalar radius)
	Create a |VertexGenerator| that can produce vertices for a filled circle of the given radius around the given center with enough polygon sub-divisions to provide reasonable fidelity when viewed under the given view transform. More...
EllipticalVertexGenerator	StrokedCircle (const Matrix &view_transform, const Point &center, Scalar radius, Scalar half_width)
	Create a |VertexGenerator| that can produce vertices for a stroked circle of the given radius and half_width around the given shared center with enough polygon sub-divisions to provide reasonable fidelity when viewed under the given view transform. The outer edge of the stroked circle is generated at (radius + half_width) and the inner edge is generated at (radius - half_width). More...
EllipticalVertexGenerator	RoundCapLine (const Matrix &view_transform, const Point &p0, const Point &p1, Scalar radius)
	Create a |VertexGenerator| that can produce vertices for a line with round end caps of the given radius with enough polygon sub-divisions to provide reasonable fidelity when viewed under the given view transform. More...
EllipticalVertexGenerator	FilledEllipse (const Matrix &view_transform, const Rect &bounds)
	Create a |VertexGenerator| that can produce vertices for a filled ellipse inscribed within the given bounds with enough polygon sub-divisions to provide reasonable fidelity when viewed under the given view transform. More...
EllipticalVertexGenerator	FilledRoundRect (const Matrix &view_transform, const Rect &bounds, const Size &radii)
	Create a |VertexGenerator| that can produce vertices for a filled round rect within the given bounds and corner radii with enough polygon sub-divisions to provide reasonable fidelity when viewed under the given view transform. More...

Static Public Attributes
static constexpr Scalar	kCircleTolerance = 0.1f
	The pixel tolerance used by the algorighm to determine how many divisions to create for a circle. More...

Detailed Description

A utility that generates triangles of the specified fill type given a polyline. This happens on the CPU.

This object is not thread safe, and its methods must not be called from multiple threads.

Definition at line 39 of file tessellator.h.

Member Typedef Documentation

BuilderCallback

using impeller::Tessellator::BuilderCallback = std::function<bool(const float* vertices, size_t vertices_count, const uint16_t* indices, size_t indices_count)>

A callback that returns the results of the tessellation.

   The index buffer may not be populated, in which case [indices] will
   be nullptr and indices_count will be 0. 

Definition at line 189 of file tessellator.h.

TessellatedVertexProc

using impeller::Tessellator::TessellatedVertexProc = std::function<void(const Point& p)>

A callback function for a |VertexGenerator| to deliver the vertices it computes as |Point| objects.

Definition at line 86 of file tessellator.h.

Member Enumeration Documentation

Result

enum impeller::Tessellator::Result

strong

Enumerator
kSuccess
kInputError
kTessellationError

Definition at line 78 of file tessellator.h.

                    {
    kSuccess,
    kInputError,
    kTessellationError,
  };

Constructor & Destructor Documentation

Tessellator()

impeller::Tessellator::Tessellator

(

)

Definition at line 34 of file tessellator.cc.

    : point_buffer_(std::make_unique<std::vector<Point>>()),
      c_tessellator_(nullptr, &DestroyTessellator) {
  point_buffer_->reserve(2048);
  TESSalloc alloc = kAlloc;
  {
    // libTess2 copies the TESSalloc despite the non-const argument.
    CTessellator tessellator(::tessNewTess(&alloc), &DestroyTessellator);
    c_tessellator_ = std::move(tessellator);
  }
}

References impeller::DestroyTessellator(), and impeller::kAlloc.

~Tessellator()

impeller::Tessellator::~Tessellator ( )

default

Member Function Documentation

FilledCircle()

EllipticalVertexGenerator impeller::Tessellator::FilledCircle	(	const Matrix &	view_transform,
		const Point &	center,
		Scalar	radius
	)

Create a |VertexGenerator| that can produce vertices for a filled circle of the given radius around the given center with enough polygon sub-divisions to provide reasonable fidelity when viewed under the given view transform.

Note that the view transform is only used to choose the number of sample points to use per quarter circle and the returned points are not transformed by it, instead they are relative to the coordinate space of the center point.

Definition at line 390 of file tessellator.cc.

                   {
  auto divisions =
      ComputeQuadrantDivisions(view_transform.GetMaxBasisLength() * radius);
  return EllipticalVertexGenerator(Tessellator::GenerateFilledCircle,
                                   GetTrigsForDivisions(divisions),
                                   PrimitiveType::kTriangleStrip, 4,
                                   {
                                       .reference_centers = {center, center},
                                       .radii = {radius, radius},
                                       .half_width = -1.0f,
                                   });
}

References impeller::ComputeQuadrantDivisions(), and impeller::Matrix::GetMaxBasisLength().

FilledEllipse()

EllipticalVertexGenerator impeller::Tessellator::FilledEllipse	(	const Matrix &	view_transform,
		const Rect &	bounds
	)

Create a |VertexGenerator| that can produce vertices for a filled ellipse inscribed within the given bounds with enough polygon sub-divisions to provide reasonable fidelity when viewed under the given view transform.

Note that the view transform is only used to choose the number of sample points to use per quarter circle and the returned points are not transformed by it, instead they are relative to the coordinate space of the bounds.

Definition at line 450 of file tessellator.cc.

                        {
  if (bounds.IsSquare()) {
    return FilledCircle(view_transform, bounds.GetCenter(),
                        bounds.GetWidth() * 0.5f);
  }
  auto max_radius = bounds.GetSize().MaxDimension();
  auto divisions =
      ComputeQuadrantDivisions(view_transform.GetMaxBasisLength() * max_radius);
  auto center = bounds.GetCenter();
  return EllipticalVertexGenerator(Tessellator::GenerateFilledEllipse,
                                   GetTrigsForDivisions(divisions),
                                   PrimitiveType::kTriangleStrip, 4,
                                   {
                                       .reference_centers = {center, center},
                                       .radii = bounds.GetSize() * 0.5f,
                                       .half_width = -1.0f,
                                   });
}

References impeller::ComputeQuadrantDivisions(), impeller::TRect< T >::GetCenter(), impeller::Matrix::GetMaxBasisLength(), impeller::TRect< T >::GetSize(), impeller::TRect< T >::GetWidth(), impeller::TRect< T >::IsSquare(), and impeller::TSize< T >::MaxDimension().

FilledRoundRect()

EllipticalVertexGenerator impeller::Tessellator::FilledRoundRect	(	const Matrix &	view_transform,
		const Rect &	bounds,
		const Size &	radii
	)

Create a |VertexGenerator| that can produce vertices for a filled round rect within the given bounds and corner radii with enough polygon sub-divisions to provide reasonable fidelity when viewed under the given view transform.

Note that the view transform is only used to choose the number of sample points to use per quarter circle and the returned points are not transformed by it, instead they are relative to the coordinate space of the bounds.

Definition at line 471 of file tessellator.cc.

                       {
  if (radii.width * 2 < bounds.GetWidth() ||
      radii.height * 2 < bounds.GetHeight()) {
    auto max_radius = radii.MaxDimension();
    auto divisions = ComputeQuadrantDivisions(
        view_transform.GetMaxBasisLength() * max_radius);
    auto upper_left = bounds.GetLeftTop() + radii;
    auto lower_right = bounds.GetRightBottom() - radii;
    return EllipticalVertexGenerator(Tessellator::GenerateFilledRoundRect,
                                     GetTrigsForDivisions(divisions),
                                     PrimitiveType::kTriangleStrip, 4,
                                     {
                                         .reference_centers =
                                             {
                                                 upper_left,
                                                 lower_right,
                                             },
                                         .radii = radii,
                                         .half_width = -1.0f,
                                     });
  } else {
    return FilledEllipse(view_transform, bounds);
  }
}

References impeller::ComputeQuadrantDivisions(), impeller::TRect< T >::GetHeight(), impeller::TRect< T >::GetLeftTop(), impeller::Matrix::GetMaxBasisLength(), impeller::TRect< T >::GetRightBottom(), impeller::TRect< T >::GetWidth(), impeller::TSize< T >::height, impeller::TSize< T >::MaxDimension(), and impeller::TSize< T >::width.

RoundCapLine()

EllipticalVertexGenerator impeller::Tessellator::RoundCapLine	(	const Matrix &	view_transform,
		const Point &	p0,
		const Point &	p1,
		Scalar	radius
	)

Create a |VertexGenerator| that can produce vertices for a line with round end caps of the given radius with enough polygon sub-divisions to provide reasonable fidelity when viewed under the given view transform.

Note that the view transform is only used to choose the number of sample points to use per quarter circle and the returned points are not transformed by it, instead they are relative to the coordinate space of the two points.

Definition at line 427 of file tessellator.cc.

                   {
  auto along = p1 - p0;
  auto length = along.GetLength();
  if (length > kEhCloseEnough) {
    auto divisions =
        ComputeQuadrantDivisions(view_transform.GetMaxBasisLength() * radius);
    return EllipticalVertexGenerator(Tessellator::GenerateRoundCapLine,
                                     GetTrigsForDivisions(divisions),
                                     PrimitiveType::kTriangleStrip, 4,
                                     {
                                         .reference_centers = {p0, p1},
                                         .radii = {radius, radius},
                                         .half_width = -1.0f,
                                     });
  } else {
    return FilledCircle(view_transform, p0, radius);
  }
}

References impeller::ComputeQuadrantDivisions(), impeller::TPoint< T >::GetLength(), impeller::Matrix::GetMaxBasisLength(), and impeller::kEhCloseEnough.

StrokedCircle()

EllipticalVertexGenerator impeller::Tessellator::StrokedCircle	(	const Matrix &	view_transform,
		const Point &	center,
		Scalar	radius,
		Scalar	half_width
	)

Create a |VertexGenerator| that can produce vertices for a stroked circle of the given radius and half_width around the given shared center with enough polygon sub-divisions to provide reasonable fidelity when viewed under the given view transform. The outer edge of the stroked circle is generated at (radius + half_width) and the inner edge is generated at (radius - half_width).

Note that the view transform is only used to choose the number of sample points to use per quarter circle and the returned points are not transformed by it, instead they are relative to the coordinate space of the center point.

Definition at line 406 of file tessellator.cc.

                       {
  if (half_width > 0) {
    auto divisions = ComputeQuadrantDivisions(
        view_transform.GetMaxBasisLength() * radius + half_width);
    return EllipticalVertexGenerator(Tessellator::GenerateStrokedCircle,
                                     GetTrigsForDivisions(divisions),
                                     PrimitiveType::kTriangleStrip, 8,
                                     {
                                         .reference_centers = {center, center},
                                         .radii = {radius, radius},
                                         .half_width = half_width,
                                     });
  } else {
    return FilledCircle(view_transform, center, radius);
  }
}

References impeller::ComputeQuadrantDivisions(), and impeller::Matrix::GetMaxBasisLength().

Tessellate()

Tessellator::Result impeller::Tessellator::Tessellate	(	const Path &	path,
		Scalar	tolerance,
		const BuilderCallback &	callback
	)

Generates filled triangles from the path. A callback is invoked once for the entire tessellation.

Parameters

[in]	path	The path to tessellate.
[in]	tolerance	The tolerance value for conversion of the path to a polyline. This value is often derived from the Matrix::GetMaxBasisLength of the CTM applied to the path for rendering.
[in]	callback	The callback, return false to indicate failure.

Returns

The result status of the tessellation.

Feed contour information to the tessellator.

Let's tessellate.

Definition at line 64 of file tessellator.cc.

                                                                             {
  if (!callback) {
    return Result::kInputError;
  }
 
  point_buffer_->clear();
  auto polyline =
      path.CreatePolyline(tolerance, std::move(point_buffer_),
                          [this](Path::Polyline::PointBufferPtr point_buffer) {
                            point_buffer_ = std::move(point_buffer);
                          });
 
  auto fill_type = path.GetFillType();
 
  if (polyline.points->empty()) {
    return Result::kInputError;
  }
 
  auto tessellator = c_tessellator_.get();
  if (!tessellator) {
    return Result::kTessellationError;
  }
 
  constexpr int kVertexSize = 2;
  constexpr int kPolygonSize = 3;
 
  //----------------------------------------------------------------------------
  /// Feed contour information to the tessellator.
  ///
  static_assert(sizeof(Point) == 2 * sizeof(float));
  for (size_t contour_i = 0; contour_i < polyline.contours.size();
       contour_i++) {
    size_t start_point_index, end_point_index;
    std::tie(start_point_index, end_point_index) =
        polyline.GetContourPointBounds(contour_i);
 
    ::tessAddContour(tessellator,  // the C tessellator
                     kVertexSize,  //
                     polyline.points->data() + start_point_index,  //
                     sizeof(Point),                                //
                     end_point_index - start_point_index           //
    );
  }
 
  //----------------------------------------------------------------------------
  /// Let's tessellate.
  ///
  auto result = ::tessTesselate(tessellator,                   // tessellator
                                ToTessWindingRule(fill_type),  // winding
                                TESS_POLYGONS,                 // element type
                                kPolygonSize,                  // polygon size
                                kVertexSize,                   // vertex size
                                nullptr  // normal (null is automatic)
  );
 
  if (result != 1) {
    return Result::kTessellationError;
  }
 
  int element_item_count = tessGetElementCount(tessellator) * kPolygonSize;
 
  // We default to using a 16bit index buffer, but in cases where we generate
  // more tessellated data than this can contain we need to fall back to
  // dropping the index buffer entirely. Instead code could instead switch to
  // a uint32 index buffer, but this is done for simplicity with the other
  // fast path above.
  if (element_item_count < USHRT_MAX) {
    int vertex_item_count = tessGetVertexCount(tessellator);
    auto vertices = tessGetVertices(tessellator);
    auto elements = tessGetElements(tessellator);
 
    // libtess uses an int index internally due to usage of -1 as a sentinel
    // value.
    std::vector<uint16_t> indices(element_item_count);
    for (int i = 0; i < element_item_count; i++) {
      indices[i] = static_cast<uint16_t>(elements[i]);
    }
    if (!callback(vertices, vertex_item_count, indices.data(),
                  element_item_count)) {
      return Result::kInputError;
    }
  } else {
    std::vector<Point> points;
    std::vector<float> data;
 
    int vertex_item_count = tessGetVertexCount(tessellator) * kVertexSize;
    auto vertices = tessGetVertices(tessellator);
    points.reserve(vertex_item_count);
    for (int i = 0; i < vertex_item_count; i += 2) {
      points.emplace_back(vertices[i], vertices[i + 1]);
    }
 
    int element_item_count = tessGetElementCount(tessellator) * kPolygonSize;
    auto elements = tessGetElements(tessellator);
    data.reserve(element_item_count);
    for (int i = 0; i < element_item_count; i++) {
      data.emplace_back(points[elements[i]].x);
      data.emplace_back(points[elements[i]].y);
    }
    if (!callback(data.data(), element_item_count, nullptr, 0u)) {
      return Result::kInputError;
    }
  }
 
  return Result::kSuccess;
}

References impeller::Path::CreatePolyline(), impeller::Path::GetFillType(), kInputError, kSuccess, kTessellationError, and impeller::ToTessWindingRule().

Referenced by impeller::BM_Polyline(), impeller::Tessellate(), impeller::testing::TEST(), and impeller::testing::TEST_P().

TessellateConvex()

std::vector< Point > impeller::Tessellator::TessellateConvex	(	const Path &	path,
		Scalar	tolerance
	)

Given a convex path, create a triangle fan structure.

Parameters

[in]	path	The path to tessellate.
[in]	tolerance	The tolerance value for conversion of the path to a polyline. This value is often derived from the Matrix::GetMaxBasisLength of the CTM applied to the path for rendering.

Returns

A point vector containing the vertices in triangle strip format.

Definition at line 173 of file tessellator.cc.

                                                                   {
  std::vector<Point> output;
 
  point_buffer_->clear();
  auto polyline =
      path.CreatePolyline(tolerance, std::move(point_buffer_),
                          [this](Path::Polyline::PointBufferPtr point_buffer) {
                            point_buffer_ = std::move(point_buffer);
                          });
 
  output.reserve(polyline.points->size() +
                 (4 * (polyline.contours.size() - 1)));
  for (auto j = 0u; j < polyline.contours.size(); j++) {
    auto [start, end] = polyline.GetContourPointBounds(j);
    auto first_point = polyline.GetPoint(start);
 
    // Some polygons will not self close and an additional triangle
    // must be inserted, others will self close and we need to avoid
    // inserting an extra triangle.
    if (polyline.GetPoint(end - 1) == first_point) {
      end--;
    }
 
    if (j > 0) {
      // Triangle strip break.
      output.emplace_back(output.back());
      output.emplace_back(first_point);
      output.emplace_back(first_point);
    } else {
      output.emplace_back(first_point);
    }
 
    size_t a = start + 1;
    size_t b = end - 1;
    while (a < b) {
      output.emplace_back(polyline.GetPoint(a));
      output.emplace_back(polyline.GetPoint(b));
      a++;
      b--;
    }
    if (a == b) {
      output.emplace_back(polyline.GetPoint(a));
    }
  }
  return output;
}

References impeller::Path::CreatePolyline(), and impeller::Path::Polyline::GetContourPointBounds().

Referenced by impeller::BM_Convex(), and impeller::testing::TEST().

Member Data Documentation

kCircleTolerance

constexpr Scalar impeller::Tessellator::kCircleTolerance = 0.1f

staticconstexpr

The pixel tolerance used by the algorighm to determine how many divisions to create for a circle.

No point on the polygon of vertices should deviate from the true circle by more than this tolerance.

Definition at line 226 of file tessellator.h.

Referenced by impeller::ComputeQuadrantDivisions(), and impeller::testing::TEST().

---

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

• impeller/tessellator/tessellator.h
• impeller/tessellator/tessellator.cc