The Gameduino Python package ¶

Contents

The Gameduino Python package

The Gameduino Python package contains tools for Gameduino developers. To install it on Linux or Mac:

sudo easy_install gameduino

and on Windows, assuming you already installed Python 2.7 and setuptools:

cd \Python27\Scripts
easy_install PIL
easy_install PySerial
easy_install gameduino

For graphics work, you will need the Python Imaging Library (PIL). It is quite popular so many systems have it installed. To check if you have it, from Python do:

>>> import Image
>>>

gameduino.prep - for graphics and sound preparation ¶

The prep module provides utilities for preparing Gameduino media: images and sound. These utilities can be used, for example, to take image files and encode them so that the Gameduino can display them as backgrounds or sprites.

The module defines these constants for use as the palset argument to ImageRAM.addsprites():

PALETTE256A	256-color palette A
PALETTE256B	256-color palette B
PALETTE256C	256-color palette C
PALETTE256D	256-color palette D
PALETTE4A	Four-color palette A
PALETTE4B	Four-color palette B
PALETTE16A	Sixteen-color palette A
PALETTE16B	Sixteen-color palette B

gameduino.prep.encode(im)¶

Convert a PIL image to a Gameduino character background image.

Parameters:	im – A Python Imaging Library image
Return type:	tuple of data for (picture, character, font) all `array.array`.

The image must have dimensions that are multiples of 8. If any character cell contains more than four colors, then the cell’s pixel are quantized to four colors before encoding. If the image requires more than 256 unique character cells, this function throws exception OverflowError. The tuple returned contains three pieces of data:

picture - the bytes representing the character cells. For input image sized (w, h) this array has size (w/8)*(h/8). Type of this array is ‘B’ (unsigned byte)
character - the glyphs for all used 8x8 characters. One character is 16 bytes. Type of this array is ‘B’ (unsigned byte)
palette - the 4-color palettes for all used 8x8 characters. One character is 8 bytes. Type of this array is ‘H’ (unsigned short)

To display the image, load these three arrays into Gameduino memory. For example, to encode a single image and write its data to a header file titlescreen.h:

import gameduino.prep as gdprep
(dpic, dchr, dpal) = gdprep.encode(Image.open("titlescreen.png"))
hdr = open("titlescreen.h", "w")
gdprep.dump(hdr, "titlescreen_pic", dpic)
gdprep.dump(hdr, "titlescreen_chr", dchr)
gdprep.dump(hdr, "titlescreen_pal", dpal)

and to display the image on the screen, an Arduino sketch might do:

#include "titlescreen.h"

