Images Overview

Made of pixels and used by codea for drawing to the screen and texturing meshes

Loading and drawing an image

function setup()
   -- load an image from a builtin image asset
   img = image.read(asset.builtin.Cargo_Bot.Codea_Icon)
end

function draw()
   background(64)
   sprite(img, WIDTH/2, HEIGHT/2)
end

Image

class image

static image(width, height[, hasMips = false, numLayers = 1, format = image.rgba, depthFormat = none])

Create a blank 2D image (default format is rgba)

Parameters:

• width (integer) – The width of the image

• height (integer) – The height of the image

• hasMips (boolean) – Enables mipmapping for this image

• numLayers (integer) – The number of layers for this image

• format (image format) – The image format

• depthFormat (depth format) – The image depth format

static cube(size)

Create a blank cube image (6 faces with equal sized dimensions)

Parameters:

size (integer) – The size of the image cube

static cube(equirect)

Creates a cube image from a single equirect image (i.e. hdr)

Parameters:

equirect (image) – The source equirect image

static cube(imageNX, imagePX, imageNY, imagePY, imageNZ, imagePZ)

Creates a cube image from six source images, one for each cube face

static volume(width, height, depth, format)

Creates a blank volume image with the given dimensions

Parameters:

• width (integer) – The width of the volume image

• height (integer) – The height of the volume image

• depth (integer) – The depth of the volume image

• format (image format) – The format of the volume image

static read(key)

Read an image asset from the filesystem

Parameters:

key – The asset key to load

Return type:

image

static save(key, image)

Save an image asset to the filesystem

Parameters:

• key (assetKey) – The asset key to save the image to

• image (image) – The image to save

static symbol(name, ...)

Create an image from an SF Symbol. Returns nil if no symbol of that name exists.

A monochrome symbol is rendered white, so it can be recoloured at draw time with tint(). Pass a colour to bake one in instead. Symbols drawn with image.symbol.multicolor, image.symbol.hierarchical or image.symbol.palette carry their own colours — draw those with tint(255), since tint multiplies.

Options may be given in any order after the name. A flag is passed as-is (image.symbol.multicolor, image.symbol.weight.bold); an option that carries values is called with them (image.symbol.variable(0.5)). A bare number is the point size, and a colour tints a monochrome symbol.

Parameters:

name (string) – The SF Symbol name, e.g. "globe" or "cloud.sun.fill"

Return type:

image or nil

Using SF Symbols

function setup()
    -- white by default, so tint() works
    globe = image.symbol("globe")

    -- or bake a colour in
    warning = image.symbol("exclamationmark.triangle.fill", color(255, 200, 0))

    -- the symbol's own colours
    weather = image.symbol("cloud.sun.fill", image.symbol.multicolor)

    -- a fill level from 0 to 1
    signal = image.symbol("wifi", image.symbol.variable(0.66))

    -- larger and heavier
    gauge = image.symbol("gauge", image.symbol.weight.bold, 64)
end

function draw()
    background(40)

    tint(255, 0, 0)
    sprite(globe, WIDTH/2, HEIGHT/2)

    tint(255)               -- do not tint a multicolour symbol
    sprite(weather, WIDTH/2, HEIGHT/2 - 100)
end

Note

Symbol names are provided by the operating system, and Apple adds new symbols with each release. Browse the available names — and the version each was introduced in — with Apple’s SF Symbols app.

symbol: table

A table containing the rendering modes for image.symbol(), and the weight and scale sub-tables below. Options may be passed in any order after the symbol name.

Flags, passed as-is:

• monochrome - A single colour (the default), rendered white so it can be recoloured with tint()

• multicolor - The symbol’s own intrinsic colours

Options that carry values, called with them:

• hierarchical(color) - One colour applied at several opacities, preserving the symbol’s depth

• palette(color, ...) - Two or three explicit colours, applied in order

• variable(value) - A fill level from 0 to 1, for symbols that support variable rendering such as wifi, speaker.wave.3.fill and battery.100. Symbols without it ignore the value.

symbol.weight: table

A table containing the stroke weights for image.symbol():

• ultralight

• thin

• light

• regular

• medium

• semibold

• bold

• heavy

• black

symbol.scale: table

A table containing the symbol scales for image.symbol():

• small

• medium

• large

width: integer

The width of the image in pixels

height: integer

The height of the image in pixels

depth: integer

The depth of the image in pixels (for volume images)

numLayers: integer

The number of layers in this image

hasMips: boolean

Whether this image has mip mapping or not

cubeMap: boolean

Whether this image is a cube or not

numMips: integer

The number of mips this image has

sampler: samplerState

The sampler state for this image, which determines how texels are sampled by shaders

smooth: boolean

Sets/gets whether this image has linear or nearest filtering

key: assetKey

The asset key for this image (if it has one)

generateIrradiance(samples)

Generates a guassian pyramid of pre-computed irradiance levels, used for image based lighting

Parameters:

samples (integer) – The number of samples to use (optional | default = 1024)

Returns:

A new image containing the irradiance data

Return type:

image

generateIrradiance(target, samples)

Generates a guassian pyramid of pre-computed irradiance levels, used for image based lighting

Parameters:

• target (image) – A target image to store the irradiance data

• samples (integer) – The number of samples to use (optional | default = 1024)

Returns:

The target image containing the irradiance data

Return type:

image

Image Formats

Here is a list of all currently available image formats

Available Image Formats

