View on GitHub

ezEngine Documentation

The documentation for ezEngine

ezTexConv

TexConv is a command-line tool to process textures from typical input formats like PNG, TGA, JPEG and DDS into optimized formats for runtime consumption. The most common scenario is to convert a single input file A.xxx into an optimized format B.yyy. However, the tool has many additional options for advanced uses.

Command-line Help

Run TexConv.exe with the --help parameter to list all available options. Additionally, TexConv prints the used options when it is executed, to help understand what it is doing. Consult this output for details.

General Usage

TexConv always produces exactly one output file. It may use multiple input files to assemble the output from. For the assembly, it also needs a channel mapping, which tells it which channel (Red, Green, Blue or Alpha) to take from which input file and move it into which channel of the output image.

The most straight forward command line is this:

TexConv.exe -out D:/result.dds -in0 D:/img.jpg -rgba in0

Multiple Input Files

To assemble the output from multiple input files, specify each input file using the -in option with an increasing number:

-in0 D:/img0.jpg -in1 D:/img1.jpg -in2 D:/img2.jpg ...

When assembling a cubemap from 2D textures, one can also use -right, -left, -top, -bottom, -front, -back or -px, -nx, -py, -ny, -pz, -nz.

To map these inputs to the output file, a proper channel mapping is needed.

Channel Mappings

The channel-mapping options specify from which input to fill the given output channels. You can specify the input for each channel individually like this:

-r in0.b -g in0.g -b in0.r -a in1.r

Here the RGB channels of the output would be filled using the first input image, but red and blue will get swapped. The alpha channel of the output would be filled with the values from the red channel of the second input image.

Specifying the mapping for each channel separately gives the greatest flexibility. For convenience the same can be written using “swizzling” operators:

-rgb in0.bgr -a in1.r

Output Channels

The following channel-mapping options are available:

Mentioning only the R, RG or RGB channel, instructs TexConv to create an output file with only 1, 2 or 3 channels respectively.

Input Swizzling

When stating which input texture should fill which output channel, one can swizzle the input:

One may also fill channels with either black or white:

Common Options

The most interesting options are listed below. More options are listed by TexConv --help.

Output Type

Image Compression

Mipmaps

By default, TexConv generates mipmaps when the output format supports it.

Usage (sRGB / Gamma Correction)

The -usage option specifies the purpose of the output and thus tells TexConv whether to apply gamma correction to the input and output files. The usage only affects the RGB channels. The alpha channel is always considered to contain ‘linear’ values. If usage is not specified, the ‘auto’ mode will try to detect the usage from the format and file-name of the first input image. For instance, single and dual channel output formats are always linear. Check the output to see what decision TexConv made.

Image Rescaling

Examples

Convert a Color Texture

TexConv.exe -out D:/diffuse.dds -in0 D:/diffuse.jpg -rgba in0 -usage color

Convert a Normal Map

TexConv.exe -out D:/normalmap.dds -in0 D:/normalmap.png -rgb in0 -usage normalmap

Create an HDR Cubemap

TexConv.exe -out "D:/skybox.dds" -in0 "D:/skymap.hdr" -rgba in0 -type cubemap -usage hdr

A great source for HDR cubemaps is hdrihaven.com.

Bake Multiple Images into One

TexConv.exe -out "D:/Baked.dds" -in0 "D:/metal.tga" -in1 "D:/roughness.png" -in2 "D:/DiffuseAlpha.dds" -r in1.r -g in0.r -b black -a in2.a -usage linear

Extract a Single Channel

TexConv.exe -out D:/alpha-mask-only.dds -in0 D:/DiffuseAlpha.dds -r in0.a

See Also