diff options
Diffstat (limited to 'apps/plugins/lib/gray.h')
| -rw-r--r-- | apps/plugins/lib/gray.h | 300 |
1 files changed, 276 insertions, 24 deletions
diff --git a/apps/plugins/lib/gray.h b/apps/plugins/lib/gray.h index 218fb28..18be88a 100644 --- a/apps/plugins/lib/gray.h +++ b/apps/plugins/lib/gray.h @@ -9,6 +9,9 @@ * * Grayscale framework * +* This is a generic framework to use grayscale display within Rockbox +* plugins. It obviously does not work for the player. +* * Copyright (C) 2004 Jens Arnold * * All files in this archive are subject to the GNU General Public License. @@ -27,59 +30,308 @@ #ifdef HAVE_LCD_BITMAP /* and also not for the Player */ -/* This is a generic framework to use grayscale display within rockbox - * plugins. It obviously does not work for the player. +/* Initialize the framework + * + * every framework needs such a function, and it has to be called as + * the very first one */ - -/* every framework needs such a function, and it has to be called as - * the very first one */ void gray_init(struct plugin_api* newrb); -/* general functions */ +/**** general functions ****/ + +/* Prepare the grayscale display buffer + * + * arguments: + * gbuf = pointer to the memory area to use (e.g. plugin buffer) + * gbuf_size = max usable size of the buffer + * width = width in pixels (1..112) + * bheight = height in 8-pixel units (1..8) + * depth = desired number of shades - 1 (1..32) + * + * result: + * = depth if there was enough memory + * < depth if there wasn't enough memory. The number of displayable + * shades is smaller than desired, but it still works + * = 0 if there wasn't even enough memory for 1 bitplane (black & white) + * + * You can request any depth from 1 to 32, not just powers of 2. The routine + * performs "graceful degradation" if the memory is not sufficient for the + * desired depth. As long as there is at least enough memory for 1 bitplane, + * it creates as many bitplanes as fit into memory, although 1 bitplane will + * only deliver black & white display. + * + * If you need info about the memory taken by the grayscale buffer, supply an + * int* as the last parameter. This int will then contain the number of bytes + * used. The total memory needed can be calculated as follows: + * total_mem = + * sizeof(tGraybuf) (= 64 bytes currently) + * + sizeof(long) (= 4 bytes) + * + (width * bheight + sizeof(long)) * depth + * + 0..3 (longword alignment of grayscale display buffer) + */ int gray_init_buffer(unsigned char *gbuf, int gbuf_size, int width, int bheight, int depth, int *buf_taken); + +/* Release the grayscale display buffer + * + * Switches the grayscale overlay off at first if it is still running, + * then sets the pointer to NULL. + * DO CALL either this function or at least gray_show_display(false) + * before you exit, otherwise nasty things may happen. + */ void gray_release_buffer(void); + +/* Set position of the top left corner of the grayscale overlay + * + * x = left margin in pixels + * by = top margin in 8-pixel units + * + * You may set this in a way that the overlay spills across the right or + * bottom display border. In this case it will simply be clipped by the + * LCD controller. You can even set negative values, this will clip at the + * left or top border. I did not test it, but the limits may be +127 / -128 + * + * If you use this while the grayscale overlay is running, the now-freed area + * will be restored. + */ void gray_position_display(int x, int by); + +/* Switch the grayscale overlay on or off + * + * enable = true: the grayscale overlay is switched on if initialized + * = false: the grayscale overlay is switched off and the regular lcd + * content is restored + * + * DO NOT call lcd_update() or any other api function that directly accesses + * the lcd while the grayscale overlay is running! If you need to do + * lcd_update() to update something outside the grayscale overlay area, use + * gray_deferred_update() instead. + * + * Other functions to avoid are: + * lcd_blit() (obviously), lcd_update_rect(), lcd_set_contrast(), + * lcd_set_invert_display(), lcd_set_flip(), lcd_roll() + * + * The grayscale display consumes ~50 % CPU power (for a full screen overlay, + * less if the overlay is smaller) when switched on. You can switch the overlay + * on and off as many times as you want. + */ void gray_show_display(bool enable); -/* functions affecting the whole display */ +/* Set the draw mode for subsequent drawing operations + * + * drawmode = + * GRAY_DRAW_INVERSE: Foreground pixels are inverted, background pixels are + * left untouched + * GRAY_DRAW_FG: Only foreground pixels are drawn + * GRAY_DRAW_BG: Only background pixels are drawn + * GRAY_DRAW_SOLID: Foreground and background pixels are drawn + */ +void gray_set_drawmode(int drawmode); + +/* Draw modes */ +#define GRAY_DRAW_INVERSE 0 +#define GRAY_DRAW_FG 1 +#define GRAY_DRAW_BG 2 +#define GRAY_DRAW_SOLID 3 + +/* Set the foreground shade for subsequent drawing operations + * + * brightness = 0 (black) .. 255 (white) + */ +void gray_set_foreground(int brightness); + +/* Set the background shade for subsequent drawing operations + * + * brightness = 0 (black) .. 255 (white) + */ +void gray_set_background(int brightness); + +/* Set draw mode, foreground and background shades at once + * + * If you hand it -1 (or in fact any other out-of-bounds value) for a + * parameter, that particular setting won't be changed + */ +void gray_set_drawinfo(int drawmode, int fg_brightness, int bg_brightness); + +/**** functions affecting the whole display ****/ + +/* Clear the grayscale display (sets all pixels to white) */ void gray_clear_display(void); + +/* Set the grayscale display to all black */ void gray_black_display(void); + +/* Do an lcd_update() to show changes done by rb->lcd_xxx() functions (in areas + * of the screen not covered by the grayscale overlay). + * + * If the grayscale overlay is running, the update will be done in the next + * call of the interrupt routine, otherwise it will be performed right away. + * See also comment for the gray_show_display() function. + */ void gray_deferred_update(void); -/* scrolling functions */ +/**** Scrolling functions ****/ + +/* Scroll the whole grayscale buffer left by <count> pixels + * + * black_border determines if the pixels scrolled in at the right are black + * or white + * + * Scrolling left/right by an even pixel count is almost twice as fast as + * scrolling by an odd pixel count. + */ void gray_scroll_left(int count, bool black_border); + +/* Scroll the whole grayscale buffer right by <count> pixels + * + * black_border determines if the pixels scrolled in at the left are black + * or white + * + * Scrolling left/right by an even pixel count is almost twice as fast as + * scrolling by an odd pixel count. + */ void gray_scroll_right(int count, bool black_border); + +/* Scroll the whole grayscale buffer up by 8 pixels + * + * black_border determines if the pixels scrolled in at the bottom are black + * or white + * + * Scrolling up/down by 8 pixels is very fast. + */ void gray_scroll_up8(bool black_border); + +/* Scroll the whole grayscale buffer down by 8 pixels + * + * black_border determines if the pixels scrolled in at the top are black + * or white + * + * Scrolling up/down by 8 pixels is very fast. + */ void gray_scroll_down8(bool black_border); + +/* Scroll the whole grayscale buffer up by <count> pixels (<= 7) + * + * black_border determines if the pixels scrolled in at the bottom are black + * or white + * + * Scrolling up/down pixel-wise is significantly slower than scrolling + * left/right or scrolling up/down byte-wise because it involves bit + * shifting. That's why it is asm optimized. + */ void gray_scroll_up(int count, bool black_border); + +/* Scroll the whole grayscale buffer down by <count> pixels (<= 7) + * + * black_border determines if the pixels scrolled in at the top are black + * or white + * + * Scrolling up/down pixel-wise is significantly slower than scrolling + * left/right or scrolling up/down byte-wise because it involves bit + * shifting. That's why it is asm optimized. + */ void gray_scroll_down(int count, bool black_border); -/* pixel functions */ -void gray_drawpixel(int x, int y, int brightness); -void gray_invertpixel(int x, int y); +/**** Pixel and line functions ****/ + +/* Set a pixel with the current drawinfo + * + * If the drawmode is GRAY_DRAW_INVERSE, the pixel is inverted + * GRAY_DRAW_FG and GRAY_DRAW_SOLID draw the pixel in the foreground shade + * GRAY_DRAW_BG draws the pixel in the background shade + */ +void gray_drawpixel(int x, int y); + +/* Draw a line from (x1, y1) to (x2, y2) with the current drawinfo, + * See gray_drawpixel() for details + */ +void gray_drawline(int x1, int y1, int x2, int y2); + +/* Draw a horizontal line from (x1, y) to (x2, y) with the current drawinfo, + * See gray_drawpixel() for details + */ +void gray_horline(int x1, int x2, int y); + +/* Draw a vertical line from (x, y1) to (x, y2) with the current drawinfo, + * See gray_drawpixel() for details + * + * This one uses the block drawing optimization, so it is rather fast. + */ +void gray_verline(int x, int y1, int y2); + +/**** Rectangle functions ****/ + +/* Draw a (hollow) rectangle with the current drawinfo, + * See gray_drawpixel() for details + */ +void gray_drawrect(int x, int y, int nx, int ny); -/* line functions */ -void gray_drawline(int x1, int y1, int x2, int y2, int brightness); -void gray_invertline(int x1, int y1, int x2, int y2); +/* Draw a filled rectangle with the current drawinfo, + * See gray_drawpixel() for details + * + * This one uses the block drawing optimization, so it is rather fast. + */ +void gray_fillrect(int x, int y, int nx, int ny); -/* rectangle functions */ -void gray_drawrect(int x1, int y1, int x2, int y2, int brightness); -void gray_fillrect(int x1, int y1, int x2, int y2, int brightness); -void gray_invertrect(int x1, int y1, int x2, int y2); +/**** Bitmap functions ****/ -/* bitmap functions */ +/* Copy a grayscale bitmap into the display + * + * A grayscale bitmap contains one byte for every pixel that defines the + * brightness of the pixel (0..255). Bytes are read in row-major order. + * The <stride> parameter is useful if you want to show only a part of a + * bitmap. It should always be set to the "row length" of the bitmap, so + * for displaying the whole bitmap, nx == stride. + * + * This is the only drawing function NOT using the drawinfo. + */ void gray_drawgraymap(unsigned char *src, int x, int y, int nx, int ny, int stride); + +/* Display a bitmap with the current drawinfo + * + * The drawmode is used as described for gray_set_drawmode() + * + * This (now) uses the same bitmap format as the core b&w graphics routines, + * so you can use bmp2rb to generate bitmaps for use with this function as + * well. + * + * A bitmap contains one bit for every pixel that defines if that pixel is + * foreground (1) or background (0). Bits within a byte are arranged + * vertically, LSB at top. + * The bytes are stored in row-major order, with byte 0 being top left, + * byte 1 2nd from left etc. The first row of bytes defines pixel rows + * 0..7, the second row defines pixel row 8..15 etc. + * + * The <stride> parameter is useful if you want to show only a part of a + * bitmap. It should always be set to the "row length" of the bitmap. + */ void gray_drawbitmap(unsigned char *src, int x, int y, int nx, int ny, - int stride, bool draw_bg, int fg_brightness, - int bg_brightness); + int stride); -/* font support */ +/**** Font support ****/ + +/* Set font for the font routines + * + * newfont can be FONT_SYSFIXED or FONT_UI the same way as with the Rockbox + * core routines + */ void gray_setfont(int newfont); + +/* Calculate width and height of the given text in pixels when rendered with + * the currently selected font. + * + * This works exactly the same way as the core lcd_getstringsize(), only that + * it uses the selected font for grayscale. + */ int gray_getstringsize(unsigned char *str, int *w, int *h); -void gray_putsxy(int x, int y, unsigned char *str, bool draw_bg, - int fg_brightness, int bg_brightness); + +/* Display text starting at (x, y) with the current font and drawinfo + * + * The drawmode is used as described for gray_set_drawmode() + */ +void gray_putsxy(int x, int y, unsigned char *str); + #endif /* HAVE_LCD_BITMAP */ #endif /* SIMULATOR */ #endif /* __GRAY_H__ */ |