FreeBSD Manual Pages
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 April 2025 define_rendertarget(3)
NAME | SYNOPSIS | DESCRIPTION | NOTES | EXAMPLE | SEE ALSO:
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=define_rendertarget&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>