Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
launch_target(3)		  Arcan Lua API 		launch_target(3)

NAME
     launch_target - Setup and launch an external program.

SYNOPSIS
     vid:new_vid, aid:new_aid, int:cookie, int:return_code, int:elapsed
     launch_target( string:target )
     launch_target( string:target, string:config=default )
     launch_target( string:target, int:mode=LAUNCH_INTERNAL )
     launch_target( string:target, string:config=default, int:mode )
     launch_target( string:target, string:config=default, int:mode=LAUNCH_INTER-
     NAL )
     launch_target( string:target, string:config=default, int:mode=LAUNCH_INTER-
     NAL )
     launch_target( ... function:handler(source, status) )

DESCRIPTION
     Launch  Target  uses the database to build an execution environment for the
     specific tuple of target  and  config    and  launch  a  matching	external
     client.  The  mode    can	be  set  to either LAUNCH_INTERNAL  (default) or
     LAUNCH_EXTERNAL .

     if ( LAUNCH_INTERNAL ) is set, arcan will set up a  frameserver  container,
     launch  the config and continue executing as normal. The callback specified
     with handler  will be used to receive events connected with the new  frame-
     server, and the returned vid  handle can be used to control and communicate
     with the frameserver. The notes section below covers events related to this
     callback.

     if  (  LAUNCH_EXTERNAL  ) is set, arcan will minimize its execution and re-
     source footprint and wait for the specified program  to  finish  executing.
     The  return  code	of  the  program will be returned as the function return
     along with the elapsed time in milliseconds. This call is blocking  and  is
     intended  for  suspend/resume  and similar situations. It only works if the
     binary format in the database entry has also been set explicitly to  EXTER-
     NAL .

     If  the  target:config tuple does not exist (if config is not specified, it
     will be forced to 'default') or the config does not support  the  requested
     mode, BADID  will be returned.

     Every  argument  combination takes a callback function argument at the end.
     If this is not set, it should be defined through target_updatehandler    or
     there  may  be a terminal state transition on the first event received from
     the target .

     The initial states a client goes through are as follow:  "connected"  (when
     using  target_alloc ) -> "registered" (type information available) -> "pre-
     roll" (client waiting for initial state information)  ->  "resized"  (first
     frame and subsequent resizes) -> [tblents below] -> "terminated".

     Do note that the returned new_vid	has no guaranteed initial size, and will
     be invisible regardless of resize_image  blend_image  calls until the first
     "resized"	event  has  been delivered through the handler . While it can be
     constrained, the client can always initiate resizes within  a  valid  range
     and layout, animations and so on need to be able to adapt.

     Most of the key/values in sttatustbl depend on the kind, with a notable ex-
     ception  being 'frame'. Events are delivered in order, but their synchroni-
     sation to the stream of audio and video frames  may  drift.  To  counteract
     this  there  is a client provided clock. This can be combined with the ver-
     bose delivery mode ( target_flags ) in order to more tightly couple an  in-
     bound  event  with  its visual state at the time. This should rarely matter
     with the main exception being viewport events and custom messages	as  used
     with  protocol  bridges  (e.g.  X11) that may require a tighter timing when
     events are used to annotate the contents of a frame.

     Possible statustbl.kind values: "preroll", "resized",  "ident",  "coreopt",
     "message",  "failure",  "streaminfo"  "frame", "streamstatus", "segment_re-
     quest", "state_size", "viewport", "alert",  "content_state",  "registered",
     "clock",  "cursor",  "bchunkstate", "proto_update", "input_mask", "ramp_up-
     date"

NOTES
     1	    The bridge segments have the quirk that the primary is  used  as  an
	    invisible  segment	allocation factory or to convey debugging / pro-
	    filing data. The 'x11' and 'wayland' has additional expectations  on
	    interpretations  of  'message'  and 'viewport' events and the use of
	    target_anchorhints	to convey feedback  and  window  management  re-
	    strictions	to  accomodate these protocols and incorporate them. The
	    'allocator' one is used for complex UI    toolkit  constraints  that
	    need to allocate resources without a prior intent behind the primary
	    connection.

     2

EXAMPLE
     function launch_target0()
	   local tgts = list_targets();
	   if (#tgts == 0) then
		 return shutdown("no targets found, check database", -1);
	   end
	   return shutdown(string.format("%s returned %d0, tgts[1],
		 launch_target(tgts[1], LAUNCH_EXTERNAL)));
     end

EXAMPLE
     function launch_target1()
	   local tgts = list_targets();
	   if (#tgts == 0) then
		 return shutdown("no targets found, check database", -1);
	   end
	   local img = launch_target(tgts[1], LAUNCH_INTERNAL,
		 function(src, stat)
		       print(src, stat);
		 end
	   );
	   if (valid_vid(img)) then
		 show_image(img);
	   else
		 return shutdown(string.format("internal launch of %s failed.0,
		       tgts[1]), -1);
	   end
     end

MISUSE
     function launch_target0()
	   local tgts = list_targets();
	   if (#tgts == 0) then
		 return shutdown("no targets found, check database", -1);
	   end
	   launch_target("noexist", -1, launch_target);
     end

SEE ALSO:
     target_accept(3) target_alloc(3)

targetcontrol			   August 2026			launch_target(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=launch_target&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help