Graphics

When you begin a new project in Codea you'll notice that it consists of a tab called Main and some template code. Your project can consist of several tabs, the initial one is always called Main. If you add more files they will be listed across the top.

function setup()
    print(\"Hello World!\")
end

function draw()
    background(0,0,0)

    -- Do your drawing here
end

This is the framework that your project will use to run. There are two functions defined for you initially: setup() and draw().

setup() and draw() are executed by Codea when you press the play button to run your project. The setup() function is called once, at the start, and then the draw() function is called repeatedly (60 times per second, to be exact). In setup() Codea expects you to set up your initial program state, and in draw() you can tell Codea to render graphics onto the screen, update your program state over time, and so on.

In the next two sections we will cover these functions in detail.

While Codea lets you draw lines and shapes, it's far more interesting to use resources like images, sounds, and 3D models. That's where assets come in. When you call a function like sprite you need to give it an image to draw. There are a few ways to do this, the easiest is to type the code sprite() and then tap on the highlighted parentheses (). This will present the asset picker so you can visually select an image

When you do this, you'll notice that the image you select is referred to with an asset key, it might look something like asset.builtin.Planet_Cute.Icon. An asset key describes the location of a file on your device, and Codea actually checks that the file exists while you are writing your code. If you type an asset key that does not exist, you will notice that Codea puts a red marker next to your code informing you that the specified asset can't be found

Specifying Assets

Start by typing the word assets in your code followed by a dot (.), you will see the list of autocomplete suggestions appear, and these will refer to real files and folders on your device

Asset Locations

Project: to specify assets in your current project, just type asset.AssetName where "AssetName" is a file or folder in your project

Documents: to specify assets in Codea's documents folder, type asset.documents.AssetName

Built-in: to specify assets from Codea's built-in collection of sprites, sounds and shaders, use asset.builtin.AssetName

Creating New Assets

When you need to tell Codea where to save a file, you can use the Lua concatenation operator (..) to create an asset key to a non-existent path. For example:

saveText(asset.documents .. "readme.txt", "Hello World")

The code asset.documents .. "readme.txt" tells Codea to create a path in your documents folder pointing to file called "readme.txt"

Enumerating Assets

To get the number of files in a folder you can use the Lua length operator (#), some examples:

-- Number of files in your project
print(#assets)

-- Number of files in documents
print(#asset.documents)

-- Number of files in a folder in documents
print(#asset.documents.SomeFolder)

To list all assets in a folder you can append .all onto the folder path to return an array of the folder contents as asset keys, e.g.,

-- Get all files in the current project
-- and iterate over them, printing their
-- path

for i,v in pairs(asset.all) do
    print(i, v.path)
end

Special Cases

Codea tries to surface as many of the assets from your files into your code as it can, but sometimes you'll have files named with special characters and these won't translate into valid variable names in Lua. To access the raw contents of an asset library you can use square bracket notation, for example: asset.documents["My File (2).png"]. Codea won't be able to check whether the asset exists or offer autocomplete for this syntax

One other special case occurs if you have multiple files with identical names, but different file extensions. In this case Codea will offer them as static assets using _ext for the extension to differentiate. For example, asset.MyObject_png and asset.MyObject_obj refer to "MyObject.png" and "MyObject.obj" in your Codea project respectively

Asset Library Tracking

Finally, you can tell Codea to monitor a folder for changes by assigning a function to the updated property of the specified folder. Note that this only works on asset paths to folders, not to individual files. For example:

-- Track files in a folder in
-- documents for changes

asset.documents.MyFolder.updated = function (lib)
    print("Number of files " .. #lib)
end

-- Track files in your project

asset.updated = function (lib)
    print("Project files modified", lib)
end

When you press the play button, the draw() function is repeatedly executed by Codea. Codea tries to execute the draw() function 60 times per second - if it can. Codea can't guarantee that your draw() function will be called 60 times per second (it may slow down if your project performs a lot of computation, or creates highly complex drawing).

function draw()
    -- Set the background color to blueish
    background(100,120,180)

    -- Set the fill color to red
    fill(255,0,0)

    -- Set a wide outline
    strokeWidth(5)

    -- Set the outline color to white
    stroke(255)

    -- Draw a red circle with a white outline
    -- In the center of the screen
    ellipse( WIDTH/2, HEIGHT/2, 200 )
end

Note that the above code will run 60 times every second. That is, you are telling Codea to paint the background blue and draw a red circle with a white outline 60 times per second, from scratch. It does this so that you can create smooth motion by changing your program state over time, and updating your drawing code to reflect the new state. For example, you might make the circle bounce on the ground by changing its Y-position (the second parameter to ellipse()) every frame.

When you press the play button Codea will call the setup() function once, before it begins calling the draw() function. In here you can perform any once-off computations, set up program state, set the display mode, and do things that you don't need to do every frame. For example, the setup() function below creates a global variable controlled by a slider. This variable is then used in the draw() function to control the Y-position of a circle.

function setup()
    displayMode(STANDARD)
    parameter("YPosition", 0,
              HEIGHT, HEIGHT/2)
end

function draw()
    background(0)
    fill(255,0,0)
    ellipse( WIDTH/2,
             YPosition,
             200 )
end

Clears the background to the specified color. You should generally call this at the start of your draw() function in order to clear the contents of the previous frame.

Draws an ellipse centered at x, y with horizontal and vertical dimensions specified by width and height. The ellipseMode() function sets how these parameters are interpreted. Use fill() to set the color of an ellipse and stroke() to set its outline color.

If only the width is specified, this is treated as the ellipse diameter (or radius, if ellipseMode( RADIUS ) is used).

The interpretation of an ellipse's x, y, width and height parameters can be specified using the ellipseMode() function. ellipseMode() is set to CENTER by default.

Draws a rectangle with its lower-left corner positioned at x, y and sized at width, height. Use fill() to set the color of a rectangle and stroke() to set the outline color.

The interpretation of a rectangle's x, y, width and height parameters can be specified using the rectMode() function. rectMode() is set to CORNER by default.

Draws the sprite specified by asset. A sprite is a a bitmap graphic (such as a character, or a space ship). The asset specifies the location of the file to use for drawing

Alternatively, an image can be provided in instead of an asset to draw that image. CAMERA may also by provided in order to draw the current capture source video input.

By default the x and y parameters set the location of the center of the sprite, the origin mode can be set using the spriteMode() function. The last two parameters are optional and set the width and height in pixels, if these are not specified the sprite will be rendered at the pixel dimensions of its graphic. Sprites can be tinted with the tint() function.

Draws text at the given x, y location. You can set the font used by text() with the font() function. Text appearance can be further configured by using the fontSize() and fill() functions.

You can change the alignment and wrapping of text by using textAlign() and textWrapWidth(). If textWrapWidth() is set to 0 (the default) text will be drawn on one line. If textWrapWidth() is set to a value greater than 0 the text will word-wrap if it exceeds the width specified by textWrapWidth()

By default the x and y parameters set the location of the center of the text, the origin mode can be set using the textMode() function. Text color can be changed with the fill() function.

If you need to get the dimensions of a string in the current style, see the textSize function documentation.

Draws a line between the two points specified by x1,y1 and x2,y2. A line's color can be set with the stroke() function and its width can be set with the strokeWidth() function. A line's cap style can be changed with the lineCapMode() function. Note that line cap modes only take effect when drawing with the rendering mode set to smooth(). When using noSmooth(), lines will be rendered using square end caps.

Translates all subsequent drawing operations by the specified x and y values. Translations are cumulative, so a call to translate( 50, 0 ) followed by a call to translate( 10, 10 ) will translate all subsequent drawing operations by 60, 10. Translate can take an optional z parameter to specify depth.

Specifies an amount of rotation (in degrees) to apply to all subsequent drawing. All subsequent drawing functions will be rotated by angle value specified in this function. Rotations are cumulative, so calling rotate(30) followed by rotate(20) has the same effect as rotate(50).

rotate() can also be called with a specific axis, defined by the x, y, z parameters. This allows rotation to occur on an arbitrary axis for 3D effects. By default the axis is (0, 0, 1), this means that objects rotate about the axis pointing toward the viewer.

Specifies an amount of scale to apply to all drawing. All subsequent drawing functions will be scaled by the x and y values specified in this function. Scale values are specified as a scalar multipliers, for example, scale(2.0, 2.0) will double the x and y dimensions of subsequent drawing commands. scale() is cumulative, so calling scale(0.5) followed by scale(0.5) will scale all subsequent drawing operations by 0.25 (i.e., one quarter of their original size).

Sets the z level of future drawing operations. Negative values mean the drawing will occur behind (further into the screen), positive values will cause drawing to happen in front. By default all drawing will occur above previous drawing operations.

This property is pushed onto the matrix stack with pushMatrix().

Sets the projection matrix to the perspective projection defined by the parameters fov (field of view, in degrees), aspect (aspect ratio of the screen, defaults to WIDTH/HEIGHT), near and far. The near and far values specify the closest and farthest distance an object can be without being clipped by the view frustum.

When called without arguments, sets up a perspective projection with a field of view of 45 degrees and an aspect ratio of WIDTH/HEIGHT.

Sets the projection matrix to the orthographic projection defined by the parameters left, right, bottom, top, near and far. The near and far values specify the closest and farthest distance an object can be without being clipped by the view frustum.

When called with no arguments, sets up the default orthographic projection, equivalent to ortho( 0, WIDTH, 0, HEIGHT, -10, 10 ).

Sets the view matrix to the simulate a camera positioned at eye and looking at center. With an up-vector specified by up.

This can be used in conjunction with the perspective projection to simulate a camera positioned in 3D space looking at your scene.

Multiplies the matrix specified by matrix against the current model matrix. The current model matrix represents the world transform, this is the same matrix used in pushMatrix and popMatrix operations.

When called with no arguments, returns a matrix containing current world transformation. When called with a matrix argument, sets the current world transformation to the given matrix.

When called with no arguments, returns a matrix containing current view transformation. When called with a matrix argument, sets the current view transformation to the given matrix.

The view transform defaults to the identity matrix and is provided as a convenient place to store a camera transform when dealing with 3D scenes. Standard Codea projects do not normally utilise it. See the camera() function for a convenient way to set up the view transform.

When called with no arguments, returns a matrix containing current projection transformation. When called with a matrix argument, sets the current projection transformation to the given matrix.

The projection transform defaults to an orthographic projection the width and height of the screen. See the perspective and ortho functions for more advanced ways to set up the projection matrix.

This type represents a color with transparency information. You can provide this type as arguments to the style functions fill(), tint(), stroke(), and background().

This method computes a color by blending two color types. Colors are blended based on the first color's alpha value. The blend amount is determined by the alpha value of the color invoking this method.

This method computes a color by mixing two color types linearly. Colors are blended based on the specified mix value, amount. A value of 0.5 for amount will generate a color that is half way between the two input colors.

Sets the blend mode for all further drawing. The blend mode decides how new drawing operations are blended with underlying pixels.

The default blend mode is blendMode( NORMAL ), this blends graphics according to their alpha value. NORMAL will cause drawing operations to replace the underlying pixels where the alpha value is 1.0, and mix with the underlying pixels where alpha is less than 1.0.

ADDITIVE blend mode blends drawing operations by adding color. Using this mode will cause overlapping drawing to tend towards white. This allows for glowing effects, and is useful for particle rendering (e.g. sparks, glows, fire).

MULTIPLY blend mode blends drawing operations by multiplying color. Using this mode will cause overlapping drawing to tend towards black.

More advanced blend modes can be set up by using the advanced two and four parameter versions of the function. Advanced blend modes parameters are similar to the OpenGL functions glBlendFunc and glBlendFuncSeparate.

Calling blendMode() with no arguments will return the current blend mode (multiple values will returned if an advanced blend mode is set, up to four values can be returned).

Sets the blend equation for all further drawing. The blend equation determines how the destination pixels are computed given the current blend mode (see blendMode)

By default, the terms in the blend mode are added together to determine the color of the resulting pixel. Using this function you can change the operator to ADD, SUBTRACT, REVERSE_SUBTRACT, MIN, and MAX

Sets the origin of the ellipses drawn with the ellipse() function. The default is ellipseMode( CENTER ).

Sets the origin of the rectangles drawn with the rect() function. The default is rectMode( CORNER ).

Sets the origin of the sprites drawn with the sprite() function. The default is spriteMode( CENTER ).

Returns the pixel size of the sprite specified by asset. If the sprite name is valid this function returns two values, width and height.

If the sprite name represents a multi-page PDF, then this function will return three values: width, height, and page count.

Sets the origin of text drawn with the text() function. The default is textMode( CENTER ).

Sets the style of the line caps drawn with the line() function. The default is lineCapMode( ROUND ). Note that lineCapMode() only has an effect if smooth() is set.

Sets the color used to fill shapes drawn with the ellipse() and rect() functions. Also sets the color of text drawn with the text() function.

Sets the color of the fill to completely transparent.

Sets the color used to tint sprites drawn with the sprite() function. This color is multiplied with the sprite's color by default.

Setting a white tint with a partial alpha value will make a sprite semi-transparent.

Sets the color of the tint to white and completely opaque.

Sets the color used to outline the shapes drawn with the ellipse() and rect() functions. Also sets the color of lines drawn with the line() function.

Sets the width of the outline of shapes drawn with the ellipse() and rect() functions. Also sets the width of lines drawn with the line() function.

Sets the stroke width to zero.

This enables smooth line drawing, texture filtering and antialiasing. Lines will appear anti-aliased and respect styles set using the lineCapMode() function. Sprite textures will appear smoother when scaled, and primitive shapes will have antialiased edges

This disables smooth line drawing, texture filtering and antialiasing. Lines will appear aliased, scaled sprites will have pixellated textures, and primitive shapes, such as ellipse, will no longer have antialiased edges

Use this option to draw very thin lines clearly, or to draw pixel-art style graphics.

This sets the current font to the font specified by name. If no argument is given font() returns the current font. The default font is "Helvetica".

This sets the current font size to the size specified by size. If no argument is given fontSize() returns the current font size. The default font size is 17 points.

This function returns a table of font metrics for the currently defined font (as defined by font() and fontSize()). The metrics table contains advanced information about the font's measurements, such as ascent, leading, x height, and so on.

Please note that this function only works on iOS 5 and above.

This sets the alignment of text rendered with the text() function. This is generally used in conjunction with textWrapWidth() to produce multi-line, word-wrapped text aligned to the LEFT, CENTER or RIGHT. If called without arguments this function returns the current text alignment. The default text alignment is textAlign( LEFT ).

This sets the wrap width, in pixels, of text rendered with text(). If set to a value greater than 0, it causes text to wrap onto the next line when the line's width exceeds the specified width. When this is called without arguments, it returns the current text wrap width. The default text wrap width is 0, which indicates no wrapping, and that text should be rendered on one line.

This function returns the dimensions of the specified string when rendered with the current font size and style. Note that this function returns two values: width and height. You can use these dimensions to, for example, render a button behind a piece of text, position text within a speech bubble, and so on.

The pushMatrix() function saves any transformations that have been made and pushes a copy of them onto the top of the stack. You can then perform further transforms (translations, rotations and scales), perform drawing operations, and return to the previous transformation by calling popMatrix(). You can nest calls to pushMatrix() and popMatrix() for more complex object placement.

The following transform calls are preserved when using pushMatrix() and popMatrix(): translate(), rotate(), scale()

The popMatrix() function saves any transformations that have been made and pushes a copy of them onto the top of the stack. You can then perform further transforms (translations, rotations and scales), perform drawing operations, and return to the previous transformation by calling popMatrix(). You can nest calls to pushMatrix() and popMatrix() for more complex object placement.

The following transform calls are preserved when using pushMatrix() and popMatrix(): translate(), rotate(), scale()

This function resets all transformation. It replaces the current transform matrix with the identity matrix. This effectively repositions all drawing at 0, 0, with no rotation and scaling.

The pushStyle() function saves the current graphics style and pushes a copy of the current style onto the top of the stack. You can then modify the style, perform drawing operations, and return to the previous style by calling popStyle(). You can nest calls to pushStyle() and popStyle() in order to provide more control.

Styles set with the following functions are preserved when using pushStyle() and popStyle(): fill(), noFill(), stroke(), noStroke(), tint(), noTint(), strokeWidth(), lineCapMode(), ellipseMode(), rectMode(), spriteMode(), smooth(), noSmooth(), font(), fontSize(), textAlign(), textMode() and textWrapWidth()

The pushStyle() function saves the current graphics style and pushes a copy of the current style onto the top of the stack. You can then modify the style, perform drawing operations, and return to the previous style by calling popStyle(). You can nest calls to pushStyle() and popStyle() in order to provide more control.

Styles set with the following functions are preserved when using pushStyle() and popStyle(): fill(), noFill(), stroke(), noStroke(), tint(), noTint(), strokeWidth(), lineCapMode(), ellipseMode(), rectMode(), spriteMode(), smooth(), noSmooth()

Calling resetStyle() will reset all style parameters to their default values. This will effect whatever style is currently on the top of the stack.

Styles set with the following functions are reset when using resetStyle(): fill(), noFill(), stroke(), noStroke(), tint(), noTint(), strokeWidth(), lineCapMode(), ellipseMode(), rectMode(), spriteMode(), smooth(), noSmooth()

This type represents a 2D raster image, pixels can be set with image:set(x, y, color) and read with image:get(x, y). Images and sub-rectangles can be copied with image:copy(). Draw images onto the screen using sprite(image,x,y). See the relevant documentation pages for more details.You can access the width or the height of an image through its width and height properties.

The image.premultiplied flag allows you to specify whether the image was created with premultiplied alpha. Generally, for images you create yourself using image:set(), you'll want this set to false (the default). For images used with setContext() you will want this set to true. Note that using an image with setContext() will automatically set its premultiplied flag to true.The constructor can alternatively take png or jpeg encoded binary data which it will decode and use to construct the image. Using this will enable premultiplied alpha, and the encoded data is assumed to be premultiplied.

image(CAMERA) can be used to capture the current frame from the camera into a static image. This is a fairly slow operation and should not be done every frame. If there is no camera frame available (due to the capture source not being available, or still being initialized), an image with width and height of 0 is created.

This method returns the red, green, blue and alpha components of the pixel located at x, y in the image.

This method sets the red, green, blue and alpha components of the pixel located at x, y. If no alpha parameter is given, it is assumed to be 255.

This method will copy the pixels in one image into a new image. If no parameters are given, it will copy the whole image, otherwise it will copy the defined subregion. If the region is outside of the image, it will be adjusted to select a valid region from the image. If the rectangle is completely outside of the image, an error will occur.

This call causes all drawing operations to take place on the specified image instead of on-screen. Drawing commands such as ellipse, sprite and rect will render into the image given as an argument to setContext().

Calling setContext() with no arguments causes all drawing operations to return to their regular on-screen drawing functionality. Because Codea uses pre-multiplied drawing, any image passed to setContext() will have its premultiplied flag set to true.

An optional final argument useDepth can be specified to tell setContext to also allocate a depth buffer for the image. By default setContext will not. Allocating a depth buffer impacts performance, but allows rendering of 3D content into an image.

This type represents a file (not folder) on your device. Codea creates an object of this type when you specify an asset using the asset.FileName syntax in your code

This type represents a folder (not file) on your device. Codea creates an object of this type when you specify an asset using the asset.FolderName syntax in your code, folders can have nested subfolders and you can specify them by using .SubFolder to refer to them (where "SubFolder" is the name of your sub folder)

Returns a Perlin noise value in the range -1.0 to 1.0 sampled at location x, y, z. Any parameters not provided to this function are treated as zero.

Constrains all drawing performed after this function call to the rectangle specified by x, y, width, height. Any drawing that occurs outside the bounds will not be visible.

This can be used to make split-screen multiplayer games, for example. When called with zero arguments clip() disables the clipping rectangle, allowing drawing to occur anywhere on the screen.

This constant is set to the width of the screen in pixels.

This constant is set to the height of the screen in pixels.

Query this variable to get the current elapsed time, in seconds, while running your project.

Query this variable to get the time elapsed, in seconds, since the last draw call while running your project.

Query this variable to get the content scale factor. This specifies the internal scaling of images and sprites. On retina devices this will be equal to 2, on non-retina devices it will be equal to 1.

Calling cameraSource() will either set the current capture source, or return the currently selected one if called with no parameters.

The capture source determines which input source is used when the CAMERA constant is used in the image() and sprite() functions and as a mesh texture.

CAMERA_BACK is the default capture source.

If camera access is not authorized, or camera hardware is not available, cameraSource() will return the value -1

To get the dimensions of the current capture source frame, use spriteSize(CAMERA)

Uses the current capture source for images, sprites and textures on meshes.

CAMERA is a special constant that can be used with image(), sprite() and mesh.texture. When used with image() it provides an image containing a single snapshot from the device camera. When used with sprite() and mesh.texture it provides a live stream of the device's camera.

Uses the current capture source for images, sprites and textures on meshes.

CAMERA_DEPTH is a special constant that can be used with image(), sprite() and mesh.texture. When used with image() it provides an image containing a single snapshot from the device's estimated depth camera when used on supported devices. When used with sprite() and mesh.texture it provides a live stream of the device's depth camera.

Note that generally only the CAMERA_FRONT source will support depth sensing, and only on devices with a TrueDepth camera system.

Select the front camera of the device for use when using CAMERA.

Select the back camera of the device for use when using CAMERA.