GraphicsV
---------

Overlay hardware falls into two basic categories: "Z-Order" and "Basic". Z-Order hardware allows full control of the Z order of the created overlays. Basic hardware offers no control of the Z order, and it's expected that they're placed somewhere between the desktop and the mouse pointer.

Currently the API restricts Z-Order overlays to be placed underneath the desktop. Alpha-blending or transparency colour key (TCK) must be used to mark out the desktop areas through which the overlay(s) should be visible.

Because Basic overlays are ontop of the desktop, care must be taken to hide them when necessary, e.g. if an error message appears which the user must be able to see.

If an overlay supports alpha formats, it's expected that it will be alpha-blended by the hardware. TCK for overlays currently isn't supported (only the desktop should use TCK).

To account for driver restrictions and to allow for more optimal memory management, all overlays for a driver will be destroyed when the driver changes mode.

The new calls described below should only be issued from the foreground.

Across all calls, bits 16-23 of R4 are expected to be used as follows:

VSync                 Head
SetMode               Head
SetInterlace          Head
SetBlank              Head
UpdatePointer         Head
SetDMAAddress         Head
VetMode               Head
DisplayFeatures       Head
FramestoreAddress     Head
WritePaletteEntry     Head/Overlay
WritePaletteEntries   Head/Overlay
ReadPaletteEntry      Head/Overlay
Render                Head
IICOp                 Head
SelectHead            -
StartupMode           Head
PixelFormats          Head
ReadInfo              -    
VetMode2              Head
CreateOverlay         -
DestroyOverlay        Overlay
SetOverlayPosition    Overlay
MapOverlayBuffer      Overlay
UnmapOverlayBuffer    Overlay
DiscardOverlayBuffer  Overlay
VetOverlay            -
SetOverlayTransform   Overlay
SetOverlayZOrder      -

Because some calls accept both a driver number and a head number in bits 16-23, drivers should choose overlay numbers such that they don't overlap the range of head numbers.


GraphicsV_WritePaletteEntry     * 10
GraphicsV_WritePaletteEntries   * 11
GraphicsV_ReadPaletteEntry      * 12

These calls have been extended to recognise a new palette type, type 3, which is used for the transparency colour key. This palette has the following entries:

 Entry 0: TCK value. This is a raw pixel value, rather than a &BBGGRRSS palette entry.
 Entry 1: TCK mask. This indicates which bits of a pixel are significant when the hardware performs the TCK check (e.g. in a 15bpp mode, the top bit of the halfword may be ignored).

Drivers can implement these as read-only values if the values can't be changed. Drivers should ignore the call if TCK isn't in use (e.g. alpha is being used instead).


GraphicsV_ReadInfo              * 18

This call is extended to add a new item, item 5, which is a 32bit int indicating the maximum number of overlays that the driver supports. If this value is zero or the call isn't claimed then it indicates that the driver doesn't support the overlay API.


GraphicsV_CreateOverlay         * 20

In: R0 = Pointer to mode selector describing the required properties of the
         overlay.
    R1 = Aspect ratio to use when calculating returned min/max scale values
         Top 16 bits = width
         Low 16 bits = height
    R2 = Flags:
         bit 0: Overlay must support scaling
         bits 1-31: Reserved, should be zero
    R3 = Mask of which heads the overlay is to be used with
    R4 = reason code + driver number
    
Out: R0 = Overlay number
     R1 = Flags:
          bits 0-7: Overlay type
                    0 = Z-Order
                    1 = Basic
                    2+ = Reserved
          bits 8-31: Reserved
     R2 = Minimum width overlay can be scaled to
     R3 = Minimum height overlay can be scaled to
     R5 = Maximum width overlay can be scaled to
     R6 = Maximum height overlay can be scaled to

Creates a new hardware overlay.

For rotated overlays, the aspect ratio and the returned width & height values correspond to the rotated form of the overlay, i.e. as it will appear on screen.

GraphicsV drivers are not required or expected to support dynamic allocation of buffers - if multiple buffers are desired, the necessary number of buffers must be specified in the mode selector via mode variable 12.


GraphicsV_DestroyOverlay        * 21

In: R4 = reason code + driver number + overlay number

Destroys a hardware overlay.

Specifying an overlay number of zero will destroy all overlays.


GraphicsV_SetOverlayPosition    * 22

In: R0 = Pointer to coordinate array:
         Word 0: Head number
         Word 1: X position
         Word 2: Y position
    R1 = Number of entries in array
    R2 = Bank to display (ignored if R1=0)
    R4 = reason code + driver number + overlay number
    
