Serious Sam TEX Converter

Help for version 1 - viewing and converting textures from Serious Sam 1, 2 and 3. Works on Windows and Linux.

1. Introduction contents

1.1 What the program does

The Serious Sam TEX Converter opens the texture files (.tex) of the Serious Sam games, shows them, and saves them in common image formats such as TGA, PNG, PCX, BMP, TIFF, JPG, DDS and HDR. It also works the other way round: any of those images can be saved as a Serious Sam 1 texture, so you can use textures from later games in Serious Sam 1 or make new ones.

Besides converting, the program can adjust an image (Levels, Auto levels, Resize, channels, normal maps), convert many files at once (Batch conversion) and handle complete skyboxes.

The original file is never changed. All edits stay in memory until you save, and every edit can be undone.

1.2 Supported games and files

Textures can be opened from a normal folder or straight from a .gro archive. Ordinary images (TGA, PNG, PCX, BMP, TIFF, JPG, DDS, HDR) can be opened too.

2. Using the program contents

2.1 The main window

The loaded image is shown in the middle. Transparent parts show the background chosen in Preferences; by default a gray-and-white checkerboard. Very small images (smaller than 256 pixels on both sides) are enlarged by a whole number so the pixels stay sharp; the status bar then says Enlarged 4x for visibility. The saved file is never enlarged.

The title bar shows the file name. A * after the name means there are edits that have not been saved yet.

The status bar has three fields:

1. the file name;
2. the size in pixels and the kind of texture, for example 1024 x 512 SS3, HDR opaque (32-bit, RGBE) or 256 x 256 RGBA (with transparency), SS1 version 4;
3. extra information: what an edit did, what an effect texture shows, or Saved: name.

The window position and size are remembered for the next start (can be switched off in Preferences).

2.2 Opening files

Choose File > Open (Ctrl+O). The file chooser starts in the folder where you last opened something. You can choose:

• Serious Sam textures (.tex) from all three engines - the program recognizes the engine and version by itself;
• ordinary images: .tga .png .pcx .bmp .tif .jpg .dds .hdr.

If the current image has unsaved edits, the program first asks whether they may be discarded.

You can also open a file by dragging it onto the program icon, or by passing it on the command line. If you ticked Open .tex files with Serious Sam TEX Converter during installation, a double-click on a .tex file opens it directly.

2.3 Opening textures from a .gro archive

Serious Sam stores its files in .gro archives (these are ordinary zip files with another extension). Choose File > Open from .gro archive (Ctrl+G), pick the archive, and a list of all .tex files in it appears. Type part of a name in the search field to filter the list, then double-click a texture or choose it and click OK. The archive itself is not changed.

2.4 Save and Save As

Save As (Shift+Ctrl+S) asks for a file name and format. The program suggests:

• the name of the original file without extension, plus a short suffix for edits (for example _levels, _alpha, _NM);
• the folder where you last saved (or, when chosen in Preferences, the folder of the source file; textures from a .gro are never suggested next to the archive);
• the default format from Preferences (TGA unless you changed it, because Serious Editor reads TGA).

You do not have to type an extension: the program adds the extension of the format chosen in the list.

Save (Ctrl+S) saves again to the file you last saved to with Save As, without asking again. If you have not used Save As yet for this image, Save works like Save As.

Formats in the Save As list: TGA, PNG, PCX, BMP, TIFF, JPG, DDS, Serious Sam 1 .tex and, for HDR images only, Radiance HDR. See the other image formats for what each one can store.

2.5 Warnings when information is lost

Before saving, the program checks whether the chosen format can hold everything, and lists what would be lost:

• HDR brightness - every format except .hdr stores the image as shown, with the current exposure and tone. Brightness beyond white is lost.
• Transparency - PCX, JPG and BMP (as saved by this program) have no alpha channel.
• Size - Serious Sam 1 works best with sizes that are a power of 2.
• Clipping - your Levels adjustments pushed values to pure black or white.
• Image detail - JPG compression slightly changes the image.

You can save anyway or cancel. The warnings can be switched off in Preferences > Warnings.

2.6 Saving as a Serious Sam 1 texture

Choose Serious Sam 1 texture (*.tex) in Save As. The program writes a version 4 texture with one frame, RGB or RGBA depending on transparency.

• If the image is larger than 1024 pixels on a side, the program offers to resize it to the largest fitting power of 2 (for example 2048 x 1024 becomes 1024 x 512).
• If the image came from a Serious Sam 1 texture, the original firstMip is kept, so the texture keeps the same size in the game. Otherwise the mex size equals the pixel size.

