Next Previous Contents

6. The picoTK C application interface (API)

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.

6.1 Initializing picoTK and the graphical context

     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.

6.2 Setting Options

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):

The ampersand is used to get the address of the font, which is casted to type struct picoFont

6.3 Coordinate system and color model

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 for each color depth which contains the mapping in a defined format. This means that the color mapping is known at compile-time (through but is unknown at run-time.

6.4 Drawing primitives

    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.

6.5 Scrollable terminal box

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()

6.6 Text metrics functions

    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().

Next Previous Contents