graphics commands

(global)

Background

background(red, green, blue, alpha)

Clears the current context with solid color, can also be used to set image backgrounds when combined with context.push()

Parameters:

• red (number) – The red component of the color (0-255)

• green (number) – The green component of the color (0-255)

• blue (number) – The blue component of the color (0-255)

• alpha (number) – The alpha component of the color (0-255)

background(color)

Clears the current context with solid color, can also be used to set image backgrounds when combined with context.push()

Parameters:

color (color) – The color to set the background to

background(cubeImage[, mipLevel = 0])

Clears the current background with the contents of a cube image, using the current camera settings to define eye direction

Parameters:

• cubeImage (image) – The image to clear the background with

• mipLevel (number) – The mip level of the image to use, useful for displaying pre-blurred image mips, such as those calculated using image.generateIrradiance()

background(shader)

Clears the current background using a custom shader

Parameters:

shader (shader) – The shader to use when clearing the background, should be a shader that is compatible with sprite rendering (i.e. uses the same vertex attributes)

Example

function setup()
    -- Create a custom background shader
    skybox = shader{
        name = "Skybox",
        
        properties =
        {
            {"environment", "texture"},
            {"mipLevel", "float", 0}
        },
        
        pass =
        {
            cullFace = "none", -- backgrounds don't need culling
            depthWrite = false, -- no need to write to depth buffer
            depthFunc = "always", -- no need for depth testing
            blendMode = "disabled", -- no need for blending
            renderQueue = "background", -- render behind everything else
            
            vertex =
            [[
            #version 430
            #include <codea/common.glsl>
            
            layout (location = POSITION) in vec3 a_position;
            
            layout (location = 0) out vec3 v_eyeDirection;
            
            void main()
            {
                // vertex layout is a quad between -1 and 1, use this to unproject and calculate eye direction from view/perspective matrix
                vec3 unprojected = (u_invProj * vec4(a_position, 1)).xyz;
                v_eyeDirection = mat3(u_invView) * unprojected;
                
                gl_Position = vec4(a_position.xy, 1, 1);
            }
            ]],
    
            fragment =
            [[       
                #version 430
                #include <codea/common.glsl>
    
                layout (location = 0) in vec3 v_eyeDirection;
                out vec4 fragColor;
    
                uniform samplerCube environment;
                uniform float mipLevel;
    
                void main()
                {
                    vec3 rayDir = normalize(v_eyeDirection);
                    rayDir = vec3(rayDir.x, rayDir.y, rayDir.z);
                    vec3 col = texture(environment, rayDir, mipLevel).rgb;
                    fragColor = vec4(col, 1.0);
                }
            ]],
        }
    }

    local hdr = image.cube(image.read(asset.builtin.hdr.Norway_Forest))
    skybox.environment = hdr:generateIrradiance()

    -- Test mip level adjustment
    parameter.number("MipLevel", 0, 10, 0, function(mip)
        skybox.mipLevel = mip
    end)  

    parameter.vec2("Rotation", vec2(0,0))
end

function draw()
    matrix.perspective() 
    local v = mat4.orbit(vec3(0, 0, 0), 1, Rotation:unpack())    
    matrix.view(v)
    background(skybox)
end

Vector Graphics

A set of graphics functions which are so commonly used they are in the global namespace for convenience

line(x1, y1, x2, y2)

Draws 2D line from the start point (x1, y1) to the end point (x2, y2) based on the current style:

Parameters:

• x1 (number) – the x coordinate of the start point

• y1 (number) – the y coordinate of the start point

• x2 (number) – the x coordinate of the end point

• y2 (number) – the y coordinate of the end point

• Color with style.stroke()

• Width with style.strokeWidth()

• End Caps with style.lineCapMode()

  • SQUARE

  • PROJECT

  • ROUND

line(x, y)

Adds a straight segment from the last point to (x, y), when called inside shape()

polyline(x1, y1, x2, y2, ... xn, yn)

Draws a continuous 2D line with an arbitrary number of points (x1, y1, etc…) based on the current style

• Color with style.stroke()

• Width with style.strokeWidth()

• End Caps with style.lineCap()

• Line Joins with style.lineJoin()

  • ROUND

  • MITER

  • BEVEL

polygon(x1, y1, x2, y2, ... xn, yn)

Draws a closed 2D polygon with an arbitrary number of points based on the current style

bezier(x1, y1, cx1, cy1, cx2, cy2, x2, y2)

Draw a quadratic bezier curve using four points based on the current style

bezier(cx1, cy1, cx2, cy2, x2, y2)

Adds a curved segment from the last point to (x2, y2), when called inside shape()

shape(x, y, [closed = true, ]func)

Draws a shape from a path that starts at (x, y) and is built by the drawing commands called inside func. The shape is filled and outlined using the current style

Inside func, use line(x, y) and bezier(cx1, cy1, cx2, cy2, x2, y2) to add segments from the last point. Commands such as rect() and ellipse() add separate outlines to the shape. An outline inside another one cuts a hole in it