2.7 Saving as DDS

When you save as DDS, a small window asks for the DDS format:

The program preselects the best choice for the image. Generate mipmaps also stores the smaller versions that games use for distant surfaces; leave it on for games. Ctrl+S reuses the last choice.

3. Menu reference and keyboard shortcuts contents

4. Editing and Undo contents

4.1 Undo, Redo and Revert to original

Every edit (Levels, Auto levels, Resize, Channels, Normal map) becomes a step in a history. The menu shows which step will be undone, for example Undo Levels.

• Undo (Ctrl+Z) goes one step back, Redo (Ctrl+Y) one step forward.
• If you make a new edit after Undo, the undone steps are dropped (as in every program).
• Revert to original goes back to the image as it was opened.
• The original is always kept. The number of steps is limited (30 by default, see Preferences); when the limit is reached, the oldest edit is dropped, never the original. Each step of a 2048 x 2048 image uses about 16 MB of memory.
• Opening another file or quitting with unsaved edits asks Discard them? first.

4.2 Levels

Adjust > Levels (Ctrl+L) changes the brightness range of the image. The window shows the histogram of the image with three markers below it:

• black (left triangle): this input value and everything darker becomes the output black;
• gamma (gray triangle, middle): moves the mid tones; it sits where the result becomes middle gray. A gamma above 1 makes the image lighter, below 1 darker;
• white (right triangle): this input value and everything lighter becomes the output white.

Drag the markers with the mouse or type the numbers in Input: Black, Gamma, White. Output: Black, White sets the darkest and lightest value of the result (for example output white 200 makes the image dimmer).

Channel: RGB changes all colors together; Red, Green and Blue change one color only (useful to correct a color cast). Each channel keeps its own settings; the RGB setting is applied on top of the separate ones. The alpha channel (transparency) is never changed.

The main window shows the result while you work. Auto fills in the Auto levels values, Reset sets everything back. Cancel leaves the image as it was; OK applies the change as one Undo step.

Below the histogram the program shows how many values are clipped (see clipping). The parts of the histogram that would be clipped are shaded red. Tick Show clipping to see in the main window which pixels become pure white (red) or pure black (blue).

4.3 Auto levels

Adjust > Auto levels finds the darkest and the lightest value in the image (red, green and blue together) and stretches that range to 0 - 255. Nothing is clipped: the darkest pixel becomes exactly black and the lightest exactly white. Fully transparent pixels are not counted. The colors keep their balance because all three channels get the same stretch.

If the image already runs from black to white, Auto levels says there is nothing to change.

4.4 Clipping and merged tones

Clipping means that different values all become pure black (0) or pure white (255). After saving, the difference between them is gone for good. That is why:

• Auto levels never clips;
• Levels shows the clipping live in red (Clipping: 1234 values (0.50%)) or Clipping: none in green;
• OK asks Apply anyway? when the adjustment clips (can be switched off in Preferences);
• the save warning mentions edits with clipping.

The count is per color value: a pixel whose red and green are both clipped counts twice.

Merged tones: an image has 256 steps per channel. If you make the range narrower (for example output 50 - 200), some neighboring steps fall together. This is not clipping, but it is also not reversible after saving. Until you save, Undo always brings the original back.

4.5 Resize

Tools > Resize (Ctrl+R) shows the current size and lets you choose a new width and height from a list of powers of 2, or type any number. With Keep aspect ratio the other side follows. Fit Serious Sam 1 chooses the largest power-of-2 size of at most 1024 with about the same proportions.

Reducing is done in good quality: the image is halved step by step by averaging 2 x 2 pixels (like mipmaps), so fine details do not flicker. Transparent pixels count less for the color, so no dark edges appear around transparent parts.

4.6 Channels

Games use the channels of a texture differently. In Serious Sam 3, for example, the shininess (gloss) is stored in the alpha of the _GM textures, while another game may expect a separate gray gloss image. Tools > Channels offers:

• Extract red / green / blue / alpha as grayscale - one channel as a gray, fully opaque image;
• Load alpha from image... - use the brightness of another image (a mask) as transparency: white = opaque, black = transparent. A mask of another size is scaled first;
• Invert alpha - transparent becomes opaque and the other way round;
• Remove alpha (make opaque) - everything fully opaque; the colors under transparent parts become visible.

4.7 Normal map tools

A normal map stores a direction per pixel as a color: red = X (left/right), green = Y (up/down), blue = Z (towards you). The values 0 - 255 mean -1 to +1, so "straight ahead" is (128, 128, 255): the familiar light blue. Tools > Normal map offers:

