[<< wikibooks] Trainz/refs/texture.txt file
== Introduction ==

Text files names with *.texture.txt suffix and extension are used as the preferred method of specifying graphics file options and processes in virtually every asset containing non-baked-in texture painted meshes for their purpose is to configure graphics textures behavior in Trainz. These files may also control how textures are processed by Content Manager, notably by providing pathspecs, and triggering additional validations to best generate healthy assets.
These files are, through ignorance or the workings of the exporters, generally located in the same folder as the source texture files, typically .bmp, .tga or .jpg, and make reference to them, but can utilize some basic DOS/Windows file structure navigation one folder level removed, but not two. 
These are control files which are generated automatically by the Trainz exporter or importer (i.e. Translator software from Gmax, Blender and AutoDesk's 3dsMax formats to Trainz data needs—Auran/N3V sources and updates these from time to time) but may be edited by hand when specialization is required.
The first three or four lines are the most common and in fact, most texture.txt files have only two to four lines, unlike the below:

 


== 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:

=

Texture.txt files may be commented using the C++ 'hack-hack' comment style:

// This file was created for TRS2006-SP1 then retrograded to trainz-build 2.0 for TRS2004


== Tokens ==
Here is a list of supported tokens. Any other values should not be used.

Further, It must be understood thatthe mesh and the texture.txt file are always in the same folder.
The texture itself can be in a common location, and referenced by several meshes of the asset (how many black.tga textures do the 8 or more meshes of a Steam Locomotive need?), but the referencing is via the texture.txt file whose name must match with the name the mesh is referencing. i.e. The mesh refers to the name of the texture.txt file, which need not match that of the texture used as the Primary within.
Assuming a common texture file, different mesh names and/or locations, and a different 'look' from additional graphics:
four of the eight in the above example each with a different name' can reference the same texture and use identical processing 'tokens', but each must exist to support it's referencing from within the mesh file.
two of the remaining could be referencing an entirely different 'black2.tga'
and the others the same but with a different mix of the tokens presented above in the composite example, and detailed below.
The points to master are the Onto relationship of a texture.txt file and mesh file, and that the texture name and location can be very different—there is no reason they need be co-located with either the mesh or the texture.txt file. The later has the job of marrying the two and defining the way THAT MESH renders the texture image. 

In the below, we'll present a 'example line' in the same sections. And amplifying commentary in () following.


=== Primary ===
Specify texture file name

 - Primary texture. Filename including extension.Primary=common_textures\Red-roof-tiles.tga 
(The MESH location is in folder containing a subfolder named 'common_textures', so likely the Asset's root folder '..\editing\username'.)Primary=..\green-siding.tga
(The MESH location is in a sub-folder and 'common_textures' are in the level above, likely the asset's root folder)Primary=..\traincar_left_door\brass-window-trim.tga 
(The MESH location is likely in a '..\traincar_right_door\' 'sister folder' from it's relative containing the 'shared_texture'. Likely, both are sub-folders of a '\traincar_asset-name_body' folder. This example from tests using a Randall Whitepass Pullman coach, and the brass.tga texture.) 


=== Alpha ===
Specify alpha channel for texture. Note that if there is only one 32bit file with RGB and A channels, this must still be specified with the same name used in Primary

 - Alpha texture, may be the same or different from the primary


=== Tile ===
Wrap texture addressing horizontally, vertically or both. Otherwise texture is clamped.

 - (default) No wrapping
s - Wrap horizontally
t - Wrap vertically
st - Wrap both horizontally and vertically


=== Dimension ===
Number of dimensions the texture has. Not required since only 2D textures are currently supported.

two - (default) Two dimensional
cube - (unsupported)
volume - (unsupported)
one - (unsupported)


=== Compression ===
Compression format used by CMP. If this is not supplied, format is chosen automatically.

none - Do not compress. Warning: Uncompressed textures consume large amounts of memory and slow performance.
dxt1 - Suitable for opaque or alpha masked textures
dxt3 - Alternately the best for alpha blended textures if the texture contains sharp contrasts. Try DXT5 first.
dxt5 - Usually the best for alpha blended textures


=== Hint ===
Texture usage hint, for internal use only. Note this should NOT be used to try and disble mip mapping.

static - (default) Standard texture resource
dynamic - Texture will be modified in memory


=== NormalMapHint ===
Hint about texture being a normal map. Important to use as this will affect final texture quality. Compression, mip map generation and renormalization of XYZ (RGB) is effected.

none - (default) This is not a normal map
normalmap - This is a normal map


=== ModifyMap ===
Allows the texture to be modified when the texture.txt file is read. Currently this is to allow the green channel (Y axis) to be flipped for normal maps. 

none - (default) Do not modify texture
flipgreen - flip green channel which is Y Axis of normal map


=== AlphaHint ===
Specify how the alpha channel is used. Affects final alpha quality. May also affect texture compression and mip generation.

opaque - (default with no alpha present) No alpha channel used.
semitransparent - (default with alpha present) Alpha blended
masked - Alpha masked - this gives 8-bit grayscale shading from full transparency to fully blocking the object depending upont the pixel by pixel values of the Alpha channel or mask.


=== Anisotropy ===
Anisotropic sampling quality. The higher the number, the better the visual quality but at significant performance cost. Where texture quality is needed specify a higher value. Trainz can now control anisotropy via a slider, so the highest setting is used by default. 

1 - No anisotropic filtering
2 - Low
4 - Medium
8 - High
16 - (default) Very High


=== AutoMip ===
Auto mip map generation. Chris, is this depricated? CMP now generates mip maps at highest quality instead of game load/run time.

none - Don't generate mip maps
default - (default) Whatever the default method is
fastest - Attempt to improve load time at expense of quality
nicest - Attempt to improve quality regardless of time


=== MagFilter ===
Texture sampling filter used when texture is magnified

nearest - No blending with neighboring texels
linear - (game default) Blends with neighboring texels for smooth zoom effect
default - (default) Game default


=== MinFilter ===
Texture sampling filter used when texture is minified

nearest - No blending with neighboring texels
linear - (game default) Blends with neighboring texels for smooth shrink effect
default - (default) Game default


=== MipFilter ===
Texture sampling filter used on mip map selection

nearest - No blending with other mip maps
linear - (game default) Smooth blendig between mip maps (Note, operates independently but should be used in conjunction with anisotropic sampling)
default - (default) Game default
none - Disable mip map generation in CMP and use in game. Specifically for user interface elements.


= Comments & Suggestions =
Hint is mentioned even though it is intended for internal use only, because it has been used and abused by well meaning people since its discovery. Anisotropy should be used to improve texture quality, and MipFilter=none should be used to disable mip mapping only for interface textures.