category: Specification <div id="toc_heading"></div><div id="toc"></div> h2. Goals For many years RISC OS has been running on platforms where either the base hardware supports attaching more than one monitor or, through the addition of expansion cards can do so (eg. the Iyonix PC). However, the operating system is unaware that this is the case and believes it is only ever plotting into a single screen being shown on a single monitor. This proposal identifies a number of places where changes will be needed to add Multiple Display support, both at the lower driver level, presenting these displays for configuration, and defining user interface conventions so that applications can make effective use of extra screen space. h2. Existing documentation h3. Relevant specifications h3. Relevant forum threads "Proposed GraphicsV enhancements":/forum/forums/3/topics/309 h2. Terminology A *driver* is software, usually in a module, which presents heads and overlays to the rest of the operating system. A *screen* is the logical framestore into which images are painted. A *head* is the output of a graphics adapter (there are one or more of these per driver). An *overlay* is a graphics plane in memory which is mixed with the default plane with the desktop on (there may be zero or more of these per head output). A *connection* is the point where a monitor joins the head (a head may have more than one connection, for example different shaped sockets). A *display* is the monitor or panel where the image is ultimately shown. [[Hierarchy-1.png|Graphics hierarchy:pic]] h2. Detail h3. Kernel awareness h3. GraphicsV extensions h4. Overview Update GraphicsV and other OS components to allow a driver to have multiple heads active at once. h4. Proposed changes All existing GraphicsV calls will be updated to accept a head number in bits 16-23 of R4, with the exception of [[GraphicsV 15]] (select head), which will become obsolete. Additionally, some new calls are needed: h5. GraphicsV DriverFeatures A call to read the number of available heads, and any other driver-global features. h5. GraphicsV HeadFeatures A call to read the features of an individual head. In particular, it's expected that it will need to return a bitmask indicating which other heads cannot be active at the same time as this head. For example, the Pandora TV-out cable offers S-Video and Composite as two separate connectors (and therefore separate heads from the user's perspective), but it's impossible to use both at once. This call should also return a localised string containing the name of the head, suitable for display to the user, e.g. in the display manager. A head ID suitable for use in configuration files may also be desirable, however it's expected that simply using the head number will be sufficient (as the head numbers should remain stable, at least until the user swaps the video card for another) h5. GraphicsV ClaimOS The OS will issue this call when it begins to use a head for the VDU driver. The driver should use this call as a hint that it should give this head preferential treatment over other heads, e.g. ensuring a hardware cursor overlay is available. h5. GraphicsV ReleaseOS The counterpart to ClaimOS, this call will be issued when the OS stops using a head. h5. Programmatic description of physical display arrangement Each display may be arranged in an imaginary grid, surrounded by up to 8 other displays. [[RelativePositions-1.png|Display grid positions:pic]] For any reference display (the central one in this image) its position relative to its neighbours requires a table of 8x16 bit values for Top/Middle/Bottom, Left/Centre/Right. This allows for a theoretical 32 heads per driver, and up to 256 drivers, and the special value -1 to denote that there is no display in that space. h5. Other changes Similar to with multiple driver support, consideration will be needed for how the default selection is stored in CMOS. As most machines will be able to support multiple heads out of the box, display detection support will be required in order to ensure the OS picks the right head on startup. h4. Potential future enhancements Once multiple head support is implemented it's worth considering implementing a Geminus-style app to allow for multiple monitor use within the desktop. There are, broadly speaking, four ways of providing multiple monitor support, each with differing level of implementation complexity: # For drivers which are flexible in terms of their memory allocation (NVidia, OMAP) it should be possible to specify a memory layout where two or more framebuffers are placed side-by-side to create one framebuffer at the physical memory level. The OS will see this conjoined framebuffer, while the driver(s) will see two framebuffers with large stride values (specified using the 'extra bytes' [[VIDC control list|control list item]]. However this technique will only work if the same pixel format is available across all heads. It's expected that this approach would be implemented by creating a GraphicsV driver which acts as a man in the middle, so that the OS only directly talks to one driver but that driver organises things with the other two. # For drivers with inflexible memory, allocate the driver framebuffers as normal, but restrict the line length to a multiple of the page size. Then utilise the MMU to create a conjoined logical mapping of the two buffers. This will require the driver to have greater control over memory management than is currently possible, so the "improved memory management" task will need implementing first. As above, this approach is expected to be implemented in the form of a man-in-the-middle GraphicsV driver, and is also subject to the pixel format limitations. # For other situations, implement a GraphicsV driver which allocates its own framebuffer from ordinary RAM, marks it as read-only, and uses an abort handler to trap writes. Then at regular intervals copy the contents of any changed pages to the buffers which are managed by the real drivers. This approach will allow any size or configuration of screen geometry to be used, and can also allow for transformation between different pixel formats (within reason - the driver would probably want to ensure the hardware isn't using a lower colour depth than the user requested). However performance will be worse than the other approaches. Dealing with monitors in the arrangement that have differing resolutions, therefore there are 'holes' in the combined display. h3. ScreenModes support h3. User interface h4. Concept of a preferred/primary head h4. The Window Manager h4. The Toolbox h4. Screen setup plug-in The display manager and screen setup plugin will need updating to allow selection of the head to use. Rather than end up with two new drop downs (one for driver, one for head) it'll probably make sense to combine them into one list. h4. Display Manager The display manager and screen setup plugin will need updating to allow selection of the head to use. Rather than end up with two new drop downs (one for driver, one for head) it'll probably make sense to combine them into one list. h2. Implementation progress table(bordered). |_<. Phase |_=. Status |_=. Completion |_<. Latest updates | |<. Conceptual design |=. In progress |=. 20% |<. 05-Feb-2021 Document updated (see history)<br>23-Jun-2021 Document updated (see history) | |<. Mock ups/visualisation |=. - |=. - |<. - | |<. Prototype coding |=. - |=. - |<. - | |<. Final implementation |=. - |=. - |<. - | |<. Testing/integration |=. - |=. - |<. - | h2. Document history v1.00 - 05-Feb-2021 * Outline added v1.01 - 23-Jun-2021 * Link to relevant external references