xref: /freebsd/share/man/man4/splash.4 (revision aa0a1e58f0189b0fde359a8bda032887e72057fa)
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.\" $FreeBSD$
28.\"
29.Dd November 29, 2010
30.Dt SPLASH 4
31.Os
32.Sh NAME
33.Nm splash
34.Nd splash screen / screen saver interface
35.Sh SYNOPSIS
36.Cd "device splash"
37.Sh DESCRIPTION
38The
39.Nm
40pseudo device driver adds support for the splash screen and screen
41savers to the kernel.
42This driver is required if the splash bitmap image is to be loaded or
43any screen saver is to be used.
44.Ss Splash screen
45You can load and display an arbitrary bitmap image file as a welcome banner
46on the screen when the system is about to start.
47This image will remain on the screen
48during kernel initialization process
49until the login prompt appears on the screen
50or until a screen saver is loaded and initialized.
51The image will also disappear if you hit any key,
52although this may not work immediately
53if the kernel is still probing devices.
54.Pp
55If you specify the
56.Fl c
57or
58.Fl v
59boot option when loading the kernel, the splash image will not appear.
60However, it
61is still loaded and can be used as a screen saver later: see below.
62.Pp
63In order to display the bitmap, the bitmap file itself and the
64matching splash image decoder module must be loaded by the boot loader.
65Currently the following decoder modules are available:
66.Pp
67.Bl -tag -width splash_decoder -compact
68.It Pa splash_bmp.ko
69W*ndows BMP file decoder.
70While the BMP file format allows images of various color depths, this
71decoder currently only handles 256 color bitmaps.
72Bitmaps of other color depths will not be displayed.
73.It Pa splash_pcx.ko
74ZSoft PCX decoder.
75This decoder currently only supports version 5 8-bpp single-plane
76images.
77.El
78.Pp
79The
80.Sx EXAMPLES
81section illustrates how to set up the splash screen.
82.Pp
83If the standard VGA video mode is used,
84the size of the bitmap must be 320x200 or less.
85If you enable the VESA mode support in the kernel,
86either by statically linking the VESA module or by loading the VESA module
87(see
88.Xr vga 4 ) ,
89you can load bitmaps up to a resolution of 1024x768, depending on the VESA
90BIOS and the amount of video memory on the video card.
91.Ss Screen saver
92The screen saver will activate when the system is considered idle: i.e.\&
93when the user has not typed a key or moved the mouse for a specified period
94of time.
95As the screen saver is an optional module,
96it must be explicitly loaded into memory.
97Currently the following screen saver modules are available:
98.Pp
99.Bl -tag -width splash_module.ko -compact
100.It Pa blank_saver.ko
101This screen saver simply blanks the screen.
102.It Pa beastie_saver.ko
103Animated graphical
104.Bx
105Daemon.
106.It Pa daemon_saver.ko
107Animated
108.Bx
109Daemon screen saver.
110.It Pa dragon_saver.ko
111Draws a random dragon curve.
112.It Pa fade_saver.ko
113The screen will gradually fade away.
114.It Pa fire_saver.ko
115A fire which becomes higher as load increases.
116.It Pa green_saver.ko
117The screen will be blanked, similar to
118.Pa blank_saver.ko .
119If the monitor and the video card's BIOS support it
120the screen will also be powered off.
121.It Pa logo_saver.ko
122Animated graphical
123.Fx
124logo.
125.It Pa rain_saver.ko
126Draws a shower on the screen.
127.It Pa snake_saver.ko
128Draws a snake of string.
129.It Pa star_saver.ko
130Twinkling stars.
131.It Pa warp_saver.ko
132Streaking stars.
133.El
134.Pp
135Screen saver modules can be loaded using
136.Xr kldload 8 :
137.Pp
138.Dl kldload logo_saver
139.Pp
140The timeout value in seconds can be specified as follows:
141.Pp
142.Dl vidcontrol -t N
143.Pp
144Alternatively, you can set the
145.Ar saver
146variable in the
147.Pa /etc/rc.conf
148to the screen saver of your choice and
149the timeout value to the
150.Ar blanktime
151variable so that the screen saver is automatically loaded
152and the timeout value is set when the system starts.
153.Pp
154The screen saver may be instantly activated by hitting the
155.Ar saver
156key: the defaults are
157.Em Shift-Pause
158on the AT enhanced keyboard and
159.Em Shift-Ctrl-NumLock/Pause
160on the AT 84 keyboard.
161You can change the
162.Ar saver
163key by modifying the keymap
164(see
165.Xr kbdcontrol 1 ,
166.Xr keymap 5 ) ,
167and assign the
168.Ar saver
169function to a key of your preference.
170.Pp
171The screen saver will not run if the screen is not in text mode.
172.Ss Splash screen as a screen saver
173If you load a splash image but do not load a screen saver,
174you can continue using the splash module as a screen saver.
175The screen blanking interval can be specified as described in the
176.Sx Screen saver
177section above.
178.\".Sh DRIVER CONFIGURATION
179.Sh FILES
180.Bl -tag -width /boot/kernel/splash_xxxx.ko -compact
181.It Pa /boot/defaults/loader.conf
182boot loader configuration defaults
183.It Pa /etc/rc.conf
184system configuration information
185.It Pa /boot/kernel/splash_*.ko
186splash image decoder modules
187.It Pa /boot/kernel/*_saver.ko
188screen saver modules
189.It Pa /boot/kernel/vesa.ko
190the VESA support module
191.El
192.Sh EXAMPLES
193In order to load the splash screen or the screen saver, you must
194have the following line in the kernel configuration file.
195.Pp
196.Dl device splash
197.Pp
198Next, edit
199.Pa /boot/loader.conf
200(see
201.Xr loader.conf 5 )
202and include the following lines:
203.Bd -literal -offset indent
204splash_bmp_load="YES"
205bitmap_load="YES"
206bitmap_name="/boot/chuck.bmp"
207.Ed
208.Pp
209In the above example, the file
210.Pa /boot/chuck.bmp
211is loaded.
212In the following example, the VESA module
213is loaded so that a bitmap file which cannot be displayed in standard
214VGA modes may be shown using one of the VESA video modes.
215.Bd -literal -offset indent
216splash_pcx_load="YES"
217vesa_load="YES"
218bitmap_load="YES"
219bitmap_name="/boot/chuck.pcx"
220.Ed
221.Pp
222If the VESA support is statically linked to the kernel, it is not
223necessary to load the VESA module.
224Just load the bitmap file and the splash decoder module as in the
225first example above.
226.\".Sh DIAGNOSTICS
227.Sh SEE ALSO
228.Xr vidcontrol 1 ,
229.Xr syscons 4 ,
230.Xr vga 4 ,
231.Xr loader.conf 5 ,
232.Xr rc.conf 5 ,
233.Xr kldload 8 ,
234.Xr kldunload 8
235.Sh HISTORY
236The
237.Nm
238driver first appeared in
239.Fx 3.1 .
240.Sh AUTHORS
241.An -nosplit
242The
243.Nm
244driver and this manual page were written by
245.An Kazutaka Yokota Aq yokota@FreeBSD.org .
246The
247.Pa splash_bmp
248module was written by
249.An Michael Smith Aq msmith@FreeBSD.org
250and
251.An Kazutaka Yokota .
252The
253.Pa splash_pcx
254module was written by
255.An Dag-Erling Sm\(/orgrav Aq des@FreeBSD.org
256based on the
257.Pa splash_bmp
258code.
259.Sh CAVEATS
260Both the splash screen and the screen saver work with
261.Xr syscons 4
262only.
263.Sh BUGS
264If you load a screen saver while another screen saver has already
265been loaded, the first screen saver will not be automatically unloaded
266and will remain in memory, wasting kernel memory space.
267