Showing changes from revision #3 to #4:
Added | Removed | Changed
The current GraphicsV API specifies that the top byte of R4 is used to specify the display number, with 0 being the ‘default’. However, no methods are defined (or implemented) for enumerating the list of available displays, notifying the system of display addition/removal, etc.
To rectify this, the following changes are proposed:
The primary aim of this change is to provide support for the features of the OMAP3 display subsystem. Thus, the new GraphicsV must support multiple hardware overlays, each with differing restrictions on available buffer formats, and provide the ability for programs to alter the display order of the overlays (where the hardware supports it)
To add support for hardware overlays, the following changes are proposed:
GraphicsV already has some support for this via call 15. However that call only allows one head to be active at once; what’s needed instead is a way of supporing supporting multiple active heads at once.
Proposal:
Most, if not all of the above, is capable of being covered by the settings table described in the Display Capabilities & Configuration section.
Both heads and overlays have ownership states. There are three different states of ownership:
This system allows programs to coexist with the VDU much as they do now. Programs can use the standard OS APIs to change the screen mode, or they can claim ownership of the default head and overlays and set everything manually. If the program exits then the desktop will reclaim the head & overlays for the system, resetting the right WIMP mode. Additionally, the inability of one program to reclaim an overlay that is owned by another allows for the safe implementation of media players and the like where more YUV overlays may be requested than actually exist.
If a program wishes to do more than use the basic OS_ScreenMode interface that exists now, then it must register itself with the system via a new OS_ScreenMode reason code. Upon registration the program will provide a pointer to a callback function that will be called upon certain important events (e.g. the system reclaiming a head or overlay that is owned by the program). Upon registration the program will also provide a list of understood property IDs (see the Display Capabilities & Configuration section); this will allow drivers to make ‘best guess’ choices for configuration values that the program does not provide or understand. In return for the registration request, the system will return to the program a unique ID that allows the system to identify the program. The program uses this ID when it wants to claim or relinquish ownership over resources.
New calls:
Further API details are TBD.
There are many restrictions which govern how the different features of the OMAP3 display controller can be used. For example, the display timings affect the range of supported overlay scales; the colour format affects whether rotation is supported; scaling is only available with certain transparency methods; the colour phase rotation matrix is not available for TV-out; the limited number of transparency modes/overlay display orders places restrictions on the system if you want a YUV overlay to appear ‘under’ the desktop (i.e. so menus/windows and the mouse can appear ontop of it); PLL restrictions mean that the system isn’t capable of generating every pixel rate that lies between the min & max value; it may make sense to restrict configurations that use excessive memory bandwidth (e.g. having three fullscreen 32bpp overlays utilising transparency), to utilise hardware display rotation the driver will have to exert tight control over VRAM assignment, etc. Although creating an API that allows these restrictions (and any others that might apply to other hardware) to be communicated to programs is likely impossible, we can at the least strive for an API that:
As an attempt to satisfy the above criteria, all the configuration values of a driver will be contained within a table. Each column represents an entity within the driver (a head or an overlay), and each row represents a property. The values in the cells represent the configured values within the driver. By passing tables back and forth between programs and drivers, it is possible for programs to safely alter the configuration of the driver, to receive feedback about the driver’s current configuration, and to receive feedback about which configuration values are invalid.
Ordinarily the only rows that will be present in a settings table will be those that the program indicated to the system that it understood upon registration (via OS_ScreenMode X1). How to handle columns (i.e. whether all columns must always be present, or whether they are sometimes omitted) is TBD.
To use these new APIs, programs must first register themselves (see above)
New calls:
ID | Name | Description |
---|---|---|
1 | Enable | For heads, a bool indicating whether the head is enabled. |
For overlays, a bitmask indicating which heads the overlay is enabled on. | ||
2 | Head configuration | An enum indicating the head configuration in use. Each of the possible values is associated with a human-readable string, allowing the user to select the appropriate configuration (e.g. SVideo or Composite for TV-out) |
3 | X, Y | Two signed ints giving the coordinates of the head/overlay within ‘overlayspace’ |
4 | Width, height | Two unsigned ints giving the size of the head/overlay in pixels |
5 | Scaled size | Two signed ints giving the scaled size of the head/overlay in pixels. Zero has the special meaning of 1:1 scaling. Negative values allow for flipping of the image. |
6 | Rotation | Some value indicating the rotation to be applied to the head/overlay. |
7 | Colour phase rotation matrix | A 4×4 matrix that transforms the RGBA values of the head/overlay pixels |
8 | Transparency mode | An enum indicating the transparency mode in use by the head/overlay |
9 | Transparency colour key | Encoded pixel value that is treated as the transparent colour for the transparency colour key transparency method |
10 | Alpha | 0-255 value indicating global alpha of overlay |
11 | YUV matrix | A 4×3 matrix that transforms YUV values to RGB values |
12 | Display timings | A set of mode timings for the head (minus the display size, which is specified |
13 | DMA settings | A set of DMA settings for an overlay. VIDC-style DMA init, base, and limit, along with vduinit (introduced by GraphicsV), and a value describing the number of bytes between each scanline (to allow for non-contiguous buffer formats that are required to make multi-monitor setups easy) |
14 | Overlay ordering | For heads, an enum indicating which overlay ordering is in use. |
For overlays, a notional Z value indicating how the overlays are layered ontop of each other. | ||
(The intention is that each driver will only one of the two ordering methods to be used at a time) | ||
15 | Palette mode | A bool indicating whether the overlay palette is fixed or flexible |
16 | Gamma mode | A bool indicating whether the head/overlay gamma table is fixed or flexible |
17 | Test card display | A bool indicating whether the head should display the built in ‘test card’ image, if any (e.g. TV-out colour bars on OMAP) |
18 | Background colour | A colour value giving the background colour used by the head (when no overlay is visible for a given pixel) |
19 | Border colour | A colour value giving the border colour used by the head |
v1 – 31/1/2010
v2 – 28/3/2010