release
dev builds
extras
themes manual
wiki
device status forums
mailing lists
IRC bugs
patches
dev guide



Wiki > Main > GraphicsAPI (compare)

Difference: GraphicsAPI (r19 vs. r18)

Rockbox graphics API documentation - new, unified API

Overview

Existing implementations:

  • Black & white core (Targets with monochrome displays)
  • 4-level greyscale core (Targets with grayscale displays)
  • 16-bit colour core (Colour targets)
  • Greyscale library (Archos recorders, Ondios, Iriver H1x0, iAudio M5, greyscale iPods; 129 shades)
  • Archos player graphics library (black & white)

Key features:

  • Uses a draw mode concept.
  • Full clipping support
  • Core implementations are extendable by plugin library code

Concepts

The main idea is that instead of having multiple functions for the same primitive, there is a draw mode. The draw modes act as follows:

ModeEffect for elements with foreground only (pixels, lines, filled primitives)Effect for elements with foreground and background (monochrome bitmaps, text)
COMPLEMENT invert (xor) all pixels belonging to the primitive invert (xor) all foreground pixels, leave background pixels as-is
BG do nothing leave foreground pixels as-is, draw background pixels with current background colour (b&w: white)
FG draw all pixels with current foreground colour draw foreground pixels with current foreground colour (b&w: black), leave background pixels as-is
SOLID draw all pixels with current foreground colour draw foreground pixels with current foreground colour (b&w: black), draw background pixels with current background colour (b&w: white)
COMPLEMENT+INVERSEVID do nothing leave foreground pixels as-is, invert (xor) all background pixels
BG+INVERSEVID draw all pixels with current background colour draw foreground pixels with current background colour (b&w: white), leave background pixels as-is
FG+INVERSEVID do nothing leave foreground pixels as-is, draw background pixels with current foreground colour (b&w: black)
SOLID+INVERSEVID draw all pixels with current background colour draw foreground pixels with current background colour (b&w: white), draw background pixels with current foreground colour (b&w: black)

Default values

drawmode DRMODE_SOLID
foreground LCD_DEFAULT_FG (b&w: black, fixed)
background LCD_DEFAULT_BG (b&w: white, fixed)

Functions called in the UI thread context should be safe to assume that these defaults are set. If a function needs to change a value, it should restore the default before returning or calling other functions which depend on the correct values. Functions called from other threads can't assume anything about the drawmode or the foreground and background, and have to reset them to whatever they were set before prior to returning or yielding. Avoid changing these values in interrupt context unless you're absolutely sure what you are doing.

Functions

The function prefix is replaced by a generic xxx_ in the following table.

