Diff: RA8875.h

Revision:

79:544eb4964795

Parent:

78:faf49c381591

Child:

81:01da2e34283d

--- a/RA8875.h	Sun Dec 28 03:14:35 2014 +0000
+++ b/RA8875.h	Sun Dec 28 19:55:16 2014 +0000
@@ -67,7 +67,7 @@
 
 // What better place for some test code than in here and the companion
 // .cpp file. See also the bottom of this file.
-#define TESTENABLE
+//#define TESTENABLE
 
 /// DOS colors - slightly color enhanced
 #define Black       (color_t)(RGB(0,0,0))
@@ -121,6 +121,7 @@
 ///
 /// int main()
 /// {
+///     lcd.init(480,272,16);
 ///     lcd.printf("printing 3 x 2 = %d", 3*2);
 ///     lcd.circle(       400,25,  25,               BrightRed);
 ///     lcd.fillcircle(   400,25,  15,               RGB(128,255,128));
@@ -223,6 +224,7 @@
     ///
     /// int main()
     /// {
+    ///     lcd.init(true,255,480,272,16); // powerup, backlight full, w x h x c
     ///     lcd.printf("printing 3 x 2 = %d", 3*2);
     ///     lcd.circle(400,25, 25, BrightRed);
     /// }
@@ -245,6 +247,29 @@
     // at startup, and not at runtime.
     //~RA8875();
     
+    /// Initialize the driver.
+    ///
+    /// @param[in] power defines if the display should be left in the power-on or off state.
+    ///            If power is true (on), the backlight is set to 100%.
+    /// @param[in] width in pixels to configure the display for.
+    /// @param[in] height in pixels to configure the display for.
+    /// @param[in] color_bpp can be either 8 or 16, but must be consistent
+    ///     with the width and height parameters.
+    /// @returns success/failure code. @see RetCode_t.
+    ///
+    RetCode_t init(bool poweron, int width, int height, int color_bpp);
+    
+    /// Get a pointer to the error code.
+    ///
+    /// This method returns a pointer to a text string that matches the
+    /// code. @see RetCode_t.
+    ///
+    /// @param[in] code is the return value from RetCode_t to look up.
+    /// @returns a pointer to the text message representing code. If code
+    ///     is not a valid value, then it returns the text for bad_parameter;
+    const char * GetErrorMessage(RetCode_t code);
+    
+    
     /// Select the drawing layer for subsequent commands.
     ///
     /// If the screen configuration is 480 x 272, or if it is 800 x 480 
@@ -409,34 +434,40 @@
     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.
+    /// Poll the TouchPanel and on a touch event return the a to d filtered x, y coordinates.
     ///
     /// 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.
+    /// x and the y axis.
+    ///
+    /// @note The returned values are not in display (pixel) units but are in analog to
+    ///     digital converter units.
     /// 
     /// @note This API is usually not needed. @see TouchPanelCalibrate. 
-    ///     @see TouchPanelPoint.
+    ///     @see TouchPanelReadable.
     /// 
-    /// @param[out] x is the x position where the touch was registered.
-    /// @param[out] y is the y position where the touch was registered.
+    /// @param[out] x is the x scale a/d value.
+    /// @param[out] y is the y scale a/d value.
     /// @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);
+    bool TouchPanelA2DFiltered(loc_t *x, loc_t *y);
 
-    /// Poll the TouchPanel and on a touch event return the raw x, y coordinates.
+    /// Poll the TouchPanel and on a touch event return the a to d raw x, y coordinates.
     ///
     /// 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.
+    /// and the results are returned. 
     ///
+    /// @note The returned values are not in display (pixel) units but are in analog to
+    ///     digital converter units.
+    /// 
     /// @note This API is usually not needed. @see TouchPanelCalibrate. 
-    ///     @see TouchPanelPoint.
+    ///     @see TouchPanelReadable.
     /// 
-    /// @param[out] x is the x position where the touch was registered.
-    /// @param[out] y is the y position where the touch was registered.
+    /// @param[out] x is the x scale a/d value.
+    /// @param[out] y is the y scale a/d value.
     /// @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);
+    bool TouchPanelA2DRaw(loc_t *x, loc_t *y);
     
     /// Calibrate the touch panel.
     ///
