CUGL 2.1
Cornell University Game Library
Public Member Functions | List of all members
cugl::SimpleExtruder Class Reference

#include <CUSimpleExtruder.h>

Public Member Functions

 SimpleExtruder ()
 
 SimpleExtruder (const std::vector< Vec2 > &points, bool closed)
 
 SimpleExtruder (const Path2 &path)
 
 ~SimpleExtruder ()
 
void setJoint (poly2::Joint joint)
 
poly2::Joint getJoint () const
 
void setEndCap (poly2::EndCap endcap)
 
poly2::EndCap getEndCap () const
 
void setTolerance (float tolerance)
 
float getTolerance () const
 
void setMitreLimit (float limit)
 
float getMitreLimit () const
 
void set (const std::vector< Vec2 > &points, bool closed)
 
void set (const Vec2 *points, size_t size, bool closed)
 
void set (const Path2 &path)
 
void reset ()
 
void clear ()
 
void calculate (float width)
 
void calculate (float lwidth, float rwidth)
 
Poly2 getPolygon () const
 
Poly2getPolygon (Poly2 *buffer) const
 
std::vector< Path2getBorder () const
 
size_t getBorder (std::vector< Path2 > &buffer) const
 
cugl::Mesh< SpriteVertex2getMesh (Color4 color) const
 
cugl::Mesh< SpriteVertex2 > * getMesh (cugl::Mesh< SpriteVertex2 > *mesh, Color4 color) const
 
cugl::Mesh< SpriteVertex2getMesh (Color4 inner, Color4 outer) const
 
cugl::Mesh< SpriteVertex2 > * getMesh (cugl::Mesh< SpriteVertex2 > *mesh, Color4 inner, Color4 outer) const
 
Vec2 getSide (Uint32 index) const
 

Detailed Description

This class is a factory for extruding paths into a solid polygon.

An extrusion of a path is a polygon that follows the path but gives it width. Hence it takes a path and turns it into a solid shape. This is more complicated than simply triangulating the original path. The new polygon has more vertices, depending on the choice of joint (shape at the corners) and cap (shape at the end).

This class is significantly faster than ComplexExtruder. It guarantees sub-millisecond performance for most applications (even thousands of vertices), and so it can be used at framerate. However, this speed comes at significant cost percision. In particular, the Poly2 object created has overlapping triangles, as the algorithm makes no effort to detecting crossing or overlaps. While this is fine for drawing the extrusion with a scene2::PathNode, it is not accurate for high precision geometry computations. In particular, it will not provide an accurate picture of the boundary. For a geometrically accurate extrusion, you should use ComplexExtruder instead.

One advantage of this tool has over ComplexExtruder is that it keeps track of the left and right sides of the extrusion at all times (which is only possible since overlaps are preserved). This information can be abstracted and used to properly fade or texture the stroke.

As with all factories, the methods are broken up into three phases: initialization, calculation, and materialization. To use the factory, you first set the data (in this case a set of vertices or Path2 object) with the initialization methods. You then call the calculation method. Finally, you use the materialization methods to access the data in several different ways.

This division allows us to support multithreaded calculation if the data generation takes too long. However, note that this factory is not thread safe in that you cannot access data while it is still in mid-calculation.

CREDITS: This code heavily inspired by NanoVG by Mikko Mononen (memon.nosp@m.@ins.nosp@m.ide.o.nosp@m.rg), and the bulk of the algorithm is taken from that code. However it is has been altered and optimized according to extensive profiling.

Constructor & Destructor Documentation

◆ SimpleExtruder() [1/3]

cugl::SimpleExtruder::SimpleExtruder ( )

Creates an extruder with no vertex data.

◆ SimpleExtruder() [2/3]

cugl::SimpleExtruder::SimpleExtruder ( const std::vector< Vec2 > &  points,
bool  closed 
)

Creates an extruder with the given path.

The path data is copied. The extruder does not retain any references to the original data.

Parameters
pointsThe path to extrude
closedWhether the path is closed

