Diff: RA8875.h

Revision:

78:faf49c381591

Parent:

77:9206c13aa527

Child:

79:544eb4964795

--- a/RA8875.h	Fri Dec 26 21:34:28 2014 +0000
+++ b/RA8875.h	Sun Dec 28 03:14:35 2014 +0000
@@ -1,3 +1,57 @@
+///
+/// @mainpage RA8875 Display Controller Driver library
+///
+/// The RA8875 Display controller is a powerful interface for low cost displays. It
+/// can support displays up to 800 x 600 pixels x 16-bit color. Another common 
+/// implementation is 480 x 272 x 16 with two layers. The two layers can be 
+/// exchanged, or blended in various ways (transparency, OR, AND, and more).
+/// It includes graphics acceleration capabilities for drawing primitives, 
+/// such as line, rectangle, circles, and more.
+///
+/// The controller additionally supports backlight control (via PWM), keypad scanning
+/// (for a 4 x 5 matrix) and resistive touch-panel support. 
+///
+/// @section Display_Config Display Configuration
+///
+/// This section details basics for bringing the display online. At a minimum,
+/// the display is instantiated. After that any of the available commands
+/// may be issued.
+///
+/// During the instantiation, the display is powered on, cleared, and the backlight
+/// is energized. Additionally, the keypad and touchscreen features are activated.
+/// It is important to keep in mind that the keypad had the default mapping, and
+/// the touchscreen does not have the calibration matrix configured, so additional
+/// steps may be necessary.
+/// 
+/// @code 
+/// RA8875 lcd(p5, p6, p7, p12, NC, "tft");
+/// lcd.foreground(Blue);
+/// lcd.line(0,0, 479,271);
+/// ...
+/// @endcode
+///
+/// @section Touch_Panel Touch Panel
+///
+/// The supported touch panel interface is for a resistive panel, and is natively 
+/// supported by the RA8875 controller. There are a few steps to enable this interface.
+///
+/// @subsection Touch_Panel_Enable Touch Panel Enable
+///
+/// @see TouchPanelInit has two forms - fully automatic, and controlled. See the APIs for
+/// details.
+///
+/// @subsection Touch_Panel_Calibration
+/// 
+/// The touch panel is not initially calibrated on startup. The application should 
+/// provide a means to activate the calibration process, and that should not require
+/// the touchscreen as it may not yet be usable. Alternately, a calibration matrix
+/// can be loaded from non-volatile and installed.
+///
+/// @section Keypad Keypad
+///
+/// The keypad has a default keypad mapping, but there is an API that permits
+/// installing a custom keymap.
+///
 #ifndef RA8875_H
 #define RA8875_H
 #include <mbed.h>
@@ -9,7 +63,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.
@@ -305,12 +359,19 @@
  
     /// Initialize theTouch Panel controller with default values 
     ///
+    /// This activates the simplified touch panel init, which may work for
+    /// most uses. The alternate API is available if fine-grained control
+    /// is needed for the numerous settings.
+    ///
     /// @returns success/failure code. @see RetCode_t.
     ///
     RetCode_t TouchPanelInit(void);
         
     /// Initialize the Touch Panel controller with detailed settings.
     ///
+    /// This is the detailed touch panel init, which provides the ability
+    /// to set nearly every possible option.
+    ///
     /// @param[in]  bTpEnable           Touch Panel enable/disable control:
     ///                                 - TP_ENABLE: enable the touch panel
     ///                                 - TP_DISABLE: disable the touch panel
@@ -345,25 +406,38 @@
     ///                                 - TP_ADC_SAMPLE_65536_CLKS: Wait 65536 system clocks
     /// @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);
+    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[inout] x is the x position where the touch was registered.
-    /// @param[inout] y is the y position where the touch was registered.
+    /// This method reads the touch controller, which has a 10-bit range for each the
+    /// x and the y axis. The returned values are not in display (pixel) units.
+    /// 
+    /// @note This API is usually not needed. @see TouchPanelCalibrate. 
+    ///     @see TouchPanelPoint.
+    /// 
+    /// @param[out] x is the x position where the touch was registered.
+    /// @param[out] 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.
     ///
     uint8_t TouchPanelRead(loc_t *x, loc_t *y);
 
     /// Poll the TouchPanel and on a touch event return the raw x, y coordinates.
     ///
-    /// @param[inout] x is the x position where the touch was registered.
-    /// @param[inout] y is the y position where the touch was registered.
+    /// This method reads the touch controller, which has a 10-bit range for each the
+    /// x and the y axis. A number of samples of the raw data are taken, filtered,
+    /// and the results are returned. The returned values are not in display (pixel) units.
+    ///
+    /// @note This API is usually not needed. @see TouchPanelCalibrate. 
+    ///     @see TouchPanelPoint.
+    /// 
+    /// @param[out] x is the x position where the touch was registered.
+    /// @param[out] 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.
     ///
     uint8_t TouchPanelReadRaw(loc_t *x, loc_t *y);
     
-    
     /// Calibrate the touch panel.
     ///
     /// This method accepts two lists - one list is target points in ,
@@ -381,21 +455,21 @@
     ///     http://www.embedded.com/design/system-integration/4023968/How-To-Calibrate-Touch-Screens
     ///
     /// @copyright Copyright (c) 2001, Carlos E. Vidales. All rights reserved.
-    /// This sample program was written and put in the public domain 
-    ///  by Carlos E. Vidales.  The program is provided "as is" 
-    ///  without warranty of any kind, either expressed or implied.
-    /// If you choose to use the program within your own products
-    ///  you do so at your own risk, and assume the responsibility
-    ///  for servicing, repairing or correcting the program should
-    ///  it prove defective in any manner.
-    /// You may copy and distribute the program's source code in any 
-    ///  medium, provided that you also include in each copy an
-    ///  appropriate copyright notice and disclaimer of warranty.
-    /// You may also modify this program and distribute copies of
-    ///  it provided that you include prominent notices stating 
-    ///  that you changed the file(s) and the date of any change,
-    ///  and that you do not charge any royalties or licenses for 
-    ///  its use.
+    ///     This sample program was written and put in the public domain 
+    ///      by Carlos E. Vidales.  The program is provided "as is" 
+    ///      without warranty of any kind, either expressed or implied.
+    ///     If you choose to use the program within your own products
+    ///      you do so at your own risk, and assume the responsibility
+    ///      for servicing, repairing or correcting the program should
+    ///      it prove defective in any manner.
+    ///     You may copy and distribute the program's source code in any 
+    ///      medium, provided that you also include in each copy an
+    ///      appropriate copyright notice and disclaimer of warranty.
+    ///     You may also modify this program and distribute copies of
+    ///      it provided that you include prominent notices stating 
+    ///      that you changed the file(s) and the date of any change,
+    ///      and that you do not charge any royalties or licenses for 
+    ///      its use.
     ///
     /// @param[in] display is a pointer to a set of 3 points, which 
     ///             are in display units of measure. These are the targets
@@ -410,6 +484,30 @@
     ///
     RetCode_t TouchPanelCalibrate(point_t display[3], point_t screen[3], tpMatrix_t * matrix);
 
+    /// Get the screen calibrated point of touch.
+    ///
+    /// This method determines if there is a touch and if so it will provide
+    /// the screen-relative touch coordinates.
+    ///
+    /// @code
+    ///     Timer t;
+    ///     t.start();
+    ///     do {
+    ///        point_t point = {0, 0};
+    ///        if (display.TouchPanelPoint(&point)) {
+    ///            display.pixel(point.x, point.y, Red);
+    ///        }
+    ///    } while (t.read_ms() < 30000);
+    /// @endcode
+    ///
+    /// @param[out] touch is the touch point, if a touch is registered.
+    /// @returns 
+    ///             - touch: if a touch was registered, 
+    ///             - no_touch: if no touch was detected,
+    ///             - bad_parameter: if the calibration matrix is not defined.
+    ///
+    RetCode_t TouchPanelPoint(point_t * touch);
+
     /// Set the calibration matrix for the touch panel.
     ///
     /// This method is used to set the calibration matrix for the touch panel. After
@@ -418,22 +516,22 @@
     /// passed in to this method. It will then be held to perform the corrections when
     /// reading the touch panel point.
     ///
+    /// @code
+    /// FILE * fh = fopen("/local/tpmatrix.cfg", "r");
+    /// if (fh) {
+    ///     tpMatrix_t matrix;
+    ///     if (fread(fh, &matrix, sizeof(tpMatrix_t))) {
+    ///         lcd.TouchPanelSetMatrix(&matrix);
+    ///     }
+    ///     fclose(fh);
+    /// }
+    /// @endcode
+    /// 
     /// @param[in] matrix is a pointer to the touch panel calibration matrix.
     /// @returns success/failure code. @see RetCode_t.
     ///
     RetCode_t TouchPanelSetMatrix(tpMatrix_t * matrix);
-    
-    /// Get the screen calibrated point of touch.
-    ///
-    /// This method determines if there is a touch and if so it will provide
-    /// the screen-relative touch coordinates.
-    ///
-    /// @param[out] touch is the touch point, if a touch is registered.
-    /// @returns true if a touch was registered, no_touch if not, and bad_parameter if the 
-    ///     calibration matrix is not defined.
-    ///
-    RetCode_t TouchPanelPoint(point_t * touch);
-        
+   
 #if 0
     /// Append interrupt handler for specific RA8875 interrupt source
     ///