MakeACE Release Notes

---------------------

Instructions
------------

* Purpose of this utility

The MakeACE utility converts industry-standard image file formats into the
Kuju image file format known as ACE (extension .ACE) which can be used with
Microsoft Train Simulator. MakeACE supports Windows Bitmap files (extension
.BMP) which contain 24-bit RGB encoded images and Truevision Targa files
(extension .TGA) which contain 24-bit RGB encoded or 32-bit RGBA (Red, Green,
Blue + alpha "translucency" channel) encoded images.

ACE files are used for textures applied to shapes (henceforth texture ACEs)
and bitmaps used for the cab panels and controls (henceforth bitmap ACEs).

The ACE files you create can be one of three types:

i) Solid - these are created by converting 24-bit BMP or TGA files and the
resulting ACE file contains only solid pixels. You might use such ACE
files for the general texture detail on buildings and trains you are
creating.
ii) Trans - these are created by converting 32-bit TGA files and specifying
the transparency mask option. The resulting ACE file will contain both
solid pixels and transparent pixels. You can still use solid areas of
this ACE type for the general texture detail on your object but in
addition you can use areas containing transparent pixels for details such
as railings, ladders and other areas that require the appearance of a
"hole" in your object. This is also a good choice for simple cab
backgrounds and controls.
iii) Alpha - these are creating by converting 32-bit TGA files and not
specifying the transparency mask option. The resulting ACE files will
contain solid and both partially and completely transparent pixels. This
texture type can be used in a similar way to the Trans type, except it
also allows you to create effects such as tinted windows.

Additionally you can choose which compression type to use when creating your
ACE file, if any. There are three choices:

i) No compression - the image is stored uncompressed.

ii) ZLib compression - this is a lossless compression technique similar to
that used by programs such as PKZIP and WinZip.
iii) DXT compression - this is a lossy technique that can only be used for
Solid and Trans type texture ACE files. DXT compression cannot be used
for bitmap ACE files.

It is recommended that you use either ZLib or DXT compression as there is

unlikely to be any advantage gained from using no compression at all.

For Alpha type ACE files you cannot use DXT, so the recommended option is
ZLib.

For Trans and Solid type ACE files you could choose to use DXT. This will not
result in as small a file size on your hard disk as ZLib would produce,
however many modern graphics cards support DXT compression and so can store it
in memory still compressed which allows your graphics card to store more
textures that would be possible with ZLib compressed or uncompressed ACE
files. If a graphics card does not support DXT the file will be decompressed
when it is loaded into the game.

The only issue to consider is that DXT is a lossy technique which can produce
artifacts in the compressed image. Therefore, you may wish to experiment with
DXT and ZLib compression to determine whether there is a noticable reduction
in image quality when using DXT compression with a particular image.

Texture and bitmap ACEs differ in four important ways:

i) Texture ACEs contain MIPMAPS which are used when rendering shapes in
the distance, bitmap ACEs do not contain MIPMAPs.
ii) Textures must be a minimum of 32x32 and a maximum of 512x512. Bitmaps
can be a minimum of 1x1 and a maximum of 1024x1024.
iii) Texture ACEs must be square, i.e. the width must equal the height, e.g.
256x256 is OK, 256x512 is not.
iv) Texture ACEs must have dimensions which are an integral (whole number)
power of two, i.e. their width and height must be powers of two e.g.
256x256 is OK, 200x200 is not, as two to the power seven is 128 and
two to the power eight is 256, thus 200 is not an integral power of two.

Therefore valid source and destination image sizes for creating a texture
ACE are 32x32, 64x64, 128x128, 256x256 and 512x512.

Additionally, the source BMP or TGA file for a bitmap ACE must meet the
criteria for a texture ACE, except you may also use a source image of size
1024x1024. However, the destination image can be cropped to contain only the
top left corner of the source image using the width and height command line
options.

Hence, valid sizes for the source image when creating a bitmap ACE are 32x32,
64x64, 128x128, 256x256, 512x512 and 1024x1024.

The destination image size when creating a bitmap ACE can be any size from 1x1
to the size of the source image.

One final factor is that depending on the application used to create your
source images you may find that your ACE file has been created upside down.
If this occurs there is an option to flip the image during the conversion
process.

* Usage

MakeACE is a command-line utility, that is it must be used from a DOS or

command prompt window within Windows or using the Run option on the Start
Menu. The MakeACE command-line is constructed as follows:

MakeACE <input file> <output file> [options]

The possible command line options are detailed below:

-trans

Creates a Trans type ACE file from a source 32-bit TGA file

-flip

Flips the source image during the conversion process.

-zlib
Uses ZLib compression.

-dxt

Uses DXT compression if the source image is Solid or Trans.

-bmp

Creates a bitmap ACE file with no MIPMAPs and allows the use of the width and
height options.

-width:<nnn>
-height:<nnn>

Used with the bitmap option to crop the contents of the destination image to
the top-left corner of the source image.

* Examples

MakeACE texture.ace texture.bmp

Convert 24-bit BMP file "texture.bmp" to uncompressed Solid type ACE file
"texture.ace".

MakeACE texture.ace texture.tga -trans

Convert 32-bit TGA file "texture.tga" to uncompressed Trans type ACE file
"texture.ace".

MakeACE texture.ace texture.tga -flip

Convert TGA file "texture.tga" to uncompressed Solid (if TGA is 24-bit) or

Alpha (if TGA is 32-bit) ACE file, flipping the image vertically during the
conversion process.

MakeACE texture.ace texture.bmp -zlib

Convert 24-bit BMP file "texture.bmp" to ZLib compressed Solid type ACE file
"texture.ace".

MakeACE texture.ace texture.bmp -dxt

Convert 24-bit BMP file "texture.bmp" to DXT compressed Solid type ACE file
"texture.ace".

MakeACE texture.ace texture.tga -dxt -trans

Convert 32-bit TGA file "texture.tga" to DXT compressed Trans type ACE file
"texture.ace".

MakeACE bitmap.ace bitmap.tga -bmp -width:640 -height:480

Convert 32-bit TGA file "bitmap.tga" (size 1024x1024) to uncompressed Alpha

type ACE file "bitmap.tga" (size 640x480), storing the top-left 640x480 corner
of the source image in the destination image. This is the recommended way to
create a 640x480 cab background from a 1024x1024 source image which contains
the cab background in the top-left 640x480 pixels and black in the remainder
of the image.
MakeACE bitmap.ace bitmap.tga -bmp -width:1024 -height:768

Convert 32-bit TGA file "bitmap.tga" (size 1024x1024) to uncompressed Alpha

type ACE file "bitmap.tga" (size 1024x768), storing the top 768 rows of pixels
of the source image in the destination image. This is the recommended way to
create a 1024x768 cab background from a 1024x1024 source image which contains
the cab background in the top 768 rows and black in the remainder of the
image.

MakeACE bitmap.ace bitmap.tga -bmp -width:1024 -height:768 -trans -zlib

Convert 32-bit TGA file "bitmap.tga" (size 1024x1024) to ZLib compressed Trans
type ACE file "bitmap.tga" (size 1024x768), storing the top 768 rows of pixels
of the source image in the destination image.

Update History
---------------

* Prevented the user from creating bitmap ACEs with DXT compression.

* Added DXT compression.

* Added ZLib compression.

* Added -flip command line option to handle images which have been created
with unusual co-ordinate origins.

* Removed artificial minimum size limit for bitmaps.

* Added support for exporting arbitrarily sized bitmaps for creation of cab
views and controls