• Flip green (DirectX <-> OpenGL) - games differ here: DirectX style has green pointing down, OpenGL style up. If bumps look like dents, flip green;
• Flip red - rarely needed;
• Rebuild blue (Z) from red and green - needed when only X and Y were stored, as in BC5 (other programs show those maps olive green);
• Normalize - gives every direction length 1 again (after scaling they become slightly too short);
• Create from height map... - makes a normal map from the brightness of the image (light = high, dark = low). You enter a strength (1 = subtle, 2 = normal, 5 = strong; the default is set in Preferences). The edges wrap around, because textures are usually repeated. The result is OpenGL style (green up). Useful for Serious Sam 1 textures, which have no normal maps.

5. The HDR menu contents

These items only work when an HDR image is loaded (a Serious Sam 3 HDR texture or a .hdr file). Without one, the program shows a message and nothing changes.

• Exposure +1 EV / -1 EV (Ctrl+Up / Ctrl+Down) - each step makes the image twice as light or twice as dark.
• Reset exposure (Ctrl+0) - back to 0 EV. At 0 EV the result is the same as a TGA export from Serious Editor.
• Tone: Editor (clip) - like Serious Editor: everything brighter than white is cut off.
• Tone: Filmic - bright parts are rolled off softly, as in games (ACES film curve), so clouds around the sun keep some detail.
• Switch tone (Ctrl+T) - switches between the two.

The exposure and tone are one setting for all HDR files, so the faces of a skybox always fit together. They are remembered for the next start, or set to fixed values in Preferences.

6. The Histogram window contents

Tools > Histogram (Ctrl+I) opens a window next to the main window. A histogram counts how many pixels have each brightness (0 - 255): dark is on the left, light on the right, and the higher the bar, the more pixels. The window stays open and follows when you open another image or make an edit.

Choices in the list: RGB (red, green and blue over each other), Red, Green, Blue, Luminance (brightness as the eye sees it), Alpha (transparency) and, for HDR images, HDR brightness (stops): the real brightness of the HDR data in stops, with a line where the white point of the current exposure lies.

7. The Batch conversion window contents

Tools > Batch conversion (Ctrl+B) converts many files in one go. The main window is not changed.

The file list (left)

• Add files... - choose one or more files;
• Add folder... - all files of the source format in a folder, including subfolders;
• Add from .gro... - choose textures in an archive (Ctrl+click or Shift+click for several);
• Add all from .gro... - every texture in an archive;
• drag files or folders from the file manager onto the list;
• Remove selected and Remove all - clear the list (the files themselves are not touched).

Click a line to see a preview and its properties on the right.

Settings (right)

Convert Selected converts the selected lines, Convert All the whole list. During conversion the Close button becomes Stop. Afterwards a report lists how many files were converted, skipped and failed, and why.

Safety checks

• A source file is never overwritten by its own result.
• When files with the same name (from different folders or archives) would end up as the same output file, the program asks: number them (name_2, name_3...), convert only the first of each name, or stop.
• For PCX, JPG and BMP output the program warns first that transparency will be lost.

All settings of this window, including the output folder, are remembered for the next time.

8. The Skybox window contents

Tools > Skybox (Ctrl+K) shows a complete skybox and exports it. If the image in the main window is a skybox face, that set is loaded straight away.

After loading, the program checks how the faces fit together by comparing their edges. If the top face is turned, it is rotated to fit, and you get a message such as Top face turned 90 degrees to fit. If the side faces seem to be in reverse order, or the top face does not clearly fit, the program warns you to check the preview. If faces are missing (at least N, E, S, W and the top are needed), they stay empty.

The exposure and tone chosen here are also used in the main window afterwards.

9. Preferences and remembered settings contents

Tools > Preferences (Ctrl+P) has three tabs. Defaults puts all choices back to the standard values; nothing is stored until you click OK.

General

Saving

Warnings

Remembered without asking

The program also remembers: the last folder used for opening and the last folder used for saving (separately), the HDR exposure and tone, the last DDS choice, and all settings of the Batch window.

Where the settings are stored

In a plain text file named TexConverter.prefs, one name = value per line:

• Windows: C:\Users\<name>\AppData\Roaming\TexConverter\TexConverter.prefs
• Linux: in the program data folder in your home folder (a hidden folder), in a subfolder TexConverter.

Delete the file to start again with all default settings.

10. Background: the Serious Sam 1 .tex format contents

Serious Sam: The First Encounter and The Second Encounter (Serious Engine 1) use their own texture format. A file is made of chunks: a four-letter name followed by data. All numbers are 32-bit integers ("LONG"), least significant byte first.

