Textured primitives in Löve?

[timmeh42]

A feature I really like in Gamemaker is the ability to draw primtive shapes defined as sets of triangles, textured with an image stretched over the triangle. The great usefulness of this lies in drawing distorted images, among other things.

I realise that this would be significantly harder to implement than, say quads, but it is super-useful - is there any possibility of it being a feature in the near future?

[substitute541]

... Probably.

[slime]

https://bitbucket.org/rude/love/issue/4 ... lation-for

[timmeh42]

Thanks slime, I didn't know that suggestions could be posted there - cool to see the discussion is ongoing, at least.

[Xgoff]

just for kicks, an api idea i'm working on

Code: Select all

----- PointBatch
-- `PointBatch`es provide a way to access vertex buffer functionality
-- from LOVE. Specifically, they make it possible to set color and
-- texture coordinate information on a per-vertex basis. As a side-
-- effect, they can be drawn with a single call like simple shapes,
-- making them quite efficient. If it weren't obvious due to their
-- name, `PointBatch`es are similar to `SpriteBatch`es; in fact, they 
-- are a superset of `SpriteBatch` functionality. They are more 
-- powerful, but this comes at the cost of being more difficult to
-- use!

--- Create a new `PointBatch`.
-- Create a new `PointBatch` with the specified image and maximum
-- number of points.
-- @param image:Image Image to use. `nil` specifies no image.
-- @param maxpoints:number Maximum number of points to allow.
-- @param mode:string Draw mode of `PointBatch`. Note that this affects how many indices need to be provided for a given element! Can be "fill" (3 indices/element), "line" (2 indices/element) or "point" (1 index/element). Default is "fill". NOTE: maybe allow more eg for line strips?
-- @return PointBatch New `Pointbatch`.
love.graphics.newPointBatch (image, maxpoints, mode)

--- Extended love.graphics.draw
-- Can now draw `PointBatch`es.
-- @param pb:PointBatch `PointBatch` to draw.
-- @param ...:number... The other arguments i'm too lazy to list because they haven't changed at all.
love.graphics.draw(pb, ...)

----- Point Data Management
-- `PointBatche`s are not much use without points! Points can be 
-- added individually or in groups via shapes. Points, along
-- with their position, also contain color and texture coordinate
-- data.

--- Add a single point to the `PointBatch`.
-- @param x:number X position of point.
-- @param y:number Y position of point.
-- @param r:number Red component of vertex color. Default is Red component of current color.
-- @param g:number Green component of vertex color. Default is Green component of current color.
-- @param b:number Blue component of vertex color. Default is Blue component of current color.
-- @param a:number Alpha component of vertex color. Default is Alpha component of current color.
-- @param s:number X position of texture coordinate. Float in range 0.0-1.0, inclusive. Default is 0.
-- @param t:number Y position of texture coordinate. Float in range 0.0-1.0, inclusive. Default is 0.
-- @return number id of added point. NOTE: Currently a number, may later become lightuserdata.
PointBatch:add (x, y, r, g, b, a, s, t)

--- TODO. For `SpriteBatch`es, this allows you to define a sprite with a `Quad` instead of the whole image. 
PointBatch:addq ()

--- TODO. Only imports sprites; doesn't change the image.
PointBatch:addSpriteBatch ()

--- TODO. Only imports points and indices; doesn't change the image. Draw modes must be the same.
PointBatch:addPointBatch ()

--- Add a rectangle to the `PointBatch`.
-- Adds points and indices for a rectangle.
-- @param x:number X position of upper-left point of rectangle.
-- @param y:number Y position of upper-left point of rectangle.
-- @param w:number Width of rectangle.
-- @param h:number Height of rectangle.
-- @param ...:number...|table A list of numbers, or a table of numbers, of the ids for up to 4 points to use. Only the color and texcoord information will be used, starting at the upper-left corner and going counter-clockwise. Defaults to current color and texcoord (0, 0) for missing points.
PointBatch:addRectangle (x, y, w, h, ...)

--- Add a circle to the `PointBatch`.
-- Adds points and indices for a circle. Or regular polygons, if you have few enough points...
-- @param x:number X position of center of circle.
-- @param y:number Y position of center of circle.
-- @param r:number Radius of circle
-- @param ...:number...|table A list of numbers, or a table of numbers, of at least 3 point ids to use. Only the color and texcoord information will be used, starting at the top-most point and going counter-clockwise.
PointBatch:addCircle (x, y, r, ...)

--- Get a point from its id (see above NOTE).
-- @param id:number ID of point.
-- @return number... X, Y, R, G, B, A, S and T values of point.
PointBatch:get (id)

--- Set a point's data.
-- @param id:number ID of point.
-- @param x:number New X position of point.
-- @param y:number New Y position of point.
-- @param r:number New Red component of vertex color.
-- @param g:number New Green component of vertex color.
-- @param b:number New Blue component of vertex color.
-- @param a:number New Alpha component of vertex color.
-- @param s:number New X position of texture coordinate. Float in range 0.0-1.0, inclusive.
-- @param t:number New Y position of texture coordinate. Float in range 0.0-1.0, inclusive.
PointBatch:set (id, x, y, r, g, b, a, s, t)

--- Clear all points from PointBatch.
PointBatch:clear ()

--- Set texcoords of all points.
-- Sets the texcoords of each point to its relative position in 
-- the bounding box defined by the group of all points.
PointBatch:setTexcoords ()

----- Index Management
-- Indices tell the graphics card which points actually make 
-- up triangles. Points will not have any visible effect until
-- they are added to the index list. A given point can be
-- added more than once, and in fact this is necessary if you
-- want interpolation across a shape. This is advanced 
-- functionality, so it is recommended to use the basic shapes
-- unless you really need this flexibility.

--- Add one or more indices to the index list.
-- Indices are used in conjunction with `GL_TRIANGLES`, `GL_LINES`,
-- or `GL_POINTS`, depending on the `PointBatch`'s draw mode.
-- @param ...:number...|table A list of or a table containing point ids.
PointBatch:addIndices (...)

--- Get a table containing the index list entries.
PointBatch:getIndices ()

--- Clear all indices.
PointBatch:clearIndices ()

--- Get draw mode.
-- The draw mode specifies how the `PointBatch` should be drawn.
-- The draw mode cannot be changed, as a set of indices are
-- only meaningful for one draw mode type.
-- @return string Draw mode of this `PointBatch`.
PointBatch:getDrawMode ()

----- Image Management

--- Set the current `PointBatch` image, or remove it by passing `nil`.
-- @param image:Image New image to use.
PointBatch:setImage (image)

--- Get the current `PointBatch` image, or nil if none.
-- @return Image Current image.
PointBatch:getImage ()

----- Binding/Unbinding
-- These work exactly like they do in `SpriteBatche`s: `bind` 
-- causes further modifications to the `PointBatch`'s GPU data
-- to be delayed until a matching call to `unbind`. This is 
-- recommended if you will be performing a lot of updates in
-- a short time (eg. adding points in a loop).

--- Bind `PointBatch` and delay updates to GPU.
-- Note: changes will not be visible until `unbind` is called!
PointBatch:bind ()

--- Unbind `PointBatch` and send updates to GPU.
PointBatch:unbind ()