◆ SimpleExtruder() [3/3]

cugl::SimpleExtruder::SimpleExtruder ( const Path2 path)

Creates an extruder with the given path.

The path data is copied. The extruder does not retain any references to the original data.

Parameters
pathThe path to extrude

◆ ~SimpleExtruder()

cugl::SimpleExtruder::~SimpleExtruder ( )

Deletes this extruder, releasing all resources.

Member Function Documentation

◆ calculate() [1/2]

void cugl::SimpleExtruder::calculate ( float  lwidth,
float  rwidth 
)

Performs an asymmetric extrusion of the current path data.

An extrusion of a path is a polygon that follows the path but gives it width. Hence it takes a path and turns it into a solid shape. This is more complicated than simply triangulating the original path. The new polygon has more vertices, depending on the choice of joint (shape at the corners) and cap (shape at the end).

This version of the method allows you to specify the left and right side widths independently. In particular, this allows us to define an "half extrusion" that starts from the center line.

Parameters
lwidthThe width of the left side of the extrusion
rwidthThe width of the right side of the extrusion

◆ calculate() [2/2]

void cugl::SimpleExtruder::calculate ( float  width)
inline

Performs a extrusion of the current path data.

An extrusion of a path is a polygon that follows the path but gives it width. Hence it takes a path and turns it into a solid shape. This is more complicated than simply triangulating the original path. The new polygon has more vertices, depending on the choice of joint (shape at the corners) and cap (shape at the end).

The stroke width is measured from the left side of the extrusion to the right side of the extrusion. So a stroke of width 20 is actually 10 pixels from the center on each side.

Parameters
widthThe stroke width of the extrusion

◆ clear()

void cugl::SimpleExtruder::clear ( )

Clears all internal data, including initial path data.

When this method is called, you will need to set a new path before calling calculate. However, the joint, cap, and tolerance settings are preserved.

◆ getBorder() [1/2]

std::vector<Path2> cugl::SimpleExtruder::getBorder ( ) const

Returns a (closed) path representing the extrusion border(s)

So long as the calculation is complete, the vector is guaranteed to contain at least one path. Counter-clockwise paths correspond to the exterior boundary of the stroke. Clockwise paths are potential holes in the extrusion. There is no guarantee on the order of the returned paths.

If the calculation is not yet performed, this method will return the empty path.

Returns
a (closed) path representing the extrusion border

◆ getBorder() [2/2]

size_t cugl::SimpleExtruder::getBorder ( std::vector< Path2 > &  buffer) const

Stores a (closed) path representing the extrusion border in the buffer

So long as the calculation is complete, the vector is guaranteed to contain at least one path. Counter-clockwise paths correspond to the exterior boundary of the stroke. Clockwise paths are potential holes in the extrusion. There is no guarantee on the order of the returned paths.

This method will append append its results to the provided buffer. It will not erase any existing data. You should clear the buffer first if you do not want to preserve the original data.

If the calculation is not yet performed, this method will do nothing.

Parameters
bufferThe buffer to store the path around the extrusion
Returns
the number of elements added to the buffer

◆ getEndCap()

poly2::EndCap cugl::SimpleExtruder::getEndCap ( ) const
inline

Returns the end cap value for the extrusion.

The end cap type determines how the extrusion draws the ends of the line segments at the start and end of the path. See poly2::EndCap for the description of the types.

Returns
the end cap value for the extrusion.

◆ getJoint()

poly2::Joint cugl::SimpleExtruder::getJoint ( ) const
inline

Returns the joint value for the extrusion.

The joint type determines how the extrusion joins the extruded line segments together. See poly2::Joint for the description of the types.

Returns
the joint value for the extrusion.

◆ getMesh() [1/4]

cugl::Mesh<SpriteVertex2> cugl::SimpleExtruder::getMesh ( Color4  color) const

Returns a mesh representing the path extrusion.

