Skinning Basics

This documentation introduces the basic skinning tools used by the P.I.S.D. Layers. Applications and games are free to use these tools as they wish. Therefore they may not implement all the functionality detailed here. There are specific notes at the end of this document on some individual applications using the P.I.S.D. skinning system.

An image box is a rectangular area of specified size made by combining one or more images. An image box uses a set of image files with matching file names. Image Boxes load a set of 1,3 or 9 images which it then tiles or re sizes to produce the box of the requested size. The file names match the following pattern:

The base name can be anything you like and is used to identify the members of the image box. The image box position identifies where in the box the image belongs. This is dependant on the number of images that make up the set. The system automatically works out which kind of image box to use by the files it finds. Therefore it is important to make sure you have all the images that make up the image box otherwise it will not load. Image file type can be any supported image format such as JPG, PNG. It is recommended to use PNG rather than JPG as a JPG image slightly distorts the image and can create strange effects when the image box is drawn.

This is the best image box to use as it will re size in both directions with little or no distortion. The files required for a 9-way image box are:

In the case of buttons you can specify an image box for each state the button can have. The following image boxes are required to draw this object:

The following image boxes are optional:

For example, if you want to create a set of images for a button when the mouse if hovering over it using a 9-way image box, you need the following images:

You can then repeat the above replacing "over" with "down" to create the images to show a button in the down state (i.e. pushed by the user clicking on it).

The skinning system is built around style sets. Each one details a look that can be applied to any on screen object. They are simple text files allowing you to link to images, set spacing and a selection of other visible settings.

Style sets can work in two different ways, graphical or API mode.

In API mode, the object defined by the style set will use API drawing routines to render the object. These are such tools as draw_line() and draw_rect(). This creates a very fast but rather simple, dated look. You can use the style set to control the colours used to draw the object and a few simple settings.

In graphical mode, image box(s) are used to render the object. This is achieved by setting the "image_filename" field in the style. This is used as the <base_name> field when loading in image boxes. When in graphical mode the API drawing information is not used and can be ignored.

Here are the supported settings for a style set:

In order to define a graphical button using a style set you first need to create the required image box sets for each button state you want. In this example we will create a button using 3-way Horizontal image boxes for the up, down and over button states. We will use a base name of "my_button", but this could be anything we like that identifies this buttons images. So that means we need the following images:

Assuming the above images are in a sub folder named "ibox_images", you would then make the following changes to the style set to tell it which images to use:

Now when this style set is used to skin a button, the images you created above will be used to draw that button.

Grids are often used to display tables of data. It is often hard to read a grid if the background is one uniform tone or colour. There are a number of tools to change the visual appearance of grids to make them easier to see.

ssef_grid_type_cells and ssef_grid_type_lines can make the lines stand out by changing the way the grid draws its background. This is not suitable if you want to round the corners of your grid as it would round each cell or each line respectively.

You can use ssef_grid_two_tone and grid_two_tone_value to darken each alternate line. If you wish to lighten the line you can supply a negative two tone value. This easily adds a subtle line effect that can help the visual impact of a grid.

The last option is only available if it is supported by the application you are skinning. It is possible to supply separate style sets for alternate rows. So all the even numbered rows use one style set and the odd numbered rows use another style set. This gives you the most graphical control, however not all applications support this method.

All there methods above work in conjunction with each other. This allows you to combine the effects to create the desired look..

There are three supported colour formats, RGB, HSL and CMYK. RGB is how the graphics hardware works and therefore is used internally by the system. This means both HSL and CMYK need to be converted which can introduce slight errors. This means you should consider using the RGB format in preference to HSL and CMYK.

The CMYK format is designed around printer hardware, specifying the amount of each coloured ink needed to create the desired colour. This means the RGB and CMYK systems are very different in how they combine colours. For example all colours combined with the CMYK system creates black, but all colours combined with the RGB system creates white. Conversion between these different systems is only approximate as a result, so any colour specified as CMYK is not going to be very accurate.

The skinning system uses a full 8-bit alpha channel which is pre-pended to the three supported colour formats. So RGB becomes ARGB, where the A indicates the alpha value. An alpha channel of zero means the colour is transparent, with an alpha channel of the maximum range being solid.

In order to make things simpler the system understands four different number ranges. They are all the same internally so feel free to use whichever number range you feel most comfortable using.

The core design of the P.I.S.D. Layers aims to remove platform specific knowledge. One of the areas where this is most obvious is disk paths. Each OS has its own way to identify and handle disk drives and devices. For example Microsoft Windows uses driver letters (c:\, d:\, etc) which are not understood on Apple Mac or Linux. The P.I.S.D. Layers handle this by creating a set of useful locations the core of which are relative to the application location. This allows paths to have a sensible meaning on all the platforms supported by the P.I.S.D. Layers. That way a path saved on one platform has a good chance of working on another.

The locations can be considered equivalent to drive specifications. You can append sub-folders using the / character. Do not use a the windows \ character as it is not supported. So to set the path to an installed data file in the sub folder "my-path" you should use "$APPDATA/my-path".

Here are the known folder locations:

The Out Of The Park Baseball skin does not allow the screen layout to be changed. This is deliberate due to the complexity of some of the screens. That said, there is the ability to adjust border sizes and alignment information. The style sets can be found in data/skins/ootp classic/style_sets.

Out Of The Park Baseball currently uses the "two tone" settings for grids (See Grid Style Set section) which darkens every alternate row. It does not support the alternate style set system.

Once you have changed the skinning information you will need to delete the skin cache file data/skins/ootp classic/skin.bin. When you restart the game it will take quiet a bit longer to start as it reads all the skinning information and rebuilds the skin cache. On a Mac it can take a really long time as opening files can be rather slow. Or if you prefer you can select "rebuild skin" option from the game menu.

There are lots more settings and bits you can change. Its is very easy to mess things up so make sure you copy an existing skin and don't change the supplied one so you can always get back in.

If you get stuck then please feel free to email someone@pisd.co.uk for help.