Bjorn Stahl edited this page Jan 21, 2018 · 3 revisions

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. Currently, these are:

     benchmark.lua - used for tests/benchmark
     mouse.lua - mouse gesturing
     symtable.lua - translation table for keysyms to characters / labels
     composition_surface.lua - crude window manager
     hook/input_playback, input_record - used for testing and demonstration
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.