Class Graphics

A vector graphics.

Functions

tove.newGraphics (data[, size="auto"]) Create a new Graphics.

Tables

Graphics.paths tove.List of Paths in this Graphics

Methods

Graphics:addPath (path) Add a Path.
Graphics:animate (a, b, t) Animate between two Graphics.
Graphics:arc (x, y, r, startAngle, endAngle, ccw) Draw an arc.
Graphics:beginPath () Start a fresh Path for drawing.
Graphics:beginSubpath () Inside the current Path, start a fresh Subpath.
Graphics:cacheKeyFrame () Cache the current shape as key frame.
Graphics:clean ([eps=1e-2]) Clean paths.
Graphics:clear () Remove all Paths.
Graphics:clearCache () Clear internal drawing cache.
Graphics:clone () Create a deep copy.
Graphics:closePath () Close the current Path, thereby creating a loop.
Graphics:closeSubpath () Inside the current Path, close the current Subpath, thereby creating a loop.
Graphics:computeAABB ([prec="high"]) Compute bounding box.
Graphics:curveTo (cp1x, cp1y, cp2x, cp2y, x, y) Draw a cubic Bézier curve to (x, y).
Graphics:draw (x, y[, r=0[, sx=1[, sy=1]]]) Draw to screen.
Graphics:drawCircle (x, y, r) Draw a circle.
Graphics:drawEllipse (x, y, rx, ry) Draw an ellipse.
Graphics:drawRect (x, y, w, h, rx, ry) Draw a rectangle.
Graphics:fill () Add fill to shape.
Graphics:getCurrentPath () Get the current Path for drawing.
Graphics:getDisplay () Get display mode.
Graphics:getHeight ([prec="high"]) Get height.
Graphics:getNumTriangles () Get number of triangles.
Graphics:getQuality () Get display quality.
Graphics:getUsage () Get usage.
Graphics:getWidth ([prec="high"]) Get width.
Graphics:hit (x, y) Check if inside.
Graphics:lineTo (x, y) Draw a line to (x, y).
Graphics:moveTo (x, y) Move to position (x, y).
Graphics:rescale (size[, center]) Rescale to given size.
Graphics:rotate (w, k) Rotate elements.
Graphics:setCacheSize (size) Set internal key frame cache size.
Graphics:setDisplay (mode[, args]) Set display mode.
Graphics:setFillColor (r[, g[, b[, a=0]]]) Set fill color.
Graphics:setLineColor (r[, g[, b[, a=0]]]) Set line color.
Graphics:setLineDash (widths) Set line dash pattern.
Graphics:setLineDashOffset (offset) Set line dash offset.
Graphics:setLineWidth (width) Set line width.
Graphics:setMiterLimit (miterLimit) Set miter limit.
Graphics:setMonochrome (r, g, b) Set all colors to one.
Graphics:setName (name) Set name.
Graphics:setOrientation (orientation) Set orientation of all Subpaths.
Graphics:setResolution (resolution) Set resolution.
Graphics:setUsage (what, usage) Set usage.
Graphics:stroke () Add stroke to shape.
Graphics:warmup () Warm-up shaders.
Graphics:warp (f) Warp points.


Functions

Methods
tove.newGraphics (data[, size="auto"])
Create a new Graphics.

Parameters:

  • data string or {Path,...} either an SVG string or a table of Paths
  • size int or string the size to scale the Graphics to. Use "auto" (scale longest side to 1024), "copy" (do not scale and use original size) or a number (the number of pixels to scale to). (default "auto")

Returns:

    Graphics a new Graphics

Usage:

    local svg = love.filesystem.read("MyGraphics.svg")
g = tove.newGraphics(svg, 200)  -- scale to 200 pixels

Tables

Graphics.paths
tove.List of Paths in this Graphics

Methods

Graphics:addPath (path)
Add a Path. The new Path will be appended after other existing Paths.

Parameters:

Graphics:animate (a, b, t)
Animate between two Graphics. Makes this Graphics to an interpolated inbetween.

Parameters:

See also:

Graphics:arc (x, y, r, startAngle, endAngle, ccw)
Draw an arc.