10.1 Version 4 (normal textures)

Flags: bit 0 (value 1) = the texture has an alpha channel (transparency); bit 1 (value 2) = "32-bit", only a hint for the game that does not change how the pixels are stored.

The game makes the smaller mipmap levels itself when it loads the texture, so only the largest picture is in the file.

Frames: an animated texture has several frames (pictures). The program shows the first one.

10.2 Mex size and firstMip

The width and height in the file are not pixels but mex: the unit Serious Engine 1 uses to decide how large the texture appears on a surface. The pixel size follows from it:

pixel size = mex size / 2^firstMip      (mex size = pixel size x 2^firstMip)

Example: mex 1024 x 1024 with firstMip 2 is a 256 x 256 pixel image that covers the same area as a 1024 x 1024 texture with firstMip 0. This is how SE1 lets a low-resolution texture cover a large surface. When you save an SE1 texture again, the program keeps the original firstMip, so the size in the game stays the same; after Resize, the firstMip is adjusted accordingly.

10.3 Version 3 (older textures)

The pixels are 16-bit colors: 5 bits red, 5 bits green, 5 bits blue (32 steps per color instead of 256). The program reads these and shows them as normal 24-bit images; it always saves version 4.

10.4 Effect textures (water, fire)

Some version 4 textures contain an effect instead of a picture: at offset 36 there is an FXDT chunk with the effect type, the size of a calculation buffer and the effect sources, then an FXBF buffer, an ANIM block and the name of a base texture (DFNM). The real image is calculated by the game while you play. The program shows the base texture if it is found next to the file (following the chain if the base is itself an effect), and otherwise the buffer as a gray image. The status bar says what is shown.

10.5 Rules for good SS1 textures

• Use sizes that are a power of 2: 16, 32, 64, 128, 256, 512, 1024. Width and height may differ (for example 512 x 256).
• Keep each side at 1024 pixels or less.
• Serious Editor imports TGA and PCX; the program's PCX files use 24-bit RLE, which the editor accepts.

10.6 Serious Sam 2 and 3 textures in short

Serious Engine 2 and 3 store textures in Croteam's general storage format, which starts with CTSEMETA (sometimes preceded by a signature SIGSTRM1), followed by a version text such as Serious Sam 2, a description of all data types, and the objects. The texture data sits around a chunk named STAR: width, height, flags and format just before it, the pixels after it.

• Serious Sam 2: pixels are packed with zlib. Uncompressed formats store B, G, R(, A) of the largest picture; compressed formats store DXT1, DXT3 or DXT5 with all mipmaps.
• Serious Sam 3 / Fusion: pixels are not packed and all mipmaps are present. Formats include opaque and translucent 32-bit, grayscale, alpha only, DXT1, DXT3, DXT5, BC5 normal maps and HDR (RGBE).
• Serious Sam 3: BFE (2011): like Fusion, but each channel can be stored separately with each byte as the difference from the previous one (delta coding), which packs better in a .gro.

The status bar shows the format name as Serious Editor calls it, for example compressed translucent (8-bit, DXT5).

11. Background: the other image formats contents

DXT (BC) compression

DXT divides an image into blocks of 4 x 4 pixels. Per block it stores two colors (16-bit: 5 bits red, 6 green, 5 blue) and, per pixel, 2 bits that say which of four colors the pixel gets: the two stored colors or one of two colors in between. That makes the files much smaller, and graphics cards can use them directly, but colors in a block are approximated.

Mipmaps

Mipmaps are smaller copies of a texture, each half the size of the previous one, down to 1 x 1 pixel. A game uses a smaller copy for surfaces far away, which looks calmer and is faster. DDS and SE2/SE3 textures can store them; Serious Sam 1 makes them itself while loading. The program always shows the largest picture.

12. Background: what is HDR? contents

An ordinary image stores each color as a number from 0 to 255. Pure white (255) is the brightest thing that can be stored: a white wall and the sun get the same value. This is low dynamic range.

HDR (high dynamic range) stores how bright light really is, without an upper limit. In a sky texture the sun can be thousands of times brighter than the clouds. Serious Sam 3 uses HDR textures for skies, so the game can light the level with them and choose the exposure itself.

Stops and EV

