NAME

Arcan - Scripting Overview

SYNOPSIS

There is little work involved in getting an application (short, appl) up and running in Arcan. Simply create a directory with a qualifying name matching ([a-Z]1[a-Z,0-9]* along with 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, look at 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: kind : touch devid, subid, pressure, size, x, y

kind : analog source, devid, subid, active, relative, samples

kind : digital, translated = true number, keysym, modifiers, devid, subid, utf8, active, device, subdevice

kind : digital, translated = false source, devid, subid, active

kind : 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()

This 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 be used to 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()

This entrypoint will be 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

load_image(3) load_image_asynch(3) image_loaded(3) delete_image(3) show_image(3) hide_image(3) move_image(3) nudge_image(3) rotate_image(3) scale_image(3) resize_image(3) resample_image(3) blend_image(3) crop_image(3) persist_image(3) image_parent(3) center_image(3) image_children(3) order_image(3) max_current_image_order(3) link_image(3) relink_image(3) set_image_as_frame(3) image_framesetsize(3) image_framecyclemode(3) image_pushasynch(3) image_active_frame(3) image_origo_offset(3) image_inherit_order(3) image_tesselation(3) expire_image(3) reset_image_transform(3) instant_image_transform(3) tag_image_transform(3) image_transform_cycle(3) copy_image_transform(3) transfer_image_transform(3) copy_surface_properties(3) image_set_txcos(3) image_get_txcos(3) image_set_txcos_default(3) image_texfilter(3) image_scale_txcos(3) image_clip_on(3) image_clip_off(3) image_mask_toggle(3) image_mask_set(3) image_screen_coordinates(3) image_mask_clear(3) image_tracetag(3) image_mask_clearall(3) image_shader(3) image_state(3) image_access_storage(3) image_resize_storage(3) image_metadata(3) image_sharestorage(3) image_matchstorage(3) cursor_setstorage(3) cursor_position(3) move_cursor(3) nudge_cursor(3) resize_cursor(3) image_color(3) image_mipmap(3) fill_surface(3) alloc_surface(3) raw_surface(3) color_surface(3) null_surface(3) image_surface_properties(3) image_storage_properties(3) image_storage_slice(3) render_text(3) text_surface(3) text_dimensions(3) random_surface(3) force_image_blend(3) image_hit(3) pick_items(3) image_surface_initial_properties(3) image_surface_resolve_properties(3) image_surface_resolve(3) image_surface_initial(3)

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>