Parameters:

  • x number x coordinate of centre of arc
  • y number y coordinate of centre of arc
  • r number radius of arc
  • startAngle number angle at which to start drawing
  • endAngle number angle at which to stop drawing
  • ccw bool true if drawing between given angles is counterclockwise
Graphics:beginPath ()
Start a fresh Path for drawing. The previously active Path will get closed but won't be made into loop. Subsequent drawing commands like Graphics:lineTo will draw into the newly started Path.

Returns:

    Path new active Path in this Graphics

Usage:

    g:moveTo(10, 10)
g:lineTo(20, 15)
g:lineTo(5, 0)
g:beginPath()  -- do not connect lines above into a loop
g:moveTo(50, 50)
g:lineTo(60, 55)
Graphics:beginSubpath ()
Inside the current Path, start a fresh Subpath. The previously active Subpath will not be made into a loop. Subsequent drawing commands like Graphics:lineTo will draw into the new Subpath inside the same Path.
Graphics:cacheKeyFrame ()
Cache the current shape as key frame. In "mesh" display mode, indicate to TÖVE that the current shape of this Graphics will recur in your animations as key frame. This allows TÖVE to precompute a triangulation for the current shape and reuse that later on. It also tells TÖVE to never evict this specific triangulation from its internal cache.

See also:

Usage:

    setKeyFrame1(g)
g:cacheKeyFrame()
setKeyFrame2(g)
g:cacheKeyFrame()
Graphics:clean ([eps=1e-2])
Clean paths. Removes duplicate or collinear points which can cause problems with various algorithms (e.g. triangulation) in TÖVE. If you have messy vector input, this can be a good first step after loading.

Parameters:

  • eps number triangle area at which triangles get collapsed (default 1e-2)
Graphics:clear ()
Remove all Paths. Effectively empties this Graphics of all drawable content.
Graphics:clearCache ()
Clear internal drawing cache. Recreates internal drawing objects (e.g. meshes). You shouldn't need this. Please note that this is NOT related to Graphics:cacheKeyFrame.
Graphics:clone ()
Create a deep copy. This cloned copy will include new copies of all Paths.

Returns:

    Graphics cloned Graphics.
Graphics:closePath ()
Close the current Path, thereby creating a loop. Subsequent drawing commands like Graphics:lineTo will automatically start a fresh Path.

Usage:

    g:moveTo(10, 10)
g:lineTo(20, 15)
g:lineTo(5, 0)
g:closePath() -- connect lines above into a loop
Graphics:closeSubpath ()
Inside the current Path, close the current Subpath, thereby creating a loop. Subsequent drawing commands like Graphics:lineTo will automatically start a fresh Subpath inside the same Path. Use this method if you want to draw holes.
Graphics:computeAABB ([prec="high"])
Compute bounding box. "low" precision will not correctly compute certain line boundaries (miters), however it will be exact for fills and much faster than "high".

Parameters:

  • prec string precision of bounding box: "high" (i.e. exact) or "low" (faster) (default "high")

Returns:

  1. number x0 (left-most x)
  2. number y0 (top-most y)
  3. number x1 (right-most x)
  4. number y1 (bottom-most y)
Graphics:curveTo (cp1x, cp1y, cp2x, cp2y, x, y)
Draw a cubic Bézier curve to (x, y). See Bézier curves on Wikipedia.

Parameters:

  • cp1x number x coordinate of curve's first control point (P1)
  • cp1y number y coordinate of curve's first control point (P1)
  • cp2x number x coordinate of curve's second control point (P2)
  • cp2y number y coordinate of curve's second control point (P2)
  • x number x coordinate of curve's end position (P3)
  • y number y coordinate of curve's end position (P3)

Returns:

    Command curve command

Usage:

    g:moveTo(10, 20)
g:curveTo(7, 5, 10, 3, 50, 30)
Graphics:draw (x, y[, r=0[, sx=1[, sy=1]]])
Draw to screen. The details of how the rendering happens can get configured through Graphics:setDisplay.

Parameters:

  • x number the x-axis position to draw at
  • y number the y-axis position to draw at
  • r number orientation in radians (default 0)
  • sx number scale factor in x (default 1)
  • sy number scale factor in y (default 1)

See also:

Usage:

    g:draw(120, 150, 0.1)  -- draw at (120, 150) with some rotation
