Luis Amell
This is the David Smart RA8875 Library with mods for working with FRDM-K64F
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