Parameters:

• x (number) – the x coordinate of the first point

• y (number) – the y coordinate of the first point

• closed (boolean) – whether to join the last point back to the first and fill the shape. An open shape is only outlined

• func (function) – a function that builds the shape

A speech bubble with a hole

function draw()
    background(40, 40, 50)
    style.fill(255, 200, 50).stroke(220, 120, 30).strokeWidth(4)

    shape(200, 300, function()
        -- The tail
        line(250, 300)
        line(220, 230)
        line(300, 300)

        line(500, 300)
        bezier(560, 300, 560, 450, 500, 450)
        line(200, 450)
        bezier(140, 450, 140, 300, 200, 300)

        -- This outline cuts a hole in the bubble
        ellipse(350, 375, 60, 60)
    end)
end

arc(x, y, radius, startAngle, endAngle, dir)

Draws a 2D arc with a given origin, radius and start, end angles + direction

Parameters:

• x (number) – x coordinate of the arc origin

• y (number) – y coordinate of the arc origin

• radius (number) – the radius arc

• startAngle (number) – the start angle of the arc (in degrees)

• endAngle (number) – the end angle of the arc (in degrees)

• dir (integer) – the direction of the arc, 1 or clockwise, -1 for anti-clockwise

ellipse(x, y, w, h)

ellipse(x, y, r)

Draw an ellipse with a given origin point and width / height (or radius)

rect(x, y, w, h[, radius = 0])

Draws a rectangle with a given origin point and width / height, origin and sizing behaviour depends on style.shapeMode()

Optional parameter radius specified the corner radius

Parameters:

• x (number) – the x coordinate of the rectangle

• y (number) – the y coordinate of the rectangle

• w (number) – the width of the rectangle

• h (number) – the height of the rectangle

• radius (number) – the radius of the rounded corners

rect(x, y, w, h, r1, r2, r3, r4)

Draws a rectangle with a given origin point and width / height, origin and sizing behaviour depends on style.shapeMode()

The corner radius of each corner can be set independently using the additional parameters r1, r2, r3 and r4

Parameters:

• x (number) – the x coordinate of the rectangle

• y (number) – the y coordinate of the rectangle

• w (number) – the width of the rectangle

• h (number) – the height of the rectangle

• r1 (number) – the radius of the top-left corner

• r2 (number) – the radius of the top-right corner

• r3 (number) – the radius of the bottom-right corner

• r4 (number) – the radius of the bottom-left corner

Sprites

sprite(image, x, y[, w, h])

sprite(asset.key, x, y[, w, h])

sprite(sprite.slice, x, y[, w, h])

Draws a sprite using an asset - image, asset.key or sprite.slice

sprite(shader, x, y, w, h)

Text

text(str, x, y[, w, h])

Draws one or more lines of text based on the current style. Use the optional width and height parameters to draw a fixed size text box with line wrapping enabled

• Text Color with style.fill()

• Text Outline with style.stroke()

• Text Outline Thickness with style.strokeWidth()

• Text Alignment with style.textAlign()

  • LEFT

  • CENTER

  • RIGHT

  • TOP

  • MIDDLE

  • BOTTOM

• Text Style with style.textStyle()

  • TEXT_NORMAL

    • Renders the text normally

  • TEXT_BACKGROUND

    • Renders a rectangle behind the text using the background color

  • TEXT_UNDERLINE

    • Renders a line below the text

  • TEXT_OVERLINE

    • Renders a line above the text

  • TEXT_STRIKE_THROUGH

    • Renders a line through the text

  • TEXT_BOLD

    • Renders the text in bold

  • TEXT_ITALICS

    • Renders the text in italics

  • TEXT_RICH

    • Enables rich text, which parses xml tags within the supplied string to format individual characters.

  • TEXT_UPPERCASE

    • Renders all text in uppercase

  • TEXT_LOWERCASE

    • Renders all text in lowercase

  • TEXT_NATIVE

    • Enables native text rendering, which uses the system font renderer to draw text and supports emojis. Note that other text styles are disabled while using the native renderer.

Built-In Tags

Bold and Italic

The <i>quick brown fox</i> jumps over the <b>lazy dog</b>.

Custom Tags

Custom tags can assigned using a callback function - text.style.myCustomTag = function(tag, format) ... end

The tag parameter gives access to custom xml tag attributes

The format parameter gives access to text formatting options that can be adjusted per tag, derived from text styles in the style module

• textAlign

• textStyle

• fontSize

• fontName

• fillColor

• strokeColor

• strokeWidth

• textOverline

• textUnderline

• textStrikeThrough

• textBackground

• textShadow

• textShadowOffset

• textShadowSoftner

• callback

The additional parameter callback is a special function used to modify individual glyphs (characters) when the text is rendered. The callback function has the following parameters:

• str - the string being drawn

• index - the index of the current glyph in the string

• mod - a reference to a glyphModifier object, used to modify the current glyph

