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.

Setup

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");
end

To 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");
end

the 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).

Common Functions

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).

Creation / Destruction

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.

Transformation

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

Relationships

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

Draw Tuning

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

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

Shaders

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

Offscreen

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

Global Graphics State

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

Properties

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

Database

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

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

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

System and Device Control

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

File / Resource IO

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

Accelerated Cursor

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

Input

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

Special Devices

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

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

Target Control

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

Debugging

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

Support Scripts

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