API Reference

The main module. Import with:

from specgfx import *
specgfx.specgfx.AT(y, x)

Returns control codes to set the coordinates of the text cursor.

Use this in a PRINT or SET command. Example: PRINT("normal",AT(5,15),"row 5 column 15",AT(14,4),"row 14 column 4")

Args:

  • y - integer - the y coordinate to move to (0-23)
  • x - integer - the x coordinate to move to (0-31)
specgfx.specgfx.ATTR(x, y)

Gets the attribute at a given text position. The attribute is an 8-bit value. The lowest three bits specify the ink colour, the next three bits specify the paper, the next bit specifies brightness, and the highest bit specified flash.

Args:

  • x - integer (0-31) - the column of the attribute to get
  • y - integer (0-23) - the row of the attribute to get
specgfx.specgfx.AUTOUPDATE()

Enable automatic updating, allowing the effects of all text and graphics operations to be seen immediately. Note that this is the default, and so it is only useful to call this if you have previously called MANUALUPDATE.

specgfx.specgfx.BEEP(duration, pitch)

Plays a beep. This is pretty crude, and the pitches become more and more approximate the higher they go.

Args:
  • duration - float - approximate time in seconds
  • pitch - float (-60 to 69) - the approximate number of semitones above middle C
specgfx.specgfx.BORDER(n)

Sets the border colour.

Args:

  • n - integer - the border colour (0-7)
specgfx.specgfx.BRIGHT(n)

Returns control codes to set or unset bright text.

Use this in a PRINT or SET command. Example: PRINT("normal",BRIGHT(1),"bright",BRIGHT(0),"normal")

Args:

  • n - integer - bright or not (0-1)
specgfx.specgfx.BYE()

Shut down the display and exit python.

specgfx.specgfx.CIRCLE(x, y, r, **args)

Draws a circle.

  • x - the x coordinate of the circle center
  • y - the y coordinate of the circle center
  • r - the radius of the circle, in pixels
  • INK (0-7)
  • PAPER (0-7)
  • BRIGHT (0-1)
  • FLASH (0-1)
  • OVER (0-1) - draw in XOR or not
  • INVERSE (0-1) - erase or not
specgfx.specgfx.CLS()

Clears the screen, and moves the text cursor to the top left.

specgfx.specgfx.DRAW(dx, dy, a=None, **args)

Draws a line from the last graphics point drawn (by PLOT or DRAW). Note that the coordinates are relative from that point, not absolute - ie. they specify the number of pixels to go right or down.

When called with the a argument, draws an arc from the graphics cursor position, ending dx pixels to the right of and dy pixels below that position. Turns through a radians - to the left if a is positive, to the right if a is negative.

Args:

  • dx - the number of pixels to move right (can be negative)
  • dy - the number of pixels to move down (can be negative)
  • a - optional - draws an arc the angle to turn through, in radians (can be negative)
  • INK (0-7) - the colour to draw in
  • OVER (0-1) - draw in XOR or not
  • INVERSE (0-1) - erase or not
specgfx.specgfx.DRAWTO(x, y, a=None, **args)

Draws a line from the last graphics point drawn (by PLOT or DRAW), to the point specified by x and y. Note that the coordinates are absolute.

Args:

  • x - the x coordinate to draw to
  • y - the y coordinate to draw to
  • a - optional - draws an arc the angle to turn through, in radians (can be negative)
  • INK (0-7) - the colour to draw in
  • OVER (0-1) - draw in XOR or not
  • INVERSE (0-1) - erase or not
specgfx.specgfx.FLASH(n)

Returns control codes to set or unset flashing text.

Use this in a PRINT or SET command. Example: PRINT("normal",FLASH(1),"flashing",FLASH(0),"normal")

Args:

  • n - integer - flashing or not (0-1)
specgfx.specgfx.GETCHARDEF(charno)

Fetches the definition of a character, as a tuple of 8 integers. See UDG for more details.

Args:

  • charno - integer (32-255) - the character to get the definition of.
specgfx.specgfx.GETKEY()

Waits for a keypress, and returns the ASCII character of the key pressed.

specgfx.specgfx.GETMEMORY()

