Permalink
Fetching contributors…
Cannot retrieve contributors at this time
121 lines (88 sloc) 5.34 KB

Libpointing

Build Status Build status

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.