functionb&wgreycolourdescription
special functions
void xxx_blit(fb_data *data, int x, int block_y, int width, int block_height, int stride)DONE1) DONE1)   Special high-performance function to move external bitmap data (native lcd bitmap format) directly into the lcd.
void xxx_update()DONEDONEDONE Update lcd contents with contents of the whole framebuffer.
void xxx_update_rect(int x, int y, int width, int height)DONEDONEDONE Update a rectangular area of the lcd contents with the corresponding area of the framebuffer. The boundaries (horizontal or vertical depending on the hardware) of the update area are adjusted to block boundaries, i.e. the function always updates whole blocks.
void xxx_clear_display()DONEDONE2) DONE Clear the whole framebuffer, i.e. set all pixels to the current background colour (white for b&w) or to the current foreground colour (black for b&w) if inversevid is on.
parameter handling
void xxx_set_drawmode(int mode)DONEDONEDONE Set draw mode for subsequent drawing operations (inverse / foreground / background / solid + inversevid flag). Foreground and background are fixed to black & white for b&w graphics.
int xxx_get_drawmode()DONEDONEDONE Return current draw mode.
void xxx_set_foreground(unsigned foreground)   DONEDONE Set the foreground brightness (0..MAX_LEVEL) / colour (packed RGB value) for subsequent drawing operations.
unsigned xxx_get_foreground()   DONEDONE Return current foreground brightness (0..MAX_LEVEL) / colour (packed RGB value).
void xxx_set_background(unsigned background)   DONEDONE Set the background brightness (0..MAX_LEVEL) / colour (packed RGB value) for subsequent drawing operations.
unsigned xxx_get_background()   DONEDONE Return current background brightness (0..MAX_LEVEL) / colour (packed RGB value).
void xxx_set_drawinfo(int mode, unsigned foreground, unsigned background)   DONEDONE Set draw mode, foreground and background brightness / colour at once.
pixel functions
void xxx_drawpixel(int x, int y)DONEDONEDONE Draw a pixel using current draw mode & foreground colour.
lines and line-like primitives
void xxx_drawline(int x1, int y1, int x2, int y2)DONEDONEDONE Draw a line using current draw mode & foreground colour, using the bresenham algorithm.
void xxx_hline(int x1, int x2, int y)DONEDONEDONE Draw a horizontal line using current draw mode & foreground colour. At least a bit faster than using bresenham, possibly using further optimisation.
void xxx_vline(int x, int y1, int y2)DONEDONEDONE Draw a vertical line using current draw mode & foreground colour. At least a bit faster than using bresenham, possibly using further optimisation.
void xxx_drawrect(int x, int y, int width, int height)DONEDONEDONE Draw a rectangle (frame) using current draw mode & foreground colour.
filled primitives
void xxx_fillrect(int x, int y, int width, int height)DONEDONEDONE Fill a rectangular area with foreground pixels.
void xxx_filltriangle(int x1, int y1, int x2, int y2, int x3, int y3)DONE3) DONE3) DONE3) Fill a triangular area with foreground pixels. Useful for 3-d rendering.
bitmaps and text
void xxx_bitmap_part(fb_data *data, int src_x, int src_y, int stride, int x, int y, int width, int height)DONEDONE4) DONE Draw a partial native bitmap. For b&w, this uses the current draw mode. The stride parameter is the width of the source bitmap in pixels.
void xxx_bitmap(fb_data *data, int x, int y, int width, int height)DONEDONE4) DONE Draw a native bitmap. For b&w, this uses the current draw mode.
void xxx_mono_bitmap_part(unsigned char *data, int src_x, int src_y, int stride, int x, int y, int width, int height)DONEDONEDONE Draw a partial monochrome (1-bit) bitmap. This uses the current draw mode, foreground and background colour. For monochrome displays this function is simply an alias to xxx_bitmap_part() and hence uses the same bitmap format. For greyscale and colour displays the format should be similar to the respective native format, i.e. for iriver H1xx, where the native format consists of vertical 4-pixel blocks (2bpp), the monochrome format consists of vertical 8-pixel blocks (same as the native archos recorder/ Ondio and native iriver H1X0? remote format).
void xxx_mono_bitmap(unsigned char *data, int x, int y, int width, int height)DONEDONEDONE Draw a monochrome (1-bit) bitmap. This uses the current draw mode, foreground and background colour.
void xxx_gray_bitmap_part(unsigned char *data, int src_x, int src_y, int stride, int x, int y, int width, int height)   DONE2)3) DONE3) Draw a partial greyscale bitmap. This uses the canonical greyscale format, 1 byte/pixel.
void xxx_gray_bitmap(unsigned char *data, int x, int y, int width, int height)   DONE2)3) DONE3) Draw a greyscale bitmap. This uses the canonical greyscale format, 1 byte/pixel.
void xxx_color_bitmap_part(unsigned char *data, int src_x, int src_y, int stride, int x, int y, int width, int height)     DONE3) Draw a partial true colour bitmap. This uses the canonical true colour format, 3 byte/pixel RGB.
void xxx_color_bitmap(unsigned char *data, int x, int y, int width, int height)     DONE3) Draw a true colour bitmap. This uses the canonical true colour format, 3 byte/pixel RGB.
void xxx_putsxyofs(int x, int y, int offset, char *string)DONEDONEDONE Draw the string, but leave out the 'offset' left pixel columns, clipping the text. Uses the current draw mode, foreground and background colour.
void xxx_putsxy(int x, int y, char *string)DONEDONEDONE Draw the string, using the current draw mode, foreground and background colour.
scrolling
void xxx_scroll_left(int count)DONE3) DONE2)3) DONE3) Scroll display contents left by 'count' pixels. Scrolled in pixels at the right are always white.
void xxx_scroll_right(int count)DONE3) DONE2)3) DONE3) Scroll display contents right by 'count' pixels. Scrolled in pixels at the left are always white.
void xxx_scroll_up(int count)DONE3) DONE2)3) DONE3) Scroll display contents up by 'count' pixels. Scrolled in pixels at the bottom are always white.
void xxx_scroll_down(int count)DONE3) DONE2)3) DONE3) Scroll display contents down by 'count' pixels. Scrolled in pixels at the top are always white

