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.
    (optional)
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 be n for POLYGONS, 2 * n for CONNECTED_POLYGONS, and 2 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.

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:

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:

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.
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
  • 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?
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:

generated by LDoc 1.4.6 Last updated 2018-06-01 13:32:03