h6. [[Programmer's Reference Manuals]] h6(. » [[Vectors]] h6((. » [[Software Vector Numbers]] h6(((. » GraphicsV h2. Graphics Vector (42) |_<^{width:3em}. Entry |<^. | |/3<^. R4|<^. Bits 0-15: "Reason Code":#reason| |<^. Bits 16-23: Head or overlay number | |<^. Bits 24-31: Driver number | |\2<^. Other registers dependent on call| h4. Use This vector is used by the RISC OS 5 kernel to communicate with the video driver. User software should always aim to use the appropriate OS SWI instead of calling GraphicsV directly. The information presented here is mainly of use to OS maintainers and video driver developers. R4 is used by all GraphicsV calls to store both the reason code and to indicate whether the call has been claimed (i.e. acted upon by a driver). When a driver claims a call, it will set R4 to zero. By checking R4 after calling GraphicsV it is possible to determine whether the driver supports that call or not. h4(#reason). Reason Codes |_<^{width:3em}. # |<^. |_<^. R4 bits 16-23 |_\2<^. Context[1] | |<^. 0|<^. Null reason code for when vector has been claimed | |<^. 1|<^. [[GraphicsV 1|VSync interrupt occurred]]| Head | BG | SVC/IRQ | |<^. 2|<^. [[GraphicsV 2|Set mode]]| Head | FG[2] | SVC | |<^. 3|<^. Obsolete[3] (was [[GraphicsV 3|Set interlace]])| Head | FG | SVC | |<^. 4|<^. [[GraphicsV 4|Set blank]]| Head | FG/BG | SVC | |<^. 5|<^. [[GraphicsV 5|Update pointer]]| Head | FG/BG | SVC/IRQ | |<^. 6|<^. [[GraphicsV 6|Set DAG]]| Head | FG/BG | SVC/IRQ | |<^. 7|<^. [[GraphicsV 7|Vet mode]]| Head | FG | SVC | |<^. 8|<^. [[GraphicsV 8|Features]]| Head | FG | SVC | |<^. 9|<^. [[GraphicsV 9|Framestore information]]| Head | FG | SVC | |<^. 10|<^. [[GraphicsV 10|Write palette entry]]| Head/Overlay | FG/BG | SVC/IRQ | |<^. 11|<^. [[GraphicsV 11|Write palette entries]]| Head/Overlay | FG/BG | SVC/IRQ | |<^. 12|<^. [[GraphicsV 12|Read palette entry]]| Head/Overlay | FG | SVC | |<^. 13|<^. [[GraphicsV 13|Render]]| Head | FG | SVC | |<^. 14|<^. [[GraphicsV 14|IIC op]]| Head | FG | SVC | |<^. 15|<^. [[GraphicsV 15|Select head]]| - | FG | SVC | |<^. 16|<^. [[GraphicsV 16|Select startup mode]]| Head | FG | SVC | |<^. 17|<^. [[GraphicsV 17|List pixel formats]]| Head | FG | SVC | |<^. 18|<^. [[GraphicsV 18|Read info]]| - | FG | SVC | |<^. 19|<^. [[GraphicsV 19|Vet mode 2]]| Head | FG | SVC | |<^. 20|<^. [[GraphicsV 20|Create overlay]]| - | FG | SVC | |<^. 21|<^. [[GraphicsV 21|Destroy overlay]]| Overlay | FG | SVC | |<^. 22|<^. [[GraphicsV 22|Set overlay position]]| Overlay | FG | SVC | |<^. 23|<^. [[GraphicsV 23|Map overlay buffer]]| Overlay | FG | SVC | |<^. 24|<^. [[GraphicsV 24|Unmap overlay buffer]]| Overlay | FG | SVC | |<^. 25|<^. [[GraphicsV 25|Discard overlay buffer]]| Overlay | FG | SVC | |<^. 26|<^. [[GraphicsV 26|Vet overlay]]| - | FG | SVC | |<^. 27|<^. [[GraphicsV 27|Set overlay transform]]| Overlay | FG | SVC | |<^. 28|<^. [[GraphicsV 28|Set overlay Z order]]| - | FG | SVC | h6. Controlling sources: "Hdr:GraphicsV":https://gitlab.riscosopen.org/RiscOS/Sources/Programmer/HdrSrc/-/blob/master/hdr/GraphicsV managed by the "allocations manager":/content/allocate h4. Notes h5. Driver registration and deregistration GraphicsV based video drivers should perform the following sequence of events on startup: # Call [[OS_ScreenMode 64]] to request a driver number # Store the number, for use by their GraphicsV handler # Call [[OS_Claim]] to install their GraphicsV handler # Start generating [[GraphicsV 1|VSync calls]] if possible # Perform any other initialisation that's required to prepare the driver/hardware # Call [[OS_ScreenMode 65]] to let the OS know that the driver is ready for use Once [[OS_ScreenMode 65]] is called, the driver should expect to start receiving GraphicsV calls from the OS and from other software. Before that point no calls should be received, and if they are then it's a bug in someone else's code and not yours. On shutdown, drivers should use the following sequence: # Call [[OS_ScreenMode 66]] to indicate that the driver is stopping. Once this call returns, the driver should no longer receive GraphicsV calls. # Halt generation of VSync calls # Call [[OS_Release]] to release the GraphicsV handler # Call [[OS_ScreenMode 67]] to release the driver number and allow it to be allocated for use by other drivers. Note that OS_ScreenMode reasons 64-67 must only be called from the foreground. See also [[HAL Video API]] for details on how the OS translates GraphicsV calls to HAL calls for systems which contain a video driver in their HAL. fn1. *Calling contexts* GraphicsV drivers can be called under a variety of different situations. Consult the table above, and the list below, to determine the situations in which each entry point may be called and how the implementation is allowed to behave. * FG - These calls must only be made from the foreground, with interrupts enabled. E.g. usermode applications, callbacks, or RTSupport threads. Calls marked "BG" or "FG/BG" may be called while a foreground call is in progress, but no other foreground calls should occur. Foreground calls are allowed to block for long periods of time, and are allowed to enable/disable interrupts at will. * BG - These calls must only be made from the background, i.e. from within an interrupt handler. The implementation must execute quickly and in a non-blocking manner. On entry, interrupt state is undefined. Drivers may disable interrupts as required, but should not enable them if they were disabled on entry. The implementation must also be fully re-entrant, as the same (or a different) background call may be made while the first is in progress. * FG/BG - These calls may be made from the foreground or the background. The same execution rules as background calls apply - the implementation must be fast, non-blocking, must not enable interrupts if they were disabled on entry, and must be re-entrant with other driver calls. * SVC - Vector handlers are only entered in SVC mode. * SVC/IRQ - The kernel may call these entries from SVC or IRQ mode. Therefore, care must be taken to preserve R14_svc around any SWI calls. fn2. *GraphicsV 2* As an addition to the above rules, drivers are free to ignore any background calls they receive while they are in the middle of processing a mode change. fn3. *GraphicsV 3* This call is obsolete. Interlace settings should be specified via the VIDC list given to GraphicsV 2/7. h4. See also * [[Software Vector Numbers]] * [[OS_ScreenMode]] * [[HAL Video API]] h5. Other languages documentation [[GraphicsV (français)|Français]]