Railway Simulation BAHN 3.86r3 8/2012

Specification of Data Formats for User-defined and Zoom Graphics Data

Last recent changes: 2012-Aug-27

Valid for versions:

• 3.59Beta1-9, Release1+2, 04/1999-02/2000
• 3.5WBeta1-4, 12/1999-05/2000
• 3.70Beta, Release1-3, 06/2000-07/2001
• 3.75Beta1-9a, 04/2001-01/2002
• 3.80Release1, 04/2002
• 3.81Beta, Release1, 05-08/2003
• 3.83Beta, Release1-2a, 06/2004-06/2006
• 3.84Beta, Release1-3, 03/2005-05/2008
• 3.85Beta, Release1-3, 09/2008-02/2010
• 3.86Beta1-5, Release1-3, 12/2010-08/2012

(Info about older versions deleted, for more see German original file T13GR.TXT incl. formats from BAHN 3.40, e.g. 16 colors with[out] transparency)

There is no warranty for the contents of this file. Changes are reserved.

Contents:

• Changes
• General Information
• Filenames and Extensions
• Data Types
• Colors (24bpp/32bpp)
• Color Palette (256 colors)
• Packing of colors (24bpp/32bpp)
• Night colors
• Scenery Elements, Driving Way Elements, Signals (.gz1)
• Variants (Scenic elements only)
• Animations (Scenic elements only)
• Filenames and Directories of Single Files (.gz1)
• Zoom2 and Zoom4 Graphics for Scenery Elements and Signals (.gz2,.gz4)
• Archive Files for Scenery Elements and Signals (.uz1,.uz2,.uz4,.fwn/.fxn)
• "Initial Problem" - Creating a new .uz1 File
• Scenery Elements, Old Style (.uzg)
• Vehicle Data (.nfz)
• Zoom2 Vehicle Graphics (.fz2/.fzz)
• Archive Files for Zoom2 Vehicle Graphics "bahn.fz2"/"name.fz2"
• Zoom4 Vehicle Graphics (.fz4)
• Archive Files for Zoom4 Vehicle Graphics "bahn.fz4"/"name.fz4"
• Standard Vehicle Library File (bahn.fzg)
• Vehicle Graphics, Old Style (.ufg)
• Vehicle Set Data, Old Style (.uzz)

Changes

There follow the changes in reverse order.

Changes in BAHN 3.86b2

• Format of Zoom2/Zoom4 standard vehicle archives (bahn.fz2, bahn.fz4) changed
• Archive files also available for user-defined vehicle graphics in Zoom2/Zoom4
• All signals support immediate phases and alternating (blinking)
• New scheme for filenames of single files for scenery and signals

Changes in BAHN 3.86b1

• Vehicle gfx files (Zoom1,2,4): Properties ZGGEIG_FRONT2 and ZGGEIG_SEITE2 are now handled for any Zoom extra (same as ZGGEIG_HSTR and ZGGEIG_HSTL)
  I.e. when not set in Zoom1 but set in Zoom2 then it is used correctly when displaying Zoom2.
• New File sub formats ZOOMXFZGSUBFORMAT5 and ZOOMXGZGSUBFORMAT5 for single files (vehicles and scenery/ways)
• New lamp colors: FARBE_LAMPE_KALTWEISS, FARBE_LAMPE_GELBWEISS, FARBE_LAMPE_GAS_GELB
• New configurable colors: FARBE_WIE_xxx for rails, sleepers etc.
• New packing algorithm for graphics data
• Driving way data are now based on .gz1, using the same colors (i.e. old 256color format only needed to load old style user-defined files)
• .gz1 contains information about cursor movement direction and driving way
• Length of text lines extended from 81 to 121 characters
• Max. number of layers GSYMTEIL_MAXZAHL extended from 3 to 4 for .gz1/gz2/gz4

Changes in BAHN 3.85r3

• Vehicle gfx files (Zoom1,2,4) support open doors:
  new properties ZGGEIG_HSTR and ZGGEIG_HSTL and additional side views for it new file subformat ZOOMXFZGSUBFORMAT3 (used only if ZGGEIG_HSTR or _HSTL are set in the file)
• Scenery gfx files (Zoom1,2,4): new properties and data for clocks, look for GSYMEIG_UHR new file subformat ZOOMXGZGSUBFORMAT3 (used only if GSYMEIG_UHR is set in the file)

Changes in BAHN 3.85

• Zoom2 vehicle gfx files: Text line uses Unicode UTF-16 by default. However, BAHN can load it as ANSI-8 but will save as Unicode.
• Zoom2 vehicle gfx files: Renamed to ".fz2" extension instead of ".fzz" (with 3.85r1, in the Beta version is the old extension used, and 3.85r1+r2 load both)
• User-defined vehicle sets (.nfz) with Unicode text support
• Vehicle data with 2 additional side and roof views for running backwards (optionally)
• New Zoom4 vehicles as single and archive files
• Number of sets of user-defined scenery extended to 110 per layout. New set file format with up to 90 single elements each
• Color assignment of scenery is now compatible to vehicles (24bpp, lights)
• No more restrictions in size of user-defined scenic elements compared with the standard ones (height extended, overlapping left + right possible)
• Each scenic element with own graphics, i.e. they are not needed to be mirrored because in some case it does not make sense.
• Each scenic element can exist in 1, 2 or 4 versions that may differ depending on the BAHN co-ordinates (e.g. one and the same tree can look different at different locations, like for standard gfx since many years)
• Scenic elements can own up to 99 animation phases and smoke/steam that can be animated using own animation program files
• Scenic and driving way elements can get own graphics for Zoom2+Zoom4 views similar to the vehicles.
• User-defined data can be attached to layout files. The data structures remain, and while loading the layout, the files are restored.

Changes in BAHN 3.84

• Any text data inside BAHN are processed as Unicode-16bit (low-high, typical for x86 CPU family). This is also true when running under Win98 or WinME. While loading and saving text data, they are transformed using the codepage information given in BAHN-Options-Miscelleanous.
• Zoom2 vehicle gfx files: Text line supports Unicode UTF-16 but is stored as ANSI for compatibility with 3.83.
• Zoom2 standard vehicle graphics files are combined into "bahn.fz2" archive file
• since Beta8 5/2005 up to 100 .uzg files per layout instead 50

Changes in BAHN 3.83

• New color format 24bpp/32bpp (see section 4)
• Zoom2 gfx for vehicles (since Beta2, see section 5)
• New vehicle data format .nfz (since Beta3, see section2) (variable length, 16 vehicles per set instead of 8, more colors, extra front/rear view, extended front light change, variable steam...)
• since Beta3 9/2004 up to 100 .nfz/.ufg+.uzz files per layout instead 40
• -since Beta5 1/2005 up to 50 .uzg files per layout instead 40

Changes in BAHN 3.81

(although extended, no new data format has been defined, i.e. these data can be loaded by 3.59..3.80 and may look a bit crazy then).

• new color FARBE_BASEL_GRUEN
• since Beta1 1/2003 up to 40 .ufg/.uzz files per layout instead 8
• since Beta4 5/2003 up to 30 .uzg files per layout instead 10
• since Beta5 7/2003 up to 40 .uzg files per layout instead 30

Changes in BAHN 3.75Beta/BAHN 3.80

(although extended, no new data format has been defined, i.e. these data can be loaded by 3.59..3.70 and may look a bit crazy then).

• new color FARBE_GLAS ("half" transparency)
• new colors FARBE_KAKAOBRAUN, FARBE_MITTELHELLGRAU
• new DATEIFARBE_HINTERGRUND (for variable background color)
• number of .uzg files per layout 10 (instead of 4)
• number of .ufg/.uzz files per layout 8 each (instead of 1)
• names of .uzz files must be equal to respective .ufg name
• filenames Windows32-compatible (long, coding Windows/ANSI)
• Attention: Texts in .uzz-files are still coded DOS/OEM!
• Stronger regulation for .ufg block numbers (see at definition NUTZERFMSPSATZNR_MIN)

Changes in B359Beta9

• FARBE_MITTELHELLBLAU ex FARBE_WEISSBLAU
• new colors FARBE_WEISSBLAU, FARBE_DUNKELGRUENBLAU, FARBE_HELLGRUENBLAU FARBE_MITTELDUNKELGRAU, FARBE_MITTELGELB

Changes in B359Beta8

• color FARBE_CREMEWEISS (RGB values)
• new window colors FFARBE_G_NACHTS_xxx, FFARBE_B_NACHTS_xxx
• new color FARBE_SCHWARZBRAUNGRUEN

General Information

Filenames and Extensions

"xxxxx" is a placeholder for any name of a user-defined file. Some files are connected via their names, e.g. the pairs of .ufg/.uzz must have the same name, for instance "My_Cars.ufg" and "My_Cars.uzz" belong together. The same is with Zoom2/4 archives to .nfz files, e.g. "My_locos.fz2" may store the Zoom2 graphics to the vehicles of "My_locos.nfz".

In case of single files, the name consists of the archive name and some more added info, typically numbers and sometimes letters, e.g. "My_locos-00-01.fz2". You find more details about it here and in the BAHN Help at "Filenames" and "Single files" topics. The scheme of filenames for single files for scenery and ways was changed with BAHN 3.86Beta2.

