FreeBSD Manual Pages
map_video_display(3) Arcan Lua API map_video_display(3) NAME map_video_display - Specify virtual object to output mapping. SYNOPSIS bool:success, number:free_layers map_video_display( vid:src, number:display ) map_video_display( vid:src, number:display, number:blithint, num- ber:layer_index ) map_video_display( vid:src, number:display, number:blithint, num- ber:layer_index, number:x, number:y ) DESCRIPTION This functions updates the mapping between a higher level visual object src and an output display . This includes the currently set shader, custom texture coordinates and so on. The optional blithint argument (default: HINT_NONE ) can be one of the following: HINT_FIT , HINT_CROP , HINT_ROTATE_CW_ 90, HINT_ROTATE_CCW_ 90, HINT_YFLIP . It is also pos- sible to OR it with the optional HINT_PRIMARY . FIT and CROP deter- mine the strategy to deal with for the case where the current mode on the display fail to match the storage dimensions of src . YFLIP , RO- TATE_CW_ 90, ROTATE_CCW_ 90 deals with outputs that can have a varying physical rotation and supports accelerated mapping. HINT_PRIMARY tells the platform layer that the synchronisation to the display SHOULD be prioritized in the case of multiple displays. The function returns true if the object was successfully mapped to the display, and false if the underlying platform rejected it for some reason, as not all out- puts can accept all kinds of sources or an arbitrary number of layers. It will also return the maximum number of currently free mapping lay- ers, this is not a guarantee that a certain object can be mapped to a higher layer, the combination need to be tested for the current combi- nation of screens, resolutions and mappings. Providing a layer_index along with an *x* and *y* coordinate allows multiple objects to be mapped to the same logical output and composited accordinly. For layers higher than zero, additional hint flags can be set: HINT_CURSOR - the layer will be treated as a cursor layer and implies alpha blending. This may be updated out of the normal processing pipeline and as part of a raw input handler where other graphics func- tions might be unavailable. There is also an experimental HINT_DIRECT flag that, if set, will dis- able any platform controlled heuristic between direct scanout and forced composition. This is an optimization that has a number of driver and backend bugs still. For normal/simple display configurations it is likely to work, but with edge cases for multi-display hotplug, rotated secondary displays and so on. This is marked experimental, but if the feature is deprecated that flag will simply resolve to 0 so it is API -wise safe for use. The caveats should be conveyed to a user. NOTES 1 A src referencing an object with a feed- function, such as one coming from define_recordtarget , define_calctarget and so on, is a terminal state transition. 2 Multiple output paths with varying performance characteristics may apply here, including forced repacking stages that are very costly. Avoid using custom texture coordinate sets, custom shaders or using the src object as part of other rendering operations to ensure that any fast scanout path can be applied. 3 A rendertarget as src has a different coordinate transform when going from 'as a texture' to 'as an output' behavior and may end up inverted. The engine will attempt to account for this, but only if no custom texture coordinate set has been defined for the object. 4 When calling map_video_display with a rendertarget as src, its projection transform may be rebuilt. This will override any co- ordinate system changes made by image_resize_storage which then needs to be repeated. 5 Mapping the same rendertarget to multiple displays is undefined behaviour. The reason is that the backing store of src might need to mutate to fit the scanout characteristics of display . Even for the same display, these ted to have slight changes that make sharing semantics have subtle edge cases that are hard to predict. The best workaround for this is to create additional rendertargets through define_linktarget . EXAMPLE function map_video_display0() resize_video_canvas(640, 480); img_1 = fill_surface(320, 200, 255, 0, 0); img_2 = fill_surface(320, 200, 0, 255, 0); img_3 = fill_surface(320, 200, 0, 0, 255); img_4 = fill_surface(320, 200, 255, 0, 255); show_image({img_1, img_2, img_3, img_4}); move_image(img_2, 320, 0); move_image(img_3, 0, 200); move_image(img_4, 320, 200); a = null_surface(640, 480); move_image(a, 320, 240, 1000); image_sharestorage(WORLDID, a); outputs = {}; list = video_displaymodes(); uniq = 0; for i,v in ipairs(list) do if (outputs[v.displayid] == nil) then outputs[v.displayid] = v; uniq = uniq + 1; end end if (uniq < 2) then return shutdown("insufficient outputs"); end local first = nil; local second = nil; for k,v in pairs(list) do if (first == nil) then first = k; elseif (second == nil and k ~= first) then second = k; break; end end if (second == nil) then return shutdown("no secondary display output found."); end map_video_display(first, WORLDID); map_video_display(second, next_a); end MISUSE function map_video_display0() map_video_display("random", WORLDID); end SEE ALSO: vidsys April 2025 map_video_display(3)
NAME | SYNOPSIS | DESCRIPTION | NOTES | EXAMPLE | MISUSE | SEE ALSO:
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=map_video_display&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>