From 7fc0f17fb37326c86a83627b856a5b75f522c090 Mon Sep 17 00:00:00 2001 From: Robin Haberkorn Date: Wed, 13 Sep 2023 17:26:53 +0300 Subject: added LDoc documentation * gives a useful overview of everything supported right now * especially the type documentation is useful, as these things are not self-evident in Lua (because of dynamic typing). * The LDoc page can later be published as the Github pages of the project. This can even be done automatically by a Github action. However, we should first make sure that it's okay to publish the project before defending the thesis since Github pages will always be public even for private repositories. * Documentation of command-line parameters is lacking (TODO). * It may be possible to use types like "Stream(number)" to describe streams of numbers. The LDoc documentation mentions boxed types. Perhaps there can even be Streamable(number)? * We are also lacking good example programs and/or introductory material. --- evdev.lua | 82 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 75 insertions(+), 7 deletions(-) (limited to 'evdev.lua') diff --git a/evdev.lua b/evdev.lua index dcf5a57..4eba28c 100644 --- a/evdev.lua +++ b/evdev.lua @@ -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 -- cgit v1.2.3