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_RO- TATE_CW_ 90, HINT_ROTATE_CCW_ 90, HINT_YFLIP . It is also possible to OR it with the optional HINT_PRIMARY . FIT and CROP determine the strategy to deal with for the case where the current mode on the display fail to match the storage dimensions of src . YFLIP , ROTATE_CW_ 90, ROTATE_CCW_ 90 deals with outputs that can have a varying physical rotation and sup- ports accelerated mapping. HINT_PRIMARY tells the platform layer that the synchronisation to the display SHOULD be prioritized in the case of multi- ple 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 outputs can accept all kinds of sources or an arbitrary number of layers. It will also return the maximum number of cur- rently free mapping layers, 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 combination 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 lay- ers higher than zero, additional hint flags can be set: HINT_CURSOR - the layer will be treated as a cursor layer and implies al- pha blending. This may be updated out of the normal processing pipeline and as part of a raw input handler where other graphics functions might be un- available. There is also an experimental HINT_DIRECT flag that, if set, will disable any platform controlled heuristic between direct scanout and forced compo- sition. 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 com- ing 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 go- ing 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 pro- jection transform may be rebuilt. This will override any coordinate system changes made by image_resize_storage which then needs to be repeated. 5 Mapping the same rendertarget to multiple displays is undefined be- haviour. 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 se- mantics 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 August 2026 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+15.1.quarterly>