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

FreeBSD Manual Pages

  
 
  

home | help
define_rendertarget(3)	   Library Functions Manual	define_rendertarget(3)

NAME
       define_rendertarget - Create an offscreen rendering pipe

SYNOPSIS
       bool:status
       define_rendertarget( vid:dst, t_vid:vtbl	)
       define_rendertarget( vid:dst, t_vid:vtbl, int:detach )
       define_rendertarget( vid:dst, t_vid:vtbl, int:detach, int:scale )
       define_rendertarget(   vid:dst,	 t_vid:vtbl,   int:detach,  int:scale,
       int:rate	)
       define_rendertarget(  vid:dst,	t_vid:vtbl,   int:detach,   int:scale,
       int:rate, int:format )
       define_rendertarget( vid:dst, t_vid:vtbl, int:detach, int:scale )
       define_rendertarget( int:rate, int:format, float:hppcm, float:vppcm )

DESCRIPTION
       This function creates a separate	rendering pipeline that	sends its out-
       put to the storage of another vid- connected object. The	 preconditions
       is  that	 the dst  is not part of the integer-indexed vtbl  and that it
       has a textured backing store.  alloc_surface  is	 a  particularly  good
       function	 for creating a	surface	that can be used as a valid dst	. This
       is an expensive yet powerful function that is the basis	for  many  ad-
       vanced effects, but also	for offscreen composition and both synchronous
       and asynchronous	GPU -> CPU  transfers.

       The optional detach  argument can be set	to either RENDERTARGET_DETACH
       or RENDERTARGET_NODETACH	, and the default is RENDERTARGET_DETACH . For
       RENDERTARGET_DETACH , all members of vtbl  are  disconnected  from  the
       main pipeline and only used when	updating dst , while their association
       is kept in RENDERTARGET_NODETACH	.

       The optional scale  argument determine how the various  output-relative
       properties  e.g.	 object	 size  should be handled in the	case that dst
       does not	have the same dimensions as the	current	canvas.	The default is
       RENDERTARGET_NOSCALE    where the object	would simply be	clipped	if its
       final positions fall outside the	dimensions of the dst .	For RENDERTAR-
       GET_SCALE , a scale transform that maps coordinates in the current can-
       vas dimensions to those of the dst .

       The optional rate  argument determine how often the rendertarget	should
       be  updated.  A	value  of  0 disables automatic	updates	and rendertar-
       get_forceupdate needs to	be called manually whenever  the  rendertarget
       is to be	updated. A value of INT_MIN  < n < 0 means that	the rendertar-
       get should only be updated every	n video	frames,	and a value of INT_MAX
	 > n > 0 means that the	contents should	be updated very	n logic	ticks.
       Default is -1 (every frame).

       The optional format  defines additional flags for the backing store  of
       dst  .  Possible	 values	 are RENDERTARGET_COLOR	 (default), RENDERTAR-
       GET_DEPTH , RENDERTARGET_FULL  and the additional bitfields  RENDERTAR-
       GET_MULTISAMPLE	and RENDERTARGET_ALPHA . The difference	between	COLOR
       and FULL	 is that a stencil buffer (for certain clipping	operations) is
       not  always present in COLOR .  DEPTH  is a special case	primarily used
       when only the contents of the depth buffer is to	be used.  This	opera-
       tion  converts  the  backing  store from	having a textured backing to a
       DEPTH  one and makes a lot of other  operations	invalid.  Its  primary
       purpose	is  depth-buffer  based	3D effects (e.g. shadow	mapping). Note
       that you	can control the	format of the output through alloc_surface .

       MULTISAMPLE  is a bitflag that can be set (bit.bor) for when  you  need
       higher  quality	rendering/anti-aliasing	 and comes at a	high cost when
       the rendertarget	is updated both	from the process itself	 and  from  an
       additional  internal sampling of	the multisample	buffer into the	datas-
       tore pointed to by dst .	It is also likely to break if you are  running
       on weak/old hardware on a GLES 2	level of acceleration.

       ALPHA   is another bitflag that can be set in order for the alpha chan-
       nel contents to be kept rather than resolved.

NOTES
       1      Using the	same object or backing store for dst  and as a	member
	      of vtbl  results in undefined contents in	dst .

       2

	      RENDERTARGET_SCALE    transform  factors are not updated when/if
	      the default canvas is resized.

       3

	      WORLDID  can not be immediately used as part of the *vid table*,
	      but it is	possible to use	image_sharestorage  to a null_surface
	      and then use that	as part	of *vid	table*.	 The  two  caveats  in
	      that  case  is  that the contents	of the null_surface  will have
	      its Y axis inverted and if the new rendertarget  is  visible  in
	      the WORLDID , the	contents will quickly converge to an undefined
	      state from the resulting feedback	loop.

EXAMPLE
       function	define_rendertarget0()
	     local a = color_surface(64, 64, 0,	255, 0);
	     local rtgt	= alloc_surface(320, 200);
	     define_rendertarget(rtgt, {a});
	     show_image({rtgt, a});
	     move_image(rtgt, 100, 100,	100);
	     move_image(rtgt, 0, 0, 100);
	     image_transform_cycle(rtgt, true);
       end

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

Arcan Lua API			September 2022		define_rendertarget(3)

NAME | SYNOPSIS | DESCRIPTION | NOTES | EXAMPLE | SEE ALSO:

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=define_rendertarget&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help