This DirectXTex sample is an implementation of the texconv
command-line texture utility from the DirectX SDK utilizing DirectXTex rather than D3DX. This tool loads an image and prepares it for runtime use by resizing, format conversion,
mip-map generation, block-compression, and writes the result in a file format suited for runtime use.
To create cubemaps, volume maps, or texture arrays from individual files, use
Texconv.exe uses the following command syntax:
texconv [-w number] [-h number] [-m number] [-f format] [-if filter] [-srgb | -srgbi | -srgbo] [-px string] [-sx string] [-o directory] [-ft file-type] [-hflip] [-vflip] [-sepalpha] [-wrap | -mirror] [-pmalpha] [-fl feature-level] [-pow2] [-tu | -tf] [-dword] [-xlum] [-dx10] [-nologo] [-singleproc] [-nogpu] [-aw number] [-nmap flags] [-nmapamp number] [-bcuniform] [-bcmax] [-bcdither] [-timing]
The file-name parameter indicates the file(s) to convert.
The optional command-line switches are described in the following table.
Optional Switches Description
- -w number Width of the output texture in pixels.
- -h number Height of the output texture in pixels.
- -m number Number of mipmap levels to generate in the output texture. This setting only applies to DDS output.
- -f format Output format. Specify the DXGI format without the DXGI_FORMAT_ prefix (i.e. "-f BC1_UNORM").
- -if filter Image filter. Use one of the following: POINT, LINEAR, CUBIC, FANT, BOX, TRIANGLE, POINT_DITHER, LINEAR_DITHER, CUBIC_DITHER, FANT_DITHER, BOX_DITHER, TRIANGLE_DITHER, POINT_DITHER_DIFFUSION, LINEAR_DITHER_DIFFUSION, CUBIC_DITHER_DIFFUSION,
FANT_DITHER_DIFFUSION, BOX_DITHER_DIFFUSION, or TRIANGLE_DITHER_DIFFUSION. Filters with DITHER in their name indicate that the 4x4 ordered dither algorithm, while "DITHER_DIFFUSION" is error diffusion dithering.
- -srgb, -srgbi, or -srgbo Use sRGB if both the input and output data are in the sRGB color format (ie. gamma ~2.2). Use sRGBi if only the input is in sRGB; use sRGBo if only the output is in sRGB.
- -px string Text string to attach to the front of the resulting texture's name.
- -sx string Text string to attach to the end of the resulting texture's name.
- -o directory Output directory.
- -ft file-type A file type for the output texture. Use one of the following: bmp, dds, jpg, png, or tiff. The default value is dds.
- -hflip Perform horizonal flip of image
- -vflip Perform horizonal flip of image
- -sepalpha Separates alpha channel for resize/mipmap generation. This implies an alpha mode setting of DDS_ALPHA_MODE_CUSTOM as this is typically only used if the alpha channel doesn't contain transparency information.
- -wrap, -mirror Sets the texture addressing mode for filtering to wrap or mirror, otherwise defaults to clamp.
- -pmalpha Converts the final texture data to use premultiplied alpha. This sets an alpha mode of DDS_ALPHA_MODE_PREMULTIPLIED unless the entire alpha channel is fully opaque.
- -pow2 Fits each texture to a power-of-2 for width & height, minimizing changes to the aspect ratio.
- -fl feature-level Sets the target feature level which determines the maximum supported texture size. Defaults to "11.0" which is 16834, the limit for 11.0 and 11.1 Feature Level hardware.
- -tu DDS files with TYPELESS formats are treated as UNORM
- -tf DDS files with TYPELESS formats are treated as FLOAT
- -dword For DDS files use a DWORD alignment instead of BYTE alignment (used for some legacy files)
- -xlum DDS files with L8, A8L8, or L16 formats are expanded to 8:8:8:8 or 16:16:16:16
- -dx10 Forces DDS file output to always use the "DX10" header extension, and allows the writing of alpha mode metadata information. The resulting file may not be compatible with the legacy D3DX10 or D3DX11 libraries.
- -nologo Suppress copyright message.
- -singleproc If the DirectXTex library and the texconv utility are built with OpenMP enabled, by default the tool will use multi-threading for CPU-based compression of BC6H and BC7 formats to spread the compression work across multiple cores. This
flag disables this behavior forcing it to remain on a single core.
- -nogpu When compressing BC6H / BC7 content, texconv will use DirectCompute on the GPU if available. Use of this flag forces texconv to always use the software codec instead.
- -aw number Provides an alpha weighting to use with the error metric for the BC7 GPU compressor. Defaults to 1.0.
- -nmap flags Indicates conversion from a height-map to a normal-map. The
flags is a combination of one or more of the following, and must have one of
r, g, b, a, or l:
- r Use the red channel of the input as the height
- g Use the green channel of the input as the height
- b Use the blue channel of the input as the height
- a Use the alpha channel of the input as the height
- l Use the luminance computed from red, green, and blue channels of the input as the height
- m Use mirroring in U & V. Defaults to wrap when doing the central difference computation.
- u Use mirroring in U. Defaults to wrap when doing the central difference computation.
- v Use mirroring in V. Defaults to wrap when doing the central difference computation.
- i Invert sign of the computed normal
- o Compute a rough occlusion term and encode it into the alpha channel of the output.
- -nmapamp number Indicates an amplitude for the normal map, which defaults to 1.
- -bcuniform Uses uniform weighting rather than perceptual (BC1-BC3)
- -bcmax Uses maximum compression (BC7: enables mode 0 & 2 usage)
- -bcdither Uses dithering (BC1-BC3)
- -timing Displays compression timing information
Open a Command Prompt
, and change to the directory containing Texconv.exe (i.e. ...\DirectXTex\Texconv\Release)
Enter the following command-line after changing to the appropriate directory:
texconv -pow2 -f BC1_UNORM cat.jpg
This loads a JPEG image 'cat.jpg', resizes the image to a power of 2 in each dimension (if the original was 512 x 683 it is resized to 256 x 512), mipmaps are generated, the file is converted to BC1_UNORM (aka DXT1) block compression, and written out
texconv -nmap lo -nmapamp 2 -f R8G8B8A8_UNORM heightmap.png
This loads the PNG image 'heightmap.png', converts it to a normal-map using luminance and an amplitude of 2, and writes the data out as a 'heightmap.dds' with mipmaps and an occlusion term in the alpha channel using the R8G8B8A8_UNORM format.