diff options
Diffstat (limited to 'evdev.lua')
| -rw-r--r-- | evdev.lua | 82 |
1 files changed, 75 insertions, 7 deletions
@@ -1,3 +1,6 @@ +--- +--- @module applause +--- local ffi = require "ffi" local C = ffi.C @@ -34,8 +37,35 @@ enum applause_evdev_abs { }; ]] +--- Stream of Evdev (HID device) events. +-- This allows using ordinary keyboards, trackpads, trackpoints, mice etc. as +-- real-time controllers. +-- See also [input-event-codes.h](https://raw.githubusercontent.com/torvalds/linux/master/include/uapi/linux/input-event-codes.h) +-- for useful constants. +-- @type EvdevStream +-- @see MIDIStream EvdevStream = DeriveClass(Stream) +--- Create EvdevStream (stream HID device events). +-- @function new +-- @tparam int|string id +-- Either an integer referring to the device node (`/dev/input/eventX`) or +-- a Lua pattern matched against the device names. +-- The first matching device is used. +-- @bool[opt=true] grab +-- Whether to "grab" the device. +-- A "grabbed" device will get its events delivered exclusively to Applause, +-- so it will not interfer with the operating system +-- (pressed keyboard keys or mouse movement will not cause any trouble). +-- Consequently there can only be one EvdevStream per grabbed device. +-- The device will be "ungrabbed" once the object is garbage collected. +-- @treturn EvdevStream +-- A stream of C structures, describing the event in detail. +-- Its fields will be 0 if no event ocurred. +-- @todo Document the C structure as a Lua table. +-- @see Stream:evrel +-- @see Stream:evabs +-- @see Stream:evkey function EvdevStream:ctor(id, grab) local grab = grab == nil or grab @@ -81,10 +111,22 @@ function EvdevStream:gtick() end end --- Relative devices like some mouses and the trackpoint. --- The coordinate is returned in `resolution` steps between [-1, 1] --- NOTE: `code` is optional (default: REL_X) and you can specify a number (0 or 1) --- or string ('REL_X', 'REL_Y') as well. +--- Filter Evdev event stream to get the last value of a device with relative positioning (EV_REL). +-- This can be used to retrieve the position of mice for instance. +-- The relative movements are automatically converted to absolute positions given a resolution and +-- the stream "holds" the last value. +-- It is usally applied on streams returned by @{EvdevStream:new}. +-- @within Class Stream +-- @tparam[opt='REL_X'] applause_evdev_rel|int|string code +-- This is a C value, integer or string ('REL_X', 'REL_Y'...), specifying the axis to extract. +-- The possible values correspond to the C header `input-event-codes.h`. +-- @number[opt=1000] resolution +-- The device resolution, ie. the number of steps between [-1,1]. +-- The larger this value, the longer it takes to move from the minimum to the maximum position. +-- @treturn Stream Stream of numbers between [-1,1]. +-- @see EvdevStream:new +-- @see Stream:scale +-- @usage EvdevStream("TrackPoint"):evrel():scale(440,880):SinOsc():play() function Stream:evrel(code, resolution) code = ffi.cast("enum applause_evdev_rel", code) resolution = resolution or 1000 @@ -97,7 +139,23 @@ function Stream:evrel(code, resolution) end) / (resolution/2) - 1 end --- FIXME: min and max can be read from the properties of the corresponding code. +--- Filter Evdev event stream to get the last value of a device with absolute positioning (EV_ABS). +-- This can be used to retrieve the position of touchpads for instance. +-- @within Class Stream +-- @tparam[opt='ABS_X'] applause_evdev_abs|int|string code +-- This is a C value, integer or string ('ABS_X', 'ABS_Y'...), specifying the axis to extract. +-- The possible values correspond to the C header `input-event-codes.h`. +-- @int min +-- Minimum value (absolute position). +-- This will currently have to be looked up manually using `evtest`. +-- @int max +-- Maximum value (absolute position). +-- This will currently have to be looked up manually using `evtest`. +-- @treturn Stream Stream of numbers between [-1,1]. +-- @see EvdevStream:new +-- @see Stream:scale +-- @usage EvdevStream("TouchPad"):evabs('ABS_X', 1232, 5712):scale(440,880):SinOsc():play() +-- @fixme min and max can be read from the properties of the corresponding code. -- This would however require us to do all postprocessing already in EvdevStream:gtick() -- or even in applause_evdev_new(). function Stream:evabs(code, min, max) @@ -110,8 +168,18 @@ function Stream:evabs(code, min, max) end) end --- FIXME: We haven't got constants for all KEY_X constants,# --- so you will have to look up the key code in input-event-codes.h. +--- Filter Evdev event stream to get the last key code (EV_KEY). +-- This can be used to turn PC keyboards into controllers. +-- The key code will be generated as long as the key is pressed, +-- otherwise it will be 0. +-- @within Class Stream +-- @int key +-- The key code to extract. +-- This must currently always be an integer, corresponding to the +-- `KEY_X` constants from `input-event-codes.h`. +-- @treturn Stream Stream of key codes or 0 if the key is not currently pressed. +-- @see EvdevStream:new +-- @usage EvdevStream(10):evkey(16):instrument(Stream.SinOsc(440)):play() function Stream:evkey(key) return self:scan(function(last, sample) last = last or 0 |