Beginner's Guide to Egfx
by Bret Victor
Egfx is cool. I swear. When I first wrote it, I thought it was kinda neat,
nothing special... but when I actually used it for the first time
on my ditch day stack, I had an enormous amount of fun. I made a maze
game where the maze was many times the screen size and the screen panned
around the maze, "glowing" animations with things fading in and out, and
lots of other stuff. Egfx made it all really easy.
Egfx can be a little complicated at first (especially if you didn't
actually write it yourself), so hopefully I can explain how to use it...
What is Egfx?
is what you use if you want to draw pictures on the LED screen, instead
of just text. It supports multiple, arbitrarily-sized drawing buffers,
multiple "colors" (shades of intensity) and real drawing objects such as
lines and rectangles. All the cool kids use Egfx, and that's why they
are constantly surrounded by beautiful scantily-clad women (or men, depending
on their tastes). Shouldn't you use Egfx too?
When you start up Egfx with Egfx_SetMode
, you specify how many colors you want
(numcolors) and what the screen refresh rate should be. There are
some trade-offs involved, because if the product of these two numbers is
too high, the processor will be slowed down or the screen will flicker
horribly. The refresh rate though
should be above 50 Hz or there will be a noticable flicker. The general
rule is to use the fewest colors and slowest refresh rate that still looks
good. I think that at 60 Hz, seven or eight colors is about the max, but
you can experiment.
Buffers and Colors
When you draw in Egfx, you draw into a "buffer", which is not necessarily
connected to the physical screen. The buffer is created with
Egfx_CreateBuffer and can
be of arbitrary size. A one-byte value
(the "pixel color") is associated with each pixel in the buffer. The
intensity of the pixel on the screen is determined by its color as well
as the baseline and numcolors.
baseline is a parameter
that you can set which determines what color is considered "off" or "black".
All colors that are baseline or less do not light up. Colors that are
(baseline + numcolors - 1) or greater are at full intensity.
Colors in between are proportionally dimmer. You can play neat tricks with
the baseline parameter, such as slowly increasing or decreasing it to
make the screen "fade out" or "fade in". baseline starts out set to
zero to make things simple, but it is recommended that you set it to a value
closer to midrange such as 128 (and then Wipe) to give yourself more
Cursors and Drawing
The "cursor" is the position within the buffer where the next drawing command
will start drawing. There are a number of
commands that deal with moving
the cursor around. In addition, some of the drawing commands themselves move
the cursor while they draw. You often want the cursor to move in some
direction after a drawing command completes; for this, the
parameter can be used to move the cursor in one of the four directions (or
execute a graphics script resource) after each drawing command. Whenever
the cursor is told to go past the edge of the buffer, it wraps around to the
A drawing command
changes the pixel color of the pixels it draws on. How
exactly it changes them depends on the
drawing mode. A drawing mode might
use the color parameter, the
delta parameter, or neither.
Putting It Onscreen
In order for anyone to see what's in the buffer, the buffer (or part of it)
has to be mapped to the physical screen. The easiest way to do this is
with ScreenSet, which maps the entire
screen to a chunk of the buffer. Note that the buffer appears to "wrap
around" in the horizontal direction; if the chunk is too close to the right
edge of the buffer, part of the left edge of the buffer will be shown on the
screen. And if the buffer's width is less than the width of the screen, you
will see identical pictures side-by-side. Note also that there is no
wrap around in the vertical direction -- you should avoid mapping the screen
off the bottom edge of the buffer.
You can also map a chunk of the buffer to only part of the screen, using
This command lets you set a range of onscreen columns instead of all of them.
Once your buffer is mapped to the screen, you can make it appear it move
around using the Pan commands. These commands
shift the buffer mappings according to the
For example, if the screen is mapped so that
the top-left corner is position (0,0) in the buffer and you pan right, the
top-left corner will now be at position (1,0) and the picture will appear to
have shifted left. You can implement quite a number of impressive effects
just by panning around. Many types of animations can be implemented with
panning or screen/range setting, and it is much quicker than redrawing.
You can call Egfx_CreateBuffer as
much as you like to allocate more drawing buffers.
Use SetBuffer to set which buffer you
are drawing to, and use ScreenSet
or RangeSet to map it to the screen or
part of the screen. The
stored cursor positions are properties
of the current drawing buffer, and change when you switch buffers. All
other parameters stay the same though, including the cursor position
(although it might "wrap around" if it is out of the range of the buffer
being switched to). When a Pan command is
given, each range of the screen pans through whichever buffer it's been
Does this mean you can do "double-buffered" animations? Of course!
Also, some pretty interesting effects can be implemented by mapping
differently sized buffers to different parts of the screen and panning
All Egfx commands are given in "scripts", which simply consist of the
command numbers, followed by their parameters if any, and ending with a
zero byte. Libcoke may generate graphics scripts for you, if it exists.
You can execute a graphics script directly with
Egfx_ScriptInline, or you can upload
a script as a resource. Resource scripts can be executed with
from within other scripts with the
ScriptResource graphics command,
used for AutoMove, or executed
periodically automatically using
Gfx and Egfx
Neither Gfx nor Egfx erase their buffers when you turn them on. Therefore,
it is conceivable to be, say, scrolling some text with Gfx while displaying
an animation with Egfx, and switching between them by calling
Note that when you enable
one graphics mode, it automatically turns the other one off, so you don't
have to worry about both of them accidently being enabled together.
As always, feel free to ask me anything that's on your mind:
And of course, if you feel like adding anything to Egfx or implementing
the commands that haven't been implemented yet, that would be great.