mouse.h

Go to the documentation of this file.

/*
 * This file is part of the Ultibo project, https://ultibo.org/
 *
 * The MIT License (MIT)
 *
 * Copyright (c) 2026 Garry Wood <garry@softoz.com.au>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 * THE SOFTWARE.
 */
#ifndef _ULTIBO_MOUSE_H
#define _ULTIBO_MOUSE_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "ultibo/globaltypes.h"
#include "ultibo/globalconst.h"
#include "ultibo/devices.h"

#define MOUSE_NAME_PREFIX   "Mouse" 

#define MOUSE_TYPE_NONE 0
#define MOUSE_TYPE_USB  1
#define MOUSE_TYPE_PS2  2
#define MOUSE_TYPE_SERIAL   3
 
#define MOUSE_TYPE_MAX  3

#define MOUSE_STATE_DETACHED    0
#define MOUSE_STATE_DETACHING   1
#define MOUSE_STATE_ATTACHING   2
#define MOUSE_STATE_ATTACHED    3
 
#define MOUSE_STATE_MAX 3

#define MOUSE_FLAG_NONE 0x00000000
#define MOUSE_FLAG_NON_BLOCK    0x00000001 
#define MOUSE_FLAG_DIRECT_READ  0x00000002 
#define MOUSE_FLAG_SWAP_BUTTONS 0x00000004 
#define MOUSE_FLAG_PEEK_BUFFER  0x00000008 
#define MOUSE_FLAG_SWAP_XY  0x00000010 
#define MOUSE_FLAG_INVERT_X 0x00000020 
#define MOUSE_FLAG_INVERT_Y 0x00000040 
#define MOUSE_FLAG_SWAP_MAX_XY  0x00000080 

#define MOUSE_FLAG_MASK MOUSE_FLAG_NON_BLOCK | MOUSE_FLAG_DIRECT_READ | MOUSE_FLAG_SWAP_BUTTONS | MOUSE_FLAG_SWAP_XY | MOUSE_FLAG_INVERT_X | MOUSE_FLAG_INVERT_Y | MOUSE_FLAG_SWAP_MAX_XY

#define MOUSE_CONTROL_GET_FLAG  1 
#define MOUSE_CONTROL_SET_FLAG  2 
#define MOUSE_CONTROL_CLEAR_FLAG    3 
#define MOUSE_CONTROL_FLUSH_BUFFER  4 
#define MOUSE_CONTROL_GET_SAMPLE_RATE   5 
#define MOUSE_CONTROL_SET_SAMPLE_RATE   6 
#define MOUSE_CONTROL_GET_MAX_X 7 
#define MOUSE_CONTROL_GET_MAX_Y 8 
#define MOUSE_CONTROL_GET_MAX_WHEEL 9 
#define MOUSE_CONTROL_GET_MAX_BUTTONS   10 
#define MOUSE_CONTROL_GET_ROTATION  11 
#define MOUSE_CONTROL_SET_ROTATION  12 

#define MOUSE_BUFFER_SIZE   512

#define MOUSE_SAMPLE_RATE   100 

#define MOUSE_LEFT_BUTTON   0x0001 
#define MOUSE_RIGHT_BUTTON  0x0002 
#define MOUSE_MIDDLE_BUTTON 0x0004 
#define MOUSE_SIDE_BUTTON   0x0008 
#define MOUSE_EXTRA_BUTTON  0x0010 
#define MOUSE_TOUCH_BUTTON  0x0020 
#define MOUSE_ABSOLUTE_X    0x0040 
#define MOUSE_ABSOLUTE_Y    0x0080 
#define MOUSE_ABSOLUTE_WHEEL    0x0100 

#define MOUSE_ROTATION_0    FRAMEBUFFER_ROTATION_0 
#define MOUSE_ROTATION_90   FRAMEBUFFER_ROTATION_90 
#define MOUSE_ROTATION_180  FRAMEBUFFER_ROTATION_180 
#define MOUSE_ROTATION_270  FRAMEBUFFER_ROTATION_270 


#define USB_HID_SUBCLASS_NONE   0 
#define USB_HID_SUBCLASS_BOOT   1 

