|Description:||enhanced mode (graphics mode) video driver|
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.
cokerr Egfx_QueryVersion (char* versionstring)
returns the version string.
cokerr Egfx_SetMode (byte numColors, byte refreshRate,
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.
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.
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.
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.
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.
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.
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_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)|
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
remembers the current cursor position so it can be restored later
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.
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.
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)
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)
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
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