FabGL
ESP32 VGA Controller and Graphics Library
|
The PS2 Mouse controller class. More...
#include <mouse.h>
Public Member Functions | |
int | availableStatus () |
Gets the number of available mouse status. More... | |
void | begin (gpio_num_t clkGPIO, gpio_num_t dataGPIO) |
Initializes MouseClass specifying CLOCK and DATA GPIOs. More... | |
void | begin (int PS2Port) |
Initializes MouseClass without initializing the PS/2 controller. More... | |
int | deltaAvailable () |
Determines the number of mouse movements available in the queue. More... | |
bool | getNextDelta (MouseDelta *delta, int timeOutMS=-1, bool requestResendOnTimeOut=false) |
Gets a mouse movement from the queue. More... | |
MouseStatus | getNextStatus (int timeOutMS=-1) |
Gets the next status from the status queue. More... | |
PS2Device | identify () |
Identifies the device attached to the PS2 port. More... | |
bool | isMouseAvailable () |
Checks if mouse has been detected and correctly initialized. More... | |
bool | lock (int timeOutMS) |
Gets exclusive access to the device. More... | |
int & | movementAcceleration () |
Gets or set mouse movement acceleration factor. More... | |
bool | reset () |
Sends a Reset command to the mouse. More... | |
bool | setResolution (int value) |
Sets the resolution. More... | |
bool | setSampleRate (int value) |
Sets the maximum rate of mouse movements reporting. More... | |
bool | setScaling (int value) |
Sets the scaling. More... | |
void | setUIApp (uiApp *app) |
Sets current UI app. More... | |
void | setupAbsolutePositioner (int width, int height, bool createAbsolutePositionsQueue, bool updateVGAController, uiApp *app) |
Initializes absolute position handler. More... | |
MouseStatus & | status () |
Gets or sets current mouse status. More... | |
void | terminateAbsolutePositioner () |
Terminates absolute position handler. More... | |
void | unlock () |
Releases device from exclusive access. More... | |
void | updateAbsolutePosition (MouseDelta *delta) |
Updates absolute position from the specified mouse delta event. More... | |
int & | wheelAcceleration () |
Gets or sets wheel acceleration factor. More... | |
The PS2 Mouse controller class.
MouseClass connects to one port of the PS2 Controller class (fabgl::PS2ControllerClass) to decode and get mouse movements.
At the moment MouseClass supports standard PS/2 mouse (X and Y axis with three buttons) and Microsoft Intellimouse compatible mouse (X and Y axis, scroll wheel with three buttons).
MouseClass allows to set movement parameters, like sample rate, resolution and scaling.
The PS2 controller uses ULP coprocessor and RTC slow memory to communicate with the PS2 device.
Applications do not need to create an instance of MouseClass because an instance named Mouse is created automatically.
Because fabgl::PS2ControllerClass supports up to two PS/2 ports, it is possible to have connected two PS/2 devices. The most common configuration is Keyboard on port 0 and Mouse on port 1. However you may have two mice connected at the same time using the Mouse instance on port 0 and creating a new one on port 1.
Example:
// Setup pins GPIO26 for CLK and GPIO27 for DATA Mouse.begin(GPIO_NUM_26, GPIO_NUM_27); if (Mouse.deltaAvailable()) { MouseDelta mouseDelta; Mouse.getNextDelta(&mouseDelta); Serial.printf("deltaX = %d deltaY = %d deltaZ = %d leftBtn = %d midBtn = %d rightBtn = %d\n", mouseDelta.deltaX, mouseDelta.deltaY, mouseDelta.deltaZ, mouseDelta.leftButton, mouseDelta.middleButton, mouseDelta.rightButton); }
int fabgl::MouseClass::availableStatus | ( | ) |
Gets the number of available mouse status.
Mouse status contains absolute mouse position, scroll wheel delta and buttons status.
Mouse status queue is populated only when createAbsolutePositionsQueue parameter of MouseClass.setupAbsolutePositioner() is true.
void fabgl::MouseClass::begin | ( | gpio_num_t | clkGPIO, |
gpio_num_t | dataGPIO | ||
) |
Initializes MouseClass specifying CLOCK and DATA GPIOs.
A reset command (MouseClass.reset() method) is automatically sent to the mouse.
This method also initializes the PS2ControllerClass to use port 0 only.
clkGPIO | The GPIO number of Clock line |
dataGPIO | The GPIO number of Data line |
Example:
// Setup pins GPIO26 for CLK and GPIO27 for DATA Mouse.begin(GPIO_NUM_26, GPIO_NUM_27);
void fabgl::MouseClass::begin | ( | int | PS2Port | ) |
Initializes MouseClass without initializing the PS/2 controller.
A reset command (MouseClass.reset() method) is automatically sent to the mouse.
This method does not initialize the PS2ControllerClass.
PS2Port | The PS/2 port to use (0 or 1). |
Example:
// Setup pins GPIO26 for CLK and GPIO27 for DATA on port 0 PS2Controller.begin(GPIO_NUM_26, GPIO_NUM_27); // clk, dat Mouse.begin(0); // port 0
int fabgl::MouseClass::deltaAvailable | ( | ) |
Determines the number of mouse movements available in the queue.
bool fabgl::MouseClass::getNextDelta | ( | MouseDelta * | delta, |
int | timeOutMS = -1 , |
||
bool | requestResendOnTimeOut = false |
||
) |
Gets a mouse movement from the queue.
delta | Pointer to MouseDelta structure to be filled with mouse movement. May be nullptr if not required (in this case only Status().buttons is updated. |
timeOutMS | Timeout in milliseconds. -1 means no timeout (infinite time). |
requestResendOnTimeOut | If true and timeout has expired then asks the mouse to resend the mouse movement. |
Example:
MouseDelta mouseDelta; Mouse.getNextDelta(&mouseDelta);
MouseStatus fabgl::MouseClass::getNextStatus | ( | int | timeOutMS = -1 | ) |
Gets the next status from the status queue.
Mouse status contains absolute mouse position, scroll wheel delta and buttons status.
Mouse status queue is populated only when createAbsolutePositionsQueue parameter of MouseClass.setupAbsolutePositioner() is true.
timeOutMS | Timeout in milliseconds to wait for a new status. -1 = wait forever. |
Example:
// wait for events from mouse and draw a pixel at the mouse position if left button is down MouseStatus status = Mouse.getNextStatus(); if (status.buttons.left) { Canvas.setPenColor(Color::BrightRed); Canvas.setPixel(status.X, status.Y); }
|
inlineinherited |
Identifies the device attached to the PS2 port.
|
inline |
Checks if mouse has been detected and correctly initialized.
isMouseAvailable() returns a valid value only after MouseClass.begin() or MouseClass.reset() has been called.
|
inherited |
Gets exclusive access to the device.
timeOutMS | Timeout in milliseconds to wait before fail. |
|
inline |
Gets or set mouse movement acceleration factor.
Mouse movement acceleration is calculated in MouseClass.updateAbsolutePosition() and depends by the acceleration factor and time of call.
Lower values generate little acceleration, high values generate a lot of acceleration.
Suggested range is 0 ... 2000. Default value is 180.
bool fabgl::MouseClass::reset | ( | ) |
Sends a Reset command to the mouse.
|
inline |
Sets the resolution.
Resolution is the amount by which the movement counters are incremented/decremented measured as counts per millimeter.
The default resolution is 4 counts/mm.
value | Resolution encoded as follows: 0 = 1 count/mm (25 dpi), 1 = 2 counts/mm (50 dpi), 2 = 4 counts/mm (100 dpi), 3 = 8 counts/mm (200 dpi). |
|
inline |
Sets the maximum rate of mouse movements reporting.
The default sample rate is 60 samples/sec.
value | Sample rate as samples per second. Valid values: 10, 20, 40, 60, 80, 100, and 200. |
|
inline |
Sets the scaling.
The default scaling is 1:1.
value | Scaling encoded as follows: 1 = 1:1, 2 = 1:2. |
|
inline |
Sets current UI app.
app | The UI app where to send mouse events |
void fabgl::MouseClass::setupAbsolutePositioner | ( | int | width, |
int | height, | ||
bool | createAbsolutePositionsQueue, | ||
bool | updateVGAController, | ||
uiApp * | app | ||
) |
Initializes absolute position handler.
Use this method to specify the absolute mouse area inside the rectangle (0, 0) to (width - 1, height - 1).
Optinally this method creates a queue that stores absolute positions generated by updateAbsolutePosition().
This method must be called one time to initialize absolute positioning.
width | Absolute mouse area width. Mouse can travel from 0 up to width - 1. |
height | Absolute mouse area height. Mouse can travel from 0 up to height - 1. |
createAbsolutePositionsQueue | If true a queue of absolute positions is created. |
updateVGAController | If true VGA controller mouse pointer is automatically updated. |
app | Optional fabgl::uiApp where to send mouse events. |
Example:
Mouse.setupAbsolutePositioner(Canvas.getWidth(), Canvas.getHeight(), true, true, nullptr);
|
inline |
Gets or sets current mouse status.
void fabgl::MouseClass::terminateAbsolutePositioner | ( | ) |
Terminates absolute position handler.
|
inherited |
Releases device from exclusive access.
void fabgl::MouseClass::updateAbsolutePosition | ( | MouseDelta * | delta | ) |
Updates absolute position from the specified mouse delta event.
This method updates absolute mouse position, mouse wheel and buttons status.
In order to improve quality of acceleration it is important to call updateAbsolutePosition() often and at constant frequency.
updateAbsolutePosition() is automatically executed when updateVGAController or createAbsolutePositionsQueue parameters of MouseClass.setupAbsolutePositioner() is true.
delta | Mouse event to process. |
Example:
// move a sprite (previously defined) at mouse absolute position void loop() { MouseDelta delta; if (getNextDelta(&delta)) { Mouse.updateAbsolutePosition(&delta); mouseSprite.moveTo(Mouse.position().X, Mouse.position().Y); } }
|
inline |
Gets or sets wheel acceleration factor.
Wheel acceleration is calculated in MouseClass.updateAbsolutePosition() and depends by the acceleration factor and time of call.
Lower values generate little acceleration, high values generate a lot of acceleration.
Suggested range is 0 ... 100000. Default value is 60000.