Javascript Bindings

Javascript APIs for libpointing

Getting Started

We developed the libpointing bindings with almost all the functionality of the native library. To start programming quickly, you need to run:

npm install libpointing

Then you can var pointing = require('libpointing') and start using it.

Main functionality

Working with input

Creating a pointing device:

var input = pointing.PointingDevice("any:"); // Any device URI

Start receiving HID events from a device:

input.setPointingCallback(function(timestamp, dx, dy, buttons) {
	console.log(timestamp, dx, dy, buttons);
});

Hot-plugging callback for input devices:

var manager = pointing.PointingDeviceManager().addDeviceUpdateCallback(
	function(deviceDescriptor, wasAdded) {
		console.log(deviceDescriptor, wasAdded);
	}
);

manager.deviceList will return all the pointing devices.

You can access the following properties of a PointingDevice:

• uri
• vendorID
• productID
• vendor
• product
• resolution
• updateFrequency
• active

Working with output

Creating a display device:

var output = pointing.DisplayDevice("any:");

You can access the following properties of a DisplayDevice:

• uri
• size { width, height }
• bounds { size: { width, height }, origin: { x, y } }
• refreshRate
• resolution { hppi, vppi }

Working with transfer functions

TransferFunction class maps the input counts of a PointingDevice to the pixel coordinates of a DisplayDevice.

Creating a transfer function:

var tFunc = pointing.TransferFunction("any:", input, output);

List of available methods:

• applyi(dx, dy, timestamp) // Integer output
• applyd(dx, dy, timestamp) // Float output
• clearState()
• setSubPixeling(value) // By default it is turned off
• setHumanResolution(resolution)
• setCardinalitySize(cardinality, size)

List of properties:

• uri
• subPixeling
• cardinality
• widgetSize
• humanResolution

Note that in Node.js version of libpointing all transfer functions support subpixeling and the uri property returns the original transfer function URI.

Applying a transfer function to the input:

input.setPointingCallback(function(timestamp, dx, dy, buttons) {
	var pixels = tFunc.applyd(dx, dy, timestamp);
	console.log(pixels.dx, pixels.dy);
});

System pointer acceleration

You can set and get the acceleration profile of your system as follows:

var spa = pointing.SystemPointerAcceleration();
var acc = spa.get(); // To get the acceleration object
    spa.set(acc); // To set the object
});

Note that, the acceleration object varies depending on the current OS:

• { value, target } on Mac OS
• { numerator, denominator, threshold } on Linux
• { version, sliderPosition, enhancePointerPrecision } on Windows

Pointing cursor

We added 2 functions to get and set the position of the cursor:

• pointing.pointingCursor.getPosition() will return { x, y } object
• pointing.pointingCursor.setPosition(x, y) will modify the cursor position

setPosition cannot be used in a continuous fashion, since it does not modify the global behavior of the mouse cursor, but only changes it at a given time, i.e. it won't block the OS mouse events.

Libpointing in your browser

It is possible to use libpointing in your browser using almost the same APIs. You can download pointing.js from here. Then, include this file in your html code and you can will have variable pointing (just like with libpointing module). However, since libpointing accesses low-level data, pointingserver application is used to send these data to your browser.

You can check out the list of demos once pointingserver is installed:

• Balloons - Simple HTML5 multiplayer game. The number of players depends on the number of mice connected.
• Web-demo - Simple web-example, where you can test multiple mice with different transfer functions.
• Pong - Single or double player pong.
• Lagmeter - Lagmeter to measure the latencies for your mouse.
• SubPixel Demo - SubPixel Player with a custom slider to demonstrate SubPixel Interaction.

Local Pointing Server

In order to access low-level data from a browser, pointingserver app was implemented, which uses socket.io for communication.

Install pointingserver with (on Linux and Mac):

npm i pointingserver -g

Make sure, that installed package can be found on your path. For homebrew, you might need to run npm config set prefix /usr/local before installing the package which will symlink executable scripts into your /usr/local.

run it with:

pointingserver start

On Windows, you can download executable nw-based application here.

The client-part differences

All APIs are the same for the client-part, unless otherwise noted. So, discover the differences in this section.

Applying transfer functions

The main difference is in the way transfer functions are applied. Since we do not want to send the input data back and forth all the time HID events are received, transfer functions should be applied on the server-part. So, applyTransferFunction(tFunc, floatingValues) was added. Here is an example:

var input = new pointing.PointingDevice("any:?vendor=0x46d");
var output = new pointing.DisplayDevice("any:");
var tFunc = new pointing.TransferFunction("system:", input, output);
input.applyTransferFunction(tFunc, true);

input.setPointingCallback(function(timestamp, dx, dy, buttons) {
	// Here, dx and dy are already values on which the transfer
	// was applied
	console.log(timestamp, dx, dy, buttons);
});
tFunc.setSubPixeling(true).setCardinalitySize(10000, 300);

Ready callbacks

Also, since we don't want to block the execution, callback are used more often. When PointingDevice, DisplayDevice, TransferFunction objects are instantiated, the request to create the corresponding object on the server-part is sent. When the properties of the object become available ready callback is called. Example:

var input = new pointing.PointingDevice('any:?');
input.ready(function() {
	console.log(input); // The properties are available
});

Checking the server

You can test whether the server is running by checking the pointing.pointingIsAvailable variable.

Position of the cursor

Another difference is that getting the position of the mouse cursor is asynchronous (and yes.., everything is asynchronous):

pointing.cursor.getPosition(function(x, y) {
	console.log(x, y);
});