until BAHN 3.70

Per layout, 4 .uzg files and 1 .ufg+.uzz file are possible. Filenames are DOS names according to 8.3-convention and DOS/OEM-coded.

since BAHN 3.80

Per layout, 10 .uzg and 8 .ufg+.uzz files are possible. Filenames are Windows32-compatible, i.e. long names are allowed. Coding is ANSI/Windows, depending on loaded fonts and Windows installation.

Names of .uzz files are stored no more, but created from the name of the respective .ufg file. E.g. for "abcd.ufg" the name of .uzz file must be "abcd.uzz". Texts stored inside the files remain DOS/OEM-coded.

since BAHN 3.81

Per layout, 40 .uzg and 40 .ufg+.uzz files are possible.

since BAHN 3.83

Instead of .ufg/.uzz combination, new .nfz files may be used. Per layout, 100 .nfz/.ufg+.uzz files are possible. Texts stored in .nfz and .fzz are coded Windows/ANSI (8 bit). Vehicles can get more details by using extra Zoom2 graphics.

since BAHN 3.84

Per layout, up to 100 .uzg files are possible.

since BAHN 3.85

Per layout, up to 110 .uzg files are possible. These can be replaced by .gz1 single files or by .uz1 packages. All have their own graphics. i.e. they are not mirrored. The number of elements per set is extended from 72 to 90. Each element can exist in 1, 2 or 4 versions depending on the BAHN co-ordinates. Vehicles and scenery can get more details by using extra Zoom2/Zoom4 graphics.

from here for all versions

Filenames of .uzg/.uz1 and .nfz/.ufg are stored in the .nt3 layout file. Multiple layout files can use the same graphics files. No path data are stored, i.e. the user-defined graphics files must stand in the same directory as the layout file. Changing of vehicle file names is possible only if that time no user-defined vehicles from this file are in use (but some may be installed).

File Header Text

All files begin with a text of unlimited length, terminated with Ctrl+Z character (26). It should consist of printable ASCI characters only (incl. CRLF). Recommended to store an information here about program and version that created/edited the file. Using the DOS command "TYPE" or similar, the text can be displayed correctly.

Data types and symbols, used in this documentation

When loading user-defined data, not all data are completely checked for correct values (this would be impossible for some reason). In result, wrong data can cause program aborts or other bad results. Since version 3.58, wrong, changed or deleted vehicles are replaced by substitute data. That makes it possible to continue without error in many situations. However, you have to replace the substitute data by correct vehicles manually later. Wrong Zoom graphics are ignored and the standard data (scale 1:1) are used instead.

All gfx data from BAHN 3.59 to 3.81 use the 256-color-scheme.

Since 3.83, the 24bpp-scheme is used more and more.

Colors (24bpp/32bpp)

This is the standard color scheme since BAHN 3.83. It was first used in Zoom2 graphics for vehicles since BAHN 3.83Beta2 8/2004 and -optionally- for Zoom1 vehicles since 3.83Beta3 9/2004. It is also used for all file formats that have been defined later, e.g. the .nfz vehicle files, .gz1 scenery files and the respective Zoom2/4 files.

For each pixel a value of 32 bit length is needed. In BAHN it is called COLORREFRGB to distinguish from some COLORREF that is defined reverse, i.e. BGR instead of RGB.

typedef WORD32 COLORREFRGB

Meaning:

• Bit0..7 = Blue part (0..255)
• Bit8..15 = Green part (0..255)
• Bit16..23 = Red part (0..255)
• Bit24..31 = Additional information (see below)

Basic Colors

A normal (basic) color is defined by Bit24..31 = 0. Any values of Bit0..23 are possible. The values define the daylight view. At night the basic colors are displayed as dark gray values (if day-night-switching is turned on), see night colors for details.

Macro for setting a COLORREFRGB value from single r,g,b:

#define GETRGB(r, g ,b) ((WORD32) (((BYTE) (b) | ((WORD16) (g) << 8)) | (((WORD32) (BYTE) (r)) << 16)))

Special Colors

Additional information / Logical colors / Light effects is always coded in Bit24..31. There are "Logical colors" (without own RGB values), and colors with additional info (with own RGB).

Mask for any additional information:

#define FARBE_ZUSATZ 0xFf000000

Logical Colors (Colors without RGB)

Logical colors do not have an own RGB value. The bits 0..23 are interpreted in a different way, e.g. as transparency or for replacing by a color that is defined elsewhere (use of configurable colors like "As background").

#define FARBE_LOGISCH 0x80000000

Transparent Color

#define FARBE_TRANSPARENT (FARBE_LOGISCH | 0x00000001)

This "color" has no effect, i.e. the background remains unchanged.

If there are only pixels of this color from deepest level to surface, then the background color is used. In case a background picture is assigned, then the background pixels are taken from this picture instead of the background color.

Half Transparent Color ("Behind Glass")

#define FARBE_HINTERGLAS (FARBE_LOGISCH)