1) Only within the core, and only for displays with relatively few native grey levels, to make external pixel flipping possible (video, test_scanrate)
2) The greyscale library additionally provides unbuffered versions of these, saving RAM if only those basic functions are needed. Unbuffered mode doesn't use xxx_update[_rect](), changes are shown immediately.
3) For core implementations, these functions should be part of the plugin library.
4) As the greyscale library has a variable internal format, these functions are not provided as they don't make sense. Use grey[_ub]_gray_bitmap[_part]() instead, which take canonical greyscale bitmaps.

Viewports

A Viewport is simply a C struct containing an LCD state. It is defined as follows (in lcd.h):

struct viewport { int x; int y; int width; int height; #ifdef HAVE_LCD_BITMAP int font; int drawmode; #endif int xmargin; /* During the transition only - to be removed */ int ymargin; /* During the transition only - to be removed */ #if LCD_DEPTH > 1 unsigned fg_pattern; unsigned bg_pattern; #ifdef HAVE_LCD_COLOR unsigned lss_pattern; unsigned lse_pattern; unsigned lst_pattern; #endif #endif }; 

Each LCD driver has an internal full-screen viewport structure declared, and this is the default when the LCD driver is first initialised.

All the LCD functions described on this page only draw within the boundary of the viewport, and will use the current font, drawmode and colours defined in that viewport. (x,y) co-ordinates passed to the LCD functions will always be relative to the current viewport.

The current viewport is set with the following function:

void lcd_set_viewport(struct viewport* vp);

Passing NULL to this function will select the LCD driver's internal default viewport.

The exceptions to the "operate only within this viewport" rule are lcd_clear_display() and lcd_update(_rect). These act on the whole LCD. There are viewport-aware equivalents of these functions - lcd_clear_viewport() and lcd_update_viewport_(rect).

NOTES

  • The scrolling code stores a pointer to the viewport struct in use at the time the scrolling line was drawn on the screen. This means that you can't draw scrolling lines using temporary (i.e. on the stack) viewports - they must exist throughout the lifetime of the scrolling line;
  • Ther The intention is for different viewports to not overlap each other on the screen - i.e. there is no concept of Z-ordering, the LCD driver only ever knows about 1 viewport at a time.

Further ideas/suggestions

DaveHooper - 14 Jun 2005: Hm, adding scroll fns that operate on rects within the framebuffer would be a big win and is noteably absent in current apis. Would certainly help out with horizontal-scrolling text, for example, but could even be used for vertical-scrolling text, icon scrolling, windows-within-windows, etc

r20 - 24 Jan 2009 - 07:27:11 - JensArnold

Revision r19 - 03 Jul 2008 - 08:30 - JonathanGordon
Revision r18 - 22 Mar 2008 - 09:09 - DaveChapman
Copyright by the contributing authors.