This method creates a triangular mesh with the vertices of the extrusion, coloring each vertex white. However, if fringe is set to true, then each vertex will instead be colored clear (transparent), unless that vertex is on a zero-width side. This effect can be used to produce border "fringes" around a polygon for anti-aliasing.

If the calculation is not yet performed, this method will return the empty mesh.

Returns
a mesh representing the path extrusion.

◆ getMesh() [2/4]

cugl::Mesh<SpriteVertex2> cugl::SimpleExtruder::getMesh ( Color4  inner,
Color4  outer 
) const

Returns a mesh representing the path extrusion.

This method creates a triangular mesh with the vertices of the extrusion, coloring each vertex white. However, if fringe is set to true, then each vertex will instead be colored clear (transparent), unless that vertex is on a zero-width side. This effect can be used to produce border "fringes" around a polygon for anti-aliasing.

If the calculation is not yet performed, this method will return the empty mesh.

Returns
a mesh representing the path extrusion.

◆ getMesh() [3/4]

cugl::Mesh<SpriteVertex2>* cugl::SimpleExtruder::getMesh ( cugl::Mesh< SpriteVertex2 > *  mesh,
Color4  color 
) const

Stores a mesh representing the path extrusion in the given buffer

This method will add both the new vertices, and the corresponding indices to the buffer. If the buffer is not empty, the indices will be adjusted accordingly. You should clear the buffer first if you do not want to preserve the original data.

The vertices in this mesh will be colored white by default. However, if fringe is set to true, then each vertex will instead be colored clear (transparent), unless that vertex is on a zero-width side. This effect can be used to produce border "fringes" around a polygon for anti-aliasing.

If the calculation is not yet performed, this method will do nothing.

Parameters
meshThe buffer to store the extruded path mesh
colorThe default mesh color
Returns
a reference to the buffer for chaining.

◆ getMesh() [4/4]

cugl::Mesh<SpriteVertex2>* cugl::SimpleExtruder::getMesh ( cugl::Mesh< SpriteVertex2 > *  mesh,
Color4  inner,
Color4  outer 
) const

Stores a mesh representing the path extrusion in the given buffer

This method will add both the new vertices, and the corresponding indices to the buffer. If the buffer is not empty, the indices will be adjusted accordingly. You should clear the buffer first if you do not want to preserve the original data.

The vertices in this mesh will be colored white by default. However, if fringe is set to true, then each vertex will instead be colored clear (transparent), unless that vertex is on a zero-width side. This effect can be used to produce border "fringes" around a polygon for anti-aliasing.

If the calculation is not yet performed, this method will do nothing.

Parameters
meshThe buffer to store the extruded path mesh
innerThe interior mesh color
outerThe exterior mesh color
Returns
a reference to the buffer for chaining.

◆ getMitreLimit()

float cugl::SimpleExtruder::getMitreLimit ( ) const
inline

Returns the mitre limit of the extrusion.

The mitre limit sets how "pointy" a mitre joint is allowed to be before the algorithm switches it back to a bevel/square joint. Small angles can have very large mitre offsets that go way off-screen.

To determine whether to switch a miter to a bevel, the algorithm will take the two vectors at this joint, normalize them, and then average them. It will multiple the magnitude of that vector by the mitre limit. If that value is less than 1.0, it will switch to a bevel. By default this value is 10.0.

Returns
the mitre limit for joint calculations

◆ getPolygon() [1/2]

Poly2 cugl::SimpleExtruder::getPolygon ( ) const

Returns a polygon representing the path extrusion.

The polygon contains the new set of vertices together with the indices defining the extrusion path. The extruder does not maintain references to this polygon and it is safe to modify it.

If the calculation is not yet performed, this method will return the empty polygon.

Returns
a polygon representing the path extrusion.

◆ getPolygon() [2/2]

Poly2* cugl::SimpleExtruder::getPolygon ( Poly2 buffer) const

Stores the path extrusion in the given buffer.

This method will add both the new vertices, and the corresponding indices to the buffer. If the buffer is not empty, the indices will be adjusted accordingly. You should clear the buffer first if you do not want to preserve the original data.

