View source for Texture file

{{ORP-top}}
;Descripton
Trainz '''Texture files''' are ASCII text format specification files describing a single texture. Texture files have a ".texture.txt" name extension, however when a texture file is specified within a [[Config.txt file]] or similar, the ".txt" must be omitted, leaving the ".texture" extension.

Files with '''*.texture.txt''' extension are used to configure texture behavior in Trainz. These files are located in the same folder as the source texture files, typically .bmp, .tga or .jpg, and make reference to them.  These files are typically generated automatically by the exporter or importer but may be edited by hand when specialization is required.

This page describes content format v4.1.


'''Scope:''' This guideline applies to each of the following Trainz {{wp|data type|type specifications}}:
:''[[KIND Texture]], [[KIND Groundtexture]], [[Alpha masking]], [[.texture.txt Files|Miscellaneous.texture.txt Files]], and the [["Thumbnails" container]]''.

:''Related data types: "Texture-variants" container'' (asset provides alternative material configurations for the texture to display as seasonal variants.) 


==File format==

The user-editable *.texture.txt files are ASCII text formatted key-value pairs with the following options. Please note that this format is not the same (despite some similarities) as other text-based formats used by Trainz. Please be aware of the [[filename character restrictions]] when naming texture and image files.

;Syntax
Each token is specified on a new line. There is no white space on either side of the '=' sign. A empty value is sometimes valid. The syntax is:

 <token>=<value>

;Example:
 Primary=WayCoolTexture.tga
 Alpha=WayCoolTexture.tga
 Tile=st
 AlphaHint=masked
''(Example only, not recommended settings)''


===Tokens and Values===

 Primary=diffusemap.bmp

This tag specifies the filename of the image file representing the color (R, G, B) channels of the texture. Any alpha channel in the image file is ignored. The resultant texture will have a pure white (100%) alpha channel.


 Primary=diffusemap.jpg
 Alpha=diffusemap.bmp

This tag combination specifies the filenames of the image file representing the color (R, G, B) channels of the texture and the image file representing the alpha (A) channel of the texture. The alpha channel image should be grayscale. Neither file should contain an alpha channel. The two image files must be of identical size.


 Primary=diffusemap.tga
 Alpha=diffusemap.tga

This tag combination specifies the filename of a single image file representing the color and alpha (R, G, B, A) channels of the texture. In this case both tags must reference the same filename. The image file must contain an alpha channel.


 Compression=dxt3

This tag hints the usage of a particular texture compression scheme. If you don't have a specific effect in mind, don't include this tag. Valid options are currently 'none', 'dxt1', 'dxt3', 'dxt5'. Refer [[DXT Compression]].

The current selection logic for texture compression is as follows, however it should be noted that this may change between Trainz versions. The first matching rule is used.

* "Compression=none" forces no compression. This gives the best visual result for a given input image, but typically yields worse visual results per output texture filesize. It is often better to activate compression and double the image dimensions, rather than disabling compression.
* Images with an "opaque" alpha hint use DXT1 compression.
* "Compression=dxt3" will use DXT3 compression.
* DXT5 compression is used.


 NormalMapHint=normalmap

The 'NormalMapHint' tag allows the texture to be specified as a [[normal map]]. By default, Trainz will assume that your texture is a [[diffuse map]] and will apply some processing options which are not appropriate for normal maps. You must specify this option for normal maps. Valid options are 'none' and 'normalmap'.


 ModifyMap=flipgreen

The 'ModifyMap' option allows a texture's green color channel to be flipped.  Some programs such as 3ds Max create [[normal map]]s with the Y axis facing the opposite way to what is expected by the Trainz shaders.  This option can be used to make the bump effect look correct in Trainz. The option is applied by the [[Content Manager]] upon Commit. Valid options are 'none' and 'flipgreen'.


 AlphaHint=opaque

The 'AlphaHint' tag allows you to force a particular alpha mode on the texture. Valid options are 'opaque' (meaning that the alpha channel is overwritten with pure white), 'semitransparent' (meaning that the alpha channel is a grayscale blend) and 'masked' (meaning that the alpha channel is clamped to a pure black&white bitmap based on a 50% threshold.) If omitted, Trainz will supply an appropriate value for this tag based on the actual contents of the Alpha channel.



 Tile=st

Tiling refers to the ability for texture coordinates outside the range of (0.0 .. 1.0) to be treated as valid coordinates on an infinitely tiled texture. With tiling active, coordinates which pass the right/bottom side of the texture effectively wrap back onto the left/top side, and so on. Valid options include 's' (tile horizontally), 't' (tile vertically), 'st' (tile both horizontally and vertically), and 'none' (do not tile the image).


 MipAlgorithm=tend-towards-opaque

The default [[mipmap]] generation algorithm tends to make semi-transparent dithers (such as chain-link fences or tree leaves) appear more transparent in the distance. This occurs because the multiple texels of alpha in the high-detail source image (100%, 0%, 100%, 0%) are blended to a single pixel in the lower mips (50%.) The net result is that the average opacity level remains the same, but that the maximum value is reduced. Coupled with the fact that overlapping layers of semi-opaque textures do not necessarily increase the output opacity (a rendering limitation relating to performance) the net result is that something which might be quite opaque close-up may become ghostly in the distance. An alternate "tend-towards-opaque" algorithm may be selected for mipmap generation, which defeats this issue by biasing opacity toward the maximum. This increases average opacity for distant objects, and has the side effect of making soft edges become hard and potentially "blocky". It should only be used where the default algorithm gives decidedly sub-optimal results.


==Image formats==
The following image formats are acceptable as source data for the Texture file:

* Targa (.tga) files. Targa is a lossless image format with optional compression and optional alpha channel.
* JPEG (.jpg) files. JPEG is a lossy image compression format with no alpha channel support.
* Windows Bitmap (.bmp) files. BMP is a lossless image format with no compression and optional alpha channel.

These images in association with the appropriate *.texture.txt file are used by [[Content Manager]] to create the N3V binary textures that are used internally in the simulator. All built-in content has only N3V binary textures that cannot be opened with normal imaging software.

Images must be no more than 4096 pixels in either dimension, although it is strongly recommended that images are kept below this maximum. Uniform-color images should be as small as possible - certainly no larger than 16x16. Images must be power-of-two dimensions on each side, but need not be square.


==Notes on Image Editors==
* The Targa Exporter plugin shipped with some older versions of Adobe Photoshop is broken and silently corrupts or discards alpha channels; a free update is available which resolves this issue.
* Some image editors do not support alpha channels on BMP files.


==.txt file extension==
Texture files have a ".texture.txt" name extension, however when a texture file is specified within a [[Config.txt file]] or similar, the ".txt" must be omitted, leaving the ".texture" extension.
For example, a texture file named ''grass.texture.txt'' is specified in a [[KIND Groundtexture]] config file using the syntax ''texture "grass.texture"''.

==Use of image files in place of texture files==
Trainz previously supported using ''any supported image file'' type in place of a [[Texture file]]. [[TANE]] does not support this technique; a texture.txt file must be used.

[[Category:File formats]]
{{ORP-bot}}