lovr-g2d

A 2d graphics rendering library for LÖVR

Usage

g2d = require("lovr-g2d").init()

-- https://github.com/Papaew/lovr-g2d/blob/main/resources/lovr-ico.png
local image = lovr.graphics.newTexture("/lovr-ico.png")
function lovr.draw()
    g2d.set()
        g2d.print("Hello, LÖVR!", 10,10)
        g2d.draw(image, 14,30)
    g2d.unset()
end

API

Coordinate System

Function	Description
g2d.init()	Initializes the module with selected settings
g2d.set()	The entry point into drawing 2D graphics
g2d.unset()	Exit point from drawing 2D graphics
g2d.push()	Copies and pushes the current rendering settings onto the stack
g2d.pop()	Pops the current rendering settings from the stack
g2d.reset()	Resets the current graphics settings

Drawing

Function	Description
g2d.draw()	Draws a texture on the screen
g2d.circle()	Draws a circle
g2d.line()	Draws lines between points
g2d.points()	Draws one or more points
g2d.print()	Draws text on screen
g2d.rectangle()	Draws a rectangle

Graphics State

Function	Description
g2d.getColor()	Gets the current color
g2d.getFont()	Gets the current Font object
g2d.getLineWidth()	Gets the current line width
g2d.getPointSize()	Gets the point size
g2d.getShader()	Gets the current Shader
g2d.isWireframe()	Gets whether wireframe mode is used when drawing
g2d.setColor( r,g,b,a )	Sets the color used for drawing
g2d.setFont( font )	Set an already-loaded Font as the current font
g2d.setlineWidth( width )	Sets the line width
g2d.setPointSize( size )	Sets the point size
g2d.setShader( shader )	Routes drawing operations through a shader
g2d.setWireframe( enabled )	Sets whether wireframe lines will be used when drawing

TODO

• Stacks and coordinate system transform functions
  • origin, translate, rotate, scale
• Quad, spritebatches and image autobatching most likely based on this
• Shape rendering functions
  • arc, ellipse, polygon
  • line join styles, anti-aliasing for lines
• stencil and blend modes support(?)

Documentation

init()

Initializes the module with selected settings.

Function

g2d = require("lovr-g2d").init( maxTriangles, stackSize, zNear, zFar, useVeraSans )

Arguments

number maxTriangles (5000)
number stackSize (64)
number zNear (-1)
number zFar (1)
boolean useVeraSans

Returns

table g2d

set()

The entry point into drawing 2D graphics.

Can be called several times per frame, but must be closed with g2d.unset()

Function

g2d:set()
-- draw 2d stuff

Arguments

None.

Returns

Nothing.

Notes

Functions from lovr.graphics called between g2d.set() and g2d.unset() may not work correctly

unset()

Exit point from drawing 2D graphics.

Must be called after g2d.set() for correct rendering

Function

-- draw 2d stuff
g2d:unset()

Arguments

None.

Returns

Nothing.

push()

Copies and pushes the current graphics state to the stack

Function

g2d:push()

Arguments

None.

Returns

Nothing.

Usage

-- set the current color to red
g2d.setColor(1,0,0)

g2d.push() -- save current graphics state so any changes can be restored

    -- draw something else with a different color
    g2d.setColor(1,0,0)
    g2d.circle("fill", 100,100, 30)

g2d.pop() -- restore the saved graphics state

-- draw a rectangle with restored red color
g2d.rectangle("fill", 64,32, 128,96)

Notes

The function saves the following types of states:

• current color
• active font
• active shader
• wireframe mode
• line width
• point size

pop()

Returns the current graphics state to what it was before the last preceding g2d.push()

Function

g2d:pop()

Arguments

None.

Returns

Nothing.

reset()

Resets the current graphics settings to default

Makes the current drawing color white, disables active shader and wireframe mode

Also changes current font to default, line width and point size to 1.0

Function

g2d.reset()

Arguments

None.

Returns

Nothing.

Notes

This function, like any other function that change graphics state, only affects the current stack

draw()

Draws a Texture on the screen with optional rotation

Function

g2d.draw( texture, x,y, angle )

Arguments

Texture texture
number x
number y
number angle

Returns

Nothing.

Usage

function lovr.load()
    hamster = lovr.graphics.newTexture("hamster.png")
end

function lovr.draw()
    g2d.set()
        g2d.draw(hamster, 100, 100)
    g2d.unset()
end

circle()

