Graphics Libraries

Platform Scope

• graphics/Canvas: JVM interpreter, generated JVM
• graphics/Color: JVM interpreter, generated JVM
• graphics/Font: JVM interpreter, generated JVM
• graphics/Key: JVM interpreter, generated JVM
• graphics/Canvas_Input: JVM interpreter, generated JVM
• graphics/Picture: JVM interpreter, generated JVM

Opening a window needs a display. Everything else (drawing, reading pixels, saving images) also works headless, for example in tests or on a server.

Load

intern graphics/Canvas   -- also interns Color, Font, Key, Canvas_Input and Picture

Example

intern graphics/Canvas

let c := create Canvas.make(400, 400)
c.set_pen_color(Color.BLUE)
c.filled_circle(0.5, 0.5, 0.25)
c.set_pen_color(Color.BLACK)
c.text(0.5, 0.9, "hello")
c.save("circle.png")
c.show()                 -- opens a window
c.wait_until_closed()    -- keep it on screen until the user closes it

examples/graphics_example.nex draws a scene and runs a short animation. examples/graphics_input_example.nex is a small sketchpad driven by the mouse and keyboard. examples/graphics_sprite_example.nex flies a rocket sprite with the arrow keys and drags it with the mouse.

Canvas

A Canvas draws in user coordinates onto an offscreen image, and shows that image in a window on request.

• Coordinates. (0, 0) is the bottom left and (1, 1) the top right until set_x_scale/set_y_scale change them. y grows upward.
• Centre-based shapes. circle(x, y, radius), square(x, y, half_side) and rectangle(x, y, half_width, half_height) are all centred on (x, y). Lengths are scaled per axis, so with unequal x and y scales a circle comes out as an ellipse.
• Pen. Lines and outlines are drawn with the pen color, 2 * pen_radius pixels wide. The pen radius is in pixels, not user units. Colors with an alpha below 255 blend with what is underneath.
• Window. show copies the offscreen image to the window, opening the window the first time. A canvas that never calls show never opens one. Without a display, show only updates the onscreen image and wait_until_closed returns at once, so the same program runs headless.
• Buffering. With double buffering off (the default), every drawing command also refreshes an already open window. With it on, the window changes only on show. Turn it on for flicker-free animation.
• Program exit. The window closes when the program ends. A script that should stay on screen ends with wait_until_closed().
• File names. A relative name given to save or Picture.load is resolved against the directory nex was started from (NEX_USER_DIR), not the Nex install directory the launcher runs in.

from until c.is_key_pressed(Key.ESCAPE) or not c.is_window_open() do
  if c.is_mouse_pressed() then
    c.filled_circle(c.mouse_x(), c.mouse_y(), 0.01)
  end
  c.pause(16)
end

let ship := create Picture.load("ship.png")
c.enable_double_buffering()
from until c.is_key_pressed(Key.ESCAPE) or not c.is_window_open() do
  if c.is_key_pressed(Key.LEFT) then heading := heading + 4.0 end
  if c.is_mouse_pressed() then
    x := c.mouse_x()
    y := c.mouse_y()
  end
  c.clear()
  c.picture(x, y, ship, 0.05, 0.05, heading)
  c.show()
  c.pause(16)
end

Canvas_Input

The state behind a canvas's input queries, in pixels (0, 0 at the top left). The window feeds it from Swing's event thread, so it is safe to read while events arrive. It can also be fed directly, to test input handling without a window or to replay a scripted session:

c.input.record_mouse_button(40, 60, true)    -- pixel (40, 60), button down
c.input.record_key_typed("q")
c.input.record_key(Key.LEFT, true)           -- LEFT held

It also implements java.awt.event.MouseListener, MouseMotionListener, KeyListener and WindowFocusListener, which is how the window feeds it.

Key

Key codes for is_key_pressed. They are java.awt.event.KeyEvent's virtual key codes.

• Letters A to Z and digits DIGIT_0 to DIGIT_9.
• Arrows LEFT, RIGHT, UP, DOWN.
• SPACE, ENTER, ESCAPE, TAB, BACKSPACE, DELETE.
• SHIFT, CONTROL, ALT.
• HOME, END_KEY, PAGE_UP, PAGE_DOWN. (END_KEY because end is a keyword.)
• F1 to F12.

Picture

An image in memory: read from a PNG, JPEG, GIF or BMP file, or made blank, then read and changed pixel by pixel, transformed, drawn with Canvas.picture and saved.

Pixels are addressed by (col, row), with (0, 0) at the top left and rows growing downward, as in the image file. This is unlike a Canvas's user coordinates. Every pixel can hold any color and alpha exactly, whatever format the picture was loaded from.

Pixel coordinates are checked: col must be in 0..width-1 and row in 0..height-1, and rgb/argb must be in range, or the call fails its precondition. The transformations return a new picture and leave this one unchanged. Only set, set_rgb, set_argb and fill change a picture.

intern graphics/Picture

-- Red rises left to right, blue top to bottom.
let p := create Picture.make(256, 256)
from let row := 0 until row = 256 do
  from let col := 0 until col = 256 do
    p.set_rgb(col, row, col * 65536 + row)
    col := col + 1
  end
  row := row + 1
end
p.save("gradient.png")

-- Swap the red and blue channels of a photo.
let photo := create Picture.load("photo.jpg")
from let row := 0 until row = photo.height do
  from let col := 0 until col = photo.width do
    let c := photo.get(col, row)
    photo.set(col, row, create Color.make_rgba(c.blue, c.green, c.red, c.alpha))
    col := col + 1
  end
  row := row + 1
end
photo.grayscale().rotated_right().save("photo_gray.png")

A per-pixel loop is fine for small and medium images: on the compiled backend one get and one set per pixel over a 512x512 picture takes a second or two (grayscale is such a loop, so it costs about the same). fill, cropped, scaled and the flips and turns are done by Java2D in a single call, so they are much faster.

Color

An immutable RGBA value. Each channel is 0..255, and the constructor checks it. = compares colors by value.

Constants: BLACK, WHITE, RED, GREEN, BLUE, YELLOW, CYAN, MAGENTA, ORANGE, PINK, GRAY, LIGHT_GRAY, DARK_GRAY.

Font

An immutable font description. "Serif", "SansSerif" and "Monospaced" are always available. Other family names depend on the machine and fall back to a default when missing.

Constants: SANS, SERIF, MONO (all 16 point).