Graphics:drawCircle (x, y, r)
Draw a circle.

Parameters:

  • x number x coordinate of centre
  • y number y coordinate of centre
  • r number radius

Returns:

    Command circle command
Graphics:drawEllipse (x, y, rx, ry)
Draw an ellipse.

Parameters:

  • x number x coordinate of centre
  • y number y coordinate of centre
  • rx number horizontal radius
  • ry number vertical radius

Returns:

    Command ellipse command
Graphics:drawRect (x, y, w, h, rx, ry)
Draw a rectangle.

Parameters:

  • x number x coordinate of top left corner
  • y number y coordinate of top left corner
  • w number width
  • h number height
  • rx number horizontal roundness of corners
  • ry number vertical roundness of corners

Returns:

    Command rectangle command
Graphics:fill ()
Add fill to shape.

See also:

Usage:

    g:moveTo(10, 20)
g:curveTo(7, 5, 10, 3, 50, 30)
g:fill()
Graphics:getCurrentPath ()
Get the current Path for drawing.

Returns:

    Path the currently active Path that gets drawn into.
Graphics:getDisplay ()
Get display mode.

Returns:

  1. string mode the current mode as set with Graphics:setDisplay.
  2. ... the detailed quality configuration as set with Graphics:setDisplay.

See also:

Graphics:getHeight ([prec="high"])
Get height.

Parameters:

  • prec string precision: "high" (i.e. exact) or "low" (faster) (default "high")

Returns:

    number height of contents in this Graphics

See also:

Graphics:getNumTriangles ()
Get number of triangles.

Returns:

    int number of triangles involved in drawing this Graphics.
Graphics:getQuality ()
Get display quality.

Returns:

    ... the detailed quality configuration as set with Graphics:setDisplay.

See also:

Graphics:getUsage ()
Get usage.

Returns:

    table a table containing the configured usage for each dimension as key, as set with Graphics:setUsage.

See also:

Graphics:getWidth ([prec="high"])
Get width.

Parameters:

  • prec string precision: "high" (i.e. exact) or "low" (faster) (default "high")

Returns:

    number width of contents in this Graphics

See also:

Graphics:hit (x, y)
Check if inside. Returns true if the given point is inside any of the Graphics's Paths.

Parameters:

  • x number x coordinate of tested point
  • y number y coordinate of tested point
Graphics:lineTo (x, y)
Draw a line to (x, y).

Parameters:

  • x number x coordinate of line's end position
  • y number y coordinate of line's end position

Returns:

    Command line command

Usage:

    g:moveTo(10, 20)
g:lineTo(5, 30)
Graphics:moveTo (x, y)
Move to position (x, y). Automatically starts a fresh Subpath if necessary.

Parameters:

  • x number new x coordinate
  • y number new y coordinate

Returns:

    Command move command
Graphics:rescale (size[, center])
Rescale to given size.

Parameters:

  • size number target size to scale to
  • center bool center the Graphics so that calling Graphics:draw will always place it around the given draw position (defaults to true) (optional)

See also:

Graphics:rotate (w, k)
Rotate elements. Will recusively left rotate elements in this Graphics such that items found at index k will get moved to index 0.

Parameters:

  • w string what to rotate: either "path", "subpath", "point" or "curve"
  • k int how much to rotate

See also:

Graphics:setCacheSize (size)
Set internal key frame cache size. Tell TÖVE how many triangulations to cache in "mesh" mode. This number should be high enough to allow TÖVE to never cache all necessary triangulations during an animation cycle. Obviously, this number depends on the shape and kind of your animation. Note that a high number will not automatically improve performance, as cache entries need to be checked and evaluated on each frame.

Parameters:

  • size

See also:

Graphics:setDisplay (mode[, args])
Set display mode. Configures in detail how this Graphics gets rendered to the screen when you call Graphics:draw. Note that this is a very expensive operation. You should only call it once for each Graphics and never in your draw loop.

Parameters:

  • mode string either one of "texture", "mesh" or "gpux", see display
  • args ... detailed quality configuration for specified mode, see display (optional)

See also:

Graphics:setFillColor (r[, g[, b[, a=0]]])
Set fill color. Will affect subsequent calls to Graphics:fill.

