Diff: GraphicsDisplay.h

Revision:

190:3132b7dfad82

Parent:

167:8aa3fb2a5a31

Child:

196:56820026701b

--- a/GraphicsDisplay.h	Thu Sep 19 21:45:18 2019 +0000
+++ b/GraphicsDisplay.h	Sat Sep 21 17:30:00 2019 +0000
@@ -4,12 +4,17 @@
 /// @copyright © 2007-2009 sford
 /// Released under the MIT License: http://mbed.org/license/mit
 ///
+/// extensive changes in the support of the RA8875 display by
+/// Smartware Computing.
+/// @copyright © 2019 Smartware Computing.
+///
+///
 /// A library for providing a common base class for Graphics displays
 /// To port a new display, derive from this class and implement
 /// the constructor (setup the display), pixel (put a pixel
 /// at a location), width and height functions. Everything else
-/// (locate, printf, putc, cls, window, putp, fill, blit, blitbit) 
-/// will come for free. You can also provide a specialised implementation
+/// (locate, printf, putc, cls, window, putp, fill, blit, blitbit)
+/// will come for free. You can also provide a specialized implementation
 /// of window and putp to speed up the results
 ///
 #ifndef MBED_GRAPHICSDISPLAY_H
@@ -19,22 +24,22 @@
 #include "GraphicsDisplayJPEG.h"
 #include "GraphicsDisplayGIF.h"
 
-/// The GraphicsDisplay class 
-/// 
+/// The GraphicsDisplay class
+///
 /// This graphics display class supports both graphics and text operations.
 /// Typically, a subclass is derived from this which has localizations to
 /// adapt to a specific hardware platform (e.g. a display controller chip),
-/// that overrides methods in here to either add more capability or perhaps 
+/// that overrides methods in here to either add more capability or perhaps
 /// to improve performance, by leveraging specific hardware capabilities.
 ///
