Diff: RA8875.h

Revision:

64:5479dc0c8738

Parent:

55:dfbabef7003e

Child:

65:607bc289c976

--- a/RA8875.h	Sun Mar 30 23:37:41 2014 +0000
+++ b/RA8875.h	Mon Mar 31 11:24: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,21 @@
 /// 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.
 ///
 /// @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
@@ -202,7 +202,8 @@
  
     /// 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.
@@ -211,18 +212,18 @@
     /// @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 +232,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 +241,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 +269,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 +282,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);