arcan_api_overview(1)

📦 version 0.7.1, in nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

Okay so this is arcan_api_overview(1) — the Developer API Reference for Arcan, and the vibe is Scripting Overview. Bestie, it's iconic. 💖

✨ SYNOPSIS ✨

Getting an application (short, appl) up and running in Arcan is lowkey barely any work. You just create a directory with a qualifying name matching ([a-Z]1[a-Z,0-9]* and put a similarly named my_applname.lua file inside. The following section list the entry points that the engine will look for, when appropriate — replace xxx with the qualifying name of your appl. 🫶

To speed things along, check the wiki on arcan-fe.com and work through the exercises corresponding to the ability level that you want to achieve. ✨

🎀 Entry Points 🎀

  • xxx() — invoked as soon as audio/video/event/database subsystems are active. 💅
  • xxx_clock_pulse() — invoked every logical clock-pulse on a default monotonic clock at 25Hz unless clock_pulse_batch is set, then it takes precedence. The CLOCK global provides the current global clock value. ⏰
  • xxx_clock_pulse_batch(nticks, count) — alternate form to _clock_pulse that handles congestion (> 1 ticks) by providing them in one single go. 🌀
  • xxx_input(evtbl) — invoked every time an input device emits a valid output sample; this varies with user activity and filter configuration. Evtbl contains a number of fields: 🎮
    • when kind is touch: devid, subid, pressure, size, x, y
    • when kind is analog: source, devid, subid, active, relative, samples
    • when kind is digital and translated = true: number, keysym, modifiers, devid, subid, utf8, active, device, subdevice
    • when kind is digital and translated = false: source, devid, subid, active
    • when kind is eyes: blink_left, blink_right, gaze_x1, gaze_y1, gaze_x2, gaze_y2, present, head_x, head_y, head_z, head_rx, head_ry, head_rz
  • xxx_input_end() — signifies that the current input buffer is empty. This can be used as an input optimization trigger to accumulate input events before processing them forward. 🧺
  • xxx_input_raw() — behaves like an advanced complement to xxx_input. By implementing it, the application signals that it can handle out of loop input events. This can reduce input latency in cases where events arrive while GPUs are locked for scanout. The contract is that if this function is present, you cannot call any part of the API that would modify GPU related state. The safe option is to restrict handling to patching and forwarding input to an external client. If the input was consumed, return true. Otherwise the input will be re-injected when the GPUs have been unlocked. 🔥
  • xxx_adopt(vid, kind, title, parent, last) — invoked as part of system_collapse, script crash recovery fallback or on --pipe-stdin. Implies that there already exists a frameserver connection that can be adopted. Last indicates whethere there are more to come, and parent if there's a subsegment-parent relation. Return true if the connection can be imported into the current script, otherwise it will be destroyed automatically. 🫶
  • xxx_preframe_pulse() xxx_postframe_pulse() — invoked right before and after synchronized transfer of a video frame; this may occur at rather spurious intervals depending on engine configuration and active synchronization strategy. Any computation in this entrypoint should be considered costly, and it is mainly provided for monitoring purpsoes. 👀
  • xxx_adopt(vid, segid, title, parent, last) — invoked when an application is set to collapse with transfers or when recovering from a scripting error. It is used to allow the new script to retrieve externally bound vids. Return true if the VID was adopted; otherwise it will be automatically deleted. 🦋
  • xxx_display_state(action, id, state) — invoked when there has been a change in the output display configuration state, typically in response to hotplug events. 🖥️
  • xxx_fatal(msg) — invoked on a scripting error that is fatal, as a final means of saving state and conveying a message. The returned string will be attached to crash dump output. 💀
  • xxx_shutdown() — triggered as a final state before the arcan process will exit. The most reasonable use for this entrypoint is terminating network connections with protocols that work better when clients are cooperating, but also for saving configuration through the database (e.g. store_key). 👑

🧃 resource 🧃

resource(3), glob_resource(3), list_namespaces(3), zap_resource(3), open_nonblock(3), open_rawresource(3), close_rawresource(3), write_rawresource(3), read_rawresource(3), save_screenshot(3). 💾

🎯 targetcontrol 🎯

launch_target(3), target_alloc(3), target_input(3), input_target(3), suspend_target(3), resume_target(3), message_target(3), accept_target(3), pacify_target(3), stepframe_target(3), snapshot_target(3), restore_target(3), bond_target(3), reset_target(3), focus_target(3), target_portconfig(3), target_framemode(3), target_verbose(3), target_synchronous(3), target_flags(3), target_graphmode(3), target_anchorhint(3), target_displayhint(3), target_devicehint(3), target_fonthint(3), target_geohint(3), target_seek(3), target_parent(3), target_coreopt(3), target_updatehandler(3), arcantarget_hint(3), define_rendertarget(3), define_linktarget(3), define_recordtarget(3), define_calctarget(3), define_feedtarget(3), define_nulltarget(3), define_arcantarget(3), rendertarget_forceupdate(3), rendertarget_vids(3), recordtarget_gain(3), rendertarget_detach(3), rendertarget_bind(3), rendertarget_attach(3), rendertarget_noclear(3), rendertarget_id(3), rendertarget_range(3), rendertarget_metrics(3), rendertarget_reconfigure(3), launch_decode(3), launch_avfeed(3). 🌈

🗄️ database 🗄️

store_key(3), get_key(3), get_keys(3), match_keys(3), list_targets(3), list_target_tags(3), target_configurations(3). 🔐

🎧 audio 🎧

play_audio(3), delete_audio(3), load_asample(3), audio_gain(3), audio_buffer_size(3), audio_position(3), audio_outputs(3), audio_listener(3), audio_reconfigure(3), capture_audio(3), list_audio_inputs(3). 🎶

🖼️ image 🖼️

🧊 3d 🧊

new_3dmodel(3), finalize_3dmodel(3), add_3dmesh(3), attrtag_model(3), move3d_model(3), rotate3d_model(3), orient3d_model(3), scale3d_model(3), forward3d_model(3), strafe3d_model(3), step3d_model(3), camtag_model(3), build_3dplane(3), build_3dbox(3), build_sphere(3), build_cylinder(3), build_pointcloud(3), scale_3dvertices(3), swizzle_model(3), mesh_shader(3). 🧚

⚙️ system ⚙️

shutdown(3), warning(3), system_load(3), system_context_size(3), system_snapshot(3), system_collapse(3), subsystem_reset(3), utf8kind(3), decode_modifiers(3), benchmark_enable(3), benchmark_tracedata(3), benchmark_timestamp(3), benchmark_data(3), appl_arguments(3), system_identstr(3), system_defaultfont(3), frameserver_debugstall(3). 🛠️

🕹️ iodev 🕹️

kbd_repeat(3), toggle_mouse_grab(3), input_capabilities(3), input_samplebase(3), input_remap_translation(3), set_led(3), led_intensity(3), set_led_rgb(3), controller_leds(3), vr_setup(3), vr_map_limb(3), vr_metadata(3), inputanalog_filter(3), inputanalog_query(3), inputanalog_toggle(3). 🎮

📺 vidsys 📺

switch_default_scalemode(3), switch_default_texmode(3), switch_default_imageproc(3), switch_default_texfilter(3), switch_default_blendmode(3), set_context_attachment(3), resize_video_canvas(3), video_displaymodes(3), video_displaydescr(3), video_displaygamma(3), map_video_display(3), video_display_state(3), video_3dorder(3), build_shader(3), delete_shader(3), valid_vid(3), video_synchronization(3), shader_uniform(3), shader_ugroup(3), push_video_context(3), storepush_video_context(3), storepop_video_context(3), pop_video_context(3), current_context_usage(3). 🖥️

🌐 network 🌐

net_open(3), net_discover(3), net_listen(3). 📡

💫 SEE-ALSO 💫

arcan(1). 👀

🌟 AUTHOR 🌟

Bjorn Stahl <contact at arcan-fe dot com>. 💌

Okay bye bestie — this page is from arcan, dated August 2014, and it's the arcan_api_overview(1) manual. Slay and stay iconic. 💖✨

📦 where this page comes from