image

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
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

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

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 = btn.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

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])