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_INTERNAL	)
       launch_target(	       string:target,		string:config=default,
       int:mode=LAUNCH_INTERNAL	)
       launch_target( )

DESCRIPTION
       Launch  Target  uses the	database to build an execution environment for
       the specific tuple of target  and config	 and launch a matching	exter-
       nal  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  con-
       tainer,	launch	the config and continue	executing as normal. The call-
       back specified with handler  will be used to receive  events  connected
       with  the  new frameserver, 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
       resource	footprint and wait for the specified program to	finish execut-
       ing. The	return code of the program will	be returned  as	 the  function
       return along with the elapsed time in milliseconds. This	call is	block-
       ing  and	is intended for	suspend/resume and similar situations. It only
       works if	the binary format in the database entry	has also been set  ex-
       plicitly	to EXTERNAL .

       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  re-
       quested 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_updatehan-
       dler  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)
       -> "preroll" (client waiting for	initial	 state	information)  ->  "re-
       sized" (first frame and subsequent resizes) -> [tblents below] -> "ter-
       minated".

       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
       exception being 'frame'.	Events are delivered in	order, but their  syn-
       chronisation  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  verbose  delivery  mode  (  target_flags  ) in order to more
       tightly couple an inbound 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 re-
       quire a tighter timing when events are used to annotate the contents of
       a frame.

       Possible	statustbl.kind values: "preroll", "resized",  "ident",	"core-
       opt", "message",	"failure", "streaminfo"	"frame", "streamstatus", "seg-
       ment_request",	"state_size",  "viewport",  "alert",  "content_state",
       "registered", "clock", "cursor",	 "bchunkstate",	 "proto_update",  "in-
       put_mask", "ramp_update"

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			  April	2025		      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+14.3.quarterly>

home | help