Libpointing
An open-source cross-platform library to get raw events from pointing devices and master transfer functions.
Description
Libpointing is an open-source cross-platform library written in C++ that provides direct access to HID pointing devices and supports the design of pointing transfer functions. External contributions as pull requests are welcome!
-
If you use libpointing for industrial purposes, please consider funding libpointing through a research contract with Inria (contact Géry Casiez or Nicolas Roussel for this).
-
If you use libpointing for academic purposes, please cite: Casiez, G. & Roussel, N. (2011). No more bricolage! Methods and tools to characterize, replicate and compare pointing transfer functions. In proceedings of UIST'11, the 24th ACM Symposium on User Interface Software and Technology, 603-614. ACM Press. DOI
@inproceedings{Casiez:2011:NMB:2047196.2047276,
author = {Casiez, G{\'e}ry and Roussel, Nicolas},
title = {No More Bricolage!: Methods and Tools to Characterize, Replicate and Compare Pointing Transfer Functions},
booktitle = {Proceedings of the 24th Annual ACM Symposium on User Interface Software and Technology},
series = {UIST '11},
year = {2011},
isbn = {978-1-4503-0716-1},
location = {Santa Barbara, California, USA},
pages = {603--614},
numpages = {12},
url = {http://doi.acm.org/10.1145/2047196.2047276},
doi = {10.1145/2047196.2047276},
acmid = {2047276},
publisher = {ACM},
address = {New York, NY, USA},
keywords = {CD gain, control-display gain functions, pointer acceleration, pointing, toolkit, transfer functions},
}
Installation
Visit installation page or build it from source.
Documentation
Please visit our wiki.
Features
- runs on Windows, Mac OS X and Linux,
- makes it easy to choose the devices at run-time through the use of URIs,
- provides raw information from input devices,
- provides resolution and frequency information for the available pointing and display devices,
- supports hot-plugging
- allows to bypass the system's transfer functions to receive raw asynchronous events from one or more pointing devices.
- replicates as faithfully as possible the transfer functions used by Microsoft Windows, Apple OS X and Xorg (the X.Org Foundation server).
- running on these three platforms, it makes it possible to compare the replicated functions to the genuine ones as well as custom ones.
- provides the functionality to use existing transfer functions, custom ones or even build your own functions.
- supports subpixel interaction.
- Java, Python, Node.js bindings are available.
Minimalistic example
Once you correctly installed libpointing and linked it to your project, simply write #include <pointing/pointing.h> and start coding. Here is the console example which applies system specific transfer function to an input device and outputs the results to console:
#include <iostream>
#include <pointing/pointing.h>
using namespace pointing;
TransferFunction *func = 0;
// context is user data, timestamp is a moment at which the event was received
// input_dx, input_dy are displacements in horizontal and vertical directions
// buttons is a variable indicating which buttons of the pointing device were pressed.
void pointingCallback(void *, TimeStamp::inttime timestamp, int input_dx, int input_dy, int buttons) {
if (!func) return;
int output_dx = 0, output_dy = 0;
// In order to use a particular transfer function, its applyi method must be called.
func->applyi(input_dx, input_dy, &output_dx, &output_dy, timestamp);
std::cout << "Displacements in x and y: " << input_dx << " " << input_dy << std::endl;
std::cout << "Corresponding pixel displacements: " << output_dx << " " << output_dy << std::endl;
}
int main() {
// Basically, to start using main functionality of libpointing
// one needs to create objects of PointingDevice, DisplayDevice classes,
// connect them passing to TransferFunction class object.
// Any available pointing and display devices
// if debugLevel > 0, the list of available devices
// and extended information will be output.
PointingDevice *input = PointingDevice::create("any:?debugLevel=1");
DisplayDevice *output = DisplayDevice::create("any:?debugLevel=1");
func = TransferFunction::create("sigmoid:?debugLevel=2", input, output);
// To receive events from PointingDevice object, a callback function must be set.
input->setPointingCallback(pointingCallback);
while (1)
PointingDevice::idle(100); // milliseconds
delete input;
delete output;
delete func;
return 0;
}Contributors
License
This software may be used and distributed according to the terms of the GNU General Public License version 2 or any later version.
Ad-hoc licences can be granted upon request.