Description:

The Egfx module (pronounced "E-graphics") is the "enhanced-mode" driver for the 30x7 LED display. Egfx lets you work with any number of graphics buffers of arbitrary size, and map parts of them to parts of the physical screen. There is also support for color depth (shades of intensity). Drawing commands include drawing dots, lines, and rectangles in a variety of drawing modes, moving the cursor, moving the screen around within the buffers, and lots of other cool stuff. All commands are given through "graphics scripts", which can be sent on the fly or uploaded as resources. The graphics commands are documented here.

Before using Egfx, you probably want to read the Beginner's Guide to Egfx, which lays everything out a little more clearly.

Commands:

cokerr Egfx_QueryVersion (char* versionstring)
returns the version string.

cokerr Egfx_SetMode (byte numColors, byte refreshRate, byte bufferRezID)
disables egfx if numColors is 0. Otherwise, starts up egfx, with a color pallette of numColors (must be 2 or greater), a refresh rate of refreshRate hertz, and an initial drawing buffer with rezID bufferRezID. The buffer should be created beforehand with Egfx_CreateBuffer.

Errors:

ERROR_Coke_BadResourceID

cokerr Egfx_RestoreMode ()
re-enables Egfx if it had been disabled. Unlike SetMode, which initializes parameters and the screen, RestoreMode simply gives Egfx control of the screen again, without performing initialization of any kind. The command will fail if SetMode hasn't been called in the first place.

Errors:

ERROR_Egfx_ModeNeverSet

cokerr Egfx_CheckBufferSpace (byte width, byte height)
verifies that there is enough free memory to create a graphics buffer of the given size. Fails if there is not enough memory.

Errors:

ERROR_Coke_NotEnoughMemory

cokerr Egfx_CreateBuffer (byte width, byte height, byte* query)
creates a graphics buffer of the given size and returns the resource ID of the new buffer in *query. You may free the resource yourself later if you are sure that it is no longer being used.

Errors:

ERROR_Coke_NotEnoughMemory

The following command is special and will be implemented in some special way in Libcoke.
special Egfx_ScriptInline (byte[] script)
executes a graphics script. The script should end with a zero byte. The script will terminate when a zero (or any other unrecognized command) is received as a command character.

cokerr Egfx_ScriptResource (byte rezID)
executes a graphics script stored as a resource. The script must end with a zero byte.

Errors:

ERROR_Coke_BadResourceID

cokerr Egfx_StartAutoScript (byte rezID, word speed)
executes the given graphics script resource every (speed * 8) milliseconds. If this command is called while AutoScript is already active, it replaces the old AutoScript. (If you want multiple independent AutoScripts for some reason, use Coke_SetScriptTimer. In this case, be sure to use a command script that uses Egfx_ScriptResource to execute a graphics script. Don't get your scripts mixed up!)

cokerr Egfx_StopAutoScript ()
terminates the current AutoScript, if any.

Graphics commands (to be used in scripts):

Nested scripting commands:

Setting commands:

SetColor (byte color)
sets the paint color to given value

SetDelta (signed byte deltavalue)
sets paint delta to given value

SetBaseline (byte baseline)
sets baseline to given value

SetDrawingMode (byte dmode)
sets drawing mode to the given value. dmode should be one of the following:

DMODE_NONE	draw nothing; just move cursor
DMODE_COPY	copy the current paint color to pixel location
DMODE_BLEND	average the current paint color with existing pixel color
DMODE_SHADE	increase/decrease existing pixel color by delta value
DMODE_INVERT	invert pixel color between baseline and baseline + numcolors
DMODE_ERASE	copy baseline value to pixel location

SetAutoMove (byte automove)
sets the action that should be taken after a drawing command (Dot, Xline, etc.) is completed. automove can be one of the following:

AUTOMOVE_NONE	after drawing, do not move the cursor
AUTOMOVE_LEFT	after drawing, move the cursor to the left
AUTOMOVE_RIGHT	after drawing, move the cursor to the right
AUTOMOVE_UP	after drawing, move the cursor up
AUTOMOVE_DOWN	after drawing, move the cursor down
AUTOMOVE_SCRIPT	if automove >= AUTOMOVE_SCRIPT, the graphics script with resource ID (automove - AUTOMOVE_SCRIPT) is executed after each drawing command. The AutoMove script should not call any drawing commands, because when the drawing command invokes the AutoMove itself, an infinite loop will result.

SetPan (byte pan)
sets the pan setting to pan, which should be one of the following:

PAN_NONE	do nothing
PAN_LEFT	move visible screen left (appears to shift right)
PAN_RIGHT	move visible screen right (appears to shift left)
PAN_UP	move visible screen up (appears to shift down)
PAN_DOWN	move visible screen down (appears to shift up)

Cursor commands:

Xset (byte x)
sets the x position of the cursor to the given value

Yset (byte y)
sets the y position of the cursor to the given value

Xjump (signed byte deltax)
moves the x positon of the cursor by the given amount

Yjump (signed byte deltay)
moves the y positon of the cursor by the given amount

CursorStore ()
remembers the current cursor position so it can be restored later

CursorRestore ()
sets the cursor position to the stored position

CursorStoreNum (byte register)
stores the cursor position in one of four registers. register must be between 0 and 3. CursorStore () is equivalent to CursorStoreNum ( 0 ). The cursor storage registers are properties of the buffer, so each graphics buffer has its own four registers.

CursorRestoreNum (byte register)
sets the cursor position to one of the buffer's four registers. register must be between 0 and 3.

Drawing commands:

Dot ()
draws a dot at the cursor position in the current drawing mode. The cursor moves according to automove.

Xline (signed byte deltax)
draws a horizontal line of the given width from the cursor. The cursor is left at the end of the line, plus automove.

Yline (signed byte deltay)
draws a vertical line of the given height from the cursor. The cursor is left at the end of the line, plus automove.

Frame (signed byte width) (signed byte height)
draws a rectangular frame of the given dimensions. The cursor is left unchanged except for automove.

Rect (signed byte width) (signed byte height)
draws a filled rectangle of the given dimensions. The cursor is left unchanged except for automove.

Font commands: (not implemented yet)

Char (byte char)
draws the given char in the current drawing mode. (not implemented yet)

CharLine (byte char) (byte column)
draws a vertical slice from the given column of the given char. (not implemented yet)

Buffer commands: (mostly not implemented yet)

DumpResource (byte rezID)
copies data from the given resource to the drawing buffer (not implemented yet)

DumpRectResource (byte rezID, byte width, byte height)
copies data from the given resource to a section of the drawing buffer (not implemented yet)

MoveRect (byte width, byte height, signed byte deltax, signed byte deltay)
moves a section of the drawing buffer to another location (not implemented yet)

Screen commands:

RangeSet (byte startingColumn, byte width, byte x, byte y)
sets the top-left of the given portion of the screen to the given position in the current graphics buffer

Pan ()
moves the visible screen according to the current pan setting

PanThis (byte pan)
moves the visible screen according to the given PAN_x value

PanRange (byte startingColumn, byte width)
moves a portion of the screen (a range of scanlines) according to the current pan setting