VideoOverlay
------------

The GraphicsV overlay API is a low-level interface that should not be used directly by programs. Instead, programs should use the higher-level SWI-based interface that is exposed by the VideoOverlay module. The module is functional, but incomplete. Once completed its full set of duties are expected to include:

* Rendering (or coordinating the rendering) of alpha/TCK sections to allow Z-order overlays to be visible
* Associating overlays with Wimp windows/tasks
  * Allows Z-order to be automatically updated
  * Ensures overlay is destroyed if task exits or window is destroyed
* Notifying programs of when their overlays have been lost
* The public API doesn't use GraphicsV overlay IDs directly; instead a different ID system will be used, to prevent a program which has lots its overlay due to a mode change from accidentally interacting with an overlay that belongs to a different program
* Dealing with some of the complexities of Basic overlays
* Software emulation of overlays
* Allowing screen output to be redirected to an overlay

With the overlay ID system that VideoOverlay uses, zero is a suitable value for programs to use as an invalid overlay ID.

Since generic hardware overlays aren't a critical system component, it's expected that the VideoOverlay module will be disc-based rather than ROM-based. Thus programs which expect to use it should attempt to RMLoad it from !System, in the usual manner.


VideoOverlay_Create (SWI &59cc0)

In: R0 = Pointer to mode selector (as per GraphicsV_CreateOverlay)
    R1 = Aspect ratio to use when calculating returned min/max scale values (as per GraphicsV_CreateOverlay)
    R2 = Flags (as per GraphicsV_CreateOverlay)
    R3 = Task handle

Out: R0 = Overlay ID
     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
     R4 = Maximum width overlay can be scaled to
     R5 = Maximum height overlay can be scaled to

Creates a new overlay associated with the indicated Wimp task. If the task exits, the overlay will be automatically destroyed. For the overlay to become visible, it must be attached to a window via VideoOveray_SetWindow.


VideoOverlay_Destroy (SWI &59cc1)

In: R0 = Overlay ID

Destroys the given overlay.


VideoOverlay_DisplayBuffer (SWI &59cc2)

In: R0 = Overlay ID
    R1 = Buffer number

Switches which buffer is being displayed by the overlay. A negative buffer number will hide the overlay. It is important to call this every time you have a new frame to display (even if the buffer number remains the same) - if software rendering is in use then VideoOverlay will use this as an indicator that the overlay needs redrawing.


VideoOverlay_MapBuffer (SWI &59cc3)

In: R0 = Overlay ID
    R1 = Buffer 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

As per GraphicsV_MapOverlayBuffer.


VideoOverlay_UnmapBuffer (SWI &59cc4)

In: R0 = Overlay ID
    R1 = Buffer number
    
As per GraphicsV_UnmapOverlayBuffer.


VideoOverlay_DiscardBuffer (SWI &59cc5)

In: R0 = Overlay ID
    R1 = Buffer number
    
As per GraphicsV_DiscardOverlayBuffer.


VideoOverlay_Vet (SWI &59cc6)

In: R0 = Pointer to mode selector (as per GraphicsV_VetOverlay)
    R1 = Aspect ratio to use when calculating returned min/max scale values (as per GraphicsV_CreateOverlay)
    R2 = Flags (as per GraphicsV_VetOverlay)

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
     R4 = Maximum width overlay can be scaled to
     R5 = Maximum height overlay can be scaled to

As per GraphicsV_VetOverlay.


VideoOverlay_SetScale (SWI &59cc7)

In: R0 = Overlay ID
    R1 = Width
    R2 = Height
    R3 = Aspect ratio to use if image size needs adjusting
         Top 16 bits = width
         Low 16 bits = height

Out: R1 = Actual width
     R2 = Actual height

Adjusts the scale of the overlay.


VideoOverlay_SetWindow (SWI &59cc8)

In: R0 = Overlay ID
    R1 = Window handle
    
Associates the overlay with a window. For the overlay to be displayed correctly the owner of the window must call VideoOverlay_RedrawWindow for every redraw rectangle associated with that window. For Basic overlays, the owner must also be aware that any icons or other graphics which are rendered ontop of the overlay will not be visible. Windows can appear ontop of Basic overlays, but will cause VideoOverlay to fall back to software rendering for some or all of the overlay, adversely affecting performance.

Note that the window does not need to belong to the task that the overlay is associated with.


VideoOverlay_SetPosition (SWI &59cc9)

In: R0 = Overlay ID
    R1 = X offset
    R2 = Y offset
    R3-R6 = Clipping rectangle

Adjusts the position and clipping rectangle of the overlay within the window. These coordinates are specified in window coordinates. The X/Y offset indicates the position of the top-left corner of the overlay, from the user's perspective, prior to any clipping.


VideoOverlay_RedrawWindow (SWI &59cca)

In: R0 = Overlay ID
    R1 = Pointer to block from Wimp_RedrawWindow / Wimp_GetRectangle

The owner of the window which an overlay is attached to must call this SWI for every redraw rectangle associated with the window. Taking into account the current clipping rectangle set by VideoOverlay_SetPosition, VideoOverlay will fill the corresponding screen pixels with the correct colour in order to allow the alpha blending / TCK hardware to operate correctly. For overlays which are composited directly into the framebuffer (e.g. software fallback for Basic overlays), this will trigger the rendering to take place.

Whenever necessary, VideoOverlay will automatically call Wimp_ForceRedraw in order to request that relevant areas of the window are redrawn.