If the calculation is not yet performed, this method will do nothing.

Parameters
bufferThe buffer to store the extruded path
Returns
a reference to the buffer for chaining.

◆ getSide()

Vec2 cugl::SimpleExtruder::getSide ( Uint32  index) const

Returns the side information for the vertex at the given index

The side information is a two dimensional vector. The x-coordinate indicates left vs. right side. A value of -1 is on the left while 1 is on the right. A value of 0 means an interior node sitting on the path itself.

On the other hand the y-coordinate indicates cap positioning for an open curve. A value of -1 is on the start cap. A value of 1 is on the end cap. 0 values lie along the body of the main curve.

It is possible to have intermediate cap values for both left-right and start-end in the case of rounded caps. In this case, the intermediate value tracks the traversal from one side to another.

Parameters
indexThe vertex index
Returns
the side information for the vertex at the given index

◆ getTolerance()

float cugl::SimpleExtruder::getTolerance ( ) const
inline

Returns the error tolerance of the extrusion.

This value is mostly used to determine the number of segments needed for a rounded joint or endcap. The default value is 0.25f.

Returns
the error tolerance of the extrusion.

◆ reset()

void cugl::SimpleExtruder::reset ( )

Clears all computed data, but still maintains the settings.

This method preserves all initial path data, as well as the joint, cap, and tolerance settings.

◆ set() [1/3]

void cugl::SimpleExtruder::set ( const Path2 path)

Sets the path for this extruder.

The path data is copied. The extruder does not retain any references to the original data.

This method resets all interal data. You will need to reperform the calculation before accessing data.

Parameters
pathThe path to extrude

◆ set() [2/3]

void cugl::SimpleExtruder::set ( const std::vector< Vec2 > &  points,
bool  closed 
)

Sets the path for this extruder.

The path data is copied. The extruder does not retain any references to the original data. All points will be considered to be corner points.

This method resets all interal data. You will need to reperform the calculation before accessing data.

Parameters
pointsThe path to extrude
closedWhether the path is closed

◆ set() [3/3]

void cugl::SimpleExtruder::set ( const Vec2 points,
size_t  size,
bool  closed 
)

Sets the path for this extruder.

The path data is copied. The extruder does not retain any references to the original data. All points will be considered to be corner points.

This method resets all interal data. You will need to reperform the calculation before accessing data.

Parameters
pointsThe path to extrude
sizeThe number of points
closedWhether the path is closed

◆ setEndCap()

void cugl::SimpleExtruder::setEndCap ( poly2::EndCap  endcap)
inline

Sets the end cap value for the extrusion.

The end cap type determines how the extrusion draws the ends of the line segments at the start and end of the path. See poly2::EndCap for the description of the types.

Parameters
endcapThe extrusion end cap type

◆ setJoint()

void cugl::SimpleExtruder::setJoint ( poly2::Joint  joint)
inline

Sets the joint value for the extrusion.

The joint type determines how the extrusion joins the extruded line segments together. See poly2::Joint for the description of the types.

Parameters
jointThe extrusion joint type

◆ setMitreLimit()

void cugl::SimpleExtruder::setMitreLimit ( float  limit)
inline

Sets the mitre limit of the extrusion.

The mitre limit sets how "pointy" a mitre joint is allowed to be before the algorithm switches it back to a bevel/square joint. Small angles can have very large mitre offsets that go way off-screen.

To determine whether to switch a miter to a bevel, the algorithm will take the two vectors at this joint, normalize them, and then average them. It will multiple the magnitude of that vector by the mitre limit. If that value is less than 1.0, it will switch to a bevel. By default this value is 10.0.

Parameters
limitThe mitre limit for joint calculations

◆ setTolerance()

void cugl::SimpleExtruder::setTolerance ( float  tolerance)
inline

Sets the error tolerance of the extrusion.

This value is mostly used to determine the number of segments needed for a rounded joint or endcap. The default value is 0.25f.

Parameters
toleranceThe error tolerance of the extrusion.

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