Displays or hides an overlay. The coordinate space is that of logical screen coordinates, i.e. (0,0) is the top-left corner of the screen from the viewer's perspective (if the screen is rotated, (0,0) is still the top-left). Within that coordinate space, the coordinates specify the top-left corner of the overlay, as it appears on screen (e.g. if the overlay is rotated 180 degrees then it would actually correspond to the bottom-right pixel of the buffer).

The overlay will only appear on the heads which are included in the list. Therefore you can hide the overlay completely by specifying R1=0.


GraphicsV_MapOverlayBuffer      * 23

In: R0 = Bank number
    R4 = reason code + driver number + overlay number
    
Out: R0 = Pointer to array giving buffer addresses:
          Word 0: Plane 0 base logical address
          Word 1: Plane 0 stride between image rows
          Word 2+: logical addresses & strides for any additional planes
     
Maps an overlay bank/buffer into logical address space, potentially allocating the memory for it if the driver hasn't already done so.

If this is a freshly-allocated buffer, the contents are undefined. Otherwise the contents will be preserved.

Drivers may have limited logical address space available for mapping overlays, so in Wimp situations it's recommended to unmap your overlay(s) before allowing the Wimp to swap out your task.

The array returned in R0 will remain valid until the bank is unmapped.


GraphicsV_UnmapOverlayBuffer    * 24

In: R0 = Bank number
    R4 = reason code + driver number + overlay number
    
Unmaps an overlay buffer from the logical address space.


GraphicsV_DiscardOverlayBuffer  * 25

In: R0 = Bank number
    R4 = reason code + driver number + overlay number
    
Discards a buffer, freeing the memory that was allocated to it. If necessary, the buffer will be unmapped first, and if the overlay was currently displaying it then the overlay will be hidden.


GraphicsV_VetOverlay            * 26

In: R0 = Pointer to mode selector, as per GraphicsV_CreateOverlay
    R1 = Aspect ratio to use when calculating returned min/max scale values
         Top 16 bits = width
         Low 16 bits = height
    R2 = Flags:
         bit 0: Overlay must support scaling
         bits 1-31: Reserved, should be zero
    R3 = Mask of which heads the overlay is to be used with
    R4 = reason code + driver number
    
Out: R1 = Flags:
          bits 0-7: Overlay type
                    0 = Z-Order
                    1 = Basic
                    2+ = Reserved
          bits 8-31: Reserved
     R2 = Minimum width overlay can be scaled to
     R3 = Minimum height overlay can be scaled to
     R5 = Maximum width overlay can be scaled to
     R6 = Maximum height overlay can be scaled to

Allows the user to check whether an overlay with the specified properties can be created, and if so, what capabilities it will have. If the overlay can't be supported, the driver should not claim the call.

When vetting the settings, the driver should take into account any restrictions that result from the current system configuration. E.g. if all overlays are currently in use, no Vet call should succeed. Or conversely, if a Vet call succeeds, so too should a corresponding Create call.


GraphicsV_SetOverlayTransform   * 27

In: R0 = Left edge of clipping rectangle (inclusive)
    R1 = Top edge of clipping rectangle (inclusive)
    R2 = Right edge of clipping rectangle (exclusive)
    R3 = Bottom edge of clipping rectangle (exclusive)
    R4 = reason code + driver number + overlay number
    R5 = Scaled width
    R6 = Scaled height
    R7 = Aspect ratio to use if image size needs adjusting
         Top 16 bits = width
         Low 16 bits = height
    
Out: R0 = Actual left edge of clipping rectangle
     R1 = Actual top edge of clipping rectangle
     R2 = Actual right edge of clipping rectangle
     R3 = Actual bottom edge of clipping rectangle
     R5 = Actual scaled width
     R6 = Actual scaled height
     
Adjusts the scale and clipping rectangle for an overlay. R5 and R6 specify the size the overlay should be scaled to (in screen pixels). Then, the clipping rectangle defined by R0-R3 will be used to crop the displayed area. This is also specified in units of screen pixels. For rotated overlays, the values correspond to the rotated form, i.e. as it will appear on screen. Rounding errors or other hardware limits may prevent the chosen values from being used, in which case the driver will make the necessary adjustments (while maintaining the indicated aspect ratio) and return the actual values used.


GraphicsV_SetOverlayZOrder      * 28

In: R0 = Pointer to byte array containing overlay IDs
    R1 = Length of array
    R4 = reason code + driver number
    
Specifies the sorting order for any Z-Order overlays. The first entry in the list corresponds to the frontmost overlay. The effect on the order of any overlays not included in the list is unspecified.
