API
This page act as a quick overview of the different parts of the API, and how they are logically grouped together. For exploring and figuring out how/where to use the different functions, look at the Exercises.
For documentation and actual reference as to behavior, arguments and examples, see the .lua files in the doc/ subdirectory of the source repository.
Creating and launching an appl is as simple as creating a folder with a name that fits the pattern [a-Z]+[a-Z0-9_] (e.g. apitest) with a corresponding applname.lua (e.g. apitest/apitest.lua) script file. This file should define, at the least, one function, again with the same name as the folder.
function apitest()
warning("hello world");
endTo implement a handler for various events, simply create functions in the global namespace that matches the pattern applname_eventname, like this (will be very noisy):
function apitest()
warning("apitest");
end
function apitest_adopt(source, kind, parent, last)
warning("recover");
return false;
end
function apitest_clock_pulse()
warning("tick");
end
function apitest_input(iotbl)
warning("input");
end
function apitest_preframe_pulse()
warning("preframe")
end
function apitest_postframe_pulse()
warning("postframe")
end
function apitest_display_state(disp)
warning("display changed");
endthe display state and the adopt entry points are somewhat more complex and used primarily for various corner cases (multiple screens, resolution switching and switching appl while handing over external connections).
The following section covers a brief overview and tabled grouping of most functions exposed in the Lua API. In each group, the functions have been ordered by estimated usefullness (from common / useful to special needs / corner cases).
Most functions require an object identifier (vid- or visual-id) that either come from this group of functions or belong to the reserved constants BADID / WORLDID. The functions are sorted by their estimated usefulness (from common to special cases)
| Name | Notes |
|---|---|
| load_image | Synchronous (blocking) |
| delete_image | |
| load_image_asynch | Provide callback to alert state |
| render_text | Format string controlled |
| null_surface | Never rendered but used as hierarchical anchors etc. |
| fill_surface | |
| color_surface | Will not have an image based backing store |
| alloc_surface | Slightly faster than fill_surface, for offscreen (below) |
| launch_target | Requires a matching database entry (see db functions) |
| target_alloc | Creates external listening endpoints, consumed on use |
| launch_avfeed | Spawn frameserver with a specific archetype / packed arg |
| launch_decode | Convenience version of launch_avfeed |
| raw_surface | Expensive |
| random_surface | High- frequency, non cryptographic, pseudorandom 'noise' |
All newly created objects start out invisible.
Transformations are packed into five groups: translation (move), rotation, scaling (resize), blend and lifecycle. Except for lifecycle, these can be chained in a 'first move to this position in n timesteps then to this other position while rotating 45 degrees in m timesteps' fashion with controllable interpolation at each step.
| Name | Notes |
|---|---|
| blend_image | Special aliases in hide_image, show_image |
| move_image | Absolute position |
| nudge_image | Relative position |
| rotate_image | Degrees, origo at center of object |
| resize_image | Absolute values |
| scale_image | Relative factor |
| expire_image | Timed deletion |
| center_image | Position relative to a source |
| reset_image_transform | Abort all pending |
| crop_image | Crop by modifying texture coordinates |
| instant_image_transform | Perform all pending instantly |
| tag_image_transform | Attach callback trigger currently last group |
| copy_image_transform | Duplicate entire chain |
| transfer_image_transform | Copy + Reset |
Many video object properties are defined relative to a parent, and if none is defined, WORLDID. With relationship- related functions, more complex hierarchies can be established.
| Name | Notes |
|---|---|
| image_sharestorage | Set two objects to share backing store |
| link_image | Reparent an object to another. |
| image_inherit_order | Switch order- property to be relative or absolute |
| image_parent | Get a visual-id to the current parent |
| image_children | Enumerate children to a specific visual-id |
| image_mask_set | Control inheritance by masking a specific property |
| image_mask_clear | Deactivate a specific mask |
| rendertarget_attach, detach | change the attachment related to a rendertarget |
| image_mask_toggle | Flip a specific mask |
| image_mask_clearall | Deactivate all masks |
More advanced image operations for special effects, calculations and state management.
| Name | Notes |
|---|---|
| order_image | Change draw order |
| image_clip_on / _off | Toggle clipped drawing against parent |
| image_texfilter | Change scaling filtering options (none,linear,..) |
| image_set_txcos | Change 4 s,t texture coordinates used for drawing |
| image_set_txcos_default | Reset texture coordinates to default or mirrored |
| image_scale_txcos | Change 4 s,t texture coordinates with a factor |
| force_image_blend | Specify blend-mode rather than letting engine decide |
| image_access_storage | Callback-access individual pixels |
| image_resize_storage | Change dimensions of the underlying backing store |
| image_origo_offset | Change origo used for applying rotate transform |
| persist_image | Flag a visual-id to survive context push/pop |
| image_framecyclemode | Rotate backing store per frame for frameservers |
| resample_image | Use a shader to create an up/downscaled version |
| image_pushasynch | Make an asynch image load synchronous |
| image_tesselation | Subdivide the normal quad into a denser mesh |
Animation in its more primitive forms is simply having a set of state images where the currently displayed one is changed at a set rate.
| Name | Notes |
|---|---|
| image_framesetsize | Allocate secondary frameslots |
| image_transform_cycle | Set an automatic tick/cycle rate |
| image_active_frame | Change the displayed frame for a visual-id |
| set_image_as_frame | Assign source to a frameset slot in a dest |
Most graphics platforms provide some kind of accelerated drawing / effect routines, which one that is in effect can be seen with the constant SHADER_LANGUAGE ( something like GLSL120).
| Name | Notes |
|---|---|
| build_shader | compile a GPU specific program, 'shader' |
| shader_uniform | set / update variable in a shader |
| image_shader | associate a shader with a video object |
| shader_ugroup | derive a net set of uniforms from a shader |
Advanced graphics effects, sharing or GPU assisted computing use off-screen accelerated drawing to a memory buffer that is not mapped to any display. These are treated as secondary drawing pipelines to which existing objects can be reassigned.
| Name | Notes |
|---|---|
| define_rendertarget | offscreen rendertarget to vid- storage |
| define_recordtarget | rendertarget + encode frameserver feed |
| define_calctarget | rendertarget + readback + callback function |
| define_linktarget | rendertarget reusing pipeline |
| define_feedtarget | direct associate with output |
| define_nulltarget | bufferless output target |
| define_arcantarget | create upstream secondary surface |
| rendertarget_forceupdate | immediately process the drawing pipleine of a RT |
| rendertarget_vids | retrieve the current pipeline |
| rendertarget_detach/attach | modify the pipeline |
| rendertarget_reconfigure | modify output properties |
| define_linktarget | rendertarget with a pipeline derived from another |
| rendertarget_forceupdate | immediately process the drawing pipeline of a RT |
| recordtarget_gain | change audio mixing for a source in a recordtarget |
| rendertarget_noclear | save memory bandwidth when a full- clear is not needed |
| rendertarget_reconfigure | reconfigure densities, force reraster of vector assets |
| rendertarget_vids | enumerate vids associated with a rendertarget pipeline |
| rendertarget_id | tag the rendertarget with a uniform accessible id |
| Name | Notes |
|---|---|
| max_current_image_order | Return the highest used order value |
| image_screen_coordinates | Apply transforms and get coordinates in screen space |
| switch_default_scalemode | Change the default scale operation (deprec.) |
| switch_default_texmode | Change the default texturing mode |
| switch_default_imageproc | Change the default image upload processing mode |
| switch_default_texfilter | Change the default scaling filtering mode |
| resize_video_canvas | (Displayctrl), change output render resolution |
| video_displaymodes | (Displayctrl), change device resolution |
| map_video_display | (Displayctrl), change device output source |
| video_3dorder | Process 3D pipeline before or after 2D one |
| video_synchronization | (Displayctrl), change synchronization strategy |
| push_video_context | Save and free current render pipeline |
| pop_video_context | Free current pipeline and restore old |
| storepush_video_context | New context gets a vid with a RTT of the previous one |
| storepop_video_context | Restored context gets vid with RTT of the previous one |
| system_defaultfont | Define the font that \f,0 would resolve to |
| set_context_attachment | Change which rendertarget new objects are attached to |
| video_displaygamma | Access, share or modify display color lookup tables |
Routines for querying / resolving object state. Many of these functions take a time argument in order to resolve future states according to current transformation chains.
| Name | Notes |
|---|---|
| valid_vid | Check if visual-id maps to a valid object |
| image_surface_resolve_properties | Apply transforms and get state |
| image_surface_properties | Return local (non-transformed) state |
| image_storage_properties | Apply backing store information |
| image_storage_slice | Create a sliced store for cubemaps and 3dtextures |
| image_hit | Used for collision detection |
| pick_items | Used for collision selection |
| image_surface_initial_properties | For restoring initial state |
| text_dimensions | For UI component layout without rendering |
| image_matchstorage | Check if two sources has the same backing store |
| image_get_txcos | |
| image_state | Check if rendertarget,3dobj,frameserver,... |
| image_loaded | Check asynch- load state |
| current_context_usage | Chck amount of allocated vids vs allowed |
| image_color | Change the color of a color_surface |
| image_mipmap | Change the mipmapping settings |
Primarily for launching external targets or for keeping user/appl/session specific configuration.
| Name | Notes |
|---|---|
| store_key | save one or multiple kv- pairs to target,config or appl |
| get_key | retrieve a specific kv from a specific domain |
| match_keys | search for matching kv pairs |
| list_targets | list valid targets for launch_target |
| list_target_tags | get sorting/categorisation tags for target |
| target_configurations | list valid configurations for launch_target |
Audio support is still primitive, mostly used for gain control and recording for define_recordtarget. Will change in 0.6-0.7 releases.
| Name | Notes |
|---|---|
| load_asample | Preload a sample and map as an audio source |
| play_audio | Play a preloaded sample |
| delete_audio | Delete a preloaded sample |
| audio_gain | Set playback gain (with possible fade) for an audio source |
| capture_audio | Activate audio capture / playback from a valid input |
| list_audio_inputs | Enumerate currently available inputs |
3D support is rather primitive, intended most for rendering simple models.
| Name | Notes |
|---|---|
| new_3dmodel | Create an empty 3d model contain |
| finalize_3dmodel | Apply static transformations and generate bounding data |
| add_3dmesh | Attach a mesh to a 3d model |
| attrtag_model | Change model drawing flags |
| mesh_shader | Change shader used for model or for individual mesh |
| move3d_model | 3D transforms behave similarly to their 2D counter-parts, |
| rotate3d_model | except they take additional arguments for Z value and |
| orient3d_model | nudge being replaced with forward/strafe based on view |
| scale3d_model | and up vectors. |
| forward3d_model | Move along the view vector |
| strafe3d_model | Move relative to the cross between the view and up vector |
| [ step3d_model | Combine forward and strafe motion |
| camtag_model | Convert a 3d model into a camera |
| build_3dplane | Generate basic meshes |
| build_3dbox | Generate a cube or rectangular box |
| build_cylinder | Generate a cylinder model wit or without endcats |
| build_sphere | Generate a sphere or a hemisphere |
| build_pointcloud | Generate a model based on a number of points |
| scale_3dvertices | apply a destructive transform to all vertices |
| swizzle_model | Flip primitive vertice winding direction |
This class of functions is especially relevant to track or monitor, filtering them out removes most options for dynamic code execution.
| Name | Notes |
|---|---|
| shutdown | Asynch, won't occur immediately |
| system_load | Loads .lua, .so/.dll, ... |
| system_context_size | Change number of allowed visual-ids in new contexts |
| system_collapse | Used for switching appl or merging context stack |
These should be used sparringly, most configuration related data should be managed through the database functions.
| Name | Notes |
|---|---|
| resource | Test if string resolves |
| glob_resource | Scan for a resources matching pattern |
| zap_resource | Delete resource |
| open_nonblock | Create context table for asynch-I/O |
| save_screenshot | Store vid or display contents to file |
| open_rawresource | Global state for pushing short strings to one |
| close_rawresource | synchronous output file. Should be avoided if |
| write_rawresource | at all possible. |
| read_rawresource |
On some limited pointers, there might be faster ways of drawing a mouse cursor than manually mapping it to a vid.
| Name | Notes |
|---|---|
| cursor_setstorage | Assign a vid backing store to the cursor plane |
| cursor_position | Query the current cursor position |
| move_cursor | Reposition the cursor to an absolute X,Y coordinate |
| nudge_cursor | Move the cursor relative to its current position |
| resize_cursor | Change the cursor output dimensions |
Most input management is through the applname_input_event which includes tracking new devices and so on. Scanning mechanism for detecting hotplug etc. is managed in the platform layer, transparent to the appl.
| Name | Notes |
|---|---|
| kbd_repeat | Change desired press- repeat rate for translated devs. |
| toggle_mouse_grab | NOP on some video platforms, cursor device control |
| inputanalog_filter | Change filter core size and analog filter method |
| inputanalog_query | Query for available analog devices |
| inputanalog_toggle | Toggle an analog device on or off |
| utf8kind | Quick and dirty helper for UTF8- testing |
| decode_modifiers |
The led interface is rough and immature, backend is intended to be rewritten as it currently support a very limited set of device types. Will be used for both keyboards, custom mood-leds and display backlight.
| Name | Notes |
|---|---|
| set_led | Toggle a single led on / off |
| led_intensity | Set the brightness level for a single led |
| set_led_rgb | Request a specific color for a single led |
| controller_leds | Get the number of availabe leds on a controller |
| vr_setup | Activate a VR controller session (if available) |
| vr_metadata | Retrieve display metadata from the VR controller |
| vr_map_limb | Associate a VR- related input device with a model |
Networking inteface design is mostly finished, frameserver backend still has some work planned making this set of functions experimental until after 0.6. We are also missing a secure keystore with keyword aliasing.
| Name | Notes |
|---|---|
| net_open | Connect to a server |
| net_push | Send a message, serialize a vid backing store, ... |
| net_accept | Accept an incoming connection |
| net_listen | Listen for incoming connections |
| net_push_srv | Push to one or multiple connected clients |
| net_disconnect | Force disconnect a connected client |
| net_discover | Query local network or index catalog for servers |
| net_authenticate | Send authentication primitives |
| net_accept | Accept authentication or push request |
Used for external process launch and control. Functions marked (E) will queue an event to the in- queue of a connected target or frameserver. Functions marked (D) will push a descriptor or similar handle depending on OS. There is also a rich number of events that are delivered to the associated callback, check shmif event header for details.
| Name | Notes |
|---|---|
| launch_target | Needs an ID from the database functions |
| target_alloc | (ED) Push a subsegment or listen for connection |
| target_input / input_target | (E) Input table must match format of _input_event |
| suspend / resume _target | (E) state control, pause processing / polling |
| message_target | (E) custom short utf-8 message |
| accept_target | Accept a request for a new subsegment |
| pacify_target | Disconnect / Destroy frameserver but keep data. |
| stepframe_target | (E) for synchronous transfer clocks |
| snapshot_target | (E/D) For targets that reported a snapshot size |
| restore_target | (E/D) For targets that support snapshots |
| bond_target | (E/D) Both targets need snapshot and same format |
| reset_target | (E) hint only |
| target_displayhint | (E) hint on desired resolution |
| target_fonthint | (E/D) send font information |
| target_devicehint | (ED) switch accelerated graphics device or connection path |
| target_updatehandler | Replace active callback- function |
| target_framemode | (E) Hint on frame-delivery (synch, skipping) |
| target_verbose | Emit more / detailed events with frame delivery |
| target_seek | (E) Forward / Rewind to point in time (if supported) |
| target_flags | Specialized tuning for engine management |
| target_synchronous | Block/ack each transfer (expensive) |
| target_parent | Get primary segment for subsegment visual-id |
| target_metadata | Retrieve a table with tracking data |
| target_coreopt | (E) Send K/V pair |
| target_graphmode | (E) Deprecated, for changing render modes |
Support functions for getting performance or state data that might assist when troubleshooting some issue.
| Name | Notes |
|---|---|
| image_tracetag | Attach a string to vid |
| warning | Output a colored warning string to terminal |
| system_snapshot | Store .lua parsable state dump |
| system_identstr | String that identifies underlying arcan build |
| benchmark_enable | Toggle data collection |
| benchmark_timestamp | Get system timestamp |
| benchmark_data | Grab/Flush collected data |
| freeze_image | Debug build only, abort() on vid- modification |
The default distribution has a series of support scripts that are stored in the system script path (typically shared/arcan/scripts), reserving the 'builtin' folder for accessing these.
benchmark.lua - used for tests/benchmark
mouse.lua - mouse gesturing
keyboard.lua - translation table for keysyms to characters / labels
composition_surface.lua - crude window manager
hook/input_playback, input_record - used for testing and demonstration