CUGL 2.0
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 Poly2 &poly)
 
 ~SimpleExtruder ()
 
void set (const std::vector< Vec2 > &points, bool closed)
 
void set (const Poly2 &poly)
 
void setJoint (poly2::Joint joint)
 
poly2::Joint getJoint () const
 
void setEndCap (poly2::EndCap endcap)
 
poly2::EndCap getEndCap () const
 
void setPrecision (Uint32 precision)
 
Uint32 getPrecision () const
 
void reset ()
 
void clear ()
 
void calculate (float stroke)
 
Poly2 getPolygon ()
 
Poly2getPolygon (Poly2 *buffer)
 

Detailed Description

This class is a factory for extruding wireframe paths into a solid path.

An extrusion of a path is a second polygon that follows the path of the first one, 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 polygon. 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, and can be reasonably used at framerate. However, this speed comes at significant cost in flexibility. In particular, the Poly2 created has overlapping triangles (as the algorithm makes no effort to detecting crossing or overlaps). While this is fine if the polygon is drawn with a solid color, it will not look correct if the polygon is drawn with any transparency at all. For an accurate extrusion when transparency is necessary, you should use ComplexExtruder instead.

On the other hand, you can get around this problem by drawing the polygon with a solid (non-transparent) color to a texture, and then applying transparency to the texture. This is the preferred way to handle transparency if you need extrusion at framerate (such as when you are drawing the path of a finger).

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 another Poly2) 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 is ported from the Kivy implementation of Line in package kivy.vertex_instructions. We believe that this port is acceptable within the scope of the Kivy license. There are no specific credits in that file, so there is no one specific to credit. However, thanks to the Kivy team for doing the heavy lifting on this method.

Because they did all the hard work, we will recommend their picture of how joints and end caps work:

 http://kivy.org/docs/_images/line-instruction.png

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 vertex data.

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

Parameters
pointsThe vertices to extrude
closedWhether the path is closed

◆ SimpleExtruder() [3/3]

cugl::SimpleExtruder::SimpleExtruder ( const Poly2 poly)

Creates an extruder with the given vertex data.

The polygon must have geometry IMPLICIT or PATH. If it is IMPLICIT, it assumes the polygon is closed. Otherwise, it uses the indices to define the path. However, the path must be continuous. If the method detects a discontinuity in the path, it will only use the first component. Unconnected components should be extruded separately.

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

Parameters
polyThe vertices to extrude

◆ ~SimpleExtruder()

cugl::SimpleExtruder::~SimpleExtruder ( )
inline

Deletes this extruder, releasing all resources.

Member Function Documentation

◆ calculate()

void cugl::SimpleExtruder::calculate ( float  stroke)

Performs a extrusion of the current vertex data.

An extrusion of a polygon is a second polygon that follows the path of the first one, 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 polygon. The new polygon has more vertices, depending on the choice of joint (shape at the corners) and cap (shape at the end).

CREDITS: This code is ported from the Kivy implementation of Line in package kivy.vertex_instructions. We believe that this port is acceptable within the scope of the Kivy license. There are no specific credits in that file, so there is no one specific to credit. However, thanks to the Kivy team for doing the heavy lifting on this method.

Because they did all the hard work, we will plug their picture of how joints and end caps work:

 http://kivy.org/docs/_images/line-instruction.png
Parameters
strokeThe stroke width of the extrusion

◆ clear()

void cugl::SimpleExtruder::clear ( )

Clears all internal data, including initial vertex data.

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

◆ 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.

◆ getPolygon() [1/2]

Poly2 cugl::SimpleExtruder::getPolygon ( )

Returns a polygon representing the path extrusion.

The polygon contains the a completely 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)

Stores the path extrusion in the given buffer.

This method will add both the new vertices, and the corresponding indices to the new 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 polygon
Returns
a reference to the buffer for chaining.

◆ getPrecision()

Uint32 cugl::SimpleExtruder::getPrecision ( ) const
inline

Returns the precision for rounded caps and joints.

Rounded joints and caps are created as a polygon fan, just as all rounded shapes are. The precision is the number of polygons in the fan for each joint and each end cap. A lower number will result in less smooth joints/caps and is particular visible in strokes of large width. By default this value is 10.

Returns
the precision for rounded caps and joints.

◆ reset()

void cugl::SimpleExtruder::reset ( )

Clears all computed data, but still maintains the settings.

This method preserves all initial vertex data, as well as the joint, cap, and precision settings.

◆ set() [1/2]

void cugl::SimpleExtruder::set ( const Poly2 poly)

Sets the vertex data for this extruder.

The polygon must have geometry IMPLICIT or PATH. If it is IMPLICIT, it assumes the polygon is closed. Otherwise, it uses the indices to define the path. However, the path must be continuous. If the method detects a discontinuity in the path, it will only use the first component. Unconnected components should be extruded separately.

The vertex data is copied. The extruder does not retain any references to the original data. The method assumes the polygon is closed if the number of indices is twice the number of vertices.

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

Parameters
polyThe vertices to extrude

◆ set() [2/2]

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

Sets the vertex data for this extruder.

The vertex 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
pointsThe vertices to extruder
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

◆ setPrecision()

void cugl::SimpleExtruder::setPrecision ( Uint32  precision)
inline

Sets the precision for rounded caps and joints.

Rounded joints and caps are created as a polygon fan, just as all rounded shapes are. The precision is the number of polygons in the fan for each joint and each end cap. A lower number will result in less smooth joints/caps and is particular visible in strokes of large width. By default this value is 10.

Parameters
precisionThe precision for rounded caps and joints.

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