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