GraphicsDisplay.h

00001 /// @page GraphicDisplay_Copyright GraphicDisplay Library Base Class
00002 ///
00003 /// mbed GraphicsDisplay Display Library Base Class
00004 /// @copyright © 2007-2009 sford
00005 /// Released under the MIT License: http://mbed.org/license/mit
00006 ///
00007 /// extensive changes in the support of the RA8875 display by Smartware Computing.
00008 ///
00009 /// @copyright Copyright © 2012-2020 by Smartware Computing, all rights reserved.
00010 ///     This library is predominantly, that of Smartware Computing, however some
00011 ///     portions are compiled from the work of others. Where the contribution of
00012 ///     others was listed as copyright, that copyright is maintained, even as a
00013 ///     derivative work may have been created for better integration in this library.
00014 ///     See @ref Copyright_References.
00015 ///
00016 /// A library for providing a common base class for Graphics displays
00017 /// To port a new display, derive from this class and implement
00018 /// the constructor (setup the display), pixel (put a pixel
00019 /// at a location), width and height functions. Everything else
00020 /// (locate, printf, putc, cls, window, putp, fill, blit, blitbit)
00021 /// will come for free. You can also provide a specialized implementation
00022 /// of window and putp to speed up the results
00023 ///
00024 #ifndef MBED_GRAPHICSDISPLAY_H
00025 #define MBED_GRAPHICSDISPLAY_H
00026 #include "Bitmap.h"
00027 #include "TextDisplay.h"
00028 #include "GraphicsDisplayJPEG.h"
00029 #include "GraphicsDisplayGIF.h"
00030 #include "DisplayDefs.h"
00031 
00032 /// The GraphicsDisplay class
00033 ///
00034 /// This graphics display class supports both graphics and text operations.
00035 /// Typically, a subclass is derived from this which has localizations to
00036 /// adapt to a specific hardware platform (e.g. a display controller chip),
00037 /// that overrides methods in here to either add more capability or perhaps
00038 /// to improve performance, by leveraging specific hardware capabilities.
00039 ///
00040 class GraphicsDisplay : public TextDisplay
00041 {
00042 public:
00043     /// The constructor
00044     GraphicsDisplay(const char* name);
00045 
00046     //~GraphicsDisplay();
00047 
00048     /// Draw a pixel in the specified color.
00049     ///
00050     /// @note this method must be supported in the derived class.
00051     ///
00052     /// @param[in] x is the horizontal offset to this pixel.
00053     /// @param[in] y is the vertical offset to this pixel.
00054     /// @param[in] color defines the color for the pixel.
00055     /// @returns success/failure code. @see RetCode_t.
00056     ///
00057     virtual RetCode_t pixel(loc_t x, loc_t y, color_t color) = 0;
00058 
00059     /// Write a stream of pixels to the display.
00060     ///
00061     /// @note this method must be supported in the derived class.
00062     ///
00063     /// @param[in] p is a pointer to a color_t array to write.
00064     /// @param[in] count is the number of pixels to write.
00065     /// @param[in] x is the horizontal position on the display.
00066     /// @param[in] y is the vertical position on the display.
00067     /// @returns success/failure code. @see RetCode_t.
00068     ///
00069     virtual RetCode_t pixelStream(color_t * p, uint32_t count, loc_t x, loc_t y) = 0;
00070 
00071     /// Get a pixel from the display.
00072     ///
00073     /// @note this method must be supported in the derived class.
00074     ///
00075     /// @param[in] x is the horizontal offset to this pixel.
00076     /// @param[in] y is the vertical offset to this pixel.
00077     /// @returns the pixel. @see color_t
00078     ///
00079     virtual color_t getPixel(loc_t x, loc_t y) = 0;
00080 
00081     /// Get a stream of pixels from the display.
00082     ///
00083     /// @note this method must be supported in the derived class.
00084     ///
00085     /// @param[out] p is a pointer to a color_t array to accept the stream.
00086     /// @param[in] count is the number of pixels to read.
00087     /// @param[in] x is the horizontal offset to this pixel.
00088     /// @param[in] y is the vertical offset to this pixel.
00089     /// @returns success/failure code. @see RetCode_t.
00090     ///
00091     virtual RetCode_t getPixelStream(color_t * p, uint32_t count, loc_t x, loc_t y) = 0;
00092 
00093     /// get the screen width in pixels
00094     ///
00095     /// @note this method must be supported in the derived class.
00096     ///
00097     /// @returns screen width in pixels.
00098     ///
00099     virtual uint16_t width() = 0;
00100 
00101     /// get the screen height in pixels
00102     ///
00103     /// @note this method must be supported in the derived class.
00104     ///
00105     /// @returns screen height in pixels.
00106     ///
00107     virtual uint16_t height() = 0;
00108 
00109     /// Prepare the controller to write binary data to the screen by positioning
00110     /// the memory cursor.
00111     ///
00112     /// @note this method must be supported in the derived class.
00113     ///
00114     /// @param[in] x is the horizontal position in pixels (from the left edge)
00115     /// @param[in] y is the vertical position in pixels (from the top edge)
00116     /// @returns success/failure code. @see RetCode_t.
00117     ///
00118     virtual RetCode_t SetGraphicsCursor(loc_t x, loc_t y) = 0;
00119 
00120 
00121     /// Prepare the controller to write binary data to the screen by positioning
00122     /// the memory cursor.
00123     ///
00124     /// @param[in] p is the point representing the cursor position to set
00125     /// @returns @ref RetCode_t value.
00126     ///
00127     virtual RetCode_t SetGraphicsCursor(point_t p) = 0;
00128 
00129     /// Read the current graphics cursor position as a point.
00130     ///
00131     /// @returns the graphics cursor as a point.
00132     ///
00133     virtual point_t GetGraphicsCursor(void) = 0;
00134 
00135     /// Prepare the controller to read binary data from the screen by positioning
00136     /// the memory read cursor.
00137     ///
00138     /// @param[in] x is the horizontal position in pixels (from the left edge)
00139     /// @param[in] y is the vertical position in pixels (from the top edge)
00140     /// @returns success/failure code. @see RetCode_t.
00141     ///
00142     virtual RetCode_t SetGraphicsCursorRead(loc_t x, loc_t y) = 0;
00143 
00144 
00145     /// Set the window, constraining where items are written to the screen.
00146     ///
00147     /// After setting the window, text and graphics are constrained to this
00148     /// window. Text will wrap from the right edge back to the left and down
00149     /// one row and from the bottom to the top. Graphics drawing will be clipped
00150     /// at the edge of the window.
00151     ///
00152     /// @note If the initial text write is outside the window, it will be shown
00153     /// where the cursor position it. Once the write hits the right edge of
00154     /// the defined window, it will then wrap back to the left edge. Once it
00155     /// hits the bottom, it wraps to the top of the window. For this reason,
00156     /// it is common to set the text cursor to the window.
00157     ///
00158     /// @code
00159     ///     rect_t r = {10,10, 90,90};
00160     ///     r = lcd.SetWindow(r);
00161     ///     lcd.SetTextCursor(r.p1.x, r.p1.y);
00162     ///     lcd.puts("012345678901234567890123456789012345678901234567890");
00163     ///     lcd.SetWindow(r); restore to previous window setting
00164     /// @endcode
00165     ///
00166     /// @param[in] r is the rect_t used to set the window.
00167     /// @returns the previous window definition.
00168     ///
00169     virtual rect_t SetWindow(rect_t r) = 0;
00170 
00171     /// Set the window, constraining where items are written to the screen.
00172     ///
00173     /// After setting the window, text and graphics are constrained to this
00174     /// window. Text will wrap from the right edge back to the left and down
00175     /// one row and from the bottom to the top. Graphics drawing will be clipped
00176     /// at the edge of the window.
00177     ///
00178     /// @note if no parameters are provided, it restores the window to full screen.
00179     ///
00180     /// @note If the initial text write is outside the window, it will be shown
00181     /// where the cursor positions it. Once the write hits the right edge of
00182     /// the defined window, it will then wrap back to the left edge. Once it
00183     /// hits the bottom, it wraps to the top of the window. For this reason,
00184     /// it is common to set the text cursor to the window.
00185     ///
00186     /// @code
00187     ///     lcd.SetWindow(10,10, 80,80);
00188     ///     lcd.SetTextCursor(10,10);
00189     ///     lcd.puts("012345678901234567890123456789012345678901234567890");
00190     ///     lcd.SetWindow(); restore to full screen
00191     /// @endcode
00192     ///
00193     /// @param[in] x1 is the left edge in pixels.
00194     /// @param[in] y1 is the top edge in pixels.
00195     /// @param[in] x2 is the right edge in pixels.
00196     /// @param[in] y2 is the bottom edge in pixels.
00197     /// @returns the previous window definition.
00198     ///
00199     virtual rect_t SetWindow(loc_t x1 = 0, loc_t y1 = 0, loc_t x2 = (loc_t)-1, loc_t y2 = (loc_t)-1) = 0;
00200 
00201     /// Get the current window setting, which constrains what is written to the screen.
00202     ///
00203     /// @returns the current window definition.
00204     ///
00205     virtual rect_t GetWindow() = 0;
00206 
00207     /// Draw a filled rectangle in the specified color
00208     ///
00209     /// @note As a side effect, this changes the current
00210     ///     foreground color for subsequent operations.
00211     ///
00212     /// @note this method must be supported in the derived class.
00213     ///
00214     /// @param[in] x1 is the horizontal start of the line.
00215     /// @param[in] y1 is the vertical start of the line.
00216     /// @param[in] x2 is the horizontal end of the line.
00217     /// @param[in] y2 is the vertical end of the line.
00218     /// @param[in] color defines the foreground color.
00219     /// @param[in] fillit is optional to NOFILL the rectangle. default is FILL.
00220     /// @returns success/failure code. @see RetCode_t.
00221     ///
00222     virtual RetCode_t fillrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2,
00223         color_t color, fill_t fillit = FILL) = 0;
00224 
00225     /// Select the drawing layer for subsequent commands.
00226     ///
00227     /// If the screen configuration is 480 x 272, or if it is 800 x 480
00228     /// and 8-bit color, the the display supports two layers, which can
00229     /// be independently drawn on and shown. Additionally, complex
00230     /// operations involving both layers are permitted.
00231     ///
00232     /// @code
00233     ///     //lcd.SetLayerMode(OnlyLayer0); // default is layer 0
00234     ///     lcd.rect(400,130, 475,155,Brown);
00235     ///     lcd.SelectDrawingLayer(1);
00236     ///     lcd.circle(400,25, 25, BrightRed);
00237     ///     wait(1);
00238     ///     lcd.SetLayerMode(ShowLayer1);
00239     /// @endcode
00240     ///
00241     /// @attention The user manual refers to Layer 1 and Layer 2, however the
00242     ///     actual register values are value 0 and 1. This API as well as
00243     ///     others that reference the layers use the values 0 and 1 for
00244     ///     cleaner iteration in the code.
00245     ///
00246     /// @param[in] layer is 0 or 1 to select the layer for subsequent
00247     ///     commands.
00248     /// @returns The previous drawing layer.
00249     ///
00250     virtual uint16_t SelectDrawingLayer(uint16_t layer) = 0;
00251 
00252 
00253     /// Get the currently active drawing layer.
00254     ///
00255     /// This returns a value, 0 or 1, based on the screen configuration
00256     /// and the currently active drawing layer.
00257     ///
00258     /// @code
00259     ///     uint16_t prevLayer;
00260     ///     prevLayer = lcd.SelectDrawingLayer(x);
00261     ///     lcd.circle(400,25, 25, BrightRed);
00262     ///     lcd.SelectDrawingLayer(prevLayer);
00263     /// @endcode
00264     ///
00265     /// @attention The user manual refers to Layer 1 and Layer 2, however the
00266     ///     actual register values are value 0 and 1. This API as well as
00267     ///     others that reference the layers use the values 0 and 1 for
00268     ///     cleaner integration in the code.
00269     ///
00270     /// @returns the current drawing layer; 0 or 1.
00271     ///
00272     virtual uint16_t GetDrawingLayer(void) = 0;
00273 
00274     /// a function to write the command and data to the RA8875 chip.
00275     ///
00276     /// @param command is the RA8875 instruction to perform
00277     /// @param data is the optional data to the instruction.
00278     /// @returns success/failure code. @see RetCode_t.
00279     ///
00280     virtual RetCode_t WriteCommand(unsigned char command, unsigned int data = 0xFFFF) = 0;
00281 
00282 
00283     /// a function to write the data to the RA8875 chip.
00284     ///
00285     /// This is typically used after a command has been initiated, and where
00286     /// there may be a data stream to follow.
00287     ///
00288     /// @param data is the optional data to the instruction.
00289     /// @returns success/failure code. @see RetCode_t.
00290     ///
00291     virtual RetCode_t WriteData(unsigned char data) = 0;
00292 
00293     /// Clear the screen.
00294     ///
00295     /// The behavior is to clear the whole screen.
00296     ///
00297     /// @param[in] layers is ignored, but supports maintaining the same
00298     ///     API for the graphics layer.
00299     /// @returns success/failure code. @see RetCode_t.
00300     ///
00301     virtual RetCode_t cls(uint16_t layers = 0);
00302 
00303     /// method to put a single color pixel to the screen.
00304     ///
00305     /// This method may be called as many times as necessary after
00306     /// @see _StartGraphicsStream() is called, and it should be followed
00307     /// by _EndGraphicsStream.
00308     ///
00309     /// @param[in] pixel is a color value to be put on the screen.
00310     /// @returns success/failure code. @see RetCode_t.
00311     ///
00312     virtual RetCode_t _putp(color_t pixel);
00313 
00314     /// method to fill a region.
00315     ///
00316     /// This method fills a region with the specified color. It essentially
00317     /// is an alias for fillrect, however this uses width and height rather
00318     /// than a second x,y pair.
00319     ///
00320     /// @param[in] x is the left-edge of the region.
00321     /// @param[in] y is the top-edge of the region.
00322     /// @param[in] w specifies the width of the region.
00323     /// @param[in] h specifies the height of the region.
00324     /// @param[in] color is the color value to use to fill the region
00325     /// @returns success/failure code. @see RetCode_t.
00326     ///
00327     virtual RetCode_t fill(loc_t x, loc_t y, dim_t w, dim_t h, color_t color);
00328 
00329     /// method to stream bitmap data to the display
00330     ///
00331     /// This method fills a region from a stream of color data.
00332     ///
00333     /// @param[in] x is the left-edge of the region.
00334     /// @param[in] y is the top-edge of the region.
00335     /// @param[in] w specifies the width of the region.
00336     /// @param[in] h specifies the height of the region.
00337     /// @param[in] color is a pointer to a color stream with w x h values.
00338     /// @returns success/failure code. @see RetCode_t.
00339     ///
00340     virtual RetCode_t blit(loc_t x, loc_t y, dim_t w, dim_t h, const int * color);
00341 
00342     /// This method returns the width in pixels of the chosen character
00343     /// from the previously selected external font.
00344     ///
00345     /// @param[in] c is the character of interest.
00346     /// @param[in, out] width is a pointer to where the width will be stored.
00347     ///     This parameter is NULL tested and will only be written if not null
00348     ///     which is convenient if you only want the height.
00349     /// @param[in, out] height is a pointer to where the height will be stored.
00350     ///     This parameter is NULL tested and will only be written if not null
00351     ///     which is convenient if you only want the width.
00352     /// @returns a pointer to the raw character data or NULL if not found.
00353     ///
00354     virtual const uint8_t * getCharMetrics(const unsigned char c, dim_t * width, dim_t * height);
00355 
00356     /// This method transfers one character from the external font data
00357     /// to the screen.
00358     ///
00359     /// The font being used has already been set with the SelectUserFont
00360     /// API.
00361     ///
00362     /// @note the font data is in a special format as generate by
00363     ///         the mikroe font creator.
00364     ///         See http://www.mikroe.com/glcd-font-creator/
00365     ///
00366     /// @param[in] x is the horizontal pixel coordinate
00367     /// @param[in] y is the vertical pixel coordinate
00368     /// @param[in] c is the character to render
00369     /// @returns how far the cursor should advance to the right in pixels.
00370     /// @returns zero if the character could not be rendered.
00371     ///
00372     virtual int fontblit(loc_t x, loc_t y, const unsigned char c);
00373 
00374     /// This method returns the color value from a palette.
00375     ///
00376     /// This method accepts a pointer to a Bitmap color palette, which
00377     /// is a table in memory composed of RGB Quad values (r, g, b, 0),
00378     /// and an index into that table. It then extracts the color information
00379     /// and down-samples it to a color_t value which it returns.
00380     ///
00381     /// @note This method probably has very little value outside of
00382     ///         the internal methods for reading BMP files.
00383     ///
00384     /// @param[in] colorPaletteArray is the handle to the color palette array to use.
00385     /// @param[in] index is the index into the color palette.
00386     /// @returns the color in color_t format.
00387     ///
00388     color_t RGBQuadToRGB16(RGBQUAD * colorPaletteArray, uint16_t index);
00389 
00390     /// This method converts a 16-bit color value into a 24-bit RGB Quad.
00391     ///
00392     /// @param[in] c is the 16-bit color. @see color_t.
00393     /// @returns an RGBQUAD value. @see RGBQUAD
00394     ///
00395     RGBQUAD RGB16ToRGBQuad(color_t c);
00396 
00397 
00398     /// This method gets the rectangle that would render a specified image file.
00399     ///
00400     /// This is the more programmer "obvious" method of getting the size of
00401     /// an image file.
00402     ///
00403     /// @note The present implementation calls the RenderImageFile API with the
00404     ///         optional getDim parameter.
00405     ///
00406     /// @note Not all image file formats are supported. Check the return value.
00407     ///
00408     /// @param[in] x is the horizontal pixel coordinate of the top-left corner.
00409     /// @param[in] y is the vertical pixel coordinate of the top-left corner.
00410     /// @param[in] FileName refers to the fully qualified path and file on
00411     ///     a mounted file system. The filename is optional, in which case
00412     ///     it simply returns a rect_t with all elements set to zero.
00413     /// @returns a rect_t that would contain the specified image. When the
00414     ///     specified file cannot be found, or where this method is not yet
00415     ///     supported, all elements of the returned rect_r will be zero.
00416     ///
00417     rect_t GetImageRect(loc_t x, loc_t y, const char * FileName = NULL);
00418 
00419 
00420     /// This method gets the rectangle that would render a specified image file.
00421     ///
00422     /// This is the more programmer "obvious" method of getting the size of
00423     /// an image file.
00424     ///
00425     /// @note The present implementation calls the RenderImageFile API with the
00426     ///         optional getDim parameter.
00427     ///
00428     /// @note Not all image file formats are supported. Check the return value.
00429     ///
00430     /// @param[in] pt is the point defining the top-left corner.
00431     /// @param[in] FileName refers to the fully qualified path and file on
00432     ///     a mounted file system. The filename is optional, in which case
00433     ///     it simply returns a rect_t with all elements set to zero.
00434     /// @returns a rect_t that would contain the specified image. When the
00435     ///     specified file cannot be found, or where this method is not yet
00436     ///     supported, all elements of the returned rect_r will be zero.
00437     ///
00438     rect_t GetImageRect(point_t pt, const char* FileName);
00439 
00440 
00441     /// This method attempts to render a specified graphics image file at
00442     /// the specified screen location.
00443     ///
00444     /// This supports several variants of the following file types:
00445     /// @li Bitmap file format,
00446     /// @li Icon file format.
00447     /// @li Jpeg file format.
00448     ///
00449     /// @note The specified image width and height, when adjusted for the
00450     ///     x and y origin, must fit on the screen, or the image will not
00451     ///     be shown (it does not clip the image).
00452     ///
00453     /// @note The file extension is tested, and if it ends in a supported
00454     ///     format, the appropriate handler is called to render that image.
00455     ///
00456     /// @param[in] pt is the pixel coordinate of the top-left corner.
00457     /// @param[in] FileName refers to the fully qualified path and file on
00458     ///     a mounted file system.
00459     /// @param[in] getDim when not NULL the image is not drawn. Instead, the
00460     ///             getDim is filled in as the rectangle that would be drawn
00461     ///             relative to the provided x,y origin. This basically
00462     ///             provides a GetImageRect on a specified file.
00463     /// @returns success or error code.
00464     ///
00465     RetCode_t RenderImageFile(point_t pt, const char* FileName, rect_t* getDim = NULL);
00466 
00467 
00468     /// This method attempts to render a specified graphics image file at
00469     /// the specified screen location.
00470     ///
00471     /// This supports several variants of the following file types:
00472     /// @li Bitmap file format,
00473     /// @li Icon file format.
00474     /// @li Jpeg file format.
00475     ///
00476     /// @note The specified image width and height, when adjusted for the
00477     ///     x and y origin, must fit on the screen, or the image will not
00478     ///     be shown (it does not clip the image).
00479     ///
00480     /// @note The file extension is tested, and if it ends in a supported
00481     ///     format, the appropriate handler is called to render that image.
00482     ///
00483     /// @param[in] x is the horizontal pixel coordinate of the top-left corner.
00484     /// @param[in] y is the vertical pixel coordinate of the top-left corner.
00485     /// @param[in] FileName refers to the fully qualified path and file on
00486     ///     a mounted file system.
00487     /// @param[in] getDim when not NULL caused the image to not be drawn. Instead,
00488     ///             getDim is filled in as the rectangle that would be drawn
00489     ///             relative to the provided x,y origin. This basically
00490     ///             provides a GetImageRect on a specified file. @see GetImageRect
00491     ///             is the recommended and more obvious API.
00492     /// @returns success or error code.
00493     ///
00494     RetCode_t RenderImageFile(loc_t x, loc_t y, const char * FileName, rect_t * getDim = NULL);
00495 
00496     /// This method reads a disk file that is in jpeg format and
00497     /// puts it on the screen.
00498     ///
00499     /// @param[in] x is the horizontal pixel coordinate
00500     /// @param[in] y is the vertical pixel coordinate
00501     /// @param[in] Name_JPG is the filename on the mounted file system.
00502     /// @returns success or error code.
00503     ///
00504     RetCode_t RenderJpegFile(loc_t x, loc_t y, const char *Name_JPG);
00505 
00506     /// This method reads a disk file that is in bitmap format and
00507     /// puts it on the screen.
00508     ///
00509     /// Supported formats:
00510     /// @li 1-bit color format  (2 colors)
00511     /// @li 4-bit color format  (16 colors)
00512     /// @li 8-bit color format  (256 colors)
00513     /// @li 16-bit color format (65k colors)
00514     /// @li 24-bit color format (16M colors)
00515     /// @li compression: no.
00516     ///
00517     /// @note This is a slow operation, typically due to the use of
00518     ///         the file system, and partially because bmp files
00519     ///         are stored from the bottom up, and the memory is written
00520     ///         from the top down; as a result, it constantly 'seeks'
00521     ///         on the file system for the next row of information.
00522     ///
00523     /// As a performance test, a sample picture was timed. A family picture
00524     /// was converted to Bitmap format; shrunk to 352 x 272 pixels and save
00525     /// in 8-bit color format. The resulting file size was 94.5 KByte.
00526     /// The SPI port interface was set to 20 MHz.
00527     /// The original bitmap rendering software was purely in software,
00528     /// pushing 1 pixel at a time to the write function, which did use SPI
00529     /// hardware (not pin wiggling) to transfer commands and data to the
00530     /// display. Then, the driver was improved to leverage the capability
00531     /// of the derived display driver. As a final check, instead of the
00532     /// [known slow] local file system, a randomly chosen USB stick was
00533     /// used. The performance results are impressive (but depend on the
00534     /// listed factors).
00535     ///
00536     /// @li 34 seconds, LocalFileSystem, Software Rendering
00537     /// @li 9 seconds, LocalFileSystem, Hardware Rending for RA8875
00538     /// @li 3 seconds, MSCFileSystem, Hardware Rendering for RA8875
00539     ///
00540     /// @param[in] x is the horizontal pixel coordinate
00541     /// @param[in] y is the vertical pixel coordinate
00542     /// @param[in] Name_BMP is the filename on the mounted file system.
00543     /// @param[in] getDim when not NULL is filled in initialized to the x,y
00544     ///             origin, and from the size of the image, which is not drawn.
00545     /// @returns success or error code.
00546     ///
00547     RetCode_t RenderBitmapFile(loc_t x, loc_t y, const char *Name_BMP, rect_t * getDim = NULL);
00548 
00549 
00550     /// This method reads a disk file that is in ico format and
00551     /// puts it on the screen.
00552     ///
00553     /// Reading the disk is slow, but a typical icon file is small
00554     /// so it should be ok.
00555     ///
00556     /// @note An Icon file can have more than one icon in it. This
00557     ///     implementation only processes the first image in the file.
00558     ///
00559     /// @param[in] x is the horizontal pixel coordinate
00560     /// @param[in] y is the vertical pixel coordinate
00561     /// @param[in] Name_ICO is the filename on the mounted file system.
00562     /// @returns success or error code.
00563     ///
00564     RetCode_t RenderIconFile(loc_t x, loc_t y, const char *Name_ICO);
00565 
00566 
00567     /// Render a GIF file on screen.
00568     ///
00569     /// This function reads a GIF file, and places it on-screen at the specified
00570     /// coordinates.
00571     ///
00572     /// @param[in] x is the left edge of the on-screen coordinates.
00573     /// @param[in] y is the top edge of the on-screen coordinates.
00574     /// @param[in] Name_GIF is a pointer to the fully qualified filename.
00575     /// @returns noerror, or a variety of error codes.
00576     ///
00577     RetCode_t RenderGIFFile(loc_t x, loc_t y, const char *Name_GIF);
00578 
00579 
00580     /// GetGIFMetrics
00581     ///
00582     /// Get the GIF Image metrics.
00583     ///
00584     /// @param[out] imageDescriptor contains the image metrics on success.
00585     /// @param[in] Name_GIF is the filename of the GIF file of interest.
00586     /// @returns noerror, or a variety of error codes.
00587     ///
00588     RetCode_t GetGIFMetrics(gif_screen_descriptor_t * imageDescriptor, const char * Name_GIF);
00589 
00590 
00591     /// prints one character at the specified coordinates.
00592     ///
00593     /// This will print the character at the specified pixel coordinates.
00594     ///
00595     /// @param[in] x is the horizontal offset in pixels.
00596     /// @param[in] y is the vertical offset in pixels.
00597     /// @param[in] value is the character to print.
00598     /// @returns number of pixels to index to the right if a character was printed, 0 otherwise.
00599     ///
00600     virtual int character(int x, int y, int value);
00601 
00602     /// get the number of columns based on the currently active font
00603     ///
00604     /// @returns number of columns.
00605     ///
00606     virtual int columns(void);
00607 
00608     /// get the number of rows based on the currently active font
00609     ///
00610     /// @returns number of rows.
00611     ///
00612     virtual int rows(void);
00613 
00614     /// Select a User Font for all subsequent text.
00615     ///
00616     /// @note Tool to create the fonts is accessible from its creator
00617     ///     available at http://www.mikroe.com.
00618     ///     For version 1.2.0.0, choose the "Export for TFT and new GLCD"
00619     ///     format.
00620     ///
00621     /// @param[in] font is a pointer to a specially formed font resource.
00622     /// @returns @ref RetCode_t value.
00623     ///
00624     virtual RetCode_t SelectUserFont(const uint8_t * font = NULL);
00625 
00626 
00627 protected:
00628 
00629     /// Pure virtual method indicating the start of a graphics stream.
00630     ///
00631     /// This is called prior to a stream of pixel data being sent.
00632     /// This may cause register configuration changes in the derived
00633     /// class in order to prepare the hardware to accept the streaming
00634     /// data.
00635     ///
00636     /// @note this method must be supported in the derived class.
00637     ///
00638     /// @returns @ref RetCode_t value.
00639     ///
00640     virtual RetCode_t _StartGraphicsStream(void) = 0;
00641 
00642     /// Pure virtual method indicating the end of a graphics stream.
00643     ///
00644     /// This is called to conclude a stream of pixel data that was sent.
00645     /// This may cause register configuration changes in the derived
00646     /// class in order to stop the hardware from accept the streaming
00647     /// data.
00648     ///
00649     /// @note this method must be supported in the derived class.
00650     ///
00651     /// @returns @ref RetCode_t value.
00652     ///
00653     virtual RetCode_t _EndGraphicsStream(void) = 0;
00654 
00655     /// Protected method to render an image given a file handle and
00656     /// coordinates.
00657     ///
00658     /// @param[in] x is the horizontal pixel coordinate
00659     /// @param[in] y is the vertical pixel coordinate
00660     /// @param[in] fileOffset is the offset into the file where the image data starts
00661     /// @param[in] fh is the file handle to the stream already opened for the data.
00662     /// @param[in] getDim when not NULL is filled in from the size of the image, and the image is not drawn.
00663     /// @returns success or error code.
00664     ///
00665     RetCode_t _RenderBitmap(loc_t x, loc_t y, uint32_t fileOffset, FILE * fh, rect_t * getDim = NULL);
00666 
00667 
00668     /// Protected method to render a GIF given a file handle and
00669     /// coordinates.
00670     ///
00671     /// @param[in] x is the horizontal pixel coordinate
00672     /// @param[in] y is the vertical pixel coordinate
00673     /// @param[in] fh is the file handle to the stream already opened for the data.
00674     /// @returns success or error code.
00675     ///
00676     RetCode_t _RenderGIF(loc_t x, loc_t y, FILE * fh);
00677 
00678 
00679 private:
00680 
00681     loc_t img_x;    /// x position of a rendered jpg
00682     loc_t img_y;    /// y position of a rendered jpg
00683 
00684     /// Analyze the jpeg data in preparation for decompression.
00685     ///
00686     JRESULT jd_prepare(JDEC * jd, uint16_t(* infunc)(JDEC * jd, uint8_t * buffer, uint16_t bufsize), void * pool, uint16_t poolsize, void * filehandle);
00687 
00688     /// Decompress the jpeg and render it.
00689     ///
00690     JRESULT jd_decomp(JDEC * jd, uint16_t(* outfunct)(JDEC * jd, void * stream, JRECT * rect), uint8_t scale);
00691 
00692     /// helper function to read data from the file system
00693     ///
00694     uint16_t privInFunc(JDEC * jd, uint8_t * buff, uint16_t ndata);
00695 
00696     /// helper function to read data from the file system
00697     ///
00698     uint16_t getJpegData(JDEC * jd, uint8_t *buff, uint16_t ndata);
00699 
00700     /// helper function to write data to the display
00701     ///
00702     uint16_t privOutFunc(JDEC * jd, void * bitmap, JRECT * rect);
00703 
00704     JRESULT mcu_output (
00705         JDEC * jd,   /* Pointer to the decompressor object */
00706         uint16_t (* outfunc)(JDEC * jd, void * stream, JRECT * rect),  /* RGB output function */
00707         uint16_t x,     /* MCU position in the image (left of the MCU) */
00708         uint16_t y      /* MCU position in the image (top of the MCU) */
00709     );
00710 
00711     int16_t bitext (    /* >=0: extracted data, <0: error code */
00712         JDEC * jd,   /* Pointer to the decompressor object */
00713         uint16_t nbit   /* Number of bits to extract (1 to 11) */
00714     );
00715 
00716     int16_t huffext (           /* >=0: decoded data, <0: error code */
00717         JDEC * jd,           /* Pointer to the decompressor object */
00718         const uint8_t * hbits,  /* Pointer to the bit distribution table */
00719         const uint16_t * hcode,  /* Pointer to the code word table */
00720         const uint8_t * hdata   /* Pointer to the data table */
00721     );
00722 
00723     JRESULT restart (
00724         JDEC * jd,   /* Pointer to the decompressor object */
00725         uint16_t rstn   /* Expected restart sequence number */
00726     );
00727 
00728     JRESULT mcu_load (
00729         JDEC * jd        /* Pointer to the decompressor object */
00730     );
00731 
00732     gif_screen_descriptor_t screen_descriptor;      // attributes for the whole screen
00733     bool screen_descriptor_isvalid;             // has been read
00734     color_t * global_color_table;
00735     int global_color_table_size;
00736     color_t * local_color_table;
00737     int local_color_table_size;
00738     RetCode_t GetGIFHeader(FILE * fh);
00739     bool hasGIFHeader(FILE * fh);
00740     int process_gif_extension(FILE * fh);
00741     RetCode_t process_gif_image_descriptor(FILE * fh, uint8_t ** uncompress_gifed_data, int width, int height);
00742     int read_gif_sub_blocks(FILE * fh, unsigned char **data);
00743     RetCode_t uncompress_gif(int code_length, const unsigned char *input, int input_length, unsigned char *out);
00744     size_t read_filesystem_bytes(void * buffer, int numBytes, FILE * fh);
00745     RetCode_t readGIFImageDescriptor(FILE * fh, gif_image_descriptor_t * gif_image_descriptor);
00746     RetCode_t readColorTable(color_t * colorTable, int colorTableSize, FILE * fh);
00747 
00748 
00749 protected:
00750     /// Pure virtual method to write a boolean stream to the display.
00751     ///
00752     /// This takes a bit stream in memory and using the current color settings
00753     /// it will stream it to the display. Along the way, each bit is translated
00754     /// to either the foreground or background color value and then that pixel
00755     /// is pushed onward.
00756     ///
00757     /// This is similar, but different, to the @ref pixelStream API, which is
00758     /// given a stream of color values.
00759     ///
00760     /// @param[in] x is the horizontal position on the display.
00761     /// @param[in] y is the vertical position on the display.
00762     /// @param[in] w is the width of the rectangular region to fill.
00763     /// @param[in] h is the height of the rectangular region to fill.
00764     /// @param[in] boolStream is the inline memory image from which to extract
00765     ///         the bitstream.
00766     /// @returns @ref RetCode_t value.
00767     ///
00768     virtual RetCode_t booleanStream(loc_t x, loc_t y, dim_t w, dim_t h, const uint8_t * boolStream) = 0;
00769 
00770 
00771     const unsigned char * font;     ///< reference to an external font somewhere in memory
00772 
00773     // pixel location
00774     short _x;                       ///< keeps track of current X location
00775     short _y;                       ///< keeps track of current Y location
00776 
00777     uint8_t fontScaleX;             ///< tracks the font scale factor for Soft fonts. Range: 1 .. 4
00778     uint8_t fontScaleY;             ///< tracks the font scale factor for soft fonts. Range: 1 .. 4
00779 
00780     rect_t windowrect;              ///< window commands are held here for speed of access
00781 };
00782 
00783 #endif
00784