love.primitive would be a new module that exposes vertex array functionality. specifically, it would be possible to define per-vertex colors and texture coordinates, which is currently not possible with the regular shape drawing functions. additionally, it allows drawing complex shapes with only one draw call rather than many, which could speed up certain use cases.
New object types
- PointPrimitive: represents a single point. PointPrimitives contain color and vertex coordinate information.
- LinePrimitive: represents a line (segment, actually) composed of two PointPrimitives.
- PolygonPrimitive: represents a polygon, composed of 3 or more PointPrimitives. NOTE: allow LinePrimitives too?
- PrimitiveGroup: groups one or more of the above. NOTE: allow nested groups?
- PointPrimitive:getX(): returns x coord of vertex
- PointPrimitive:getY(): returns y coord of vertex
- PointPrimitive:getPosition(): returns x and y coords of vertex
- PointPrimitive:getColor(): returns r, g, b, and a values of vertex
- PointPrimitive:getTexCoord(): returns u and v texcoord of vertex
- NOTE: setter methods go here, because i'm lazy
- LinePrimitive:getPoints(): returns both PointPrimitives making up the line
- LinePrimitive:getOtherPoint(p): returns the point that is not p
- PolygonPrimitive:getPoints(as_table): returns all PointPrimitives making up the polygon as individual values, or inside a table if as_table is true
- PolygonPrimitive:setTexcoords(): sets the texcoord of each PointPrimitive relative to its position in the bounding box defined by the polygon.
the following three functions create primitive shapes
- love.primitive.newPoint(x, y, [r, g, b, a, [u, v]]): creates and returns a new PointPrimitive with the given x and y coordinates. the color values and vertex coordinates can be provided as well, but if omitted, r, g, b, and a default to the current color, and u and v default to 0
- love.primitive.newLine(p1, p2): creates and returns a new LinePrimitive from two PointPrimitives
- love.primitive.newPolygon(p1, p2, p3, ...): creates and returns a new PolygonPrimitive from at least 3 PointPrimitives
the following function creates a group. groups can be used to draw several primitives at once
- love.primitive.newGroup(p, ...): creates and returns a new PrimitiveGroup from one or more of the above primitive types
the following function is used to draw a primitive or group.
- love.graphics.primitive(mode, p, x, y, r, sx, sy, ox, oy, kx, ky): draws primitive or group p. the x, y, r, sx, sy, ox, oy, kx, ky arguments work the same as they do in love.graphics.draw. mode works as usual, but introduces a new DrawMode point. in general, the behavior of mode is:
- point: renders everything as points
- line: renders LinePrimitives and PolygonPrimitives as lines. PointPrimitives will not be rendered
- fill: renders PolygonPrimitives filled. PointPrimitives and LinePrimitives will not be rendered