Parameters:

  • r number, string, Paint or nil red
  • g number green (optional)
  • b number blue (optional)
  • a number alpha (default 0)

Usage:

    g:setFillColor(0.8, 0, 0, 0.5)  -- transparent reddish
g:setFillColor("#00ff00")  -- opaque green
Graphics:setLineColor (r[, g[, b[, a=0]]])
Set line color. Will affect subsequent calls to Graphics:stroke.

Parameters:

  • r number, string, Paint or nil red
  • g number green (optional)
  • b number blue (optional)
  • a number alpha (default 0)

See also:

Graphics:setLineDash (widths)
Set line dash pattern. Takes a list of dash lengths. Will affect lines drawn with subsequent calls to Graphics:stroke.

Parameters:

  • widths number... lengths of dashes

Usage:

    g:setLineDash(0.5, 5.0, 1.5, 5.0)
Graphics:setLineDashOffset (offset)
Set line dash offset. Will affect lines drawn with calls to Graphics:stroke. See Mozilla for a good description of line dash offsets.

Parameters:

  • offset number new line dash offset
Graphics:setLineWidth (width)
Set line width. Will affect lines drawn with subsequent calls to Graphics:stroke.

Parameters:

  • width number new line width
Graphics:setMiterLimit (miterLimit)
Set miter limit. Will affect lines drawn with calls to Graphics:stroke. See Mozilla for a good description of miter limits.

Parameters:

  • miterLimit number new miter limit
Graphics:setMonochrome (r, g, b)
Set all colors to one. Will change all fills and line colors to the given color, making the Graphics appear monochrome.

Parameters:

  • r number red
  • g number green
  • b number blue
Graphics:setName (name)
Set name. That name will show up in error messages concering this Graphics.

Parameters:

Graphics:setOrientation (orientation)
Set orientation of all Subpaths.

Parameters:

  • orientation string "cw" for clockwise, "ccw" for counterclockwise
Graphics:setResolution (resolution)
Set resolution. Determines how much you can scale this Graphics when drawing without it looking bad. Affects the "texture" and "mesh" display modes. Note that this will not affect the size of the Graphics when drawing with scale 1.

Parameters:

  • resolution number scale factor up to which Graphics will look crisp when scaled in Graphics:draw (or through a Transform)

See also:

Usage:

    g:setDisplay("texture")
g:draw(0, 0) -- looks crisp
g:draw(0, 0, 2) -- at scale 2, things get fuzzy
g:setResolution(2)
g:draw(0, 0) -- same size as before
g:draw(0, 0, 2) -- at scale 2, things still look good
g:draw(0, 0, 3) -- now things get fuzzy
Graphics:setUsage (what, usage)
Set usage. Indicates which elements of the Graphics you want to change (i.e. animate) at runtime. Currently, this method only has an effect for display mode "mesh". Hint: to force meshes to not use shaders, use g:setUsage("shaders", "avoid").

Parameters:

See also:

Usage:

    g:setUsage("points", "stream") -- animate points on each frame
g:setUsage("colors", "stream") -- animate colors on each frame
Graphics:stroke ()
Add stroke to shape. g:moveTo(10, 20) g:curveTo(7, 5, 10, 3, 50, 30) g:stroke()

See also:

Graphics:warmup ()
Warm-up shaders. Instructs TÖVE to compile all shaders involved in drawing this Graphics with the current display settings. On some platforms, compiling gpux shaders can take a long time. Graphics:warmup will quit after a certain time and allow you to display some progress info. In these cases you need to call it again until it returns nil.

Returns:

    number or nil nil if all shaders were compiled, otherwise a number between 0 and 1 indicating percentage of shaders compiled so far.

See also:

Graphics:warp (f)
Warp points. Allows you to change the shape of a vector graphics in a way that animates well. The specified function applies a space mapping: it gets called for specific positions and returns new ones. TÖVE will call the function for non-control-points only and decide where to put control points itself based on an estimation of previous curve form. The curvature argument lets you estimate and change how curvy the shape is at a given (non-control) point.

Parameters:

  • f function takes (x, y, curvature) and returns the same

See also:

generated by LDoc 1.4.6 Last updated 2019-04-19 11:25:52