#define USB_HID_BOOT_PROTOCOL_NONE  0 
#define USB_HID_BOOT_PROTOCOL_KEYBOARD  1 
#define USB_HID_BOOT_PROTOCOL_MOUSE 2 

#define USB_HID_DESCRIPTOR_TYPE_HID 0x21 
#define USB_HID_DESCRIPTOR_TYPE_REPORT  0x22 
#define USB_HID_DESCRIPTOR_TYPE_PHYSICAL_DESCRIPTOR 0x23 

#define USB_HID_REQUEST_GET_REPORT  0x01
#define USB_HID_REQUEST_GET_IDLE    0x02
#define USB_HID_REQUEST_GET_PROTOCOL    0x03 
#define USB_HID_REQUEST_SET_REPORT  0x09
#define USB_HID_REQUEST_SET_IDLE    0x0A
#define USB_HID_REQUEST_SET_PROTOCOL    0x0B 

#define USB_HID_PROTOCOL_BOOT   0 
#define USB_HID_PROTOCOL_REPORT 1 

#define USB_HID_REPORT_INPUT    1 
#define USB_HID_REPORT_OUTPUT   2 
#define USB_HID_REPORT_FEATURE  3 

#define USB_HID_REPORTID_NONE   0 

#define USB_HID_BOOT_LEFT_BUTTON    (1 << 0)
#define USB_HID_BOOT_RIGHT_BUTTON   (1 << 1)
#define USB_HID_BOOT_MIDDLE_BUTTON  (1 << 2)
#define USB_HID_BOOT_SIDE_BUTTON    (1 << 3)
#define USB_HID_BOOT_EXTRA_BUTTON   (1 << 4)

#define USB_HID_BOOT_REPORT_SIZE    8 
#define USB_HID_BOOT_DATA_SIZE  8 

typedef struct _MOUSE_DATA MOUSE_DATA;
struct _MOUSE_DATA
{
    uint16_t buttons; 
    int16_t offsetx; 
    int16_t offsety; 
    int16_t offsetwheel; 
    uint16_t maximumx; 
    uint16_t maximumy; 
    uint16_t maximumwheel; 
    uint16_t reserved; 
};

typedef struct _MOUSE_BUFFER MOUSE_BUFFER;
struct _MOUSE_BUFFER
{
    SEMAPHORE_HANDLE wait; 
    uint32_t start; 
    uint32_t count; 
    MOUSE_DATA buffer[MOUSE_BUFFER_SIZE];
};

typedef struct _MOUSE_PROPERTIES MOUSE_PROPERTIES;
struct _MOUSE_PROPERTIES
{
    uint32_t flags; 
    uint32_t rotation; 
    uint32_t maxx; 
    uint32_t maxy; 
    uint32_t maxwheel; 
    uint32_t maxbuttons; 
};

typedef struct _MOUSE_DEVICE MOUSE_DEVICE;

typedef uint32_t STDCALL (*mouse_enumerate_cb)(MOUSE_DEVICE *mouse, void *data);
typedef uint32_t STDCALL (*mouse_notification_cb)(DEVICE *device, void *data, uint32_t notification);

typedef uint32_t STDCALL (*mouse_device_read_proc)(MOUSE_DEVICE *mouse, void *buffer, uint32_t size, uint32_t *count);
typedef uint32_t STDCALL (*mouse_device_update_proc)(MOUSE_DEVICE *mouse);
typedef uint32_t STDCALL (*mouse_device_control_proc)(MOUSE_DEVICE *mouse, int request, size_t argument1, size_t *argument2);
 
typedef uint32_t STDCALL (*mouse_device_get_properties_proc)(MOUSE_DEVICE *mouse, MOUSE_PROPERTIES *properties);
 
