target_input(3)

📦
version 0.7.1 · 2 versions
, in nixos 26.05

💅 target_input(3) — the Arcan Lua API, bestie edition ✨

okay so this is target_input, straight out of the Arcan Lua API — she's a little function with a big job and honestly? iconic. 🎀

✨ NAME ✨

target_input — basically "hey, forward this input data to a frameserver for me" 🫶

🌸 SYNOPSIS 🌸

resbool
target_input( tgtvid, inputtbl )

💖 DESCRIPTION 💖

okay so here's the vibe: this function takes a properly formatted inputtbl and repackages it into an event structure, which then gets added to the event queue of the frameserver specified by tgtvid. that's it, that's the whole plot. 💅

she returns true if and only if the event was properly formatted and could be successfully added to the incoming event queue of the frameserver. no cap — both conditions, or you get nothing. 😤

so a properly formatted table has these fields:

universal: (devid, subid, kind) — and the optional gang: (pts, gesture, label).

  • devid and subid exist to distinguish between different devices and subaxes or buttons ✨
  • kind tells you the type of the input, and lowkey it decides how the whole table gets interpreted
  • pts is the optional, implementation-defined relative 64-bit timestamp in milisecond resolution ⏱️
  • gesture is an optional boolean flag — it indicates whether the event is a result from abstract gesture analysis or not, and it alters the client interpretation of label 👀

🦋 if gesture is set

then the contents of label should match one of these, exactly:

 'touch', 'dbltouch', 'click', 'dblclick', 'drag', 'swipe',
 'fling', 'press', 'release', 'drag', 'drop', 'openpinch', 'closepinch',
 'rotate'

(yes 'drag' is in there twice — we don't make the rules, we just report them faithfully 💀)

🌈 if gesture is not set/true

then the contents of label should match a previously frameserver-provided labelhint, or — in the context of a game — the more abstract ' PLAYER n _BUTTON m' or ' PLAYER n _AXIS m'. 🎮

💅 if kind is touch

the required additional fields are:

  • pressure (0..1, linear scale)
  • size (px)
  • x (px)
  • y (px)

🎧 if kind is analog

the required additional fields are:

  • relative (true/false)
  • samples (indexed table of up to 4 int16_t ranged values)

these values are all the same for generic analog sources, such as game device axes. 🕹️

still in analog land, the possible additional fields are:

  • mouse (true/false) — indicates whether the samples come from a cursor-type device or not. if so, the interpretation of sample values is more complicated, because there's a large variability in how underlying device layers provide their samples 😭

and here's the tea on ordering:

  • if relative is set to true, the order is (rel_x, abs_x, rel_y, abs_y)
  • otherwise the order is (abs_x, rel_x, rel_y, abs_y)

the reason for this is that the relative indicator shows the primary origin of the samples, while the other is a result of some state estimator and can therefore be less accurate. all permutations of relative, absolute, two samples or four samples need to be accounted for 🫠

you can also indicate that the input device is no longer active on the segment by setting the leave field to true. this is important for clients that have explicit enter/leave semantics per device — typically bridges to other windowing systems. 🌉

🔥 if kind is digital

the required additional fields are:

  • active (true/false) — whether the button is in a pressed state or not

and the possible additional fields are:

  • translated (true/false)

and if translated is set, the required additional fields are:

  • keysym (value should match the SDL 1.2 table of symnames)
  • modifiers (16 bit bitfield)
  • *utf8* (single unicode character as utf-8)
  • number (undescript field, typically used to carry on device or OS specific code)

👁️ if kind is eyes

the required additional fields are, deep breath:

  • blink_left, blink_right (true/false) — if the eye lids are closed or not
  • gaze_x1, gaze_y1 (float) — screen coordinates for first gaze point
  • gaze_x2, gaze_y2 (float) — screen coordinates for second gaze point
  • present (true/false) — if the user is by the screen or not
  • head_x, head_y, head_z (float) — head position relative to the tracker
  • head_rx, head_ry, head_rz (float) — euler-angle for head

(eye tracking in a manpage, we love to see it 🧚)

⭐ NOTES ⭐

  1. instead of preparing these tables manually, it's recommended to inplace modify those you get from the applname_input event handler 🙈
  2. arguments are flexible — a table argument will be used as the input table, a number argument will be used as the frameserver vid reference ✨
  3. the kind field can also be supplied as a bool, to cut down on costly string compares — by using the kind type (analog, digital, touch) as a boolean key set to true. and the same applies to (translated, mouse). efficiency queen 👑
  4. mouse events do not necessarily translate into an event on the event-queue — the engine may choose to use a memory mapped interface. this depends on the devid (0 for accelerated cursor). 👀
⚠️ note note note: mouse events can vanish into a memory mapped interface instead of the event queue, and that devid is the thing that decides. don't come for me, it's literally what it says.

🫶 SEE ALSO 🫶

and that's the page, bestie! 💜 this lil' gem is brought to you by the targetcontrol source, rocking an October 2026 date — so go forth, forward that input, and slay ✨🎀🌈

📦 where this page comes from