picoTK is compiled into a single statically linkable library
libPTK.a (the RTEMS version of the library is called
libPTKrtems.a instead). The user's application is linked
against this library. There is a single include file PTK.h
which hold the prototypes for the exported procedures. The following
briefly describes all API functions, which are intended to be used
by the end user. The remaining functions which are used for interfacing
the picoTK low-level hardware driver to the generic picoTK "kernel"
are discussed in the section instead.
picoTK is intended to be thread-safe. I.e. in a multitasking, which RTEMS is, multiple tasks can quasi-concurrently work on (different) parts of the screen.
void picoInit(void)
picoInit() is to be called before any other library functions.
It initialises picoTK, clears the framebuffer to the default background
color (normally black) and creates the default graphic context.
Most of picoTK's functions have a parameter "graphic context".
The graphic context struct stores an environment, allowing different tasks
to have independent contexts. The graphical context is simply a data
structure of type struct picoGC. It stores such things as
foreground, background colors and the current font.
If a NULL pointer is used instead
of a pointer to struct picoGC the default graphical context is used.
void picoCreateGC(struct picoGC *gc)
picoCreateGC() initializes gc before it can be used.
The following operations can be carried out on the graphical context.
picoSetForeground(struct picoGC *gc, int color)
picoSetBackground(struct picoGC *gc, int color)
picoSetFont(struct picoGC *gc, struct picoFont *font)
Sets foregroundcolor, backgroundcolor and font for the given
graphical context gc. Foreground, backgroundcolor and font have
meaningful defaults set by picoCreateGC.
The foreground color defaults to 1,15 and 15 for 1,4 and 8 bit per pixel
modes respectively, the backgrond color defaults to 0), the default font
is a 8 by 13 pixel monospaced font (&font_8x13).
Some fonts are already part of the picoTK
library, other can be added. They can be referenced by a pointer to
a struct picoFont . The following fonts are readily usable (without
having to change the Makefile settings in the toolkit directory):
&font_10x20
&font_9x15
&font_8x13
&font_8x16
&font_7x14
&font_6x12
&font_5x7
&font_helv_b34
&font_helv_m20
&font_helv_m24
&font_helv_m25
&font_helv_m34
&font_school_m34
The ampersand is used to get the address of the font, which is casted
to type struct picoFont
The coordinate system origin (0,0) is in the upper left screen corner.
Positive values run to the right and down. Text coordinates are always
referenced to the upper left corner of a (thought) surrounding
rectangle. The same is true for pixmaps.
Color values start at 0 and go to 1, 15 and 255 for 1, 4 and 8 bit per
pixel modes respectively. The actual mapping of color values to colors
depends on the hardware implementation. picoTK applications know nothing
about the actual color mappings, i.e. there is no function to read the
RGB values corresponding to a specific color value. On the other hand
the programmer wants and has to know the actual mapping. Additionally
the process of color pixmap generation from color pictures requires to
know the color mapping. In future picoTK releases there will be a
special configuration file colorn.map for each color depth
which contains the mapping in a defined format. This means that the
color mapping is known at compile-time (through colorn.map)
but is unknown at run-time.
void picoDrawPoint(struct picoGC *gc, int x, int y)
void picoDrawLine(struct picoGC *gc,int x1, int y1, int x2, int y2)
void picoDrawRect(struct picoGC *gc,int x, int y, int w, int h)
void picoFillRect(struct picoGC *gc,int x, int y, int w, int h)
void picoReverseRect(struct picoGC *gc,int x, int y, int w, int h)
int picoDrawText(struct picoGC *gc,int x, int y, char *txt)
int picoDrawTextCentered(struct picoGC *gc, int x, int y, char *txt)
int picoDrawPixmap (struct picoGC *gc, int x, int y,
struct picoPixmap *pixmap)
picoDrawPoint() plots a single pixel at position x,
y using the foreground color.
picoDrawLine() draws a one pixel wide line between (x1,y1)
and (x2,y2) using the foreground color
picoDrawText() draws Text starting at x, y (upper left
corner of rectangle around text). Use GC-specified foreground/background
color for text display. Use the GC-specified font. The string pointed
through by txt is parsed for newline characters, which causes the
text to extend to the next line.
picoDrawTextCentered() is similar to picoDrawText() but centered
around x posistion, i.e. text extends to left and right of x to
the same amount
picoDrawPixmap() draws pixmap at x,y (upper left corner
of rectangle around pixmap). Use foreground/background color for pixmap
(monochrome pixmaps only).
picoDrawRect() draws Rectangle with an upper left corner at
(x,y) and lower right corner at (x+w-1,y+h-1)
picoFillRect() draws a filled Rectangle with an upper left corner at
(x,y) and lower right corner at (x+w-1,y+h-1)
picoReverseRect() reverses rectangular area with an upper left
corner at (x,y) and lower right corner at
(x+w-1,y+h-1). Reversing means inverting
every bit of the current color value.
This is a nice feature. picoTK can manage multiple scrollable
terminal boxes in which you can print comfortably with a special
printf compatible function (picoTermPrintf()). This makes
it easy to dump debug information or whatever else you want onto the
screen. Currently newline and return characters are interpreted to
allow formatting.
The following describes the respective API functions.
int picoTerminalCreate(struct picoTerminal *term,
struct picoGC *gc,
int x, int y, int wc, int hc)
int picoTerminalPutc(struct picoTerminal *term, int ch)
void picoTerminalPrintf(struct picoTerminal *term, char *fmt, ...)
picoTerminalCreate() creates a scrollable Terminal Window using
the settings (font, foreground color, backgroundcolor) from the
gc. The font is required to have fixed spacing in order for the
terminal to work properly. (x,y) is the upper left corner of the
terminal window. wc (width in characters) is the number of columns.
hc (height in character) is the number of line. The actual size in
pixels is depends on the font size and is internally calculated. It
can be obtained after the call to picoTerminalCreate() by looking
into term->w and term->h.
picoTerminalPutc() types single character into given terminal.
The terminal handles some special ASCII characters and VT100/320 escape
sequences:
\n (ADE 10) (Newline) moves cursor down one line.
\r (ADE 13) (Carriage Return) moves cursor to the beginning of
the current line, i.e. there is no implicit newline.
\b (ADE 8) (Backspace) moves cursor left and deletes that
character.
\e[30m ... \e[38m sets the Text foreground color (
color selection compatible to the Linux console).
\e[40m ... \e[48m sets the Text background color (
color selection compatible to the Linux console).
\e[A ... \e[D VT100 type cursor control for up, down,
right and left respectively.
picoTerminalPrintf() types characters to the terminal according to
the format string and the following parameters. It is compatible to
how POSIX printf() handles its format string. Special character are
interpreted by the terminal just as with picoTerminalPutc()
int picoTextWidth(struct picoFont *font, char *txt)
int picoTextHeight(struct picoFont *font, char *txt)
These functions calculate the width and height of the text txt
formatted using font. These functions are useful when implementing
your own text justification algorithms. The size returned is exactly
the size of the surrounding rectangle of a text drawn using the same
text and font with picoDrawText() or picoDrawTextCentered().