struct _MOUSE_DEVICE
{
    // Device Properties
    DEVICE device; 
    // Mouse Properties
    uint32_t mouseid; 
    uint32_t mousestate; 
    uint32_t mouserate; 
    mouse_device_read_proc deviceread; 
    mouse_device_update_proc deviceupdate; 
    mouse_device_control_proc devicecontrol; 
    mouse_device_get_properties_proc devicegetproperties; 
    // Driver Properties
    MUTEX_HANDLE lock; 
    MOUSE_BUFFER buffer; 
    MOUSE_PROPERTIES properties; 
    // Statistics Properties
    uint32_t receivecount;
    uint32_t receiveerrors;
    uint32_t bufferoverruns;
    // Internal Properties
    MOUSE_DEVICE *prev; 
    MOUSE_DEVICE *next; 
};

 
#ifndef _ULTIBO_KEYBOARD_H
typedef struct _USB_HID_DESCRIPTOR USB_HID_DESCRIPTOR;
struct _USB_HID_DESCRIPTOR
{
    uint8_t blength;
    uint8_t bdescriptortype;
    uint16_t bcdhid;
    uint8_t bcountrycode;
    uint8_t bnumdescriptors;
    uint8_t bhiddescriptortype;
    uint16_t whiddescriptorlength;
    // Note: Up to two optional bHIDDescriptorType/wHIDDescriptorLength pairs after the Report descriptor details
} PACKED;
#endif // _ULTIBO_KEYBOARD_H


uint32_t STDCALL mouse_peek(void);

uint32_t STDCALL mouse_read(void *buffer, uint32_t size, uint32_t *count);

uint32_t STDCALL mouse_read_ex(void *buffer, uint32_t size, uint32_t flags, uint32_t *count);

uint32_t STDCALL mouse_write(void *buffer, uint32_t size, uint32_t count);

uint32_t STDCALL mouse_flush(void);

uint32_t STDCALL mouse_device_read(MOUSE_DEVICE *mouse, void *buffer, uint32_t size, uint32_t *count);

uint32_t STDCALL mouse_device_update(MOUSE_DEVICE *mouse);

uint32_t STDCALL mouse_device_control(MOUSE_DEVICE *mouse, int request, size_t argument1, size_t *argument2);

uint32_t STDCALL mouse_device_get_properties(MOUSE_DEVICE *mouse, MOUSE_PROPERTIES *properties);

uint32_t STDCALL mouse_device_set_state(MOUSE_DEVICE *mouse, uint32_t state);

MOUSE_DEVICE * STDCALL mouse_device_create(void);

MOUSE_DEVICE * STDCALL mouse_device_create_ex(uint32_t size);

uint32_t STDCALL mouse_device_destroy(MOUSE_DEVICE *mouse);

uint32_t STDCALL mouse_device_register(MOUSE_DEVICE *mouse);

uint32_t STDCALL mouse_device_deregister(MOUSE_DEVICE *mouse);

MOUSE_DEVICE * STDCALL mouse_device_find(uint32_t mouseid);

MOUSE_DEVICE * STDCALL mouse_device_find_by_name(const char *name);

MOUSE_DEVICE * STDCALL mouse_device_find_by_description(const char *description);

uint32_t STDCALL mouse_device_enumerate(mouse_enumerate_cb callback, void *data);

uint32_t STDCALL mouse_device_notification(MOUSE_DEVICE *mouse, mouse_notification_cb callback, void *data, uint32_t notification, uint32_t flags);


uint32_t STDCALL mouse_get_count(void);

MOUSE_DEVICE * STDCALL mouse_device_check(MOUSE_DEVICE *mouse);
 
uint32_t STDCALL mouse_device_type_to_string(uint32_t mousetype, char *string, uint32_t len);
uint32_t STDCALL mouse_device_state_to_string(uint32_t mousestate, char *string, uint32_t len);

uint32_t STDCALL mouse_device_rotation_to_string(uint32_t rotation, char *string, uint32_t len);

uint32_t STDCALL mouse_device_state_to_notification(uint32_t state);

uint32_t STDCALL mouse_device_resolve_rotation(uint32_t rotation);

uint32_t STDCALL mouse_insert_data(MOUSE_DEVICE *mouse, MOUSE_DATA *data, BOOL signal);
 
#ifdef __cplusplus
}
#endif
 
#endif // _ULTIBO_MOUSE_H