Major rework of the grayscale framework:

* api change - all drawing functions now use draw mode, foreground and
  background shades set globally by separate functions
* There are now 4 draw modes for all drawing functions, no more separate
  functions for inverse drawing
* Significant speedup of 1-bit bitmap (and font) drawing (2..3 times)
* Some more speed tweaks
* Additional functions for horizontal and vertical lines
* Copied describing comments to the header file for easier reference
* The safety net against an uninitialized grayscale buffer is gone


git-svn-id: svn://svn.rockbox.org/rockbox/trunk@4711 a1c6a512-1295-4272-9138-f99709370657

1 files changed, 276 insertions, 24 deletions

diff --git a/apps/plugins/lib/gray.h b/apps/plugins/lib/gray.h
index 218fb282c8..18be88a2f2 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__ */