Kerry Martin
KSM edits to RA8875
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