Module libtess2
Corona binding for libtess2, a polygon tessellator and triangulator.
To use the plugin, add the following in build.settings
:
plugins = {
["plugin.libtess2"] = { publisherId = "com.xibalbastudios" }
}
Sample code is available here.
The Bytes type—specified in a few of the bytemap methods—may be any object that implements ByteReader, including strings.
An overview of the algorithm is available here.
Adapted from the original project:
Version 1.0.1
This is a refactored version of the original libtess which comes with the GLU reference implementation. The code is a good quality polygon tessellator and triangulator. The original code comes with a rather horrible interface and its performance suffers from lots of small memory allocations. The main point of the refactoring has been the interface and memory allocation scheme.
A lot of the GLU tessellator documentation applies to libtess2 as well, apart from the API; check out Chapter 11. See also here.
A simple bucketed memory allocator (see Graphics Gems III for reference) was added which speeds up the code by order of magnitude (tests showed 15 to 50 times improvement depending on data). The API allows the user to pass his own allocator to the library. It is possible to configure the library so that the library runs on predefined chunk of memory.
The API was changed to loosely resemble the OpenGL vertex array API. The processed data can be accessed via getter functions. The code is able to output contours, polygons and connected polygons. The output of the tessellator can be also used as input for new run. I.e. the user may first want to calculate an union all the input contours and the triangulate them.
The code is released under SGI FREE SOFTWARE LICENSE B Version 2.0. https://directory.fsf.org/wiki/License:SGIFreeBv2
Mikko Mononen memon@inside.org
Functions
NewTess () | Create a new Tessellator. |
Undef () | Getter. |
Tessellator:AddContour (vertices[, opts]) | Adds a contour to be tessellated. |
Tessellator:GetElementCount () | Getter. |
Tessellator:GetElements (arg, one_based) | Gather the elements resulting from tessellation. |
Tessellator:GetPolySize () | Getter. |
Tessellator:GetVertexCount () | Getter. |
Tessellator:GetVertexIndices (arg, one_based) | Gather the vertex indices resulting from tessellation. |
Tessellator:GetVertexSize () | Getter. |
Tessellator:GetVertices (arg) | Gather the vertices resulting from tessellation. |
Tessellator:SetOption (option, enable) | Toggles optional tessellation parameters. |
Tessellator:Tesselate (winding_rule, element_type[, poly_size=3[, normal]]) | Tessellate contours. |
Tessellator:Tesselate (winding_rule, element_type[, opts]) | Variant that takes an options table instead. |
Tessellator:UseVertexSizeOf3 (use3) | Set the vertex size used by subsequent calls to Tessellator:AddContour and Tessellator:Tesselate. |
Functions
- NewTess ()
-
Create a new Tessellator.
Returns:
-
Tessellator or nil
Tessellator object, or nil on error.
- Undef ()
-
Getter.
Returns:
-
uint
A constant that indicates an undefined index.
- Tessellator:AddContour (vertices[, opts])
-
Adds a contour to be tessellated.
TODO: Are the options applied here or at tessellation?
Parameters:
- vertices
array or Bytes
As a table, the vertices are assumed to be an array of numbers:
{ x1, y1, x2, y2, ... }
or{ x1, y1, z1, x2, y2, z2, ... }
for 2 or 3 coordinates, respectively. Any incomplete trailing vertex is ignored.This may also be provided as bytes, pointing to the start of the first float.
- opts
table
Contour options:
- count: Number of vertices in the contour, padding with all-zero values if necessary. By default (or when 0), the number of complete values in vertices.
- stride: Offset in bytes between consecutive vertices, which must be at least
sizeof(float) * self:GetVertexSize()
. This is also used to calculate the default count for vertices when provided as bytes.
- vertices
array or Bytes
As a table, the vertices are assumed to be an array of numbers:
- Tessellator:GetElementCount ()
-
Getter.
Returns:
-
uint
Number of elements in the the tesselated output.
- Tessellator:GetElements (arg, one_based)
-
Gather the elements resulting from tessellation.
Their interpretation depends on the element type supplied to Tessellator:Tesselate:
With POLYGONS type, elements are divvied up as
{ ..., vi #1, vi #2, ..., vi #n, ... }
, with n being the polygon size used to perform the tessellation. Each vi is the index for a corresponding vertex; trailing indices may be undefined, cf. Undef, meaning the element contains fewer than n vertices.CONNECTED_POLYGONS is similar:
{ ..., vi #1, vi #2, ..., vi #n, ni #1, ni #2, ..., ni #n, ... }
. The vi carry over their meaning with POLYGONS, whereas each ni is a neighbor index, indicating a particular fellow element borders that side; when ni is undefined, there is no such neighbor.BOUNDARY_CONTOURS's elements occur in pairs:
{ ..., vi #1, vi #2, ... }
. The vi have the same meaning as before, except indices are never undefined.Parameters:
- arg
string, table or nil
This may be the string "as_bytes", in which case the elements are returned as Bytes.
Otherwise, elements are supplied through a table, either using the one provided here or creating a new one.
N.B. With a custom table, any entries not overwritten will be left as-is. If necessary, use
self:GetElementCount() * ElementSize
to calculate the number of entries. ElementSize will ben
for POLYGONS,2 * n
for CONNECTED_POLYGONS, and2
for BOUNDARY_CONTOURS. - one_based bool Elements are one-based, rather than zero-based? This is ignored for Bytes and undefined elements.
Returns:
-
Bytes or table
As a table, an array
{ comp1, comp2, ... }
whose values are uints.Otherwise, a proxy object that implements Bytes and reflects the most recent tessellation results.
- arg
string, table or nil
This may be the string "as_bytes", in which case the elements are returned as Bytes.
Otherwise, elements are supplied through a table, either using the one provided here or creating a new one.
- Tessellator:GetPolySize ()
-
Getter.
Returns:
-
uint
Polygon size provided to Tessellator:Tesselate, or 0 if not yet set.
- Tessellator:GetVertexCount ()
-
Getter.
Returns:
-
uint
Number of vertices in the tessellated output.
- Tessellator:GetVertexIndices (arg, one_based)
-
Gather the vertex indices resulting from tessellation. These describe the order in which the
vertices were added and can be used to map the tessellator output to input.
Every vertex added using Tessellator:AddContour will get a new index, starting from 0.
New vertices generated at the intersections of segments are undefined, cf. Undef.
Parameters:
- arg string, table or nil As per Tessellator:GetElements.
- one_based bool Elements are one-based, rather than zero-based? This is ignored for Bytes or undefined indices.
Returns:
-
Bytes or table
As per Tessellator:GetElements.
- Tessellator:GetVertexSize ()
-
Getter.
Returns:
-
uint
Number of coordinates per vertex, i.e. 2 or 3.
See also:
- Tessellator:GetVertices (arg)
-
Gather the vertices resulting from tessellation.
Parameters:
- arg string, table or nil As per Tessellator:GetElements.
Returns:
-
Bytes or table
As a table, an array of numbers:
{ x1, y1, x2, y2, ... }
or{ x1, y1, z1, x2, y2, z2, ... }
for 2 or 3 coordinates, respectively.Bytes results follow the pattern of Tessellator:GetElements.
- Tessellator:SetOption (option, enable)
-
Toggles optional tessellation parameters.
Parameters:
- option
string
One of the following:
- CONSTRAINED_DELAUNAY_TRIANGULATION: Used an improved non-robust Constrained Delaunay triangulation. (Off by default.)
- REVERSE_CONTOURS: Tessellator:AddContour will treat clockwise contours as counter-clockwise and vice versa.
- enable bool Enable the option? Disable it otherwise.
- option
string
- Tessellator:Tesselate (winding_rule, element_type[, poly_size=3[, normal]])
-
Tessellate contours.
N.B. The method's spelling is carried over from libtess2.
Parameters:
- winding_rule
string
Rule used for tessellation. Must be one of the following (for descriptions see the OpenGL Red Book):
- "ABS_GEQ_TWO":
abs(winding_number) >= 2
- "NEGATIVE":
winding_number < 0
- "NONZERO":
winding_number ~= 0
- "ODD":
winding_number % 2 == 1
- "POSITIVE":
winding_number > 0
- "ABS_GEQ_TWO":
- element_type
string
Resulting element type. Must be one of the following:
- "BOUNDARY_CONTOURS": Generate only the outside contours of the shapes.
- "CONNECTED_POLYGONS": Generate polygons with neighbor information.
- "POLYGONS": Generate polygons.
- poly_size uint Maximum vertices per polygon when element_type is "POLYGONS". (default 3)
- normal table, Bytes or nil Defines the normal of the input contours, either as an array of three numbers or in Bytes form as three consecutive floats (if either is too small, padding 0s are added). If absent, calculated automatically. (optional)
Returns:
-
boolean
Tessellation succeeded?
- winding_rule
string
- Tessellator:Tesselate (winding_rule, element_type[, opts])
-
Variant that takes an options table instead.
Parameters:
- winding_rule string As before.
- element_type string As before.
- opts table Tessellation options, which may include poly_size and normal, whose meaning is as described before. (optional)
Returns:
-
boolean
Tessellation succeeded?
- Tessellator:UseVertexSizeOf3 (use3)
-
Set the vertex size used by subsequent calls to Tessellator:AddContour and Tessellator:Tesselate.
Parameters:
- use3 bool Use 3 coordinates per vertex, rather than 2 (the default)?
See also: