Kerry Martin
KSM edits to RA8875
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
///