h6. [[OS SWI Calls]] h6(. » [[OS_SpriteOp]] h6((. » OS_SpriteOp 61 - Switch output to mask h2. OS_SpriteOp 61 - Switch output to mask h5. (SWI &2E) |_<^{width:4em}. Entry | | |<^. R0 |<^. 61 (Reason code) + [[OS_SpriteOp|Area value]]| |<^. R1 |<^. Unused/[[Format Of Sprite Area|Sprite area]] (as defined by area value in R0) | |/2<^. R2 |<^. Sprite name/[[Format Of Sprite|pointer]] (as defined by area value in R0) | |<^. Or 0 to switch output to screen | |/4<^. R3 |<^. [[VDU Save Area]]: | |<^. 0: Use no save area (discouraged) | |<^. 1: Use kernel save area | |<^. Otherwise: Pointer to user save area | |_<^{width:4em}. Exit | | |<^. R0-R3 |<^. Required values to restore previous context | |\2<^. All other registers preserved| h4. Use This call can be used to redirect screen output to a sprite mask, or to return output back to the screen. While output is redirected to a sprite, all VDU operations including text output, [[OS_Plot]] operations, and sprite rendering will act on the sprite and not the screen. The [[VDU Variables]] and [[Mode Variable Numbers|Mode Variables]] will also reflect the change. When output is redirected to an alpha mask, [[ColourTrans]] will report a default greyscale palette (black to white gradient). For other types of mask the same logic as [[OS_SpriteOp 60]] is used. In this situation using colour translation functions to determine the pixel values/colours to write to the mask may result in invalid values being stored. If no save area is supplied in R3 or the save area is not yet initialised, the VDU state will be reset to the default for the sprite/screen mode. See [[VDU Save Area]] for more details on the state that save areas store. h4. Notes To redirect screen output to a sprite image, see [[OS_SpriteOp 60]]. You must be careful to restore output back to the screen should an error occur. It's recommended to install environment handlers so that unexpected errors (e.g. data aborts) can be fully accounted for. To restore output back to its previous location, issue OS_SpriteOp with R0-R3 containing the values returned from this call. The low-level [[PaletteV]] API only deals with the screen palette, and so does not adapt itself in any way when screen output is redirected to a sprite. Therefore any PaletteV calls made while output is redirected will manipulate the screen palette and not the sprite palette. Additionally, [[ColourTrans_WritePalette]] will return an error if called when output is redirected. [[Service_SwitchingOutputToSprite]] will be issued by this call. If a call is made to change the screen mode or switch video drivers while screen output is redirected, the output will be restored to the screen. Redirecting output to a sprite without using a save area is strongly discouraged. The reason being that it can cause issues if you either directly or indirectly call a SWI which wants to use redirection internally (e.g. the font manager makes use of redirection to build the font cache). Save areas are small (currently under 512 bytes), so there is little reason to not use them. h4. See also * [[Format Of Sprite]] * [[Format Of Sprite Area]] * [[OS_SpriteOp]] * [[OS_SpriteOp 60]] * [[VDU Save Area]] * [[ColourTrans]] * [[PaletteV]]