void setup()
{
...
  GD.copy(RAM_PIC, titlescreen_pic, sizeof(titlescreen_pic));
  GD.copy(RAM_CHR, titlescreen_chr, sizeof(titlescreen_chr));
  GD.copy(RAM_PAL, titlescreen_pal, sizeof(titlescreen_pal));

gameduino.prep.dump(hh, name, data)¶

Writes data to a header file for use in an Arduino Sketch.

Parameters:	hh (`file`) – destination header file name (string) – the name of the object, as it will appear in the header file data (`array.array`) – the data to be dumped

gameduino.prep.palettize(im, ncol)¶

Given an input image or list of images, convert to a palettized version using at most ncol colors. This function preserves transparency: if the input(s) have transparency then the returned image(s) have .info['transparency'] set to the transparent color.

If im is a single image, returns a single image. If im is a list of images, returns a list of images.

gameduino.prep.getpal(im)¶

im is a paletted image. Return its palette as a Gameduino sprite palette in an array.array of type ‘H’. This form can be used directly with dump():

import gameduino.prep as gdprep
...
gdprep.dump(hfile, "paletteA", gdprep.getpal(im))

class gameduino.prep.ImageRAM(hh)¶

The ImageRAM object simplifies loading of the Gameduino’s 16K sprite image RAM. A caller adds sprite images to the ImageRAM, and finally obtains a memory image using ImageRAM.used().

add(page, size)¶

Add a sprite image to the ImageRAM

Parameters:	page – image data, a list length 256 size – size of data elements, either 4, 16 or 256
Return type:	Returns a tuple (image, pal)

This method adds the data in page to the ImageRAM, and the returns the assigned location. image is the sprite image 0-63 containing the data, and pal is the palette bit select for the data.

For a 4-color image, pal is 0-3, for 16-color image pal is 0-1 and for a 256-color image pal is 0.

The image and pal values may be used to display the sprite using GD::sprite().

If the data would cause the ImageRAM to increase beyond 16K, this method throws exception OverflowError.

addsprites(name, size, im, palset=[0], center=(0, 0))¶

Extract multiple sprite frames from a source image, and generate the code to draw them.

Parameters:	name – name of the sprite set; used to name the generated `draw_` function size – size of each sprite frame (width, height) im – source image, mode must be ‘P’ - paletted palset – palette set to use for the sprite, one of PALETTE256A-D, PALETTE16A-B, PALETTE4A-B center – the center pixel of the sprite image. Default is (0,0) meaning top left pixel.

Given a sequence of sprite frames in im, this method extracts their data and adds it to the ImageRAM. In addition, it writes the code to draw the sprite to the ImageRAM’s header file. For example:

import gameduino.prep as gdprep
ir = gdprep.ImageRAM(open("hdr.h", "w"))
rock0 = gdprep.palettize(Image.open("rock0r.png"), 16)
ir.addsprites("rock0", (16, 16), rock0, gdprep.PALETTE16A, center = (8,8))

would extract the four 16x16 frames from the rock0r.png image:

and write the following code to hdr.h:

#define ROCK0_FRAMES 4
static void draw_rock0(int x, int y, byte anim, byte rot, byte jk = 0) {
...
}

For more more examples, see the asteroids demo game.

used()¶: Return the contents of the ImageRAM, as an array.array of type ‘B’. The size of the array depends on the amount of data added, up to a limit of 16K.

gameduino.prep.spectrum(specfile, cutoff=64, volume=255)¶

Read an Audacity spectrum file and return a list of (frequency, amplitude) pairs, loudest first.

Parameters:	cutoff – length of the list of returned pairs volume – total volume of the returned pairs
Return type:	list of tuples (frequency, amplitude) where frequency is a floating-point frequency in Hz, and amplitude in an integer amplitude.

This function can be used to create voice profiles for instruments and sounds. For example to load a choir sound, previously saved as choir.txt:

for (i, (f, a)) in enumerate(spectrum("choir.txt")):
    gd.voice(i, 0, int(4 * f), a, a)

gameduino.sim - simple simulator ¶

The Gameduino simulator can simulate some aspects of Gameduino hardware, both video and audio. It can be a useful tool for previewing media before loading on actual hardware.

The Gameduino in this module is similar to the one in gameduino.remote:

import gameduino
import gameduino.prep as gdprep
import gameduino.sim as gdsim

im = Image.open("platformer.png").convert("RGB")
(picd,chrd,pald) = gdprep.encode(im)
gd = gdsim.Gameduino()
gd.wrstr(gameduino.RAM_PIC, picd)
gd.wrstr(gameduino.RAM_CHR, chrd)
gd.wrstr(gameduino.RAM_PAL, pald)
gd.im().save("preview.png")

The simulator can produce screenshots (Gameduino.im()), generate single-note sounds (Gameduino.writewave()), and simulate collision RAM (Gameduino.coll()). It does not currently simulate the coprocessor.

class gameduino.sim.Gameduino¶

The Gameduino object simulates some aspects of the Gameduino hardware. For example:

>>> import gameduino
>>> import gameduino.sim as gdsim
>>> gd = gdsim.Gameduino()
>>> print hex(gd.rd(gameduino.IDENT))
0x6d

coll()¶

Return the 256 bytes of COLLISION RAM.

Return type:	list of byte values.

dump(a, l)¶: Dump l bytes memory starting at address a

fill(a, v, c)¶: Fill c bytes of memory at address a with value v

im()¶

Return the current screen as a 400x300 RGB PIL Image:

>>> import gameduino.sim
>>> gd = gameduino.sim.Gameduino()
>>> gd.im().save("screenshot.png")

memory()¶: Returns current image of memory as a 32768 byte string

microcode(src)¶

Halt coprocessor, load microprogram, restart coprocessor

Parameters:	src (string) – the microprogram, as a string, expressed

The string is loaded into the Gameduino’s microprogram area, and can be up to 256 bytes. For example, to load the split-screen scroll microprogram:

splitscreen_code = open("splitscreen.binle", "b").read()
gd.microcode(splitscreen_code)

putstr(x, y, v)¶: Write string v at screen position (x,y)

rd(a)¶: Read byte at address a

rdstr(a, n)¶

Read n bytes starting at address a

Return type:	string of length `n`.

silence()¶: Switch all voices off

sprite(spr, x, y, image, palette, rot, jk=0)¶

Set the state of a hardware sprite

Parameters:	spr – sprite number 0-511 x – x coordinate y – y coordinate image – sprite source image 0-63 palette – sprite palette select, 0-15, see below rot – sprite rotate control 0-7, see rotate jk – collision class control, 0-1

Palette select controls the number of colors used for the sprite, the source palette, and which data bits to use as source.

voice(v, wave, freq, lamp, ramp=None)¶

Set the state of a voice.

Parameters:	v (int) – voice number 0-63 wave (int) – wave type, 0 for sine 1 for noise freq (int) – frequency control, in quarter-hertz lamp (int) – left amplitude 0-255 ramp (int) – right amplitude 0-255, defaults to same `lamp`

wr(a, v)¶: Write a single byte v to address a.

wr16(a, v)¶: Write 16-bit value v at to address a

wr32(a, v)¶: Write 32-bit value v at to address a

writewave(duration, dst)¶

Write the simulated output of the sound system to a wave file

Parameters:	duration – length of clip in seconds dst – destination wave filename

gameduino.remote - remote interface ¶

The remote interface lets Python scripts read and write Gameduino memory, via the USB connection and a simple client running on the Arduino.

The remote interface can be more convenient than compiling and uploading a Sketch when developing media and coprocessor microprograms:

import gameduino.remote
gd = gameduino.remote.Gameduino("/dev/ttyUSB0", 115200)
gd.ascii()
gd.putstr(0, 5, "Hello from Python")

The Gameduino in this module is similar to the one in gameduino.sim.

Because this module uses USB serial interface to communicate with the Arduino, it requires the PySerial module.

The Arduino runs a simple program memloader that listens for serial commands and accesses Gameduino memory.

class gameduino.remote.Gameduino(usbport, speed)¶