@@ -448,7 +479,7 @@
     /// matrix on the next power cycle. By doing so, it can avoid the
     /// need to calibrate on every power cycle.
     ///
-    /// @note The methods "TouchPanelCalibrate", "TouchPanelPoint", and
+    /// @note The methods "TouchPanelCalibrate", "TouchPanelReadable", and
     ///     indirectly the "TouchPanelSetMatrix" methods are all derived
     ///     from a program by Carlos E. Vidales. See the copyright note
     ///     for further details. See also the article
@@ -487,26 +518,52 @@
     /// 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.
+    /// the screen-relative touch coordinates. This method can be used in
+    /// a manner similar to Serial.readable(), to determine if there was a 
+    /// touch and indicate that - but not care about the coordinates. Alternately,
+    /// if a valid pointer to a point_t is provided, then if a touch is detected
+    /// the point_t will be populated with data. 
     ///
     /// @code
     ///     Timer t;
     ///     t.start();
     ///     do {
     ///        point_t point = {0, 0};
-    ///        if (display.TouchPanelPoint(&point)) {
+    ///        if (display.TouchPanelReadable(&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.
+    /// @returns true if a touch was registered, and touch is updated.
+    /// @returns false if no touch was detected, or if the calibration matrix is not defined.
+    ///
+    bool TouchPanelReadable(point_t * touch = NULL);
+
+    /// Wait for a touch panel touch and return it.
+    /// 
+    /// This method is similar to Serial.getc() in that it will wait for a touch
+    /// and then return. In order to extract the coordinates of the touch, a
+    /// valid pointer to a point_t must be provided.
+    ///
+    /// @note There is no timeout on this function, so its use is not recommended.
     ///
-    RetCode_t TouchPanelPoint(point_t * touch);
+    /// @code
+    ///     Timer t;
+    ///     t.start();
+    ///     do {
+    ///        point_t point = {0, 0};
+    ///        display.TouchPanelGet(&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 true if a touch was registered, and touch is updated.
+    /// @returns false if no touch was detected, or if the calibration matrix is not defined.
+    ///
+    bool TouchPanelGet(point_t * touch);
 
     /// Set the calibration matrix for the touch panel.
     ///
@@ -584,7 +641,6 @@
         uint8_t longTimeAdjustment = 0,
         bool interruptEnable = false, bool wakeupEnable = false);
 
-
     /// Create Key Code definitions for the key matrix.
     ///
     /// This API provides a table of 22 key-code assignments for the matrix of keys.
@@ -1579,22 +1635,6 @@
     /// Touch Panel calibration matrix.
     tpMatrix_t tpMatrix;
 
-    /// Initialize the chip, which is normally done as part of the
-    /// constructor, so not typically called by the user.
-    ///
-    /// @note This API permits configuration, however it is not [yet]
-    ///     available to the end user. Be sure the parameters
-    ///     are consistent with each other - see the RA8875 user
-    ///     manual.
-    ///
-    /// @param[in] width in pixels to configure the display for.
-    /// @param[in] height in pixels to configure the display for.
-    /// @param[in] color_bpp can be either 8 or 16, but must be consistent
-    ///     with the width and height parameters.
-    /// @returns success/failure code. @see RetCode_t.
-    ///
-    RetCode_t init(int width, int height, int color_bpp);
-    
     /// Internal function to put a character using the built-in (internal) font engine
     ///
     /// @param[in] is the character to put to the screen.
@@ -1616,7 +1656,7 @@
     ///     the pin selection is the invert of this.
     /// @returns success/failure code. @see RetCode_t.
     ///
-    RetCode_t select(bool chipsel);
+    RetCode_t _select(bool chipsel);
 
     /// Wait while the status register indicates the controller is busy.
     ///
@@ -1652,7 +1692,7 @@
     /// @returns a value read from the port, since SPI is often shift
     ///     in while shifting out.
     ///
-    unsigned char spiwrite(unsigned char data);
+    unsigned char _spiwrite(unsigned char data);
     
     /// The most primitive - to read a data value to the SPI interface.
     ///
@@ -1662,7 +1702,7 @@
     /// @returns a value read from the port, since SPI is often shift
     ///     in while shifting out.
     ///
-    unsigned char spiread();
+    unsigned char _spiread();
     
     const uint8_t * pKeyMap;