Draws a circle on the screen

Function

g2d.circle( mode, x,y, radius, segments  )

Arguments

DrawMode mode
number x
number y
number radius
number segments

Returns

Nothing.

line()

Draws lines between points

Function

g2d.line( x1, y1, x2, y2, ...  )

Arguments

number x1
number y1
number x2
number y2
number ...
You can continue passing point positions

Returns

Nothing.

Usage

function lovr.load()
    sometable = {
        100, 100,
        200, 200,
        300, 100,
        400, 200,
    }
end

function lovr.draw()
    g2d.set()
        g2d.line(200,50, 400,50, 500,300, 100,300, 200,50)
        g2d.line(sometable) -- Also table of point positions can be passed
    g2d.unset()
end

points()

Draws one or more points

Function

g2d.points( x, y, ...  )

Arguments

number x
number y
number ...
You can continue passing point positions

Returns

Nothing.

Usage

function lovr.load()
    sometable = {
        100, 100,
        200, 200,
        300, 100,
        400, 200,
    }
end

function lovr.draw()
    g2d.set()
        g2d.points(200,50, 400,50, 500,300, 100,300, 200,50)
        g2d.points(sometable) -- Also table of point positions can be passed
    g2d.unset()
end

print()

Draws text on screen

Function

g2d.print( text, x,y, r, halign, valign )

Arguments

string text
number x
number y
number angle
HorizontalAlign halign
VerticalAlign valign

Returns

Nothing.

rectangle()

Draws a rectangle

Function

g2d.print( mode, x,y, width,height )

Arguments

DrawMode mode
number x
number y
number width
number height

Returns

Nothing.

setColor()

Sets the color used for drawing objects

Function

g2d.setColor( r,g,b,a )

Arguments

number r
number g
number b
number a

Returns

Nothing.

setFont()

Sets the active font used to render text with g2d.print

Function

g2d.setFont( font )

Arguments

Font font

Returns

Nothing.

setlineWidth()

Sets the width of lines rendered using g2d.line

Function

g2d.setlineWidth( width )

Arguments

number width

Returns

Nothing.

setPointSize()

Sets the width of drawn points, in pixels

Function

g2d.setPointSize( size )

Arguments

number size

Returns

Nothing.

setShader()

Sets or disables the Shader used for drawing

Function

g2d.setShader( shader )

Arguments

Shader shader

Returns

Nothing.

Usage

-- smol rainbow effect shader
shader = g.newShader([[
// vertex shader
vec4 position(mat4 projection, mat4 transform, vec4 vertex) {
    return projection * transform * vertex;
} ]], [[
// fragment shader
uniform float time;
vec4 color(vec4 graphicsColor, sampler2D image, vec2 uv) {
    vec3 col = 0.5 + 0.5*cos(time+uv.xyx+vec3(0,2,4));
    return vec4(col, 1.0) * lovrVertexColor * texture(image, uv);
} ]])

local time = 0
function lovr.update(dt)
    time = time + dt
    shader:send("time", time)
end

function lovr.draw()
    g2d.set()
        g2d.setShader(shader)
            g2d.circle('fill', 100,100, 50)
        g2d.setShader()
    g2d.unset()
end

setWireframe()

Enables or disables wireframe rendering

Function

g2d.setWireframe( enabled )

Arguments

boolean enabled

Returns

Nothing.

getColor()

Returns the current color

Function

g2d.getColor()

Arguments

None.

Returns

number r
number g
number b
number a

getFont()

Returns the active font

Function

g2d.getFont()

Arguments

None.

Returns

Font font

getLineWidth()

Returns the current line width

Function

g2d.getLineWidth()

Arguments

None.

Returns

number width

getPointSize()

Returns the current point size

Function

g2d.getPointSize()

Arguments

None.

Returns

number size

getShader()

Returns the active shader.

Function

g2d.getShader()

Arguments

None.

Returns

Shader shader

isWireframe()

Returns a boolean indicating whether or not wireframe rendering is enabled

Function

g2d.isWireframe()

Arguments

None.

Returns

boolean state

DrawMode

• "fill" Draw filled shape
• "line" Draw outlined shape

VerticalAlign

• "top" Align the top of the text to the origin
• "middle" Vertically center the text
• "bottom" Align the bottom of the text to the origin

HorizontalAlign

• "left" Left aligned lines of text
• "center" Centered aligned lines of text
• "right" Right aligned lines of text