Always changing the background as behind a glass (more dark+blue). When multiple overlapping, then no addition of this effect (that's unrealistic, but compatible with previous versions and faster)

The resulting color of the pixel (red, green, blue) is calculated as:

red = max( (red - GLASDIFF_ROT, 0 );
green = max( (green - GLASDIFF_GRUEN, 0 );
blue = max( (blue - GLASDIFF_BLAU, 0 );
#define GLASDIFF_ROT 70
#define GLASDIFF_GRUEN 50
#define GLASDIFF_BLAU 35


Configurable Colors

These colors are defined by the user in BAHN via "Options"-"Color Assignment". In result, on any computer they may look different, although there are defined default values.

Some of them are also generated by BAHN self, like background of grassy lines.

When drawing graphics, you don't know the RGB values that a user or BAHN really have set for background, text, rails, sleepers etc. However, maybe your graphics should include such areas or elements. Then, do not use "hard-coded" RGB values but the configurable colors instead. On output, BAHN replaces these colors by the currently set ones, incl. day-night-switching if needed.

#define FARBE_WIE_MIN (FARBE_LOGISCH | 0x00000100)
#define FARBE_WIE_MAX (FARBE_LOGISCH | 0x00000116) // since B386b1, before =_MIN
#define FARBE_WIE_ANZAHL (FARBE_WIE_MAX - FARBE_WIE_MIN + 1) // count of configurable colors


The colors introduced with BAHN 3.86 are used in files:
vehicles: from format=ZOOMXFZGFORMAT385, subformat=ZOOMXFZGSUBFORMAT5
.gzn files: from format=ZOOMXGZGFORMAT384, subformat=ZOOMXGZGSUBFORMAT5

Before, there was only defined the background color and only for scenery graphics, i.e. not for vehicles. Even now, it seems not to make sense to use these colors for vehicles.

Special Colors with Own RGB Value

Mask for colors with any light effect:

#define FARBMASK_LICHTEFFEKT 0x70000000

Light Colors

#define FARBE_IMMERHELL 0x40000000

These colors are ignored by the day-night-switching. The RGB value is valid always, also at night. They are used e.g. for signal lamps, advertising, LED matrix tables.

Lamp Colors

#define FARBE_LAMPE 0x50000000
#define FARBE_LAMPE_MIN 0
#define FARBE_LAMPE_MAX 4 // since B386b0e, before =1
#define FARBE_LAMPE_ANZAHL (FARBE_LAMPE_MAX-FARBE_LAMPE_MIN+1) // count of lamp colors

Lamps have an own day-night-switching:
The RGB value is valid at daylight (as long lamp is turned off). At night, fixed values are used instead (see below). Used e.g. for front/rear lamps of vehicles, road lamps, signs.

The colors introduced with BAHN 3.86 are used in files:
vehicles: from format=ZOOMXFZGFORMAT385, subformat=ZOOMXFZGSUBFORMAT5
.gzn files: from format=ZOOMXGZGFORMAT384, subformat=ZOOMXGZGSUBFORMAT5

Window Colors

These colors have a RGB value but a special day-night-switching:
RGB is valid as long windows do not shine (at daylight and sometimes at night). Used e.g. for windows in vehicles and buildings. If light is turned on, then fixed values are used.

The colors are combined of the mask FARBE_FENSTER, a mask defining the time and a mask defining the color.

Definition of time:

• 0 = shining whole night
• 1 = at certain times only
• 2 = ditto (but other times)

#define FARBE_FENSTER 0x60000000
#define FARBE_FENSTER_0 (FARBE_FENSTER | 0x00000000)
#define FARBE_FENSTER_1 (FARBE_FENSTER | 0x01000000)
#define FARBE_FENSTER_2 (FARBE_FENSTER | 0x02000000)
#define FARBMASK_FENSTER_ZEIT (FARBE_FENSTER | 0x03000000)


Definition of color:
Yellow:

#define FARBE_FENSTER_GELB (FARBE_FENSTER | 0x00000000)

"Neon" (blue):

#define FARBE_FENSTER_NEON (FARBE_FENSTER | 0x04000000)
#define FARBMASK_FENSTER_FARBE (FARBE_FENSTER | 0x0C000000)

Color values (RGB) for night color (shining) of windows:
Yellow version:

#define FFARBE_G_NACHTS_ROT (44<<2)
#define FFARBE_G_NACHTS_GRUEN (36<<2)
#define FFARBE_G_NACHTS_BLAU (0)


"Neon" version:

#define FFARBE_B_NACHTS_ROT (40<<2)
#define FFARBE_B_NACHTS_GRUEN (43<<2)
#define FFARBE_B_NACHTS_BLAU (39<<2)


Packing of Colors (24bpp/32bpp)

In files, the color data may be packed in a simple way, resulting in shorter and variable length of data.

The decompressing as given here shows how to interpret a value read from a file or buffer. You need to insert this into a loop, running for width * height or for size in pixels.

Unpacking of Colors BAHN 3.83-3.85

This algorithm is used for vehicles with
Format, Subformat < ZOOMXFZGFORMAT385, ZOOMXFZGSUBFORMAT5

and for scenery/way graphics with
Format, Subformat < ZOOMXGZGFORMAT384, ZOOMXGZGSUBFORMAT5

#define FARBE_KOMPRIMIERT (FARBE_LOGISCH | 0x40000000)
#define FARBMASK_KOMPR_TR 0x00010000
#define FARBE_KOMPR_TR (FARBE_KOMPRIMIERT | FARBMASK_KOMPR_TR)
#define FARBMASK_KOMPR_ZAHL 0x000000Ff
#define MAX_FARB_WDH 257


 INT32  count;
 WORD32 w32;  // i.e. COLORREFRGB
 COLORREFRGB color;

  (loop)
 
  w32 = ReadWord32(); /* read next value from file */
  if ( (w32 & FARBE_ZUSATZ) == FARBE_KOMPRIMIERT )
     /* packed, more than 1 pixel */
    {
     /* Bit7..0 contain number of loops minus 2, ie 0..255 for 2..257 */
     count = ( w32 & FARBMASK_KOMPR_ZAHL ) + 2;

     if ( w32 & FARBMASK_KOMPR_TR )
       {
        /* this color is needed more than any other... */
        color = FARBE_TRANSPARENT;
       }
     else /* color in next value from file */
       {
        color = ReadWord32();
       }
    }
  else /* not packed, single pixel */
    {
     count = 1;
     color = w32;
    }

This results in color and count, where count represents the number of pixels of the same color, following each other. At end of lines resp. columns, the packing may continue. At end of each view (when more than one, e.g. for vehicles), the packing is broken.

Unpacking of Colors since BAHN 3.86

This algorithm is used for vehicles with
Format, Subformat >= ZOOMXFZGFORMAT385, ZOOMXFZGSUBFORMAT5

and for scenery/way graphics with
Format, Subformat >= ZOOMXGZGFORMAT384, ZOOMXGZGSUBFORMAT5

There was added the possibility to repeat a short block of colors instead of a single color. Further, the view is started with an info about the total length of data. This may be used for test purposes, or to store all the data to a temporary memory block first.

#define FARBE_KOMPRIMIERT (FARBE_LOGISCH | 0x40000000)
#define FARBMASK_KOMPR_TR 0x00010000
#define FARBE_KOMPR_TR (FARBE_KOMPRIMIERT | FARBMASK_KOMPR_TR)
#define FARBMASK_KOMPR_SYS 0x00040000
#define FARBE_KOMPR_SYS (FARBE_KOMPRIMIERT | FARBMASK_KOMPR_SYS)
#define FARBMASK_KOMPR_SFB 0x0000ff00
#define FARBMASK_KOMPR_ZAHL 0x000000Ff
#define MAX_FARB_WDH 257 // max. count of repeats
#define FARBMASK_KOMPR_LEN 0x0000Ff00
#define MAX_FARBFOLGE_LEN 4 // max. length of a color repetition block (possible up to 256 but packing would become slower then)

 INT32  viewlen, count, wdhlen, i;
 WORD32 w32, f;  // i.e. COLORREFRGB
 COLORREFRGB color[MAX_FARBFOLGE_LEN];

  viewlen = ReadInt32(); // Length of packed data in COLORREFRGB, see remark above

  (loop)
  
  w32 = ReadWord32(); // read next value from file or from buffer
  if ( (w32 & FARBE_ZUSATZ) == FARBE_KOMPRIMIERT )
     // packed, more than 1 pixel
    {
     // Bit7..0 contain number of loops minus 2, ie 0..255 for 2..257
     count = ( w32 & FARBMASK_KOMPR_ZAHL ) + 2;

     if ( w32 & FARBMASK_KOMPR_TR )
       {
        // this "color" is needed more than any other...
        color[0]  = FARBE_TRANSPARENT;
        wdhlen = 1;
       }
     else
       {
        if ( w32 & FARBMASK_KOMPR_SYS )
          {
           // this color is not RGB but a configurable color
           color[0]  = (( w32 & FARBMASK_KOMPR_SFB ) >> 8 ) + FARBE_WIE_MIN;
           wdhlen = 1;
          }
        else
          {
           wdhlen = (( w32 & FARBMASK_KOMPR_LEN ) >> 8 ) + 1;
           wdhlen = min( wdhlen, MAX_FARBFOLGE_LEN ); // for security, but otherwise you should cancel here
           // there follows a number of RGB colors
           for ( i = 0; i < wdhlen; i++ )
             {
              f = ReadWord32();
              color[i] = f;
             }
          }          
       }
    }
  else /* not packed, single pixel */
    {
     count    = 1;    
     wdhlen   = 1;
     color[0] = w32;
    }

This results in count, wdhlen and color[wdhlen]. The color block color[wdhlen] stores the colors, and count represents the number of repetitions of the color block, following each other. At end of lines resp. columns, the packing may continue. At end of each view (when more than one, e.g. for vehicles), the packing is broken.

Night Colors

This section describes the handling of basic colors at night and while dawn and dusk. Some special colors remain unchanged and some have extra defined constant values at night (e.g. lamps and windows). For both see 24/32bpp-colors and 256-colors.

At Night

At night, the red, green and blue values are equal, resulting in a gray scale for all colors. The color is calculated from the daylight values as:

  {
   nw = ( red + green + blue ) / 8;

   RGBColor = GETRGB( nw, nw, nw );
  }

Dawn and Dusk

ZeitDiff = Length of dawn/dusk in minutes
ZeitLoc  = Current position inside ZeitDiff (0..ZeitDiff-1)

  {
   nw = see above (same value as at night)
   
   redloc = ( ZeitLoc * ( red - nw )) / ZeitDiff;
   greenloc = ( ZeitLoc * ( green - nw )) / ZeitDiff;
   blueloc = ( ZeitLoc * ( blue - nw )) / ZeitDiff;

   if ( Dawn )
     {
      red = max( nw + redloc, 0 );
      green = max( nw + greenloc, 0 );
      blue = max( nw + blueloc, 0 );
     }
   else /* Dusk */
     {
      red = max( red - redloc, 0 );
      green = max( green - greenloc, 0 );
      blue = max( blue - blueloc, 0 );
     }

   RGBColor = GETRGB( red, green, blue );
  }

Color Palette (256 colors)

This was the standard color system of BAHN 3.59 to BAHN 3.81. Some of the BAHN standard graphics data files still used this scheme partially until including BAHN 3.85. It is also used for some older user-defined data.

All values for color parts (red, green, blue) are calculated for a 16-bit-color controler (DAC). Valid values are 0..63 for each. For the red and blue values, the Bit0 is dont-care.

For calculating the corresponding values for 24bpp, multiply each with 4 (or shift left by 2). This is needed e.g. for palette data in PCX files, or in the 24bpp data format of newer BAHN versions. Doing so, causes minor errors, e.g. white = (63,63,63) results in (252,252,252) instead of (255,255,255).

The first 16 palette values are the same of the former 16-color-palette as used until BAHN 3.58 (VGA standard palette, but a few colors changed for BAHN).

You should use the colors only that are documented as follows. BAHN internally uses some more, but not as input data.

Special Colors

Code for transparent color (i.e. the background remains unchanged):

#define FARBE_TRANSPARENT 255

Code for "half"transparent color (since BAHN 3.75):

#define FARBE_GLAS 254

"halftransparent" means the background is changed as behind a glass. The resulting color of the pixel is calculated as:

• Black remains black
• Lighting colors (lamps, windows) remain unchanged
• Others: Calculating of parts (for 8 bit/part) as follows

#define GLASDIFF_ROT 70
#define GLASDIFF_GRUEN 50
#define GLASDIFF_BLAU 35
red = max( (red<<2) - GLASDIFF_ROT, 0 );
green = max( (green<<2) - GLASDIFF_GRUEN, 0 );
blue = max( (blue<<2) - GLASDIFF_BLAU, 0 );


Code for variable background color (available since BAHN 3.75Beta8e):
only defined for scenery graphics, do not use for vehicles

#define DATEIFARBE_HINTERGRUND 253

Basic Colors

These are the normal colors used for scenery, buildings, vehicles (with day-night-switching, inside of dialog windows always as daylight color).

The names and values do not apply to any standard, i.e. they are BAHN specific.

#define FARBE_MIN 0
#define FARBE_MAX 59 (until BAHN 3.70 incl.)
#define FARBE_MAX 61 (since BAHN 3.75)
#define FARBE_MAX 62 (since BAHN 3.81Beta1)

The RGB values given before are the values for daylight. For calculation of night values see Night colors and do not forget to multiply the Red, Green and Blue values by 4.

Light Colors

These colors are always lighting, without day-night-switching.

Use them for lamps that shine alltimes: Signals, lamps at metros, advertising and other light tables and signs.

Lamp Colors

At night, these colors appear yellow-white resp. red, over the day gray/red. Inside of dialog windows they are set to a similar basic color.

Use them for the lamps as front/rear lights of vehicles.

Night values for the lamps (RGB parts for each):
Yellow-white:

#define LNFARBE_GELB_NACHTS_ROT 63
#define LNFARBE_GELB_NACHTS_GRUEN 63
#define LNFARBE_GELB_NACHTS_BLAU 42


Red:

#define LNFARBE_ROT_NACHTS_ROT 63
#define LNFARBE_ROT_NACHTS_GRUEN 12
#define LNFARBE_ROT_NACHTS_BLAU 5


Window Colors

These colors shine yellow or blue ("neon") at night (the whole night or some time).

Use them for windows of buildings and vehicles that shine because there may be a lamp behind the window.

These colors also are available as basic colors with day-night-switching for windows that never shine, for RGB see FARBE_FF_DUNKEL.
So you can mix windows that look exactly the same at daylight, but at night some of them shine while others are dark.

80ff: Window colors that shine yellow the whole night

#define FFARBE_G0_MIN 80
#define FFARBE_G0_MAX 83
#define FFARBE_G0_DUNKEL 80// dark
#define FFARBE_G0_MITTEL 81// middle
#define FFARBE_G0_HELL 82// light
#define FFARBE_G0_BRAUN 83// brown

85ff: Window colors that shine yellow at evening and before morning, suitable for buildings; also for railways coaches for single compartments (RGB values equivalent to FARBE_FF_DUNKEL.. and FFARBE_G0_DUNKEL...)

#define FFARBE_G1_MIN 85
#define FFARBE_G1_MAX 88
#define FFARBE_G1_DUNKEL 85
#define FFARBE_G1_MITTEL 86
#define FFARBE_G1_HELL 87
#define FFARBE_G1_BRAUN 88


90ff: Window colors that shine yellow at evening and before morning (but times differing from FFARBE_G1_xxx)
suitable for buildings; also for railways coaches for single compartments (RGB values equivalent to FARBE_FF_DUNKEL.. and FFARBE_G0_DUNKEL...)

#define FFARBE_G2_MIN 90
#define FFARBE_G2_MAX 93
#define FFARBE_G2_DUNKEL 90
#define FFARBE_G2_MITTEL 91
#define FFARBE_G2_HELL 92
#define FFARBE_G2_BRAUN 93


100ff: Window colors that shine blue ("neon") the whole night

#define FFARBE_B0_MIN 100
#define FFARBE_B0_MAX 103
#define FFARBE_B0_DUNKEL 100
#define FFARBE_B0_MITTEL 101
#define FFARBE_B0_HELL 102
#define FFARBE_B0_BRAUN 103


105ff: Window colors that shine blue ("neon") at evening and before morning, suitable for buildings; also for railways coaches for single compartments (RGB values equivalent to FARBE_FF_DUNKEL.. and FFARBE_G0_DUNKEL...)

#define FFARBE_B1_MIN 105
#define FFARBE_B1_MAX 108
#define FFARBE_B1_DUNKEL 105
#define FFARBE_B1_MITTEL 106
#define FFARBE_B1_HELL 107
#define FFARBE_B1_BRAUN 108


110ff: Window colors that shine blue ("neon") at evening and before morning (but times differing from FFARBE_G1_xxx) suitable for buildings; also for railways coaches for single compartments (RGB values equivalent to FARBE_FF_DUNKEL.. and FFARBE_G0_DUNKEL...)

#define FFARBE_B2_MIN 110
#define FFARBE_B2_MAX 113
#define FFARBE_B2_DUNKEL 110
#define FFARBE_B2_MITTEL 111
#define FFARBE_B2_HELL 112
#define FFARBE_B2_BRAUN 113


Color values (RGB) for night color (shining) of windows
Yellow version:

#define FFARBE_G_NACHTS_ROT 44
#define FFARBE_G_NACHTS_GRUEN 36
#define FFARBE_G_NACHTS_BLAU 0


"Neon" version:

#define FFARBE_B_NACHTS_ROT 40
#define FFARBE_B_NACHTS_GRUEN 43
#define FFARBE_B_NACHTS_BLAU 39


Scenery Elements, Driving Way Elements, Signals (.gz1)

This is available since BAHN 3.85Beta0 9/2008 for scenery elements and driving way add-ons. Later it was extended to user-defined signals and with BAHN 3.86 to user-defined driving ways.

General Data

This section is valid for both standard and user-defined scenery. Also, the scenic add-ons of driving way elements are included, i.e. the parts that are not rails, sleepers, gravel or marking points of configurable colors, but "normal" graphics like any signs, platforms or signals. Further, the user-defined signals are included (introduced with 3.85Beta3).

A ".gz1" file holds the graphics data for exactly one element. In case of an element that exists in multiple variants or phases (like signals or animations), it holds exactly one of them.

Some standard driving way elements are combined from multiple .gz1 files: One for the way self, one for the add-on graphics and one for the platform.
The way self contains road, rails, sleepers, gravel, marking points, water etc.
The add-on contains signs, platforms, signals etc.
User-defined signals are add-ons in this sense and are always combined with a way element.

The file format is made for multi-purpose. Depending on the usage of a certain element, some properties do not make sense and are ignored.

Co-Ordinates

#define SYMBREITE 32 // basic element width in pixels for scale 1:1
#define SYMHOEHE 16 // basic element height in pixels for scale 1:1
#define MAXSYMHOEHE (6*SYMHOEHE) // max. "height" to North (upwards)

One element is a static object that can be placed in the layout at any valid position (nx,ny,nz). In BAHN, such a position is represented by SYMBREITE * SYMHOEHE pixels in 1:1 scale, or more in scales 2:1 and higher.
However, the element can be larger: It can overlap its neighbours to South (SYMHOEHE pixels), West and East (SYMBREITE pixels each) and North (MAXSYMHOEHE pixels).
The BAHN world is only two-dimensional, so in result "North" means "upwards" for many objects. However, this "upwards" is not displayed to the next upper level of BAHN layout co-ordinates (nz+1).

"The element self" (or basic element) is limited by co-ordinates x from 0 to SYMBREITE-1 and y from 0 to SYMHOEHE, where the 0,0 position is the lower left corner. To the left (West) and down (South) we find negative co-ordinates.

Layers

Maximum count of layers per element:

#define GSYMTEIL_MAXZAHL 3 // until BAHN 3.86Beta0c
#define GSYMTEIL_MAXZAHL 4 // since BAHN 3.86Beta0d (from format=ZOOMXGZGFORMAT384, subformat=ZOOMXGZGSUBFORMAT5)

The graphics of an element can consist of up to GSYMTEIL_MAXZAHL layers. This defines a kind of z co-ordinate. In case of overlapping with other elements and trains, the layer defines the order of display. Each layer has assigned one of the GFX_Z_nn values (see below).

For one element there can exist multiple layers that have assigned the same GFX_Z_nn value. In this case, the order of the data causes the order of drawing each onto the other. The BAHN integrated editor assigns the layers in a less flexible way than the data format allows.

For standard driving way elements, the layers are interpreted a bit different: GFX_Z_VG and GFX_Z_HG are used and are handled both as background. In result, it is possible to have a total number of more than GSYMTEIL_MAXZAHL layers in combination with a driving way add-on element. That was needed as long GSYMTEIL_MAXZAHL was limited to 3, but today it is more useful for optimizations.

Further, the addition of platforms is hard-coded for the most standard driving ways as copy from the simple "way + platform" elements. In result, changing the simple platform causes a change of all elements using the same platform, e.g. stopping points, turnouts or signals. On the other hand, we need less memory to store it, and the GSYMTEIL_MAXZAHL limit can be overidden.

Variants (Scenic elements only)

Any scenic element can exist in up to 4 variants. The idea is that one and the same object should be a bit different when used multiple.

Since many years, this is used in BAHN for some trees: If you set one tree into the layout and the same as the neighbour, then it may look different. The same can be used for a building with windows or advertising signs that shows different lights.

For each variant, there must exist an own ".gz1" file.

BAHN does not select the variants at random, but depending on the position in the layout:

1. nx even, ny even: "a" position
2. nx odd, ny even: "b" position
3. nx even, ny odd: "c" position
4. nx odd, ny odd: "d" position

When there exist 4 variants, then "a" to "d" are used. Otherwise "a" is used on "d", "b" on "c" and "a" on "b" when missing.

#define KEINE_ALTERNATIVE 0 // = all variants when more exist
#define MIN_ALTERNATIVE 1
#define MAX_ALTERNATIVE 4
#define MAX_ALTERNATIVZAHL ( MAX_ALTERNATIVE - MIN_ALTERNATIVE + 1 )

Animations (Scenic elements only)

Any scenic element can get additional animation phases. Controled by an animation program file (".bnm" file), it can be animated by displaying the single phases in programmable order. For details of ".bnm" files see BAHN Help.

For each phase, there must exist an own ".gz1" file. However, the animation program can consist of more steps than animation phases exist, i.e. they can be used multiple when looking the same.

#define MIN_ANIPHASE 0
#define MAX_ANIPHASE 99 // maximum animation phase

When an animation consists of steam or smoke only, then an additional graphic is not needed. Simply set the steam/smoke data in the header info (see below) and create an animation program of only one step and one phase.

The clock animations as introduced in BAHN 3.85r3 need neither extra graphics nor animation program.

Combining Variants and Animations

Both can be combined. I.e. you can create up to four different animations of the -in principle- same element (see "lturm.*" example used in the "demo_0.nt3" layout where the same tower blinks with different frequency depending on its position in the layout).

Directories and Filenames of Single Files (.gz1)

Directories (Folders)

Data for BAHN standard scenery are stored in the "\zoom1g" subdirectory of BAHN's system directory (where the .exe file is stored, by default "c:\bahn385" etc.).

Data for BAHN standard driving way add-ons are stored in "\zoom1f" instead.

Data for BAHN standard driving ways are stored in "\zoom1m" instead.

Any user-defined data (scenery, ways and signals) are stored in the same directory that contains the layout file (.nt3) that should use them.

Filenames

The integrated editor of BAHN shows the filename in the window's title.

All numbers used for filenames are decimal.

Filenames of Standard Scenic Elements

The filename is constructed from decimal element number (6 digits) + "-" + animation phase (2 digits) + a small letter + extension ".gz1".

Example: 049154-00a.gz1

If existing, then additional animation phases are shown by a phase number from 01 upwards.
Before BAHN 3.86Beta2, the phase number 00 was omitted in the filename. That is always the element that is shown when animations are turned off.

Example:
050972-00a.gz1 = Phase #0
050972-01a.gz1 = Phase #1
050972-02a.gz1 = Phase #2

If there exist variants, then the letter defines the variant from "a" to "d".
In case there are no variants, then the letter is always "a". Before BAHN 3.86Beta2, it was omitted then.

Example: 051220-00a.gz1 and 051220-00b.gz1

Filenames of Standard Driving Way Add-On Elements

The filename consists of driving way letter + number (3 digits) + "-" + version (3 digits) + phase letter.

Example: b168-000a.gz1 and s464-016b.gz1

Versions (designs): Same function but different design, e.g. different colored stopping points or elements with/without a platform.

For many driving way elements, the graphics on different driving ways look the same, and also there are many versions that look equal except of a platform on one side. Then, the same graphics are used, and some elements are defined as "primary". It does not make sense to create own graphics for all the others ("secondary") because these would never be used and waste much main memory. For the most elements, the primary driving ways are track on road and the water ways.

For the most elements that own a platform, this platform is added by BAHN, i.e. it is not a part of the element's own graphics. BAHN copies the platform from the simple driving way with platform elements, i.e. if you alter them, then all the others are changed too.

Example:
s264-002a.gz1 Stopping point with yellow-green sign and platform
The version without platform would be s264-010a.gz1 but is not defined as primary. Also, there are no primary versions for own trackbed and bus line because they look the same.

Phase letter:
The phase letter is needed for signals only. Otherwise, it is always set to "a" and was omitted before BAHN 3.86Beta2.
Some signals are flashing or switching in two or three steps, using immediate phases. In result, different graphics are needed that are marked by the phase letters:

There is always an "a" letter but the others are optionally. If not existing, then BAHN shows always the normal phase.

After switching the signal there is displayed the "b" picture for about 2s of simulation time, and then the "a" picture. However, the function of the signal is not influenced, i.e. undependent on the design of the "b" picture, the train will interpret the signal as if it has switched ready to the new status.
When a "c" picture also exists, then the order of display is "c-b-a".

Examples:

s440-000a.gz1 is a simple stop signal in clear status (green light).
s448-000a.gz1 is the same signal in danger status (red light).
A "b" version does not exist for both.

s440-060a.gz1 is a stop signal (traffic lights) with 3 phases in clear status (green light).
s448-060a.gz1 is the same signal in danger status (red light). There are "b" versions:
s448-060b.gz1 shows yellow light and is displayed before the red light.
s440-060b.gz1 shows red and yellow light and is displayed before the green light.
Notice that "b" is shown before "a" and not after.

s464-008a.gz1 is a grade crossing, blinking with two red lights, when the left light is turned on and the right light is turned off.
s464-008d.gz1 is the same but the left light is turned off and the right is turned on.

Before BAHN 3.86Beta2, the flashing signals were hard-coded for some grade crossings, using the "b" phase instead of the "d".
Since BAHN 3.86Beta2, any signals, including user-defined ones, can use both flash and immediate phases.

Filenames of Standard Driving Way Elements

New added with BAHN 3.86. Before, the driving ways were "hard-coded" from a few graphics in old 256 colors format with many layers, stored in the "bahn.gzg" file.

The filename consists of the letter "m" + driving way number (2 digits) + "-" + element number (3 digits) + "-" + "000" (3 digits, currently not used) + "a" letter (currently no meaning) + ".gz1" extension.

Example: m01-002-000a.gz1

For the ways on road and water there exist two versions: without and with borders. However, not all elements of the two versions really differ. Mostly, a difference exists for elements in a 45 degrees direction.

The element numbers are found in the nt3 layout file documentation (Appendix A).

Some elements exist for a subset of driving ways only, like the special turnouts for combination of bus way and track on road. They would not make sense for water or track on own trackbed.

Examples:

m00-001-000a.gz1 is track on road, dark grey, North-South, without borders. The version with borders is m01-001-000a.gz1 but looks exactly the same.

m14-002-000a.gz1 is water way, Northwest-Southeast, without borders. The version with borders is m15-002-000a.gz1.

Filenames of User-defined Scenic Elements and Signals BAHN 3.86Beta2

With BAHN 3.86Beta2, the scheme was changed to make it more simple. Now, the scheme is Archive name + "-" + element number (2 digits) + "-" + animation phase + small letter + extension ".gz1".

Example: Trolleybus2-58-00a.gz1 is element #58 of archive "Trolleybus2".

The animation phase is the same as for standard elements.

The small letter at the end represents either the variant (for scenery) or the signal phase (for signals). Both work the same way as for standard elements. In most situation, it is not of importance and set to "a".

For signals: The element number defines both the direction of effect and the status of the signal. There is a table in the BAHN Help at "User-defined signals" or "Zoom graphics".

You find more details in BAHN Help at "Single Graphics Files" and "Filenames".

There are prepared two versions for each signal. BAHN assumes the first version to stand right and the second one left to the way. Often you need both, undependent whether your traffic runs right or left handed, e.g. for double track lines.
In the schematic view, BAHN displays them as assumed, and it mixes the platforms in a suitable way in normal view.
This behaviour cannot be changed. However, this is a recommendation only, and you may draw something different if you need it for special ideas.

About the archive files and their filenames see .uz1 files, especially the remark of Initial problem.

File Contents of .gz1

Each file contains some header information and at least 1 up to GSYMTEIL_MAXZAHL layers of the element.

Measures

In principle the same as for .nfz data.

However, there are many elements that differ from this. Many details are shown too large because otherwise it would be impossible to make them visible.
Using Zoom graphics for higher scales, you may use more exact measures.

Limits

Width (West-East): 3*SYMBREITE
Height (North-South): MAXSYMHOEHE+SYMHOEHE

Contents Details of .gz1

This header info is similar also for Zoom2 and Zoom4 data.

File format versions and subversions:

#define ZOOMXGZGFORMAT384 0x0384
#define ZOOMXGZGSUBFORMAT0 0x00 // BAHN 3.84, 3.85Beta,r1,r2,r3
#define ZOOMXGZGSUBFORMAT3 0x03 // BAHN 3.85r3 only if GSYMEIG_UHR is set
#define ZOOMXGZGSUBFORMAT5 0x05 // BAHN 3.86

Header

Then, the views of the single layers follow. The count is given in anzebenen before.

View

All co-ordinates and width/height values must not exceed the limits as defined above.

Zoom2 and Zoom4 Graphics for Scenery Elements and Signals (.gz2,.gz4)

This is available since BAHN 3.85Beta0 9/2008.

Zoom2/Zoom4 are optional add-ons, making available more detailed graphics for any element that is available in 1:1-scale (inclusive user-defined ones). The Zoom data are used in BAHN in view scale 2:1..8:1 instead of the original scale 1:1-data.

If not available (or if any error occurs), the original data are used in the same way as before. The error message #621 in BAHN gives a return code that specifies more details about the error, see "bahn.hlp"/"bahn.chm" at "Errors and messages, 621" for more.

Data structures and handling are quite similar to Zoom1 ".gz1" data The next section describes the differences.

Differences to .gz1

File name extension is ".gz2" resp. ".gz4".

Files for standard graphics are stored to subdirectories "zoom2f" and "zoom2g" resp. "zoom4f" and "zoom4g".

The header info contains a different ZoomFaktorID:
ZoomfaktorID = BYTE[1] = '2' or '4' for Zoom2 or Zoom4

Not all possible properties make sense for Zoom2+4. See remark at definition of GSYMEIG_xxx in .gz1 section.

The co-ordinates, measures and limits are multiplied by 2 resp. 4.

Archive Files for Scenery Elements and Signals (.uz1, .uz2, .uz4, .fwn/.fxn)

This is available since BAHN 3.85Beta0 9/2008.

Storing all the scenery and driving way add-on data in single files results in thousands small files that make your computer slow down and waste resources.

For that reason, the data can be combined to a few larger archive files:

"bahn.fw1" for BAHN standard driving way graphic add-ons
"bahn.fx1" for BAHN standard scenic graphics
"name.uz1" for a set of user-defined scenic graphics or signals

For Zoom2 and Zoom4 data, replace the "1" by "2" resp. "4".

The files with standard data are stored in the BAHN system directory, i.e. at the same place as "bahn.exe".

The user-defined must be stored at the same place where the layout file is found that uses them. Thus, the ".uz1" files can replace the old ".uzg" files, using the extended possibilities of BAHN 3.85 and storing up to 90 elements each instead of 2*36, including variants and animations.

For user-defined signals, the same ".uz1" data are used. Each file can hold the two versions of a signal, in all 8 directions, with all phases.

When there exist both a single .gz1 file and a file packed in an archive file for one and the same element, then BAHN always loads the single file.

The integrated BAHN editor always stores single files. In result, the archive files can be used as security copy when you like to make experiments with some elements.

If you like to extract a single file from a package, then simply edit it in BAHN and save it to disk.

For creating and extracting the archive files there is the same command line software "fzgc2.exe" as for vehicle Zoom archives. You should find it published somewhere at www.jbss.de. The source code file "fzgc2.c" includes documentation about handling (command file parameters) and a short description of the supported archive file format, both in English and German.

"Initial Problem" - Creating a new .uz1 File

When you like to create a new ".uz1" file then you have to create its single file components first. But to store them, BAHN needs a valid filename of the not-yet-existing ".uz1" file. You cannot explicitely enter a filename for a single file.

Run BAHN and enter the name in "File"-"Userdefined Graphics"-"Scenery", "Signals" or "Driving Ways", as if it would already exist, and confirm with "OK". BAHN may give you a message that the file could not be loaded because not found. However, it will store the name, and then it will save and load the single files using this filename. Another way it would be to copy any already existing ".uz1" or ".uzg" file to another name and to use and edit it.

Scenery Elements, Old Style (.uzg)

(with BAHN 3.85 replaced by .gz1/.uz1 format, but still supported)

An ".uzg" file contains 36 graphic symbols without function, that can be used for scenery. They can be accessed as "Userdefined graphic symbols" the same way as other scenery. Each of the blocks in the Status window contains 9 symbols, so it is the best to make groups of 9 symbols that belong together in any way. You should not paint symbols that look identically to original BAHN symbols, because this may confuse the users. Avoid this, especially with the empty symbol and with driving ways.

In BAHN 3.56-3.59 each symbol consists of 4 simple symbols (32x16 pixel) that are arranged one upon the other (32x64 pixel). It is not needed to use all the simple symbols (see table data).

Any simple symbol consists of 4 partial symbols ("horizontal MiniSprites", in the following called "MSP1"). Construction of a MSP1 (8 pixels width, 16 pixels height):

16 lines with 8 byte each, where each byte represents one pixel (colors see 256 colors)

The lines follow each other from top down. All 4 MSP1 of a simple symbol stand one after the other without separator.

The file is used for 36 symbols (=4*36 simple symbols). It must contain at least 4 and at maximum 4*4*36=576 MSP1. If symbols use MSP1 that are missing in the file, then BAHN displays them as black-white pattern. To any simple symbol there belong the MSP1 from symbol number * 4 to symbol number * 4 + 3, e.g.

• Symbol 0: 0,1,2,3
• Symbol 2: 8,9,10,11
• Symbol 143: 572,573,574,575

In case of wrong values for the number, BAHN gives an error message and all symbols are replaced by standard data.

Additionally: Symbol table for arrangement of the simple symbols. The format is more flexible as needed.

Order per Symbol:

1. Down part (visible at x,y+1, as background)
2. Self1 (visible at x,y)
3. Self2 (visible at x,y, covering Self1)
4. Upper part1 (visible at x,y-1)
5. Upper part2 (visible at x,y-2)
6. Upper part3 (visible at x,y-3)

All simple symbols can be used multiple. However, it is not needed to support this, because there are 4 simple symbols available per symbol (eg B34EDI and WB35EDI use a fixed table without multi-use).

Conditions (checked while loading!):

• Self1 or Self2 or both must exist, i.e. they cannot be set to == 0xFFFF both
• Summary height at maxl 4 simple symbols, ie if Down part exists, then no Upper3 can exist, i.e. it must be set to 0xFFFF
• No divided symbols, i.e. if Upper3 exists, then Upper1 and Upper2 must be != 0xFFFF
• if Upper2 exists, then Upper1 must be != 0xFFFF

In result:

File length = Header length + 2 + 2*2 + Msp1Zahl*16*8 + 4 + 36*6*2 = at least 955 Byte

Example:
All MSP1 may be used, all 36 symbols have height = 4 symbols without down part, each uses its own MSP1. In result, the most simple table is:

Vehicle Data (.nfz)

(new since BAHN 3.83Beta3, replacing the combination of .ufg and .uzz data)

Data are organized in vehicle sets. Each file can store some sets, each set can contain some vehicles.

Maximum number of vehicle sets per file:

#define NUTZERFZGSATZ_PRODATEI 10

Maximum number of vehicles per set:

#define FZGF_MAXFZGZAHL 16

Max. Length of name of a vehicle set incl. terminator character:

#define ZUGGNAMESIZE 33

Number of text lines per vehicle:

#define MAX_FZGTEXTZAHL 5

Maximum length of a single text line of a vehicle incl. terminator (also used for the text line of Zoom2/4 vehicles and scenic graphics):
This is the number of characters, i.e. not the size in BYTE. The real size depends on the type of data (BYTE or CHAR16 Unicode characters). Terminator is '\0' (0x00) for BYTE-coded and UNICODE_NULL for CHAR16 text.

some old formats of CAREDI 1.x and 2.x:
#define MAX_UFZGTEXTLINELEN 61

until BAHN 3.86 Beta0d:
#define MAX_UGFXTEXTLINELEN_81 81

since BAHN 3.86 Beta0e
(vehicles: from format=ZOOMXFZGFORMAT385, subformat=ZOOMXFZGSUBFORMAT5)
(also used for .gzn files: from format=ZOOMXGZGFORMAT384, subformat=ZOOMXGZGSUBFORMAT5)
#define MAX_UGFXTEXTLINELEN 121

Maximum length (=count of characters) of all texts of a user-defined vehicle set:

#define MAX_UFZGTEXTLEN ( ZUGGNAMESIZE\ + MAX_FZGTEXTZAHL * FZGF_MAXFZGZAHL\ * MAX_UGFXTEXTLINELEN )

Minimum and maximum numbers of vehicle sets in the file:

#define NUTZERFZGSATZNRDATEI_MIN 4000
#define NUTZERFZGSATZNRDATEI_MAX (NUTZERFZGSATZNRDATEI_MIN + NUTZERFMSPSATZNR_PRODATEI - 1)

Measures

In BAHN, the recommended calculation of measures for scale 1:1 is:

original [mm] / 467 = pixel in BAHN.

(1 ft = 304.8mm)

However, I know that many available vehicles differ from this scale. It is a recommendation only. For displaying more details, the height and width of many vehicles are too large. Also, you cannot assume that a pixel is "quadratic" in any case, because this depends on the screen resolution. Originally, BAHN was designed for 640x480 (4:3 ratio), but also used with EGA adapters of 640x350, using the same graphics. Today, common resolutions are 800x600, 1024x768 and 1152x864 (4:3 each), but also 1280x1024 (5:4) and others. A different ratio results in a different length:height for each pixel.

Limits

Constants defined for 1:1 scale, in pixels: Vehicle length (horizontally):

#define MIN_FZGLEN 8
#define MAX_FZGLEN (32 * 8)

Vehicle height (horizontally and vertically):

#define MIN_FZGHO 2
#define MAX_FZGHO 14

Vehicle width (vertically):

#define MIN_FZGBR 4
#define MAX_FZGBR 16

maximum number of steam start points per vehicle type:

#define MAXDAMPFZAHL 3

limits of steam positions (pixel) (as undependent of vehicle length):

#define DAMPFX_MIN 0 (x minimum, counted in driving dir., begin = 0)
#define DAMPFY_MIN 4 (y minimum)
#define DAMPFY_MAX 13 (y maximum)

Contents Overview

1. Header
2. List of vehicle sets
3. Vehicle sets, each consisting of up to FZGF_MAXFZGZAHL vehicles.
4. Vehicle control data
5. Views (at minimum 6, but also 8, 10, 12, 14 up to 16)

Contents Details

Header

This header is similar also for the bahn.fzg file.

There is no real difference between 0x3830 and 0x3840 versions. However, you may use the 0x3840 value to prevent loading the data into BAHN 3.83 or 3.84 because they may get confused when the ZGGEIG_SEITE2 bit is used in the file (supported since 3.85, see vehicle properties).

The 0x3850 format is identical except that it assumes all text data stored as Unicode (CHAR16 in LOBYTE-HIBYTE notation). Numbers of characters are the same, but data lengths of text given in BYTE must get doubled.

List of Vehicle Sets

The list consists of pairs of logical number and file offset. Terminated by logical number == 0, then no file offset follows. There are at max. NUTZERFZGSATZ_PRODATEI user-defined vehicle sets.

Example:

WORD16 log.number = NUTZERFZGSATZNRDATEI_MIN
WORD32 Offset = 2
WORD16 terminator = 0

Vehicle Set

After reading the file offset, set the current file pointer position relative to this offset to reach the vehicle set data.

Vehicle

For details see also measures and limits

The length of the roof in vertical view is FzgLen/2. In result, it is recommended to use even values for length of vehicles that should be coupled to trains. Otherwise, in vertical view some rounding problem may cause a bit different display of the train depending on the current position.

For width, the use of even values is recommended. Otherwise, BAHN cannot place the vehicle exactly centered. This may be don't-care for pneu vehicles and ships, but not for something running on tracks.

Vehicle Views (Graphical Data)

There follow the single views, each as rectangle, no separator, no terminator. Set pixels not used to FARBE_TRANSPARENT. Each rectangle from top left to bottom right in lines, exceptions see below. The order of the views is as in the table. Some are available always, some depending on the properties defined in the sections above.

For each view:

If ( Eig & ZGGEIG_24BPP )

• Each Pixel = COLORREFRGB (see 24bpp colors)
• Data may be packed (see color packing), depending on format and subformat value of the vehicle
• Roof views are stored from left top to right bottom in columns instead of lines, for better packing

else

• Each Pixel = BYTE (see 256 colors)
• Data are not packed
• All views are stored from top left to bottom right in lines

Zoom2 Vehicle Graphics (.fz2/.fzz)

This is available since BAHN 3.83Beta2 2004-Aug-29.

Zoom2 is an optional add-on, making available more detailed graphics for any vehicle that is available in 1:1-scale (inclusive user-defined ones). The Zoom2 data are used in BAHN in view scale 2:1..8:1 instead of the original scale 1:1-data. If not available (or if any error occurs), the original data are used in the same way as before. The error message #620 in BAHN gives a return code that specifies more details about the error, for more see also the Help file "bahn.hlp"/"bahn.chm" at "Errors and Messages, 620".

The data are stored in separate files for each vehicle type (i.e. not in vehicle sets). For standard vehicles, the single files can be combined to archive files. The most properties of the vehicle are taken from the 1:1 data.

Directories (Folders)

Zoom2 data for BAHN standard vehicles are stored in the "\zoom2" subdirectory of BAHN's system directory (where the .exe file is stored, by default "c:\bahn383" resp. "c:\bahn386" or similar). Data for user-defined vehicles are stored in the same directory that contains the scale 1:1 data (.nfz or .ufg/.uzz files).

Filenames

For BAHN standard vehicles, the name is constructed from vehicle set number (5 digits) + '-' + local vehicle number in the set (2 digits) + extension. All numbers decimal, counting starts with 0. Extension is ".fzz" for BAHN 3.83,3.84 and 3.85Beta, but since 3.85r1 it was changed to ".fz2". However, if 3.85 does not find ".fz2" then it also looks for a suitable ".fzz" file.

Example: "05220-00.fz2" is set #5220, car #0.

BAHN shows the set and vehicle number in the "Vehicle list" function of Train menu.

For user-defined vehicles the name is constructed from the .nfz/.ufg filename (without extension) + '-' + vehicle set number (2 digits) + '-' + local vehicle number in the set (2 digits) + ".fzz". All numbers decimal, counting starts with 0.

Example: "ship1-00-01.fz2" is from "ship1.nfz" or from "ship1.ufg", set #00, vehicle #01.

Contents Overview

Each file contains some header information and at least 6 up to 16 views of the vehicle. The views are the same as described in the NFZ section, but the measures are different.

Measures

See .nfz data for the general definition in scale 1:1.

Resulting in recommended calculation of measures for scale 2:1:

original [mm] / 233.5 = pixel in BAHN.

Limits

Length: 2*MIN_FZGLEN .. 2*MAX_FZGLEN

This must be exactly = 2*length of the scale 1:1 original. Otherwise BAHN does not load this file. The length of the roof in vertical view is Length/2.

Height: 2*MIN_FZGHO .. 2*MAX_FZGHO

Note that height of front and rear view of older BAHN data formats (before BAHN 3.83) is zero. This is true for any user-defined car stored in .ufg data. When making a Zoom2-view of such an original, than lengthen the roof and make fronts and rear views of suitable height. The BAHN internal graphics editor sets the height to 2*MIN_FZGHO when loading the data and fills the data with transparent color.

Width: 2*MIN_FZGBR .. 2*MAX_FZGBR

Recommended to use even values only.

Contents Details

Header

The properties are the same as shown for nfz data. The next table mentions the differences only.

Views

The order of the views is the same as found in the NFZ section. The measures and limits are found in Contents overview above. The number of views (i.e. if available for some of them) depends on the properties (see above).

Each view is a COLORREFRGB[], as rectangle, with no separator and no terminator. Pixels not used are set to FARBE_TRANSPARENT.

if (version == ZOOM2FZGFORMAT383) and (subformat == ZOOM2FZGSUBFORMAT2):
Each rectangle from top left to bottom right in lines.

if ((version == ZOOM2FZGFORMAT383) and (subformat == ZOOM2FZGSUBFORMAT3)) or (version == ZOOMXFZGFORMAT385):
The same rectangles but using packed data, resulting in variable length of data.
Further, the roof views are stored from left top to right bottom in columns for better packing. For unpacking see color packing.

Archive Files for Zoom2 Vehicle Graphics "bahn.fz2"/"name.fz2"

For standard vehicles, this is available since BAHN 3.84Beta6 2/2007.
For user-defined ones, this was added with BAHN 3.86Beta2 2/2011.

The reason is that handling of some thousand single files may make your computer slow down and may waste resources. However, details are depending on the OS and especially on the file system.

All the Zoom2 files for the standard vehicles are combined to a single file "bahn.fz2".
This file is stored in the BAHN system directory, i.e. at the same place as "bahn.exe".

All the Zoom2 files for vehicles of a .nfz file "name.nfz" can be combined to a single file "name.fz2".
This file is stored at the same place as the .nfz file.

When there exist data for the same vehicle both in a single file as described in Zoom2 Vehicles and in an archive file, then BAHN always loads the single file.

The integrated BAHN graphics editor always stores single files. In result, you can use the archives as security copies when you like to make experiments with standard Zoom2 vehicles. If you like to copy a Zoom2 file from "bahn.fz2", then simply edit it in BAHN and save it to disk.

For creating and extracting the ".fz2" archive files there is a simple command line software "fzgc2.exe".
You should find it published somewhere at www.jbss.de. The source code file "fzgc2.c" includes documentation about handling (command file parameters) and a short description of the "bahn.fz2" archive file format, both in English and German.
In result of some changes in the data structures, there may exist different versions of this software for different BAHN versions.

Zoom4 Vehicle Graphics (.fz4)

This is available since BAHN 3.85Beta0 9/2008.

Zoom4 is an optional add-on, making available more detailed graphics for any vehicle that is available in 1:1-scale (inclusive user-defined ones). The Zoom4 data are used in BAHN in view scale 4:1 and 8:1 instead of the original scale 1:1-data (from 3.85r2 also in 6:1 scale). If not available (or if any error occurs), then the original data are used in the same way as before, or existing Zoom2 data when found.

Handling and data are nearly the same as for Zoom2 vehicle data.

Directories (Folders)

Zoom4 data for BAHN standard vehicles are stored in the "\zoom4" subdirectory of BAHN's system directory (where the .exe file is stored, by default "c:\bahn385" or similar, depending on version). Data for user-defined vehicles are stored in the same directory that contains the scale 1:1 data (.nfz or .ufg/.uzz files).

Filenames

The same as for Zoom2 data, except the standard file extension is ".fz4" instead of ".fz2".

Example: "05220-00.fz4" is set #5220, car #0.

Contents overview

Identical to Zoom2.

Measures

In general see .nfz data.

Resulting in recommended calculation of measures for scale 4:1:

original [mm] / 116.75 = pixel in BAHN.

Limits

As for Zoom2, with doubled limits:

Length: 4*MIN_FZGLEN .. 4*MAX_FZGLEN
Height: 4*MIN_FZGHO .. 4*MAX_FZGHO
Width: 4*MIN_FZGBR .. 4*MAX_FZGBR


Contents Details

Header

The header info is nearly identical with Zoom2 vehicle data. There are minor differences only.

The value of identification string is {'F','Z','G','4'}.

Supported file version versions: ZOOMXFZGFORMAT385 with subformats ZOOMXFZGSUBFORMAT0 and ZOOMXFZGSUBFORMAT3 (i.e. the same as for newer Zoom2 vehicles).

Properties: The same as for Zoom2, see also general remarks about vehicle properties.

Measures: Fzg4Len, Fzg4HoW, Fzg4Br, Fzg4HoS instead of Fxx2Xxx.

Text line always Unicode-UTF16.

Views

Structure and order same as for Zoom2 vehicles, see there. Ofcourse, the measures of Zoom4 are used instead of Zoom2.

Archive Files for Zoom4 Vehicle Graphics "bahn.fz4"/"name.fz4"

This is available for standard vehicles since BAHN 3.85Beta0 9/2008.
For user-defined vehicles, it was added with BAHN 3.86Beta2 2/2011.

The handling is the same as for Zoom2 vehicles, see at bahn.fz2/name.fz2.

For creating and extracting the ".fz4" archive files there is the same simple command line software "fzgc2.exe" as for Zoom2.

Standard Vehicle Library File (bahn.fzg)

This file is stored in the BAHN system directory, i.e. at the same place as "bahn.exe".

It contains all the BAHN standard vehicles including their Zoom1 graphics and properties. It may be of interest to read it for making an Import function to copy a BAHN standard vehicle into any other software.

The data structures are similar to .nfz files. However it stores many more vehicle sets and vehicles. Further, the data are a mix of some older data formats.

The "bahn.fzg" is language-independent, i.e. it does not contain text data. Instead, there are numbers that reference lines in the "bahn.lnv" text data file or the respective ".lnv" file for other languages, as selected by the user.
The numbers are not direct line numbers, but logical numbers. For details look at a ".lnv" file: Any line of text has a unique number standing before.

If not stated otherwise, then and limits are the same as for .nfz data.

Contents Overview

1. Header
2. Seek list of vehicle sets
3. "Compatibility Vehicle Sets"
4. Vehicle sets, each consisting of up to FZGF_MAXFZGZAHL vehicles.
5. For each car: Vehicle control data
6. For each car: Views (at minimum 6, but also 8, 10, 12, 14 up to 16)

Contents Details

Header

The seek table is a list of all vehicle sets in the file, for quicker search. If you find a vehicle set number in the table, then seek directly to the seek position to get the set.

The terminator is a set number == 0, not followed by a seek position.

"Compatibility Vehicle Sets"

Beginning with WORD16 Set number. This can be used to check whether you did seek correctly.

Set number is 1..4096.

This type is needed for opening older layouts (before BAHN 3.83). It doesn't contain vehicles, but information by what vehicles of 3.83 the old ones should be replaced. Not of interest here, so omitted here.

Normal Vehicle Sets

After reading the file offset, set the current file pointer position relative to this offset to reach the vehicle set data.

The vehicles of the set follow.

Vehicle

The graphics data follow, depending on the properties ZGGEIG_xxx and on the measures read before.

When ZGGEIG_24BPP is set, then the same as in the .nfz files:
32 bit per pixel, packed, views as for (version == ZOOMXFZGFORMAT385)

When ZGGEIG_24BPP is not set, then the "old" style is used:
8 bpp, not packed, color palette and special colors as defined for old user-defined gfx (.ufg files).
However, the ZGGEIG_FRONT2 property of BAHN 3.83 is supported.

Vehicle Graphics, Old Style (.ufg)

With BAHN 3.83, this format was replaced by .nfz format, but it is still supported to load older user-defined vehicles.

An .ufg file holds graphics data of a vehicle set of up to 8 cars. The additional data like properties and texts are stored in an .uzz file of the same name. For correct loading, both files must exist and suitable.

Data blocks consist of "MiniSprites" MSP1 and MSP2:

An MSP1 consists of 14 lines of 8 Byte each. Each byte represents 1 pixel, colors see 256-colors scheme. The both bottom lines (14+15) do not exist here because there are tracks and sleepers. Since BAHN 3.80 the tracks moved up to the symbols center, but the principle did not change, because the output of vehicles was shifted up too.

Further here are "vertical MiniSprites", in the follwing called MSP2. Consisting of 4 lines with 8 byte each, similar to MSP1.

In both MSP, lines follow from top down.

Each vehicle consists of 4 views: Horizontally left and right sides, and vertically front+roof and rear+roof. There are no extra front + rear views, i.e. the vertical height = 0 compared with newer formats.

The views are made by assignment of MSP (MSP1 for horizontal, MSP2 for vertical). In result, vehicle length is possible only in steps of MSP1 (8,16,24 pixels etc.). The most vehicles have been drawn in a way that they fitted into this limit. But, there are exceptions where the gap is filled by transparent color. For these, you should prevent coupling on the gap side, by using suitable vehicle properties in the .uzz file

In principle, one MSP can be used multiple inside the same vehicle, and also by multiple vehicles inside the same vehicle set. That was common in older BAHN versions for standard vehicles to use less main memory. For instance, many bidirectional cars used the same MSP1 for their right and left view. However, AFAIK the editors for user-defined vehicles never supported to use this optimization because of the complicated handling, resulting in longer but more simple files.

Length (in MSP):

#define MAXFSYMLEN 32 (since BAHN 3.59 Beta7 1999-10-24)

Examples:

• 1: Field railway loco and trailers
• 3: typical 2x tram 1930..1960, ET57, KSW
• 4: all PCC 4x cars (15m original <=> 4 MSP, results in usual BAHN vehicle scale: Length in MSP = original length in mm / 3750)
• 18: EMU DB ET420
• 27: BVG Berlin metro H type

The MSP are counted from 0..63, separately for MSP1 and MSP2. In result, a vehicle set can contain at max. 64 MSP. As told above, the multiple use of MSP inside a vehicle or set was not supported by known editors. In result, the summary length of all the vehicles of a set is limited to 64 MSP. This is the reason why the number of vehicles per set may be limited to less than 8, when the cars are too long.

Numbers of user-defined vehicle sets:

#define NUTZERFMSPSATZNR_MIN (4000 << 4) // minimum set number)
#define NUTZERFMSPSATZNR_PRODATEI 10 // number of sets per file)

Since BAHN 3.75, use always the set numbers 4000 to 4009. Depending on the position of the file in the list of .ufg files, BAHN maps these numbers to correct values (e.g. file #2 set #4002 becomes 4022 in the layout file).
Until BAHN 3.70, the numbers 4000 to 4095 could be used freely. However, any known versions of FZGEDI/CAREDI/GE used 4000 to 4009 and created data that are compatible with the new definition.

File structure

Header and Seek Table

Example most simple case of a seek table (1 vehicle set only):

WORD16 Set number = 4000<<4
WORD32 Offset = 2
WORD16 end sign = 0


Data Blocks

Further, the MSP numbers can get one of the both following bit masks:

#define FMSPDAMPF_ANFG 0x80 (Steam begin)
#define FMSPDAMPF_ENDE 0x40 (Steam end)

_ANFG creates steam in an angle area around a virtual chimney. _ENDE creates steam in a rectangle area and may be arranged multiple side by side. Normally, mark the MSP with the chimney as _ANFG, and the next one[s] with _ENDE, where _ENDE may be omitted in case of small locos. In the front view, the marking should be moved by 1 or 2 MSP to top, because the chimney is displayed more above.

Graphics Data

After all vehicle assignments, there follow the graphics data. First all MSP1, then all MSP2, one after the other, without separator or terminator.

They consist of BYTE[pixcount] where one byte represents one pixel as in 256-colors.

Calculation of picxount:

(Number of MSP1) * 14 * 8 + (Number of MSP2) * 4 * 8

Vehicle Set Data, Old Style (.uzz)

With BAHN 3.83, this format was replaced by .nfz format, but it is still supported to load older user-defined vehicles.

An .uzz file holds additional data of a vehicle set of up to 8 cars. The graphics data are stored in an .uzz file of the same name. For correct loading, both files must exist and suitable.

BAHN does no more allow to offer complete trains consisting of single vehicles (as in BAHN 3.20). In result, the 2 files and 2 sorts of "vehicle sets" are obsolete, however they are still in use for some compatibility reasons (with 3.83 replaced by new .nfz format).

Range for user-defined vehicle set numbers (per file at max NUTZERFZGSATZ_PRODATEI):

#define NUTZERFZGSATZ_PRODATEI 10
#define NUTZERFZGSATZ_MIN 50000


Max. Length of name of a vehicle set incl. '\0':

#define ZUGGNAMESIZE 22

There are at max. NUTZERFZGSATZ_PRODATEI user-defined vehicle sets.

File structure

Header and Seek Table

Example most simple case of a seek table (1 vehicle set only):

WORD16 Log. number = NUTZERFZGSATZ_MIN
WORD32 Offset = 2
WORD16 end sign = 0


The BAHN-Standard-data use log. numbers of 1..NUTZERFZGSATZ_MIN-1.

Data Blocks

For each vehicle set, there is a data block. As terminator, the last data block consists of logical number 0 only.

After all text lines, the vehicles follow:

Vehicle

Let the trains run...
Jan Bochmann