[apple/xnu.git] / osfmk / console / panic_ui / README

Creating a Panic UI image (either the default or loadable)

The key steps are: create an indexed image using the MacOS X system
8 clut, saved in QuickTime uncompressed 256 color format. Run it
through the genimage tool to create a C structure or a kernel
loadable file.  This code all has byte dependencies in it, therefore
this all must be done on a PowerPC machine.


===== Create the image 

Using an application like Photoshop, create an image to be used as the image 
displayed at panic time. Your selection of colors is limited to those found in
the MacOS X system 8 clut; in the application you're using, make sure you are
in "indexed mode" and that the supplied CLUT (appleClut8.act) has been selected. 

* The appleClut8.act is the default Mac OS X CLUT.

Keep in mind the following.

* There must be at least 20 lines at the bottom of the image reserved.  This is
used by the system for displaying extra panic information.  There can be more than
20 lines, but you'll have to provide this information when generating the image for
the kernel.

* You must determine the colors used by the font for displaying the panic information.
There are forground and background colors.  The default foreground is "100% White".
It is represented by a 24-bit value of 0xFFFFFF.  The default background is
"13% White, or Dark Gray".  It is represented by a 24-bit value of 0x222222. To change
the defaults, you'll have to provide this information when generating the image for
the kernel.

Save the completed image as a TIFF (still indexed off the CLUT).


===== Convert the TIFF indexed image to QuickTime RAW

Using the Preview application from 10.3.x, open the TIFF image. Use
File:Export to save the TIFF image in QuickTime image format with
options of "None" for compression and "256 Colors" for the depth.
Quality should be "Best".  The saved results should be a .qtif
formatted RAW image.


===== Generate an image for the kernel.

To generate the default kernel panic image file "panic_image.c", in your working
directory, build the program genimage:
cc -o genimage genimage.c

execute:

genimage -i <your .qtif image> -n <lines> -fg <24-bit color> -bg <24-bit color> 
** options other than -i are optional.

To genertate a kernel loadable panic image file, build the qtif2kraw binary:
cc -o qtif2kraw qtif2kraw.c

execute:

qtif2kraw -i <your .qtif image> -o <your .kraw file> -n <lines> -fg <24-bit color> -bg <24-bit color> 
** options other than -i and -o are optional.


===== Other Info

The reason an 8-bit image was choosen, was because it is easy to convert to 24 or 16 bit colors.
The system does not typically run in 8-bit mode.  If the system is in 8-bit mode.  Then we have
to check to see if the active CLUT is the same as the one that the image was created with.  If the
CLUTs are different.  The image is converted to grayscale and the nearest matching gray in the active
CLUT is used.
Commit	Line	Data
91447636 A	1	Creating a Panic UI image (either the default or loadable)
91447636 A	2
b0d623f7 A	3	The key steps are: create an indexed image using the MacOS X system
	4	8 clut, saved in QuickTime uncompressed 256 color format. Run it
	5	through the genimage tool to create a C structure or a kernel
	6	loadable file. This code all has byte dependencies in it, therefore
	7	this all must be done on a PowerPC machine.
91447636 A	8
	9
	10	===== Create the image
	11
	12	Using an application like Photoshop, create an image to be used as the image
	13	displayed at panic time. Your selection of colors is limited to those found in
	14	the MacOS X system 8 clut; in the application you're using, make sure you are
	15	in "indexed mode" and that the supplied CLUT (appleClut8.act) has been selected.
	16
	17	* The appleClut8.act is the default Mac OS X CLUT.
	18
	19	Keep in mind the following.
	20
	21	* There must be at least 20 lines at the bottom of the image reserved. This is
	22	used by the system for displaying extra panic information. There can be more than
	23	20 lines, but you'll have to provide this information when generating the image for
	24	the kernel.
	25
	26	* You must determine the colors used by the font for displaying the panic information.
	27	There are forground and background colors. The default foreground is "100% White".
	28	It is represented by a 24-bit value of 0xFFFFFF. The default background is
	29	"13% White, or Dark Gray". It is represented by a 24-bit value of 0x222222. To change
	30	the defaults, you'll have to provide this information when generating the image for
	31	the kernel.
	32
	33	Save the completed image as a TIFF (still indexed off the CLUT).
	34
	35
	36	===== Convert the TIFF indexed image to QuickTime RAW
	37
b0d623f7 A	38	Using the Preview application from 10.3.x, open the TIFF image. Use
	39	File:Export to save the TIFF image in QuickTime image format with
	40	options of "None" for compression and "256 Colors" for the depth.
	41	Quality should be "Best". The saved results should be a .qtif
91447636 A	42	formatted RAW image.
	43
	44
	45	===== Generate an image for the kernel.
	46
	47	To generate the default kernel panic image file "panic_image.c", in your working
b0d623f7 A	48	directory, build the program genimage:
	49	cc -o genimage genimage.c
	50
	51	execute:
91447636 A	52
	53	genimage -i <your .qtif image> -n <lines> -fg <24-bit color> -bg <24-bit color>
	54	** options other than -i are optional.
	55
b0d623f7 A	56	To genertate a kernel loadable panic image file, build the qtif2kraw binary:
	57	cc -o qtif2kraw qtif2kraw.c
	58
	59	execute:
91447636 A	60
	61	qtif2kraw -i <your .qtif image> -o <your .kraw file> -n <lines> -fg <24-bit color> -bg <24-bit color>
	62	** options other than -i and -o are optional.
	63
	64
	65
	66	===== Other Info
	67
	68	The reason an 8-bit image was choosen, was because it is easy to convert to 24 or 16 bit colors.
	69	The system does not typically run in 8-bit mode. If the system is in 8-bit mode. Then we have
	70	to check to see if the active CLUT is the same as the one that the image was created with. If the
	71	CLUTs are different. The image is converted to grayscale and the nearest matching gray in the active
	72	CLUT is used.
	73
	74