Advanced: Gets the screen memory, as a numpy array. This is a 32k array of unsigned 8-bit integers (mimicing the address space of a 16k ZX Spectrum, with the first 16k representing ROM), and is mostly zeros. The screen memory is laid out as in a ZX Spectrum, with the pixels starting at 0x4000 and the attributes starting at 0x5800, ending at 0x5aff

This gets the actual array that specgfx works with - changing values in this array (between 0x4000 and 0x5aff) will change the screen once you call UPDATE.

specgfx.specgfx.INIT(FULL=False, SIZEX=1)

Initialise the specgfx system.

Args:

  • FULL - boolean - whether to initialise fullscreen.
  • SIZEX - integer - size multiplier for the output screen.
specgfx.specgfx.INK(n)

Returns control codes to set the ink colour (0-7).

Use this in a PRINT or SET command. Example: PRINT("normal",INK(1),"blue",INK(2),"red")

Args:

  • n - integer - the ink colour (0-7)
specgfx.specgfx.INKEYS()

If one or more keys that produce a character are held down, returns the ASCII character of the most recently held down key. Otherwise, returns “”. Equivalent to INKEY$ in ZX Spectrum Basic.

specgfx.specgfx.INPUT(*s, end='', **args)

Interactive input - prints a prompt, returns a string. Not so much like the ZX Spectrum INPUT - more like the INPUT on the Amstrad CPC.

Args:

  • s - things to print for the prompt
  • args - arguments to pass onto PRINT
specgfx.specgfx.INVERSE(n)

Returns control codes to set or unset inverse video text.

Use this in a PRINT or SET command. Example: PRINT("normal",INVERSE(1),"inverse",INVERSE(0),"normal")

Args:

  • n - integer - inverse or not (0-1)
specgfx.specgfx.MANUALUPDATE()

Disable automatic updating - all text and graphics operations will only take effect when UPDATE is called. This is useful for speed or smooth animation. To re-enable automatic updating call AUTOUPDATE.

specgfx.specgfx.MOVE(x, y)

Moves the graphics cursor to x,y.

Args:

  • x - the x coordinate to move to
  • y - the y coordinate to move to
specgfx.specgfx.OVER(n)

Returns control codes to set or unset XOR mode text. This has interesting results when text or graphics is overwritten. Notably, writing text OVER the same text will erase the text. See the ZX Spectrum manual for more details.

Use this in a PRINT or SET command. Example: PRINT(AT(0,0),"over and",AT(0,0),OVER(1),"over again we go")

Args:

  • n - integer - XOR mode or not (0-1)
specgfx.specgfx.PAPER(n)

Returns control codes to set the paper colour (0-7).

Use this in a PRINT or SET command. Example: PRINT("normal",PAPER(1),"blue",PAPER(2),"red")

Args:

  • n - integer - the paper colour (0-7)
specgfx.specgfx.PAUSE(frames)

Pauses for a specified number of frames, while updating the screen. If specgfx is running well, it runs at 60 frames a second.

Args:

  • frames - integer - the number of frames to wait for.
specgfx.specgfx.PEEK(address)

Reads a byte in the screen memory, at the given address.

Args:

  • address - integer, from 0 to 0x7fff, but only values from 0x4000 to 0x5aff are of interest.
specgfx.specgfx.PLOT(x, y, **args)

Moves the graphics cursor to the point (x,y) and plots a pixel. NOTE: graphics coordinates are relative to the top left, so (10,30) is 10 pixels to the right of and 30 below the top left.

Args:

  • x - the x coordinate to move to
  • y - the y coordinate to move to
  • INK (0-7) - the colour to plot in
  • OVER (0-1) - draw in XOR or not
  • INVERSE (0-1) - erase or not
specgfx.specgfx.POINT(x, y)

Tests the pixel at x,y, returns 1 if it is the ink colour and 0 if it is the paper colour.

Args:

  • x - the x coordinate to test
  • y - the y coordinate to test
specgfx.specgfx.POKE(address, value)

Writes a byte to the screen memory, at the given address. Writing between 0x4000 and 0x5aff will change the screen once you call UPDATE.

Args:

  • address - integer, from 0 to 0x7fff, but only values from 0x4000 to 0x5aff are of interest.
  • value - integer - the byte to write.
specgfx.specgfx.PRINT(*s, sep='', end='\n', set=False)