Brightness differences are counted in stops (photographers' EV, exposure value). One stop is a factor of two: +1 EV is twice as light, +3 EV eight times, -1 EV half as light.

How HDR is stored: RGBE

Each pixel has three color bytes (R, G, B) and one shared exponent E that says how many stops the three must be scaled. This is the format of Radiance .hdr files, where E counts whole stops. Serious Sam 3 uses the same idea, but its E counts in steps of 1/8 stop:

value = (channel + 0.5) / 256 x 2^((E - 127.5) / 8)

The program converts this exactly into a Radiance .hdr file when you save as .hdr.

From HDR to a normal image: exposure and tone mapping

A screen and an ordinary file can only show 0 - 255, so the program has to choose which part of the brightness to show:

1. Exposure: multiply all values by 2^EV (like the shutter of a camera).
2. Tone: Editor (clip) cuts everything above white off, exactly as Serious Editor does. Filmic rolls bright parts off gradually (the ACES film curve), so they keep detail instead of becoming a flat white area.
3. Gamma 2.2: the result is converted for the screen.

At 0 EV with Editor (clip), the image matches a TGA export from Serious Editor. Every format except .hdr stores the image the way you see it, with the chosen exposure and tone; that is why the save warning mentions HDR brightness.

The exposure is one value for all HDR files, so the faces of a skybox always match. Use the HDR brightness (stops) view of the histogram to see where the light really is, and Auto (whole set) in the Skybox window for a good exposure for a whole sky.

13. Background: skyboxes and cube maps contents

13.1 The idea of a cube map

A skybox is the sky around the player. The game draws the inside of a large cube around the camera, with a picture on each face. Because the camera is always in the middle, you never see the corners and the sky looks round. Such a set of six square pictures is called a cube map.

The faces are named after the direction they face. This program uses compass directions, with the axes of the common (OpenGL) cube map naming:

Going round from left to right the sides follow each other as W, N, E, S: the right edge of each face continues on the left edge of the next one.

13.2 Serious Sam skyboxes

• Serious Sam 3: the skybox has no bottom. The side faces N, E, S and W store only the upper half of the cube side, for example 1024 x 512 pixels; their bottom edge is the horizon. The top face (file letter C, shown as U in the program) is square, for example 1024 x 1024. Skies are usually HDR.
• Serious Sam 1 and 2: the side faces are complete squares with the horizon in the middle. The sets have five faces: four sides and the top.

13.3 Face names the program recognizes

There is no single international standard for skybox names. The program therefore recognizes the common conventions: the cube map axes of OpenGL and DirectX (+X, -X, ...), the short Quake / Half-Life / Source suffixes, the words used by Unity and many skybox packs (Front, Back, Left, Right, Up, Down), compass words, Croteam's letters and numbered sets. Choose any one face; the program looks for the others in the same folder (or archive) by name:

The order of the numbered sets was checked on the original game files by comparing the edges of the faces. The word names were tested with complete sets; the edge check after loading warns you if a set does not fit.

Tip for your own sets: the most widely understood names are Front, Back, Left, Right, Up and Down (or the short _ft _bk _lf _rt _up _dn), and posx negx posy negy posz negz for technical cube maps. Engines differ in which side they call "front", so after loading check the preview; the program turns the top and bottom faces to fit and warns when the sides seem to be in the wrong order.

The set name (used for export file names) is the common start of the names without a trailing _ or -, or the folder name if there is no common start.

13.4 How the top face fits

The top edge of each side face touches one edge of the top face U. Measured on the Serious Sam 3 skies:

So when you look at U in the cross layout, N is directly below it. The bottom face D works the same way the other way round: it lies below N, with N at its top edge and E at its right edge. Other games sometimes store the top or bottom face turned by 90 or 180 degrees. After loading a set, the program compares the edges (64 points per edge) and turns the top face, and the bottom face when the sides are complete squares, until they fit best. It also checks whether the sides run N-E-S-W or the other way round.

13.5 Export layouts

Separate faces - each face as its own file with its original name and the new extension.

Strip - the four sides next to each other in the order W N E S: a picture of the horizon all the way round (4 x the face width).

Cross - the top face above N, with W N E S below it, and the bottom face (if present) below N. The empty places are transparent. This is the usual way to show an unfolded cube.

360 degree panorama (2:1, also called equirectangular) - the whole sky in one picture, as used by many other games and programs. Horizontally it covers 360 degrees with north in the middle and east to the right; vertically it runs from straight up (top row) to straight down (bottom row). Each pixel is looked up in the right face of the cube. Below the horizon there is no picture in a Serious Sam 3 sky; there the program uses the average color of the horizon (the bottom row of the side faces). If a bottom face D exists, it is used for straight down.

When all faces are HDR, every layout can also be saved as .hdr, keeping all brightness - useful for other programs that light scenes with an HDR panorama.

Index contents