Kerry Martin
KSM edits to RA8875
Diff: RA8875.h
- Revision:
- 56:7a85d226ad0d
- Parent:
- 55:dfbabef7003e
- Child:
- 57:bd53a9e165a1
--- a/RA8875.h Sun Mar 30 23:37:41 2014 +0000
+++ b/RA8875.h Mon Mar 31 23:35:51 2014 +0000
@@ -8,7 +8,7 @@
// Define this to enable code that monitors the performance of various
// graphics commands.
-#define PERF_METRICS
+//#define PERF_METRICS
// What better place for some test code than in here and the companion
// .cpp file. See also the bottom of this file.
@@ -41,21 +41,44 @@
/// This is a graphics library for the Raio RA8875 Display Controller chip
/// attached to a 4-wire SPI interface.
///
-/// It offers both primitive and high level APIs.\\
+/// It offers both primitive and high level APIs.
+///
/// Central to this API is a coordinate system, where the origin (0,0) is in
-/// the top-left corner of the display, and the width extends positive to the
-/// right and the height extends positive toward the bottom.
+/// the top-left corner of the display, and the width (x) extends positive to the
+/// right and the height (y) extends positive toward the bottom.
///
-/// As there are both graphics and text commands, one must take care to use
+/// @caution As there are both graphics and text commands, one must take care to use
/// the proper coordinate system for each. Some of the text APIs are in units
/// of column and row, which is measured in character positions (and dependent
-/// on the font size), and other text APIs permit pixel level positioning.
+/// on the font size), where other text APIs permit pixel level positioning.
+///
+/// @code
+/// #include "RA8875.h"
+/// RA8875 lcd(p5, p6, p7, p12, NC, "tft");
+///
+/// int main()
+/// {
+/// lcd.printf("printing 3 x 2 = %d", 3*2);
+/// lcd.circle( 400,25, 25, BrightRed);
+/// lcd.fillcircle( 400,25, 15, RGB(128,255,128));
+/// lcd.ellipse( 440,75, 35,20, BrightBlue);
+/// lcd.fillellipse( 440,75, 25,10, Blue);
+/// lcd.triangle( 440,100, 475,110, 450,125, Magenta);
+/// lcd.filltriangle( 445,105, 467,111, 452,120, Cyan);
+/// lcd.rect( 400,130, 475,155, Brown);
+/// lcd.fillrect( 405,135, 470,150, Pink);
+/// lcd.roundrect( 410,160, 475,190, 10,8, Yellow);
+/// lcd.fillroundrect(415,165, 470,185, 5,3, Orange);
+/// lcd.line( 430,200, 460,230, RGB(0,255,0));
+/// for (int i=0; i<=30; i+=5)
+/// lcd.pixel(435+i,200+i, White);
+/// }
+/// @endcode
///
/// @todo Add Scroll support for text.
/// @todo Improve sync between internal and external font support - cursor, window, scroll.
/// @todo Find out why it can't shift frequency after constructor runs.
/// @todo Add Hardware reset signal.
-/// @todo Add Touch Screen support.
/// @todo Add Keypad Support.
/// @todo Add high level objects - x-y graph, meter, others... but these will
/// probably be best served in another class, since they may not
@@ -112,8 +135,8 @@
/// Set the Layer 1/2 Display Mode
typedef enum
{
- OnlyLayer1, ///< Only layer 1 is visible
- OnlyLayer2, ///< Only layer 2 is visible
+ ShowLayer0, ///< Only layer 0 is visible, layer 1 is hidden
+ ShowLayer1, ///< Only layer 1 is visible, layer 0 is hidden
LightenOverlay, ///< Lighten-overlay mode
TransparentMode, ///< Transparent mode
BooleanOR, ///< Boolean OR mode
@@ -131,6 +154,17 @@
/// Constructor for a display based on the RAiO RA8875
/// display controller.
///
+ /// @code
+ /// #include "RA8875.h"
+ /// RA8875 lcd(p5, p6, p7, p12, NC, "tft");
+ ///
+ /// int main()
+ /// {
+ /// lcd.printf("printing 3 x 2 = %d", 3*2);
+ /// lcd.circle(400,25, 25, BrightRed);
+ /// }
+ /// @endcode
+ ///
/// @param mosi is the SPI master out slave in pin on the mbed.
/// @param miso is the SPI master in slave out pin on the mbed.
/// @param sclk is the SPI shift clock pin on the mbed.
@@ -155,6 +189,15 @@
/// be independently drawn on and shown. Additionally, complex
/// operations involving both layers are permitted.
///
+ /// @code
+ /// //lcd.SetLayerMode(OnlyLayer0); // default is layer 0
+ /// lcd.rect(400,130, 475,155,Brown);
+ /// lcd.SelectDrawingLayer(1);
+ /// lcd.circle(400,25, 25, BrightRed);
+ /// wait(1);
+ /// lcd.SetLayerMode(ShowLayer1);
+ /// @endcode
+ ///
/// @note The user manual refers to Layer 1 and Layer 2, however the
/// actual register values are value 0 and 1. This and other APIs
/// that reference the layers use the values 0 and 1.
@@ -172,6 +215,15 @@
/// a single layer, or applying a mode where the two layers
/// are combined using one of the hardware methods.
///
+ /// @code
+ /// //lcd.SetLayerMode(OnlyLayer0); // default is layer 0
+ /// lcd.rect(400,130, 475,155,Brown);
+ /// lcd.SelectDrawingLayer(1);
+ /// lcd.circle(400,25, 25, BrightRed);
+ /// wait(1);
+ /// lcd.SetLayerMode(ShowLayer1);
+ /// @endcode
+ ///
/// @param mode sets the mode in the Layer Transparency Register.
/// @returns success/failure code. @see RetCode_t.
///
@@ -183,6 +235,15 @@
/// from zero (fully visible) to eight (fully transparent).
/// The input value is automatically limited to this range.
///
+ /// @code
+ /// // draw something on each layer, then step-fade across
+ /// display.SetLayerMode(RA8875::TransparentMode);
+ /// for (i=0; i<=8; i++) {
+ /// display.SetLayerTransparency(i, 8-i);
+ /// wait_ms(200);
+ /// }
+ /// @endcode
+ ///
/// @param layer1 sets the layer 1 transparency.
/// @param layer2 sets the layer 2 transparency.
/// @returns success/failure code. @see RetCode_t.
@@ -202,27 +263,27 @@
/// Initialize theTouch Panel controller with default values
///
- /// @returns success/failure code. @see RetCode_t.
+ /// @returns success/failure code. @see RetCode_t.
+ ///
RetCode_t TouchPanelInit(void);
/// Initialize the Touch Panel controller with detailed settings.
///
- ///
/// @param[in] bTpEnable Touch Panel enable/disable control:
/// - TP_ENABLE: enable the touch panel
/// - TP_DISABLE: disable the touch panel
- /// bTpAutoManual Touch Panel operating mode:
+ /// @param[in] bTpAutoManual Touch Panel operating mode:
/// - TP_MODE_AUTO: automatic capture
/// - TP_MODE_MANUAL: manual capture
- /// bTpDebounce Debounce circuit enable for touch panel interrupt:
+ /// @param[in] bTpDebounce Debounce circuit enable for touch panel interrupt:
/// - TP_DEBOUNCE_OFF: disable the debounce circuit
/// - TP_DEBOUNCE_ON: enable the debounce circuit
- /// bTpManualMode When Manual Mode is selected, this sets the mode:
+ /// @param[in] bTpManualMode When Manual Mode is selected, this sets the mode:
/// - TP_MANUAL_IDLE: touch panel is idle
/// - TP_MANUAL_WAIT: wait for touch panel event
/// - TP_MANUAL_LATCH_X: latch X data
/// - TP_MANUAL_LATCH_Y: latch Y data
- /// bTpAdcClkDiv Sets the ADC clock as a fraction of the System CLK:
+ /// @param[in] bTpAdcClkDiv Sets the ADC clock as a fraction of the System CLK:
/// - TP_ADC_CLKDIV_1: Use CLK
/// - TP_ADC_CLKDIV_2: Use CLK/2
/// - TP_ADC_CLKDIV_4: Use CLK/4
@@ -231,7 +292,7 @@
/// - TP_ADC_CLKDIV_32: Use CLK/32
/// - TP_ADC_CLKDIV_64: Use CLK/64
/// - TP_ADC_CLKDIV_128: Use CLK/128
- /// bTpAdcSampleTime Touch Panel sample time delay before ADC data is ready:
+ /// @param[in] bTpAdcSampleTime Touch Panel sample time delay before ADC data is ready:
/// - TP_ADC_SAMPLE_512_CLKS: Wait 512 system clocks
/// - TP_ADC_SAMPLE_1024_CLKS: Wait 1024 system clocks
/// - TP_ADC_SAMPLE_2048_CLKS: Wait 2048 system clocks
@@ -240,17 +301,24 @@
/// - TP_ADC_SAMPLE_16384_CLKS: Wait 16384 system clocks
/// - TP_ADC_SAMPLE_32768_CLKS: Wait 32768 system clocks
/// - TP_ADC_SAMPLE_65536_CLKS: Wait 65536 system clocks
- /// @returns success/failure code. @see RetCode_t.
+ /// @returns success/failure code. @see RetCode_t.
+ ///
RetCode_t TouchPanelInit(uint8_t bTpEnable, uint8_t bTpAutoManual, uint8_t bTpDebounce, uint8_t bTpManualMode, uint8_t bTpAdcClkDiv, uint8_t bTpAdcSampleTime);
/// Poll the TouchPanel and on a touch event return the filtered x, y coordinates.
///
- /// @param x,y
+ /// @param[inout] x is the x position where the touch was registered.
+ /// @param[inout] y is the y position where the touch was registered.
+ /// @returns true if touch was detected, in which case the x and y values were set.
+ ///
unsigned char TouchPanelRead(loc_t *x, loc_t *y);
/// Poll the TouchPanel and on a touch event return the raw x, y coordinates.
///
- /// @param x,y
+ /// @param[inout] x is the x position where the touch was registered.
+ /// @param[inout] y is the y position where the touch was registered.
+ /// @returns true if touch was detected, in which case the x and y values were set.
+ ///
unsigned char TouchPanelReadRaw(loc_t *x, loc_t *y);
/// Append interrupt handler for specific RA8875 interrupt source
@@ -261,8 +329,8 @@
/// - RA8875_INT_TP: Touch panel interrupt
/// - RA8875_INT_BTE: BTE process complete interrupt
/// - RA8875_INT_BTEMCU_FONTWR: Multi-purpose interrupt (see spec sheet)
- ///
- /// @return none
+ /// @param[in] fptr is a callback function to handle the interrupt event.
+ /// @returns none
///
void AppendISR(uint8_t bISRType, void(*fptr)(void));
@@ -274,7 +342,6 @@
/// - RA8875_INT_TP: Touch panel interrupt
/// - RA8875_INT_BTE: BTE process complete interrupt
/// - RA8875_INT_BTEMCU_FONTWR: Multi-purpose interrupt (see spec sheet)
- ///
/// @return none
///
void UnAppendISR(uint8_t bISRType);
@@ -402,6 +469,11 @@
/// Prepare the controller to write text to the screen by positioning
/// the cursor.
///
+ /// @code
+ /// lcd.SetTextCursor(100, 25);
+ /// lcd.puts("Hello");
+ /// @endcode
+ ///
/// @param x is the horizontal position in pixels (from the left edge)
/// @param y is the vertical position in pixels (from the top edge)
/// @returns success/failure code. @see RetCode_t.
@@ -410,6 +482,12 @@
/// Get the current cursor position in pixels.
///
+ /// @code
+ /// point_t point = GetTextCursor();
+ /// if (point.x > 100 && point.y > 150)
+ /// //...
+ /// @endcode
+ ///
/// @returns cursor position.
///
point_t GetTextCursor(void);
@@ -454,7 +532,7 @@
/// Control the font behavior.
///
/// This command lets you make several modifications to any text that
- /// is written.
+ /// will be written to the screen.
///
/// Options can be combined:
/// Default:
@@ -497,8 +575,11 @@
///
/// @code
/// lcd.SetTextFontSize(2); // Set the font to 2x normal size
+ /// lcd.puts("Two times");
/// lcd.SetTextFontSize(2,3); // Set the font to 2x Width and 3x Height
+ /// lcd.puts("2*2 3*h");
/// lcd.SetTextFontSize(); // Restore to normal size in both dimensions
+ /// lcd.puts("normal");
/// @endcode
///
/// @note if either hScale or vScale is outside of its permitted range,
@@ -516,12 +597,20 @@
/// Write string of text to the display
///
+ /// @code
+ /// lcd.puts("Test STring");
+ /// @endcode
+ ///
/// @param string is the null terminated string to send to the display.
///
void puts(const char * string);
/// Write string of text to the display at the specified location.
///
+ /// @code
+ /// lcd.puts(10,25, "Test STring");
+ /// @endcode
+ ///
/// @param x is the horizontal position in pixels (from the left edge)
/// @param y is the vertical position in pixels (from the top edge)
/// @param string is the null terminated string to send to the display.
@@ -552,6 +641,11 @@
/// and down a row. If the initial write is outside the window, it will
/// be captured into the window when it crosses a boundary.
///
+ /// @code
+ /// lcd.window(10,10, 80,80);
+ /// lcd.puts("012345678901234567890123456789012345678901234567890");
+ /// @endcode
+ ///
/// @param x is the left edge in pixels.
/// @param y is the top edge in pixels.
/// @param width is the window width in pixels.
@@ -564,6 +658,10 @@
///
/// The behavior is to clear the whole screen. @see clsw().
///
+ /// @code
+ /// lcd.cls();
+ /// @endcode
+ ///
/// @returns success/failure code. @see RetCode_t.
///
virtual RetCode_t cls(void);
@@ -574,6 +672,11 @@
/// parameter, the action can be restricted to the active window, which
/// can be set with the @see window method.
///
+ /// @code
+ /// lcd.window(20,20, 40,10);
+ /// lcd.clsw();
+ /// @endcode
+ ///
/// @param region is an optional parameter that defaults to FULLWINDOW
/// or may be set to ACTIVEWINDOW.
/// @returns success/failure code. @see RetCode_t.
@@ -678,8 +781,7 @@
/// @param color defines the foreground color.
/// @returns success/failure code. @see RetCode_t.
///
- RetCode_t line(loc_t x1, loc_t y1, loc_t x2, loc_t y2,
- color_t color);
+ RetCode_t line(loc_t x1, loc_t y1, loc_t x2, loc_t y2, color_t color);
/// Draw a line
///
@@ -1296,4 +1398,4 @@
#endif // TESTENABLE
-#endif
\ No newline at end of file
+#endif