Kerry Martin / RA8875

KSM edits to RA8875

Dependents:   Liz_Test_Code

GraphicsDisplay.h@35:7dcab9e3ab25, 2014-01-23 (annotated)

Committer:
WiredHome
Date:
Thu Jan 23 23:51:47 2014 +0000
Revision:
35:7dcab9e3ab25
Parent:
34:c99ec28fac66
Child:
36:300f6ee0b2cf
Tweak the doc for the bitmap render to get better output documentation.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
dreschpe 0:de9d1462a835 1 /* mbed GraphicsDisplay Display Library Base Class
dreschpe 0:de9d1462a835 2 * Copyright (c) 2007-2009 sford
dreschpe 0:de9d1462a835 3 * Released under the MIT License: http://mbed.org/license/mit
dreschpe 0:de9d1462a835 4 *
dreschpe 0:de9d1462a835 5 * A library for providing a common base class for Graphics displays
dreschpe 0:de9d1462a835 6 * To port a new display, derive from this class and implement
dreschpe 0:de9d1462a835 7 * the constructor (setup the display), pixel (put a pixel
dreschpe 0:de9d1462a835 8 * at a location), width and height functions. Everything else
dreschpe 0:de9d1462a835 9 * (locate, printf, putc, cls, window, putp, fill, blit, blitbit)
dreschpe 0:de9d1462a835 10 * will come for free. You can also provide a specialised implementation
dreschpe 0:de9d1462a835 11 * of window and putp to speed up the results
dreschpe 0:de9d1462a835 12 */
dreschpe 0:de9d1462a835 13
dreschpe 0:de9d1462a835 14 #ifndef MBED_GRAPHICSDISPLAY_H
dreschpe 0:de9d1462a835 15 #define MBED_GRAPHICSDISPLAY_H
WiredHome 32:0e4f2ae512e2 16 #include "Bitmap.h"
dreschpe 0:de9d1462a835 17 #include "TextDisplay.h"
dreschpe 0:de9d1462a835 18
WiredHome 32:0e4f2ae512e2 19 /// The GraphicsDisplay class
WiredHome 32:0e4f2ae512e2 20 ///
WiredHome 32:0e4f2ae512e2 21 /// This graphics display class supports both graphics and text operations.
WiredHome 32:0e4f2ae512e2 22 /// Typically, a subclass is derived from this which has localizations to
WiredHome 32:0e4f2ae512e2 23 /// adapt to a specific hardware platform (e.g. a display controller chip),
WiredHome 32:0e4f2ae512e2 24 /// that overrides methods in here to either add more capability or perhaps
WiredHome 32:0e4f2ae512e2 25 /// to improve performance, by leveraging specific hardware capabilities.
WiredHome 32:0e4f2ae512e2 26 ///
WiredHome 32:0e4f2ae512e2 27 class GraphicsDisplay : public TextDisplay
WiredHome 32:0e4f2ae512e2 28 {
WiredHome 32:0e4f2ae512e2 29 public:
WiredHome 32:0e4f2ae512e2 30 /// The constructor
dreschpe 0:de9d1462a835 31 GraphicsDisplay(const char* name);
WiredHome 32:0e4f2ae512e2 32
WiredHome 32:0e4f2ae512e2 33 /// Draw a pixel in the specified color.
WiredHome 32:0e4f2ae512e2 34 ///
WiredHome 32:0e4f2ae512e2 35 /// @note this method must be supported in the derived class.
WiredHome 32:0e4f2ae512e2 36 ///
WiredHome 32:0e4f2ae512e2 37 /// @param x is the horizontal offset to this pixel.
WiredHome 32:0e4f2ae512e2 38 /// @param y is the vertical offset to this pixel.
WiredHome 32:0e4f2ae512e2 39 /// @param color defines the color for the pixel.
WiredHome 32:0e4f2ae512e2 40 /// @returns success/failure code. @see RetCode_t.
WiredHome 32:0e4f2ae512e2 41 ///
WiredHome 33:b6b710758ab3 42 virtual RetCode_t pixel(unsigned int x, unsigned int y, color_t color) = 0;
WiredHome 32:0e4f2ae512e2 43
WiredHome 32:0e4f2ae512e2 44 /// get the screen width in pixels
WiredHome 32:0e4f2ae512e2 45 ///
WiredHome 32:0e4f2ae512e2 46 /// @note this method must be supported in the derived class.
WiredHome 32:0e4f2ae512e2 47 ///
WiredHome 32:0e4f2ae512e2 48 /// @returns screen width in pixels.
WiredHome 32:0e4f2ae512e2 49 ///
WiredHome 32:0e4f2ae512e2 50 virtual uint16_t width() = 0;
WiredHome 32:0e4f2ae512e2 51
WiredHome 32:0e4f2ae512e2 52 /// get the screen height in pixels
WiredHome 32:0e4f2ae512e2 53 ///
WiredHome 32:0e4f2ae512e2 54 /// @note this method must be supported in the derived class.
WiredHome 32:0e4f2ae512e2 55 ///
WiredHome 32:0e4f2ae512e2 56 /// @returns screen height in pixels.
WiredHome 32:0e4f2ae512e2 57 ///
WiredHome 32:0e4f2ae512e2 58 virtual uint16_t height() = 0;
WiredHome 32:0e4f2ae512e2 59
WiredHome 32:0e4f2ae512e2 60 /// Prepare the controller to write binary data to the screen by positioning
WiredHome 32:0e4f2ae512e2 61 /// the memory cursor.
WiredHome 32:0e4f2ae512e2 62 ///
WiredHome 32:0e4f2ae512e2 63 /// @note this method must be supported in the derived class.
WiredHome 32:0e4f2ae512e2 64 ///
WiredHome 32:0e4f2ae512e2 65 /// @param x is the horizontal position in pixels (from the left edge)
WiredHome 32:0e4f2ae512e2 66 /// @param y is the vertical position in pixels (from the top edge)
WiredHome 32:0e4f2ae512e2 67 /// @returns success/failure code. @see RetCode_t.
WiredHome 32:0e4f2ae512e2 68 ///
WiredHome 32:0e4f2ae512e2 69 virtual RetCode_t SetGraphicsCursor(uint16_t x, uint16_t y) = 0;
WiredHome 32:0e4f2ae512e2 70
WiredHome 32:0e4f2ae512e2 71 /// Draw a filled rectangle in the specified color
WiredHome 32:0e4f2ae512e2 72 ///
WiredHome 32:0e4f2ae512e2 73 /// @note As a side effect, this changes the current
WiredHome 32:0e4f2ae512e2 74 /// foreground color for subsequent operations.
WiredHome 32:0e4f2ae512e2 75 ///
WiredHome 32:0e4f2ae512e2 76 /// @note this method must be supported in the derived class.
WiredHome 32:0e4f2ae512e2 77 ///
WiredHome 32:0e4f2ae512e2 78 /// @param x1 is the horizontal start of the line.
WiredHome 32:0e4f2ae512e2 79 /// @param y1 is the vertical start of the line.
WiredHome 32:0e4f2ae512e2 80 /// @param x2 is the horizontal end of the line.
WiredHome 32:0e4f2ae512e2 81 /// @param y2 is the vertical end of the line.
WiredHome 32:0e4f2ae512e2 82 /// @param color defines the foreground color.
WiredHome 32:0e4f2ae512e2 83 /// @param fillit is optional to NOFILL the rectangle. default is FILL.
WiredHome 32:0e4f2ae512e2 84 /// @returns success/failure code. @see RetCode_t.
WiredHome 32:0e4f2ae512e2 85 ///
WiredHome 32:0e4f2ae512e2 86 virtual RetCode_t fillrect(unsigned int x1, unsigned int y1, unsigned int x2, unsigned int y2,
WiredHome 32:0e4f2ae512e2 87 color_t color, fill_t fillit = FILL) = 0;
WiredHome 32:0e4f2ae512e2 88
WiredHome 32:0e4f2ae512e2 89
WiredHome 32:0e4f2ae512e2 90 virtual RetCode_t WriteCommand(unsigned char command, unsigned int data = 0xFFFF) = 0;
WiredHome 32:0e4f2ae512e2 91 virtual RetCode_t WriteData(unsigned char data) = 0;
WiredHome 32:0e4f2ae512e2 92
WiredHome 32:0e4f2ae512e2 93 /// Set the window, which controls where items are written to the screen.
WiredHome 32:0e4f2ae512e2 94 ///
WiredHome 32:0e4f2ae512e2 95 /// When something hits the window width, it wraps back to the left side
WiredHome 32:0e4f2ae512e2 96 /// and down a row. If the initial write is outside the window, it will
WiredHome 32:0e4f2ae512e2 97 /// be captured into the window when it crosses a boundary.
WiredHome 32:0e4f2ae512e2 98 ///
WiredHome 32:0e4f2ae512e2 99 /// @param x is the left edge in pixels.
WiredHome 32:0e4f2ae512e2 100 /// @param y is the top edge in pixels.
WiredHome 33:b6b710758ab3 101 /// @param w is the window width in pixels.
WiredHome 33:b6b710758ab3 102 /// @param h is the window height in pixels.
WiredHome 32:0e4f2ae512e2 103 /// @returns success/failure code. @see RetCode_t.
WiredHome 32:0e4f2ae512e2 104 ///
WiredHome 33:b6b710758ab3 105 virtual RetCode_t window(unsigned int x, unsigned int y, unsigned int w, unsigned int h);
WiredHome 32:0e4f2ae512e2 106
WiredHome 32:0e4f2ae512e2 107 /// Clear the screen.
WiredHome 32:0e4f2ae512e2 108 ///
WiredHome 32:0e4f2ae512e2 109 /// The behavior is to clear the whole screen.
WiredHome 32:0e4f2ae512e2 110 ///
WiredHome 32:0e4f2ae512e2 111 /// @returns success/failure code. @see RetCode_t.
WiredHome 32:0e4f2ae512e2 112 ///
WiredHome 32:0e4f2ae512e2 113 virtual RetCode_t cls();
WiredHome 32:0e4f2ae512e2 114
WiredHome 32:0e4f2ae512e2 115
WiredHome 31:c72e12cd5c67 116 virtual void WindowMax(void);
dreschpe 0:de9d1462a835 117
WiredHome 32:0e4f2ae512e2 118 /// method to put a single color pixel to the screen.
WiredHome 32:0e4f2ae512e2 119 ///
WiredHome 32:0e4f2ae512e2 120 /// This method may be called as many times as necessary after
WiredHome 32:0e4f2ae512e2 121 /// @see _StartGraphicsStream() is called, and it should be followed
WiredHome 32:0e4f2ae512e2 122 /// by _EndGraphicsStream.
WiredHome 32:0e4f2ae512e2 123 ///
WiredHome 32:0e4f2ae512e2 124 /// @param pixel is a color value to be put on the screen.
WiredHome 32:0e4f2ae512e2 125 /// @returns error code.
WiredHome 32:0e4f2ae512e2 126 ///
WiredHome 32:0e4f2ae512e2 127 virtual RetCode_t putp(color_t pixel);
WiredHome 32:0e4f2ae512e2 128
WiredHome 32:0e4f2ae512e2 129
WiredHome 33:b6b710758ab3 130 virtual void fill(int x, int y, int w, int h, color_t color);
WiredHome 33:b6b710758ab3 131 virtual void blit(int x, int y, int w, int h, const int * color);
WiredHome 29:422616aa04bd 132
WiredHome 33:b6b710758ab3 133 virtual int blitbit(int x, int y, int w, int h, const char * color);
dreschpe 0:de9d1462a835 134
WiredHome 29:422616aa04bd 135 /// This method transfers one character from the external font data
WiredHome 29:422616aa04bd 136 /// to the screen.
WiredHome 29:422616aa04bd 137 ///
WiredHome 29:422616aa04bd 138 /// @note the font data is in a special format as generate by
WiredHome 29:422616aa04bd 139 /// the mikroe font creator. \\
WiredHome 29:422616aa04bd 140 /// See http://www.mikroe.com/glcd-font-creator/
WiredHome 29:422616aa04bd 141 ///
WiredHome 29:422616aa04bd 142 /// @param x is the horizontal pixel coordinate
WiredHome 29:422616aa04bd 143 /// @param y is the vertical pixel coordinate
WiredHome 29:422616aa04bd 144 /// @param fontTable is the base of the table which has the metrics
WiredHome 29:422616aa04bd 145 /// @param fontChar is the start of that record in the table for the char (e.g. 'A' - 'Z')
WiredHome 29:422616aa04bd 146 /// @returns how far the cursor should advance to the right in pixels
WiredHome 29:422616aa04bd 147 ///
WiredHome 29:422616aa04bd 148 virtual int fontblit(int x, int y, const unsigned char * fontTable, const unsigned char * fontChar);
WiredHome 29:422616aa04bd 149
WiredHome 32:0e4f2ae512e2 150 /// This method returns the color value from a palette.
WiredHome 32:0e4f2ae512e2 151 ///
WiredHome 32:0e4f2ae512e2 152 /// This method accepts a pointer to a Bitmap color palette, which
WiredHome 32:0e4f2ae512e2 153 /// is a table in memory composed of RGB Quad values (r, g, b, 0),
WiredHome 32:0e4f2ae512e2 154 /// and an index into that table. It then extracts the color information
WiredHome 32:0e4f2ae512e2 155 /// and downsamples it to a color_t value which it returns.
WiredHome 32:0e4f2ae512e2 156 ///
WiredHome 32:0e4f2ae512e2 157 /// @note This method probably has very little value outside of
WiredHome 32:0e4f2ae512e2 158 /// the internal methods for reading BMP files.
WiredHome 32:0e4f2ae512e2 159 ///
WiredHome 32:0e4f2ae512e2 160 /// @param colorPalette is the handle to the color palette to use.
WiredHome 32:0e4f2ae512e2 161 /// @param i is the index into the color palette.
WiredHome 32:0e4f2ae512e2 162 /// @returns the color in color_t format.
WiredHome 32:0e4f2ae512e2 163 ///
WiredHome 32:0e4f2ae512e2 164 color_t RGBQuadToRGB16(RGBQUAD * colorPalette, uint16_t i);
WiredHome 32:0e4f2ae512e2 165
WiredHome 31:c72e12cd5c67 166 /// This method reads a disk file that is in bitmap format and
WiredHome 31:c72e12cd5c67 167 /// puts it on the screen.
WiredHome 31:c72e12cd5c67 168 ///
WiredHome 31:c72e12cd5c67 169 /// @note This only reads 16-bit bitmap format.
WiredHome 31:c72e12cd5c67 170 /// @note This is a slow operation, partially due to the use of
WiredHome 31:c72e12cd5c67 171 /// the local file system, and partially because bmp files
WiredHome 31:c72e12cd5c67 172 /// are stored from the bottom up, and the memory is written
WiredHome 32:0e4f2ae512e2 173 /// from the top down; as a result, it constantly 'seeks'
WiredHome 32:0e4f2ae512e2 174 /// on the file system for the next row of information.
WiredHome 31:c72e12cd5c67 175 ///
WiredHome 34:c99ec28fac66 176 /// As a performance test, a sample picture was timed. A family picture
WiredHome 34:c99ec28fac66 177 /// was converted to Bitmap format; shrunk to 352 x 272 pixels and save
WiredHome 34:c99ec28fac66 178 /// in 8-bit color format. The resulting file size was 94.5 KByte.
WiredHome 34:c99ec28fac66 179 /// The SPI port interface was set to 20 MHz.
WiredHome 34:c99ec28fac66 180 /// The original bitmap rendering software was purely in software,
WiredHome 34:c99ec28fac66 181 /// pushing 1 pixel at a time to the write function, which did use SPI
WiredHome 34:c99ec28fac66 182 /// hardware (not pin wiggling) to transfer commands and data to the
WiredHome 34:c99ec28fac66 183 /// display. Then, the driver was improved to leverage the capability
WiredHome 34:c99ec28fac66 184 /// of the derived display driver. As a final check, instead of the
WiredHome 34:c99ec28fac66 185 /// [known slow] local file system, a randomly chosen USB stick was
WiredHome 34:c99ec28fac66 186 /// used. The performance results are impressive (but depend on the
WiredHome 34:c99ec28fac66 187 /// listed factors).
WiredHome 34:c99ec28fac66 188 ///
WiredHome 35:7dcab9e3ab25 189 /// \li 34 seconds, LocalFileSystem, Software Rendering
WiredHome 35:7dcab9e3ab25 190 /// \li 9 seconds, LocalFileSystem, Hardware Rending for RA8875
WiredHome 35:7dcab9e3ab25 191 /// \li 3 seconds, MSCFileSystem, Hardware Rendering for RA8875
WiredHome 34:c99ec28fac66 192 ///
WiredHome 31:c72e12cd5c67 193 /// @param x is the horizontal pixel coordinate
WiredHome 31:c72e12cd5c67 194 /// @param y is the vertical pixel coordinate
WiredHome 31:c72e12cd5c67 195 /// @param Name_BMP is the filename on the local file system.
WiredHome 31:c72e12cd5c67 196 /// @returns success or error code.
WiredHome 31:c72e12cd5c67 197 ///
WiredHome 32:0e4f2ae512e2 198 RetCode_t RenderBitmapFile(unsigned int x, unsigned int y, const char *Name_BMP);
WiredHome 31:c72e12cd5c67 199
WiredHome 29:422616aa04bd 200 /// prints one character at the specified coordinates.
WiredHome 29:422616aa04bd 201 ///
WiredHome 29:422616aa04bd 202 /// This will print the character at the specified pixel coordinates.
WiredHome 29:422616aa04bd 203 ///
WiredHome 29:422616aa04bd 204 /// @param x is the horizontal offset in pixels.
WiredHome 29:422616aa04bd 205 /// @param y is the vertical offset in pixels.
WiredHome 29:422616aa04bd 206 /// @param value is the character to print.
WiredHome 29:422616aa04bd 207 /// @returns number of pixels to index to the right if a character was printed, 0 otherwise.
WiredHome 29:422616aa04bd 208 ///
WiredHome 29:422616aa04bd 209 virtual int character(int x, int y, int value);
WiredHome 29:422616aa04bd 210
WiredHome 32:0e4f2ae512e2 211 /// get the number of colums based on the currently active font
WiredHome 32:0e4f2ae512e2 212 ///
WiredHome 32:0e4f2ae512e2 213 /// @returns number of columns.
WiredHome 32:0e4f2ae512e2 214 ///
WiredHome 32:0e4f2ae512e2 215 virtual int columns(void);
WiredHome 32:0e4f2ae512e2 216
WiredHome 32:0e4f2ae512e2 217 /// get the number of rows based on the currently active font
WiredHome 32:0e4f2ae512e2 218 ///
WiredHome 32:0e4f2ae512e2 219 /// @returns number of rows.
WiredHome 32:0e4f2ae512e2 220 ///
WiredHome 32:0e4f2ae512e2 221 virtual int rows(void);
WiredHome 32:0e4f2ae512e2 222
WiredHome 32:0e4f2ae512e2 223 /// Select a bitmap font (provided by the user) for all subsequent text.
WiredHome 32:0e4f2ae512e2 224 ///
WiredHome 32:0e4f2ae512e2 225 /// @note Tool to create the fonts is accessible from its creator
WiredHome 32:0e4f2ae512e2 226 /// available at http://www.mikroe.com.
WiredHome 32:0e4f2ae512e2 227 /// Change the data to an array of type char[].
WiredHome 32:0e4f2ae512e2 228 ///
WiredHome 32:0e4f2ae512e2 229 /// @param font is a pointer to a specially formed font array.
WiredHome 32:0e4f2ae512e2 230 /// This special font array has a 4-byte header, followed by
WiredHome 32:0e4f2ae512e2 231 /// the data:
WiredHome 32:0e4f2ae512e2 232 /// - the number of bytes per char
WiredHome 32:0e4f2ae512e2 233 /// - the vertical size in pixels for each character
WiredHome 32:0e4f2ae512e2 234 /// - the horizontal size in pixels for each character
WiredHome 32:0e4f2ae512e2 235 /// - the number of bytes per vertical line (width of the array)
WiredHome 32:0e4f2ae512e2 236 /// @returns error code.
WiredHome 32:0e4f2ae512e2 237 ///
WiredHome 29:422616aa04bd 238 virtual RetCode_t set_font(const unsigned char * font = NULL);
WiredHome 32:0e4f2ae512e2 239
WiredHome 32:0e4f2ae512e2 240 protected:
WiredHome 32:0e4f2ae512e2 241
WiredHome 32:0e4f2ae512e2 242 /// Pure virtual method indicating the start of a graphics stream.
WiredHome 32:0e4f2ae512e2 243 ///
WiredHome 32:0e4f2ae512e2 244 /// This is called prior to a stream of pixel data being sent.
WiredHome 32:0e4f2ae512e2 245 /// This may cause register configuration changes in the derived
WiredHome 32:0e4f2ae512e2 246 /// class in order to prepare the hardware to accept the streaming
WiredHome 32:0e4f2ae512e2 247 /// data.
WiredHome 32:0e4f2ae512e2 248 ///
WiredHome 32:0e4f2ae512e2 249 /// @note this method must be supported in the derived class.
WiredHome 32:0e4f2ae512e2 250 ///
WiredHome 32:0e4f2ae512e2 251 /// @returns error code.
WiredHome 32:0e4f2ae512e2 252 ///
WiredHome 32:0e4f2ae512e2 253 virtual RetCode_t _StartGraphicsStream(void) = 0;
dreschpe 0:de9d1462a835 254
WiredHome 32:0e4f2ae512e2 255 /// Pure virtual method indicating the end of a graphics stream.
WiredHome 32:0e4f2ae512e2 256 ///
WiredHome 32:0e4f2ae512e2 257 /// This is called to conclude a stream of pixel data that was sent.
WiredHome 32:0e4f2ae512e2 258 /// This may cause register configuration changes in the derived
WiredHome 32:0e4f2ae512e2 259 /// class in order to stop the hardware from accept the streaming
WiredHome 32:0e4f2ae512e2 260 /// data.
WiredHome 32:0e4f2ae512e2 261 ///
WiredHome 32:0e4f2ae512e2 262 /// @note this method must be supported in the derived class.
WiredHome 32:0e4f2ae512e2 263 ///
WiredHome 32:0e4f2ae512e2 264 /// @returns error code.
WiredHome 32:0e4f2ae512e2 265 ///
WiredHome 32:0e4f2ae512e2 266 virtual RetCode_t _EndGraphicsStream(void) = 0;
WiredHome 32:0e4f2ae512e2 267
WiredHome 29:422616aa04bd 268 const unsigned char * font; ///< reference to an external font somewhere in memory
WiredHome 29:422616aa04bd 269
dreschpe 0:de9d1462a835 270 // pixel location
dreschpe 0:de9d1462a835 271 short _x;
dreschpe 0:de9d1462a835 272 short _y;
dreschpe 0:de9d1462a835 273
dreschpe 0:de9d1462a835 274 // window location
dreschpe 0:de9d1462a835 275 short _x1;
dreschpe 0:de9d1462a835 276 short _x2;
dreschpe 0:de9d1462a835 277 short _y1;
dreschpe 0:de9d1462a835 278 short _y2;
dreschpe 0:de9d1462a835 279 };
dreschpe 0:de9d1462a835 280
dreschpe 0:de9d1462a835 281 #endif
WiredHome 33:b6b710758ab3 282