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