Outputs characters to the screen. By default this does not include a newline (use \n), or spaces between the outputs.

Args:

  • s - things to print.
  • sep - same as Python’s sep option for print.
  • end - same as Python’s end option for print.
  • set - boolean - whether any changes made with INK, PAPER, BRIGHT, FLASH, INVERSE or OVER are permanent or not.
specgfx.specgfx.RESETCHARS()

Resets the character set to its original state. Undoes the effects of UDG.

specgfx.specgfx.SCREENSTR(x, y)

Examines a text position to see what character might be there. Roughly equivalent to SCREEN$ on the ZX Spectrum. Returns a string containing the possible characters, may be empty.

This uses the current contents of the character set, from position 32 to 255, and compares them against the pixels on screen. Redefining the character set will affect the results of this function. This function will not be able to detect characters written with INVERSE, or characters with graphics drawn over the top, or with other characters drawn over the top with OVER.

Args:

  • x - integer (0-31) - the column of the character to examine
  • y - integer (0-23) - the row of the character to examine.
specgfx.specgfx.SCROLLUP()

Scrolls the screen upwards by one character cell - i.e. 8 pixels.

specgfx.specgfx.SET(*s, sep='', end='')

Use this to set ink, paper, inverse etc. for text. This works like PRINT, but all changes to ink etc. are permanent.

Args:

  • s - things to print.
  • sep - same as Python’s sep option for print.
  • end - same as Python’s end option for print.
specgfx.specgfx.SETATTR(x, y, ATTR=None, INK=None, PAPER=None, BRIGHT=None, FLASH=None)

Sets the attribute at a given text position. The attribute is an 8-bit value. The lowest three bits specify the ink colour, the next three bits specify the paper, the next bit specifies brightness, and the highest bit specified flash.

Calling this with only x and y will have no effect. Calling this with x, y and ATTR will change the whole attribute. Calling this with x, y, and at least one of INK, PAPER, BRIGHT and FLASH will

Args:

  • x - integer (0-31) - the column of the attribute to set
  • y - integer (0-23) - the row of the attribute to set
  • ATTR - integer (0-255) - optional - the new attribute
  • INK - integer (0-7) - optional - the new ink value
  • PAPER - integer (0-7) - optional - the new paper value
  • BRIGHT - integer (0-1) - optional - the new brightness value
  • FLASH - integer (0-1) - optional - the new flash value
specgfx.specgfx.TAB(n)

Returns control codes to set the x-coordinate of the text cursor. If this moves the cursor forwards, the cursor stays on the line that it is on. Otherwise, the cursor moves one line downwards.

Use this in a PRINT or SET command. Example: PRINT(TAB(0),"tab 0",TAB(16),"halfway along",TAB(8),"quarter way on the next line")

Args:

  • n - integer - the x coordinate to move to (0-31)
specgfx.specgfx.UDG(charno, values)

Redefine a character in the character set, in a manner similar to User Defined Graphics (UDG) on the ZX Spectrum.

This can be used to redefine already-existing characters, if (for example) you want to use a different font, or sacrifice some or all of the letters, numbers punctuation etc. for more graphics characters. Note also that any characters already drawn to the screen will not be altered by this - if you print an “a”, then redefine “a”, then print another “a”, then the first “a” will be in the old style and the second will be in the new style.

Example:

UDG(0x90, (0b00000001,
           0b00000011,
           0b00000111,
           0b00001111,
           0b00011111,
           0b00111111,
           0b01111111,
           0b11111111))
PRINT("")

defines a triangle character and assigns it to character number 0x90 (144 in decimal) and prints it.

Args:

  • charno - integer (32-255) - the character to define
  • values - tuple of 8 integers, 0-255, representing the character.
specgfx.specgfx.UPDATE()

Updates the display, INKEYS, and checks for the PAUSE BREAK and ESC key and closing the pygame window.

There are various reasons for calling this:

  • If MANUALUPDATE has been called, call this every time you want to show the current graphics state to the user.
  • In a loop repeatedly calling INKEYS, call this to get INKEYS up to date.
  • In a delay loop, call this to pause briefly, while updating the display, keeping flashing things flashing, respecting BREAK and the window close button.
  • When doing a lot of computation (i.e. that takes a significant amount of time), call this occasionally so the system doesn’t appear to have hung.