1.\" 2.\" Copyright (c) 1999 3.\" Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer as 11.\" the first lines of this file unmodified. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 17.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 18.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 19.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 20.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 21.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 22.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 23.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 25.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd July 09, 2024 28.Dt SPLASH 4 29.Os 30.Sh NAME 31.Nm splash 32.Nd splash screen / screen saver interface 33.Sh SYNOPSIS 34.Cd "device splash" 35.Sh DESCRIPTION 36The 37.Nm 38pseudo device driver adds support for the splash screen and screen 39savers to the kernel. 40This driver is required if the splash bitmap image is to be loaded or 41any screen saver is to be used. 42.Ss Splash screen 43You can load and display an arbitrary bitmap image file as a welcome banner 44on the screen when the system is about to start. 45This image will remain on the screen 46during kernel initialization process 47until the login prompt appears on the screen 48or until a screen saver is loaded and initialized. 49The image will also disappear if you hit any key, 50although this may not work immediately 51if the kernel is still probing devices. 52.Pp 53If you specify the 54.Fl c 55or 56.Fl v 57boot option when loading the kernel, the splash image will not appear. 58However, it 59is still loaded and can be used as a screen saver later: see below. 60.Pp 61In order to display the bitmap, the bitmap file itself and the 62matching splash image decoder module must be loaded by the boot loader. 63Currently the following decoder modules are available: 64.Pp 65.Bl -tag -width splash_decoder -compact 66.It Pa splash_bmp.ko 67Windows BMP file decoder. 68While the BMP file format allows images of various color depths, this 69decoder currently only handles 256 color bitmaps. 70Bitmaps of other color depths will not be displayed. 71.It Pa splash_pcx.ko 72ZSoft PCX decoder. 73This decoder currently only supports version 5 8-bpp single-plane 74images. 75.It Pa splash_txt.ko 76TheDraw binary ASCII drawing file decoder. 77Displays a text-mode 80x25 ASCII drawing, such as that produced by 78the Binary save format in TheDraw. 79This format consists of a sequence 80of two byte pairs representing the 80x25 display, where the first byte 81is the ASCII character to draw and the second byte indicates the 82colors/attributes to use when drawing the character. 83.El 84.Pp 85The 86.Sx EXAMPLES 87section illustrates how to set up the splash screen. 88.Pp 89If the standard VGA video mode is used, 90the size of the bitmap must be 320x200 or less. 91If you enable the VESA mode support in the kernel, 92either by statically linking the VESA module or by loading the VESA module 93(see 94.Xr vga 4 ) , 95you can load bitmaps up to a resolution of 1024x768, depending on the VESA 96BIOS and the amount of video memory on the video card. 97.Ss Screen saver 98The screen saver will activate when the system is considered idle: i.e.\& 99when the user has not typed a key or moved the mouse for a specified period 100of time. 101As the screen saver is an optional module, 102it must be explicitly loaded into memory. 103Currently the following screen saver modules are available: 104.Pp 105.Bl -tag -width splash_module.ko -compact 106.It Pa blank_saver.ko 107This screen saver simply blanks the screen. 108.It Pa beastie_saver.ko 109Animated graphical 110.Bx 111Daemon. 112.It Pa daemon_saver.ko 113Animated 114.Bx 115Daemon screen saver. 116.It Pa dragon_saver.ko 117Draws a random dragon curve. 118.It Pa fade_saver.ko 119The screen will gradually fade away. 120.It Pa fire_saver.ko 121A fire which becomes higher as load increases. 122.It Pa green_saver.ko 123The screen will be blanked, similar to 124.Pa blank_saver.ko . 125If the monitor and the video card's BIOS support it 126the screen will also be powered off. 127.It Pa logo_saver.ko 128Animated graphical 129.Fx 130logo. 131.It Pa plasma_saver.ko 132Draws an animated interference pattern. 133.It Pa rain_saver.ko 134Draws a shower on the screen. 135.It Pa snake_saver.ko 136Draws a snake of string. 137.It Pa star_saver.ko 138Twinkling stars. 139.It Pa warp_saver.ko 140Streaking stars. 141.El 142.Pp 143Screen saver modules can be loaded using 144.Xr kldload 8 : 145.Pp 146.Dl kldload logo_saver 147.Pp 148The timeout value in seconds can be specified as follows: 149.Pp 150.Dl vidcontrol -t N 151.Pp 152Alternatively, you can set the 153.Ar saver 154variable in the 155.Pa /etc/rc.conf 156to the screen saver of your choice and 157the timeout value to the 158.Ar blanktime 159variable so that the screen saver is automatically loaded 160and the timeout value is set when the system starts. 161.Pp 162The screen saver may be instantly activated by hitting the 163.Ar saver 164key: the defaults are 165.Em Shift-Pause 166on the AT enhanced keyboard and 167.Em Shift-Ctrl-NumLock/Pause 168on the AT 84 keyboard. 169You can change the 170.Ar saver 171key by modifying the keymap 172(see 173.Xr kbdcontrol 1 , 174.Xr keymap 5 ) , 175and assign the 176.Ar saver 177function to a key of your preference. 178.Pp 179The screen saver will not run if the screen is not in text mode. 180.Ss Splash screen as a screen saver 181If you load a splash image but do not load a screen saver, 182you can continue using the splash module as a screen saver. 183The screen blanking interval can be specified as described in the 184.Sx Screen saver 185section above. 186.\".Sh DRIVER CONFIGURATION 187.Sh FILES 188.Bl -tag -width /boot/kernel/splash_xxxx.ko -compact 189.It Pa /boot/defaults/loader.conf 190boot loader configuration defaults 191.It Pa /etc/rc.conf 192system configuration information 193.It Pa /boot/kernel/splash_*.ko 194splash image decoder modules 195.It Pa /boot/kernel/*_saver.ko 196screen saver modules 197.It Pa /boot/kernel/vesa.ko 198the VESA support module 199.El 200.Sh EXAMPLES 201In order to load the splash screen or the screen saver, you must 202have the following line in the kernel configuration file. 203.Pp 204.Dl device splash 205.Pp 206Next for 207.Xr syscons 4 , 208edit 209.Pa /boot/loader.conf 210(see 211.Xr loader.conf 5 ) 212and include the following lines: 213.Bd -literal -offset indent 214splash_bmp_load="YES" 215bitmap_load="YES" 216bitmap_name="/boot/chuck.bmp" 217.Ed 218.Pp 219In the above example, the file 220.Pa /boot/chuck.bmp 221is loaded. 222In the following example, the VESA module 223is loaded so that a bitmap file which cannot be displayed in standard 224VGA modes may be shown using one of the VESA video modes. 225.Bd -literal -offset indent 226splash_pcx_load="YES" 227vesa_load="YES" 228bitmap_load="YES" 229bitmap_name="/boot/chuck.pcx" 230.Ed 231.Pp 232If the VESA support is statically linked to the kernel, it is not 233necessary to load the VESA module. 234Just load the bitmap file and the splash decoder module as in the 235first example above. 236.Pp 237To load a binary ASCII drawing and display this while booting, include the 238following into your 239.Pa /boot/loader.conf : 240.Bd -literal -offset indent 241splash_txt_load="YES" 242bitmap_load="YES" 243bitmap_name="/boot/splash.bin" 244.Ed 245.Pp 246For 247.Xr vt 4 , 248edit 249.Pa /boot/loader.conf 250(see 251.Xr loader.conf 5 ) 252and include the following lines: 253.Bd -literal -offset indent 254splash="/boot/images/freebsd-logo-rev.png" 255boot_mute="YES" 256.Ed 257.\".Sh DIAGNOSTICS 258.Sh SEE ALSO 259.Xr vidcontrol 1 , 260.Xr syscons 4 , 261.Xr vga 4 , 262.Xr loader.conf 5 , 263.Xr rc.conf 5 , 264.Xr kldload 8 , 265.Xr kldunload 8 266.Sh HISTORY 267The 268.Nm 269driver first appeared in 270.Fx 3.1 . 271.Sh AUTHORS 272.An -nosplit 273The 274.Nm 275driver and this manual page were written by 276.An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . 277The 278.Pa splash_bmp 279module was written by 280.An Michael Smith Aq Mt msmith@FreeBSD.org 281and 282.An Kazutaka Yokota . 283The 284.Pa splash_pcx 285module was written by 286.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org 287based on the 288.Pa splash_bmp 289code. 290The 291.Pa splash_txt 292module was written by 293.An Antony Mawer Aq Mt antony@mawer.org 294based on the 295.Pa splash_bmp 296code, with some additional inspiration from the 297.Pa daemon_saver 298code. 299The 300.Pa logo_saver , 301.Pa plasma_saver , 302.Pa rain_saver 303and 304.Pa warp_saver 305modules were written by 306.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org . 307.Pa splash 308png support for 309.Xr vt 4 310was written by 311.An Emmanuel Vadot Aq Mt manu@FreeBSD.org . 312.Sh CAVEATS 313The screen saver works with 314.Xr syscons 4 315only. 316.Pp 317For vt splash screen, only RGBA png are supported. 318.Sh BUGS 319If you load a screen saver while another screen saver has already 320been loaded, the first screen saver will not be automatically unloaded 321and will remain in memory, wasting kernel memory space. 322
