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

FreeBSD Manual Pages

  
 
  

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

NAME
     rendertarget_forceupdate - Manually perform an out-of-loop update of a ren-
     dertarget

SYNOPSIS
     nil
     rendertarget_forceupdate( vid:rendertarget )
     rendertarget_forceupdate( vid:rendertarget, bool:force_dirty=true )
     rendertarget_forceupdate( vid:rendertarget, number:refresh )
     rendertarget_forceupdate( vid:rendertarget, number:refresh, number:readback
     )
     rendertarget_forceupdate(	vid:rendertarget,  number:refresh,  number:read-
     back, bool:allow_hw=false )

DESCRIPTION
     By default, rendertargets update synchronously with the regular  video  re-
     fresh/redraw that is performed as part of the active synchronization strat-
     egy combined with the refreshrate hinted during creation.

     This function covers two use-cases.

     The  first use case is to force an out-of-loop update of the specified tar-
     get in 'manual' update mode (rate=0). By default this will always trigger a
     render pass. If the second argument is set to false, then the  update  will
     only be forced if the pipeline is actually dirty.

     The  second  use  case  is to change the refresh and readback rates for the
     specified rendertarget. This can be used as an optimization to  temporarily
     disable  rendertargets  without going through the process of rebuilding and
     migrating between rendertargets.

     Any pending counters/timers for frame or tick/based automatic updates  will
     be  reset,  and the update includes synchronizing with readback in the case
     of calctargets and recordtargets.

     If allow_hw  is set to true, the readback performed will instead be used to
     share the buffer of the rendertarget with the assigned sink. This has  com-
     plex  effects  on	the underlying graphics stack and may fail. If a failure
     can be detected it will automatically switch back to a  software  only  ap-
     proach (allow_hw=false), but it can also fail without warning.

NOTES
     1	    Trying  to	call  this  function on a VID  that references an object
	    that is not flagged as a rendertarget is a	terminal  state  transi-
	    tion.

     2	    If	a newrate is set, the rendertarget will not be updated directly.
	    If that behaviour is desired, call the function  again  without  the
	    newrate argument.

     3

EXAMPLE
     function rendertarget_forceupdate0()
	   local dst = alloc_surface(320, 200);
	   local a = color_surface(64, 64, 0, 255, 0);
	   show_image(a);
	   rotate_image(a, 45);
	   define_rendertarget(dst, {a});
	   rendertarget_forceupdate(dst);
	   save_screenshot("test.png", FORMAT_PNG, dst);
	   delete_image(dst);
     end

MISUSE
     function rendertarget_forceupdate0()
	   local a = fill_surface(32, 32, 255, 0, 0, 0);
	   rendertarget_forceupdate(a);
     end

SEE ALSO:
     define_rendertarget(3) define_calctarget(3) define_recordtarget(3)

targetcontrol			   August 2026	     rendertarget_forceupdate(3)

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

home | help