A glyphModifier has the follwing properties:

• offsetX - the amount to offset the glyphs x position in pixels

• offsetY - the amount to offset the glyphs y position in pixels

• alpha - the alpha of the current glyph (0-255)

• color - the color the of the current glyph

Example

function setup()
    text.style.wave = function(tag, format)
        local height = tag:number("height", 2)                   
        format.fillColor = color.red
        format.textStyle = format.textStyle | TEXT_ITALICS | TEXT_BOLD
        format.callback = function(str, i, mod)
            mod.offsetY = mod.offsetY + math.sin(time.elapsed*5 + i) * height
        end
    end
    
    text.style.shake = function(tag, format)
        local intensity = tag:number("intensity", 2)                   
        
        format.callback = function(str, i, mod)
            local r1 = (math.random() * 0.5 - 0.5) * intensity
            local r2 = (math.random() * 0.5 - 0.5) * intensity
            
            mod.offsetX = mod.offsetX + r1
            mod.offsetY = mod.offsetY + r2
        end
    end
    
    text.style.appear = function(tag, format)
        local t = timer * tag:number("speed", 5)                   
                
        format.callback = function(str, i, mod)
            local a = math.min(math.max(t - i, 0.0), 1.0)
            local len = str:len()
            mod.offsetY = 5 * math.cos(a * math.pi/2)
            mod.alpha = a * 255        
        end
    end
    
    parameter.text("str", "<appear speed='15'><b>This</b> line will appear and <shake intensity = '2'>shake</shake> and <wave height='5'>wave</wave> and might wrap at some point...</appear>")
    --parameter.text("str", "Here is a line of text that might wrap at some point...")
    parameter.integer("fontSize", 5, 100, 24)    
    parameter.number("WaveHeight", 0, 10, 5)
    parameter.enumerated("TextAlignH", {"LEFT", "CENTER", "RIGHT"}, 2)
    parameter.enumerated("TextAlignV", {"BOTTOM", "MIDDLE", "TOP"}, 2)
    
    parameter.action("Reset", function() timer = 0 end)
    
    alignH = {LEFT, CENTER, RIGHT}
    alignV = {BOTTOM, MIDDLE, TOP}
    timer = 0
    
    --[[
    scn = scene.default3d()
    local rig = scn.camera:add(camera.rigs.orbit)
    rig.distance = 50
    rig.angles.y = -45    
    rig.angles.y = -75
    scene.main = scn--]]
    
    
end

function draw()

    local boxWidth = 400
    local boxHeight = 200
    
    background(128)
    
    --matrix.ortho()
    
    -- Setup the text drawing style
    style.font("Arial")
    style.fill(color.cyan).fontSize(fontSize)
    
    matrix.transform3d(WIDTH/2 - 50, HEIGHT/2 - boxHeight/2, 0, 2, 2, 2, 0, 0, 0)
    --matrix.transform3d(0, 0, 0, 0.1, 0.1, 0.1, 0, 0, 0)
        
    style.fill(255)
    style.stroke(0).strokeWidth(5).textStyle(TEXT_RICH)
    --style.noStroke()
    style.textAlign(alignH[TextAlignH] | alignV[TextAlignV])
    
    local so = (CurrentTouch.pos - vec2(WIDTH/2, HEIGHT/2)) * 0.1
    
    style.textShadow(0, 0, 0, 128).textShadowSoftner(10).textShadowOffset(so.x, so.y)
        
    -- Cache some locals for performance
    local len = str:len()
    local cps = 10
    local t = timer * 5
    local r1, r2 = string.find(str, "text")
    
    text(str, 0, 0, boxWidth, boxHeight)
    
    timer = timer + time.delta
    
    -- Draw the text's bounding box and origin
    style.noFill().stroke(color.yellow).strokeWidth(2)
    rect(0, 0, boxWidth, boxHeight)
    ellipse(0, 0, 10)
end

Parameters:

• x – the x coordinate of the text

• y – the x coordinate of the text

• w – optional width of the text box

• h – optional height of the text box

• callback – a special glyph modifier callback

textSize(str[, width])

Gets the size of a text being drawn

Parameters:

• str (string) – the text to query

• width (number) – the width of the textbox

Returns:

The width and height of the text

Return type:

number, number

Gizmos

Gizmos are useful for drawing shapes in 2D/3D space for debugging and editing

gizmos.line(x1, y1, z1, x2, y2, z2)

Draws a 3D antialiased line

Color Space

colorspace(type)

Changes the color space used for drawing images and sprites

Parameters:

type – Either GAMMA or LINEAR

Contexts

context.push(image[, layer = 0, mip = 0])

Pushes an image to the context, causing subsequent drawing operations to be applied to said image until context.pop() is called

Parameters:

• image – The image to push

• layer – The layer of image to draw to

• mip – The mip of the image to draw to

context.pop()

Pops the current image from the context if one exists, subsequent drawing operations are again applied to the main context (i.e. the display)