Name	Type	Channels	SRGB
image.a8	unorm	[8]	No
image.r8	unorm	[8]	Yes
image.r8i	sint	[8]	No
image.r8u	uint	[8]	No
image.r8s	snorm	[8]	No
image.r16	unorm	[16]	Yes
image.r16i	sint	[16]	No
image.r16u	uint	[16]	No
image.r16f	float	[16]	No
image.r16s	snorm	[16]	No
image.r32i	sint	[32]	No
image.r32u	uint	[32]	No
image.r32f	float	[32]	No
image.rgb8	unorm	[8,8,8]	Yes
image.rgb8i	sint	[8,8,8]	No
image.rgb8u	uint	[8,8,8]	No
image.rgb8s	snorm	[8,8,8]	No
image.rg16	unorm	[16,16,16]	Yes
image.rg16i	sint	[16,16,16]	No
image.rg16u	uint	[16,16,16]	No
image.rg16f	float	[16,16,16]	No
image.rg16s	snorm	[16,16,16]	No
image.rg32i	sint	[32,32,32]	No
image.rg32u	uint	[32,32,32]	No
image.rg32f	float	[32,32,32]	No
image.rgb9e5f	float	[9,9,9,+5]	No
image.bgra8	unorm	[8,8,8,8]	Yes
image.rgba8	unorm	[8,8,8,8]	Yes
image.rgba8i	sint	[8,8,8,8]	No
image.rgba8u	uint	[8,8,8,8]	No
image.rgba8u	sint	[8,8,8,8]	No
image.rgba8s	snorm	[8,8,8,8]	No
image.rgba16	unorm	[16,16,16,16]	No
image.rgba16i	sint	[16,16,16,16]	No
image.rgba16u	uint	[16,16,16,16]	No
image.rgba16f	float	[16,16,16,16]	No
image.rgba16s	snorm	[16,16,16,16]	No
image.rgba32i	sint	[32,32,32,32]	No
image.rgba32u	uint	[32,32,32,32]	No
image.rgba32f	float	[32,32,32,32]	No
image.r5g6b5	n/a	[5,6,5]	No
image.rgba4	n/a	[4,4,4,4]	No
image.rgb5a1	n/a	[5,5,5,1]	No
image.rgb10a2	n/a	[10,10,10,2]	No
image.rg11b10f	float	[32,32,32,32]	No
image.d16	uint	[16]	No
image.d24	uint	[24]	n/a
image.d24s8	depth/stencil	[24,8]	n/a
image.d32	uint	[32]	n/a
image.d16f	uint	[16]	n/a
image.d24f	uint	[24]	n/a
image.d32f	float	[32]	n/a
image.d0s8	stencil	[8]	n/a

Sampler State / Mipmapping

The sampler state of an image is used to control texel sampling

The mag property controls magnification, i.e. when the image texels are larger than 1 pixel in size

The min property controls minification, i.e. when the image texels are smaller than 1 pixel in size

The mip property controls how mipmapping is handled, linear will blend between mip levels linearly, while point will map clamp to the nearest mip level and none disables mipmapping entirely

class samplerState

min: filterMode

The minification filter, can be point, linear or none

mag: filterMode

The magnification filter, can be point, linear or none

mip: filterMode

The mip filter, can be point, linear or none

u: samplerMode

The u sampler mode, can be repeat, clamp or mirror

v: samplerMode

The v sampler mode, can be repeat, clamp or mirror

w: samplerMode

The w sampler mode, can be repeat, clamp or mirror

Slices and Atlases

class image.slice

A configurable slice of an image. Use with sprite() for drawing a portion of an sprite sheet image for more efficient 2D rendering (as opposed to a large number of independ images)

Create slices using an existing image via the image.slice property. Slices can be configured using a fluent syntax, allowing for rotation, flipping and 9-patch stretching among other things

Creating slices

function setup()
   button = image.read(asset.builtin.UI.Grey_Button_10)

   -- create a stretchable 9-patch of the original image
   buttonSlice = button.slice:patch(10)
end

function draw()
   sprite(buttonSlice, WIDTH/2, HEIGHT/2, 100, 50)
end

name(name)

name()

Gets/sets the slice name (for retrieval in the atlas class)

normal()

Reset the slice to the normal drawing mode (from patch or polygon mode)

rect(x, y, w, h)

rect()

Set/gets the sub-rectangle for the slice (in pixels). Use this to draw a portion of the sliced image

patch(left, right, top, bottom)

patch(margin)

Sets the slice to draw as a 9-patch using the supplied margins. This allows the slice to be stretched to an arbitrary size while maintaining fixed-sized borders

padding(left, right, top, bottom)

padding(amount)

padding()

Sets/gets the slice padding. This allows for a larger slice to be drawn but discards empty space at the edges (useful sprites packed into an atlas that trims empty space)

anchor(x, y)

anchor()

Sets/gets the slice anchor (also known as a pivot). The anchor is the geometric center of the slice for transformations such as rotation/scale and flipping

rotate(angle)

rotate()

Sets/gets the sice rotation (in discrete 90 degree turns). Useful for atlas packed sprites that might be rotated to fit, or when reusing a slice at a different 90 degee angle

flip(x, y)

flip()

Sets/gets the horizontal and vertical flip for the slice

image: image

The image this slice is derived from

atlas: atlas

The atlas this slice is part of

class atlas

A collection of image.slice objects generated from an image

Often 2D game assets will be compiled into a single image (known as an atlas or sprite sheet) for convienience and efficiency. These can be loaded from an external text file or generated using some simple settings

static atlas(image)

Create a new blank atlas using an existing image

static read(assetKey)

static save(assetKey, atlas)

clear()

setWithCellSize(cellWidth[, cellHeight, padding])

setWithCellCount(cellColumns[, cellRows, padding])