-class GraphicsDisplay : public TextDisplay 
+class GraphicsDisplay : public TextDisplay
 {
 public:
     /// The constructor
     GraphicsDisplay(const char* name);
-    
+
     //~GraphicsDisplay();
-    
+
     /// Draw a pixel in the specified color.
     ///
     /// @note this method must be supported in the derived class.
@@ -45,7 +50,7 @@
     /// @returns success/failure code. @see RetCode_t.
     ///
     virtual RetCode_t pixel(loc_t x, loc_t y, color_t color) = 0;
-    
+
     /// Write a stream of pixels to the display.
     ///
     /// @note this method must be supported in the derived class.
@@ -79,7 +84,7 @@
     /// @returns success/failure code. @see RetCode_t.
     ///
     virtual RetCode_t getPixelStream(color_t * p, uint32_t count, loc_t x, loc_t y) = 0;
-    
+
     /// get the screen width in pixels
     ///
     /// @note this method must be supported in the derived class.
@@ -87,7 +92,7 @@
     /// @returns screen width in pixels.
     ///
     virtual uint16_t width() = 0;
-    
+
     /// get the screen height in pixels
     ///
     /// @note this method must be supported in the derived class.
@@ -106,8 +111,8 @@
     /// @returns success/failure code. @see RetCode_t.
     ///
     virtual RetCode_t SetGraphicsCursor(loc_t x, loc_t y) = 0;
-    
-    
+
+
     /// Prepare the controller to write binary data to the screen by positioning
     /// the memory cursor.
     ///
@@ -115,7 +120,7 @@
     /// @returns @ref RetCode_t value.
     ///
     virtual RetCode_t SetGraphicsCursor(point_t p) = 0;
-    
+
     /// Read the current graphics cursor position as a point.
     ///
     /// @returns the graphics cursor as a point.
@@ -130,7 +135,7 @@
     /// @returns success/failure code. @see RetCode_t.
     ///
     virtual RetCode_t SetGraphicsCursorRead(loc_t x, loc_t y) = 0;
-    
+
     /// Draw a filled rectangle in the specified color
     ///
     /// @note As a side effect, this changes the current
@@ -146,13 +151,13 @@
     /// @param[in] fillit is optional to NOFILL the rectangle. default is FILL.
     /// @returns success/failure code. @see RetCode_t.
     ///
-    virtual RetCode_t fillrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2, 
+    virtual RetCode_t fillrect(loc_t x1, loc_t y1, loc_t x2, loc_t y2,
         color_t color, fill_t fillit = FILL) = 0;
 
     /// Select the drawing layer for subsequent commands.
     ///
-    /// If the screen configuration is 480 x 272, or if it is 800 x 480 
-    /// and 8-bit color, the the display supports two layers, which can 
+    /// If the screen configuration is 480 x 272, or if it is 800 x 480
+    /// and 8-bit color, the the display supports two layers, which can
     /// be independently drawn on and shown. Additionally, complex
     /// operations involving both layers are permitted.
     ///
@@ -170,16 +175,16 @@
     ///     others that reference the layers use the values 0 and 1 for
     ///     cleaner iteration in the code.
     ///
-    /// @param[in] layer is 0 or 1 to select the layer for subsequent 
+    /// @param[in] layer is 0 or 1 to select the layer for subsequent
     ///     commands.
-    /// @param[out] prevLayer is an optiona pointer to where the previous layer
+    /// @param[out] prevLayer is an optional pointer to where the previous layer
     ///     will be written, making it a little easer to restore layers.
     ///     Writes 0 or 1 when the pointer is not NULL.
     /// @returns @ref RetCode_t value.
     ///
     virtual RetCode_t SelectDrawingLayer(uint16_t layer, uint16_t * prevLayer = NULL) = 0;
- 
-    
+
+
     /// Get the currently active drawing layer.
     ///
     /// This returns a value, 0 or 1, based on the screen configuration
@@ -198,7 +203,7 @@
     ///     cleaner iteration in the code.
     ///
     /// @returns the current drawing layer; 0 or 1.
-    /// 
+    ///
     virtual uint16_t GetDrawingLayer(void) = 0;
 
     /// a function to write the command and data to the RA8875 chip.
@@ -208,8 +213,8 @@
     /// @returns success/failure code. @see RetCode_t.
     ///
     virtual RetCode_t WriteCommand(unsigned char command, unsigned int data = 0xFFFF) = 0;
-    
-    
+
+
     /// a function to write the data to the RA8875 chip.
     ///
     /// This is typically used after a command has been initiated, and where
@@ -223,7 +228,7 @@
     /// Set the window, which controls where items are written to the screen.
     ///
     /// When something hits the window width, it wraps back to the left side
-    /// and down a row. 
+    /// and down a row.
     ///
     /// @note If the initial write is outside the window, it will
     ///     be captured into the window when it crosses a boundary. It may
@@ -237,7 +242,7 @@
     /// Set the window, which controls where items are written to the screen.
     ///
     /// When something hits the window width, it wraps back to the left side
-    /// and down a row. 
+    /// and down a row.
     ///
     /// @note If the initial write is outside the window, it will
     ///     be captured into the window when it crosses a boundary. It may
@@ -252,30 +257,30 @@
     /// @returns success/failure code. @see RetCode_t.
     ///
     virtual RetCode_t window(loc_t x = 0, loc_t y = 0, dim_t w = (dim_t)-1, dim_t h = (dim_t)-1);
-    
+
     /// method to set the window region to the full screen.
     ///
-    /// This restores the 'window' to the full screen, so that 
+    /// This restores the 'window' to the full screen, so that
     /// other operations (@see cls) would clear the whole screen.
     ///
     /// @returns success/failure code. @see RetCode_t.
     ///
     virtual RetCode_t WindowMax(void);
-    
+
     /// Clear the screen.
     ///
     /// The behavior is to clear the whole screen.
     ///
-    /// @param[in] layers is ignored, but supports maintaining the same 
+    /// @param[in] layers is ignored, but supports maintaining the same
     ///     API for the graphics layer.
     /// @returns success/failure code. @see RetCode_t.
     ///
     virtual RetCode_t cls(uint16_t layers = 0);
-    
+
     /// method to put a single color pixel to the screen.
     ///
-    /// This method may be called as many times as necessary after 
-    /// @see _StartGraphicsStream() is called, and it should be followed 
+    /// This method may be called as many times as necessary after
+    /// @see _StartGraphicsStream() is called, and it should be followed
     /// by _EndGraphicsStream.
     ///
     /// @param[in] pixel is a color value to be put on the screen.
@@ -295,9 +300,9 @@
     /// @param[in] h specifies the height of the region.
     /// @param[in] color is the color value to use to fill the region
     /// @returns success/failure code. @see RetCode_t.
-    /// 
+    ///
     virtual RetCode_t fill(loc_t x, loc_t y, dim_t w, dim_t h, color_t color);
-    
+
     /// method to stream bitmap data to the display
     ///
     /// This method fills a region from a stream of color data.
@@ -308,9 +313,9 @@
     /// @param[in] h specifies the height of the region.
     /// @param[in] color is a pointer to a color stream with w x h values.
     /// @returns success/failure code. @see RetCode_t.
-    /// 
-    virtual RetCode_t blit(loc_t x, loc_t y, dim_t w, dim_t h, const int * color);    
-    
+    ///
+    virtual RetCode_t blit(loc_t x, loc_t y, dim_t w, dim_t h, const int * color);
+
     /// This method returns the width in pixels of the chosen character
     /// from the previously selected external font.
     ///
@@ -324,7 +329,7 @@
     /// @returns a pointer to the raw character data or NULL if not found.
     ///
     virtual const uint8_t * getCharMetrics(const unsigned char c, dim_t * width, dim_t * height);
-    
+
     /// This method transfers one character from the external font data
     /// to the screen.
     ///
@@ -342,13 +347,13 @@
     /// @returns zero if the character could not be rendered.
     ///
     virtual int fontblit(loc_t x, loc_t y, const unsigned char c);
-    
+
     /// This method returns the color value from a palette.
     ///
     /// This method accepts a pointer to a Bitmap color palette, which
     /// is a table in memory composed of RGB Quad values (r, g, b, 0),
     /// and an index into that table. It then extracts the color information
-    /// and downsamples it to a color_t value which it returns.
+    /// and down-samples it to a color_t value which it returns.
     ///
     /// @note This method probably has very little value outside of
     ///         the internal methods for reading BMP files.
@@ -358,7 +363,7 @@
     /// @returns the color in color_t format.
     ///
     color_t RGBQuadToRGB16(RGBQUAD * colorPaletteArray, uint16_t index);
-    
+
     /// This method converts a 16-bit color value into a 24-bit RGB Quad.
     ///
     /// @param[in] c is the 16-bit color. @see color_t.
@@ -366,29 +371,56 @@
     ///
     RGBQUAD RGB16ToRGBQuad(color_t c);
 
+
+    /// This method gets the rectangle that would render a specified image file.
+    ///
+    /// This is the more programmer "obvious" method of getting the size of
+    /// an image file.
+    ///
+    /// @note The present implementation calls the RenderImageFile API with the
+    ///         optional getDim parameter.
+    ///
+    /// @note Not all image file formats are supported. Check the return value.
+    ///
+    /// @param[in] x is the horizontal pixel coordinate of the top-left corner.
+    /// @param[in] y is the vertical pixel coordinate of the top-left corner.
+    /// @param[in] FileName refers to the fully qualified path and file on
+    ///     a mounted file system. The filename is optional, in which case
+    ///     it simply returns a rect_t with all elements set to zero.
+    /// @returns a rect_t that would contain the specified image. When the
+    ///     specified file cannot be found, or where this method is not yet
+    ///     supported, all elements of the returned rect_r will be zero.
+    ///
+    rect_t GetImageRect(loc_t x, loc_t y, const char * FileName = NULL);
+
     /// This method attempts to render a specified graphics image file at
     /// the specified screen location.
     ///
     /// This supports several variants of the following file types:
-    /// \li Bitmap file format,
-    /// \li Icon file format.
+    /// @li Bitmap file format,
+    /// @li Icon file format.
+    /// @li Jpeg file format.
     ///
-    /// @note The specified image width and height, when adjusted for the 
+    /// @note The specified image width and height, when adjusted for the
     ///     x and y origin, must fit on the screen, or the image will not
     ///     be shown (it does not clip the image).
     ///
     /// @note The file extension is tested, and if it ends in a supported
     ///     format, the appropriate handler is called to render that image.
     ///
-    /// @param[in] x is the horizontal pixel coordinate
-    /// @param[in] y is the vertical pixel coordinate
-    /// @param[in] FileName refers to the fully qualified path and file on 
+    /// @param[in] x is the horizontal pixel coordinate of the top-left corner.
+    /// @param[in] y is the vertical pixel coordinate of the top-left corner.
+    /// @param[in] FileName refers to the fully qualified path and file on
     ///     a mounted file system.
+    /// @param[in] getDim when not NULL the image is not drawn. Instead, the
+    ///             getDim is filled in as the rectangle that would be drawn
+    ///             relative to the provided x,y origin. This basically
+    ///             provides a GetImageRect on a specified file.
     /// @returns success or error code.
     ///
-    RetCode_t RenderImageFile(loc_t x, loc_t y, const char *FileName);
+    RetCode_t RenderImageFile(loc_t x, loc_t y, const char * FileName, rect_t * getDim = NULL);
 
-    /// This method reads a disk file that is in jpeg format and 
+    /// This method reads a disk file that is in jpeg format and
     /// puts it on the screen.
     ///
     /// @param[in] x is the horizontal pixel coordinate
@@ -398,16 +430,16 @@
     ///
     RetCode_t RenderJpegFile(loc_t x, loc_t y, const char *Name_JPG);
 
-    /// This method reads a disk file that is in bitmap format and 
+    /// This method reads a disk file that is in bitmap format and
     /// puts it on the screen.
     ///
     /// Supported formats:
-    /// \li 1-bit color format  (2 colors)
-    /// \li 4-bit color format  (16 colors)
-    /// \li 8-bit color format  (256 colors)
-    /// \li 16-bit color format (65k colors)
-    /// \li 24-bit color format (16M colors)
-    /// \li compression: no.
+    /// @li 1-bit color format  (2 colors)
+    /// @li 4-bit color format  (16 colors)
+    /// @li 8-bit color format  (256 colors)
+    /// @li 16-bit color format (65k colors)
+    /// @li 24-bit color format (16M colors)
+    /// @li compression: no.
     ///
     /// @note This is a slow operation, typically due to the use of
     ///         the file system, and partially because bmp files
@@ -419,28 +451,30 @@
     /// was converted to Bitmap format; shrunk to 352 x 272 pixels and save
     /// in 8-bit color format. The resulting file size was 94.5 KByte.
     /// The SPI port interface was set to 20 MHz.
-    /// The original bitmap rendering software was purely in software, 
+    /// The original bitmap rendering software was purely in software,
     /// pushing 1 pixel at a time to the write function, which did use SPI
-    /// hardware (not pin wiggling) to transfer commands and data to the 
+    /// hardware (not pin wiggling) to transfer commands and data to the
     /// display. Then, the driver was improved to leverage the capability
     /// of the derived display driver. As a final check, instead of the
-    /// [known slow] local file system, a randomly chosen USB stick was 
+    /// [known slow] local file system, a randomly chosen USB stick was
     /// used. The performance results are impressive (but depend on the
-    /// listed factors). 
+    /// listed factors).
     ///
-    /// \li 34 seconds, LocalFileSystem, Software Rendering
-    /// \li 9 seconds, LocalFileSystem, Hardware Rending for RA8875
-    /// \li 3 seconds, MSCFileSystem, Hardware Rendering for RA8875
-    /// 
+    /// @li 34 seconds, LocalFileSystem, Software Rendering
+    /// @li 9 seconds, LocalFileSystem, Hardware Rending for RA8875
+    /// @li 3 seconds, MSCFileSystem, Hardware Rendering for RA8875
+    ///
     /// @param[in] x is the horizontal pixel coordinate
     /// @param[in] y is the vertical pixel coordinate
     /// @param[in] Name_BMP is the filename on the mounted file system.
+    /// @param[in] getDim when not NULL is filled in initialized to the x,y
+    ///             origin, and from the size of the image, which is not drawn.
     /// @returns success or error code.
     ///
-    RetCode_t RenderBitmapFile(loc_t x, loc_t y, const char *Name_BMP);
-    
-    
-    /// This method reads a disk file that is in ico format and 
+    RetCode_t RenderBitmapFile(loc_t x, loc_t y, const char *Name_BMP, rect_t * getDim = NULL);
+
+
+    /// This method reads a disk file that is in ico format and
     /// puts it on the screen.
     ///
     /// Reading the disk is slow, but a typical icon file is small
@@ -456,10 +490,10 @@
     ///
     RetCode_t RenderIconFile(loc_t x, loc_t y, const char *Name_ICO);
 
-    
+
     /// Render a GIF file on screen.
     ///
-    /// This function reads a GIF file, and places it onscreen at the specified
+    /// This function reads a GIF file, and places it on-screen at the specified
     /// coordinates.
     ///
     /// @param[in] x is the left edge of the on-screen coordinates.
@@ -473,7 +507,7 @@
     /// GetGIFMetrics
     ///
     /// Get the GIF Image metrics.
-    /// 
+    ///
     /// @param[out] imageDescriptor contains the image metrics on success.
     /// @param[in] Name_GIF is the filename of the GIF file of interest.
     /// @returns noerror, or a variety of error codes.
@@ -491,23 +525,23 @@
     /// @returns number of pixels to index to the right if a character was printed, 0 otherwise.
     ///
     virtual int character(int x, int y, int value);
-    
-    /// get the number of colums based on the currently active font
+
+    /// get the number of columns based on the currently active font
     ///
     /// @returns number of columns.
-    ///    
+    ///
     virtual int columns(void);
 
     /// get the number of rows based on the currently active font
     ///
     /// @returns number of rows.
-    ///    
+    ///
     virtual int rows(void);
-    
+
     /// Select a User Font for all subsequent text.
     ///
     /// @note Tool to create the fonts is accessible from its creator
-    ///     available at http://www.mikroe.com. 
+    ///     available at http://www.mikroe.com.
     ///     For version 1.2.0.0, choose the "Export for TFT and new GLCD"
     ///     format.
     ///
@@ -531,7 +565,7 @@
     /// @returns @ref RetCode_t value.
     ///
     virtual RetCode_t _StartGraphicsStream(void) = 0;
-    
+
     /// Pure virtual method indicating the end of a graphics stream.
     ///
     /// This is called to conclude a stream of pixel data that was sent.
@@ -545,19 +579,20 @@
     ///
     virtual RetCode_t _EndGraphicsStream(void) = 0;
 
-    /// Protected method to render an image given a file handle and 
+    /// Protected method to render an image given a file handle and
     /// coordinates.
     ///
     /// @param[in] x is the horizontal pixel coordinate
     /// @param[in] y is the vertical pixel coordinate
     /// @param[in] fileOffset is the offset into the file where the image data starts
     /// @param[in] fh is the file handle to the stream already opened for the data.
+    /// @param[in] getDim when not NULL is filled in from the size of the image, and the image is not drawn.
     /// @returns success or error code.
     ///
-    RetCode_t _RenderBitmap(loc_t x, loc_t y, uint32_t fileOffset, FILE * fh);
+    RetCode_t _RenderBitmap(loc_t x, loc_t y, uint32_t fileOffset, FILE * fh, rect_t * getDim = NULL);
 
 
-    /// Protected method to render a GIF given a file handle and 
+    /// Protected method to render a GIF given a file handle and
     /// coordinates.
     ///
     /// @param[in] x is the horizontal pixel coordinate
@@ -576,7 +611,7 @@
     /// Analyze the jpeg data in preparation for decompression.
     ///
     JRESULT jd_prepare(JDEC * jd, uint16_t(* infunc)(JDEC * jd, uint8_t * buffer, uint16_t bufsize), void * pool, uint16_t poolsize, void * filehandle);
-    
+
     /// Decompress the jpeg and render it.
     ///
     JRESULT jd_decomp(JDEC * jd, uint16_t(* outfunct)(JDEC * jd, void * stream, JRECT * rect), uint8_t scale);
@@ -592,7 +627,7 @@
     /// helper function to write data to the display
     ///
     uint16_t privOutFunc(JDEC * jd, void * bitmap, JRECT * rect);
-    
+
     JRESULT mcu_output (
         JDEC * jd,   /* Pointer to the decompressor object */
         uint16_t (* outfunc)(JDEC * jd, void * stream, JRECT * rect),  /* RGB output function */
@@ -614,7 +649,7 @@
 
     JRESULT restart (
         JDEC * jd,   /* Pointer to the decompressor object */
-        uint16_t rstn   /* Expected restert sequense number */
+        uint16_t rstn   /* Expected restart sequence number */
     );
 
     JRESULT mcu_load (
@@ -646,9 +681,9 @@
     /// to either the foreground or background color value and then that pixel
     /// is pushed onward.
     ///
-    /// This is similar, but different, to the @ref pixelStream API, which is 
+    /// This is similar, but different, to the @ref pixelStream API, which is
     /// given a stream of color values.
-    /// 
+    ///
     /// @param[in] x is the horizontal position on the display.
     /// @param[in] y is the vertical position on the display.
     /// @param[in] w is the width of the rectangular region to fill.
@@ -658,18 +693,18 @@
     /// @returns @ref RetCode_t value.
     ///
     virtual RetCode_t booleanStream(loc_t x, loc_t y, dim_t w, dim_t h, const uint8_t * boolStream) = 0;
-    
+
 
     const unsigned char * font;     ///< reference to an external font somewhere in memory
-    
+
     // pixel location
     short _x;                       ///< keeps track of current X location
     short _y;                       ///< keeps track of current Y location
-    
+
     uint8_t fontScaleX;             ///< tracks the font scale factor for Soft fonts. Range: 1 .. 4
     uint8_t fontScaleY;             ///< tracks the font scale factor for soft fonts. Range: 1 .. 4
 
-    rect_t windowrect;              ///< window commands are held here for speed of access 
+    rect_t windowrect;              ///< window commands are held here for speed of access
 };
 
 #endif