Diff: GraphicsDisplay.h

Revision:

32:0e4f2ae512e2

Parent:

31:c72e12cd5c67

Child:

33:b6b710758ab3

--- a/GraphicsDisplay.h	Mon Jan 20 19:19:48 2014 +0000
+++ b/GraphicsDisplay.h	Tue Jan 21 03:28:36 2014 +0000
@@ -13,24 +13,120 @@
 
 #ifndef MBED_GRAPHICSDISPLAY_H
 #define MBED_GRAPHICSDISPLAY_H
-
+#include "Bitmap.h"
 #include "TextDisplay.h"
 
-class GraphicsDisplay : public TextDisplay {
-
-public:         
-          
+/// The GraphicsDisplay class 
+/// 
+/// This graphics display class supports both graphics and text operations.
+/// Typically, a subclass is derived from this which has localizations to
+/// adapt to a specific hardware platform (e.g. a display controller chip),
+/// that overrides methods in here to either add more capability or perhaps 
+/// to improve performance, by leveraging specific hardware capabilities.
+///
+class GraphicsDisplay : public TextDisplay 
+{
+public:
+    /// The constructor
     GraphicsDisplay(const char* name);
-     
+    
+    /// Draw a pixel in the specified color.
+    ///
+    /// @note this method must be supported in the derived class.
+    ///
+    /// @param x is the horizontal offset to this pixel.
+    /// @param y is the vertical offset to this pixel.
+    /// @param color defines the color for the pixel.
+    /// @returns success/failure code. @see RetCode_t.
+    ///
     virtual RetCode_t pixel(unsigned int x, unsigned int y, color_t colour) = 0;
-    virtual int width() = 0;
-    virtual int height() = 0;
-        
-    virtual void window(unsigned int x,unsigned int y,unsigned int w,unsigned int h);
+    
+    /// get the screen width in pixels
+    ///
+    /// @note this method must be supported in the derived class.
+    ///
+    /// @returns screen width in pixels.
+    ///
+    virtual uint16_t width() = 0;
+    
+    /// get the screen height in pixels
+    ///
+    /// @note this method must be supported in the derived class.
+    ///
+    /// @returns screen height in pixels.
+    ///
+    virtual uint16_t height() = 0;
+
+    /// Prepare the controller to write binary data to the screen by positioning
+    /// the memory cursor.
+    ///
+    /// @note this method must be supported in the derived class.
+    ///
+    /// @param x is the horizontal position in pixels (from the left edge)
+    /// @param y is the vertical position in pixels (from the top edge)
+    /// @returns success/failure code. @see RetCode_t.
+    ///
+    virtual RetCode_t SetGraphicsCursor(uint16_t x, uint16_t y) = 0;
+    
+    /// Draw a filled rectangle in the specified color
+    ///
+    /// @note As a side effect, this changes the current
+    ///     foreground color for subsequent operations.
+    ///
+    /// @note this method must be supported in the derived class.
+    ///
+    /// @param x1 is the horizontal start of the line.
+    /// @param y1 is the vertical start of the line.
+    /// @param x2 is the horizontal end of the line.
+    /// @param y2 is the vertical end of the line.
+    /// @param color defines the foreground color.
+    /// @param fillit is optional to NOFILL the rectangle. default is FILL.
+    /// @returns success/failure code. @see RetCode_t.
+    ///
+    virtual RetCode_t fillrect(unsigned int x1, unsigned int y1, unsigned int x2, unsigned int y2, 
+        color_t color, fill_t fillit = FILL) = 0;
+
+
+    virtual RetCode_t WriteCommand(unsigned char command, unsigned int data = 0xFFFF) = 0;
+    virtual RetCode_t WriteData(unsigned char data) = 0;
+
+    /// Set the window, which controls where items are written to the screen.
+    ///
+    /// When something hits the window width, it wraps back to the left side
+    /// and down a row. If the initial write is outside the window, it will
+    /// be captured into the window when it crosses a boundary.
+    ///
+    /// @param x is the left edge in pixels.
+    /// @param y is the top edge in pixels.
+    /// @param width is the window width in pixels.
+    /// @param height is the window height in pixels.
+    /// @returns success/failure code. @see RetCode_t.
+    ///
+    virtual RetCode_t window(unsigned int x,unsigned int y,unsigned int w,unsigned int h);
+    
+    /// Clear the screen.
+    ///
+    /// The behavior is to clear the whole screen.
+    ///
+    /// @returns success/failure code. @see RetCode_t.
+    ///
+    virtual RetCode_t cls();
+    
+
     virtual void WindowMax(void);
-    virtual void putp(color_t colour);
     
-    virtual RetCode_t cls();
+    /// method to put a single color pixel to the screen.
+    ///
+    /// This method may be called as many times as necessary after 
+    /// @see _StartGraphicsStream() is called, and it should be followed 
+    /// by _EndGraphicsStream.
+    ///
+    /// @param pixel is a color value to be put on the screen.
+    /// @returns error code.
+    ///
+    virtual RetCode_t putp(color_t pixel);
+
+            
     virtual void fill(int x, int y, int w, int h, color_t colour);
     virtual void blit(int x, int y, int w, int h, const int * colour);    
     
@@ -51,6 +147,22 @@
     ///
     virtual int fontblit(int x, int y, const unsigned char * fontTable, const unsigned char * fontChar);
     
+    /// This method returns the color value from a palette.
+    ///
+    /// This method accepts a pointer to a Bitmap color palette, which
+    /// is a table in memory composed of RGB Quad values (r, g, b, 0),
+    /// and an index into that table. It then extracts the color information
+    /// and downsamples it to a color_t value which it returns.
+    ///
+    /// @note This method probably has very little value outside of
+    ///         the internal methods for reading BMP files.
+    ///
+    /// @param colorPalette is the handle to the color palette to use.
+    /// @param i is the index into the color palette.
+    /// @returns the color in color_t format.
+    ///
+    color_t RGBQuadToRGB16(RGBQUAD * colorPalette, uint16_t i);
+    
     /// This method reads a disk file that is in bitmap format and 
     /// puts it on the screen.
     ///
@@ -58,14 +170,15 @@
     /// @note This is a slow operation, partially due to the use of
     ///         the local file system, and partially because bmp files
     ///         are stored from the bottom up, and the memory is written
-    ///         from the top down.
+    ///         from the top down; as a result, it constantly 'seeks'
+    ///         on the file system for the next row of information.
     ///
     /// @param x is the horizontal pixel coordinate
     /// @param y is the vertical pixel coordinate
     /// @param Name_BMP is the filename on the local file system.
     /// @returns success or error code.
     ///
-    RetCode_t BMP_16(unsigned int x, unsigned int y, const char *Name_BMP);
+    RetCode_t RenderBitmapFile(unsigned int x, unsigned int y, const char *Name_BMP);
     
     /// prints one character at the specified coordinates.
     ///
@@ -78,11 +191,63 @@
     ///
     virtual int character(int x, int y, int value);
     
-    virtual int columns();
-    virtual int rows();
+    /// get the number of colums based on the currently active font
+    ///
+    /// @returns number of columns.
+    ///    
+    virtual int columns(void);
+
+    /// get the number of rows based on the currently active font
+    ///
+    /// @returns number of rows.
+    ///    
+    virtual int rows(void);
+    
+    /// Select a bitmap font (provided by the user) for all subsequent text.
+    ///
+    /// @note Tool to create the fonts is accessible from its creator
+    ///     available at http://www.mikroe.com. 
+    ///     Change the data to an array of type char[].
+    ///
+    /// @param font is a pointer to a specially formed font array.
+    ///     This special font array has a 4-byte header, followed by 
+    ///     the data:
+    ///   - the number of bytes per char
+    ///   - the vertical size in pixels for each character
+    ///   - the horizontal size in pixels for each character
+    ///   - the number of bytes per vertical line (width of the array)
+    /// @returns error code.
+    ///
     virtual RetCode_t set_font(const unsigned char * font = NULL);
+
+protected:
+
+    /// Pure virtual method indicating the start of a graphics stream.
+    ///
+    /// This is called prior to a stream of pixel data being sent.
+    /// This may cause register configuration changes in the derived
+    /// class in order to prepare the hardware to accept the streaming
+    /// data.
+    ///
+    /// @note this method must be supported in the derived class.
+    ///
+    /// @returns error code.
+    ///
+    virtual RetCode_t _StartGraphicsStream(void) = 0;
     
-protected:
+    /// Pure virtual method indicating the end of a graphics stream.
+    ///
+    /// This is called to conclude a stream of pixel data that was sent.
+    /// This may cause register configuration changes in the derived
+    /// class in order to stop the hardware from accept the streaming
+    /// data.
+    ///
+    /// @note this method must be supported in the derived class.
+    ///
+    /// @returns error code.
+    ///
+    virtual RetCode_t _EndGraphicsStream(void) = 0;
+
     const unsigned char * font;     ///< reference to an external font somewhere in memory
     
     // pixel location