DirectXTex sample is a command-line utility analyzing the content of images.
This tool is primarily used for debugging and development purposes.
Syntax
Texdiag.exe uses the following command syntax:
texdiag <command> [options] [--file-list <filename>] <file-name(s)>
The file-name parameter indicates the file(s) to diagnose using dds, tga, hdr, or a WIC-supported format (bmp, jpg, png, jxr, etc.).
The command-line parsing uses Windows-style
-or/for options. It also has some POSIX-like behavior: it supports--versionand--helpcommand-line options, and the use of--disables further options parsing to support filenames that begin with-or/characters. There are 'GNU long options' style command-line parameters that use--as well.
Commands
info: Outputs image metadata information such as width, height, format, etc.
analyze: Analyzes the image and generates statistics.
compare: Compares two images and returns the mean-square-error and peak-signal-to-noise ratio between them. Images must be the same size in width & height.
diff: Creates an image of absolute differences between two images. Images must be the same size in width & height.
dumpbc: Prints out the content of a BC compressed image in a human readable form. Can output all blocks or just a block for a given target pixel.
dumpdds: Writes out each individual frame of a complex DDS file.
Optional Switches Description
File options
-r: Input file names can contain wildcard characters (? or *). If this switch is used, subdirectories are also searched.
-flist filename, --file-list filename: Uses the provided filename as a text file containing a list of input files (one per line). Ignores lines that begin with # (used for comments). Does not support providing additional command-line arguments or the use of filename wildcards.
-o filename: Provides the output filename and file type for a diff command. Defaults to the same as the first input image as a bmp.
-l, --to-lowercase: Forces the output path & filename to all lower-case. Windows file system is case-insensitive by default, but some programs like git are case-sensitive.
-y, --overwrite: overwrite existing output file (if any) for diff command.
Filtering options
-if filter, --image-filter filter: Image filter used for loading WIC-based images required for some formats. 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.
DirectDraw Surface (DDS) file options
-tu, --typeless-unorm: DDS files with TYPELESS formats are treated as UNORM
-tf, --typeless-float: DDS files with TYPELESS formats are treated as FLOAT
Generally typeless formats will fail most operations, so these options let you override the type.
-dword, --dword-alignment: For DDS files that use a DWORD alignment instead of BYTE alignment (used for some legacy files typically 24bpp).
--bad-tails: For older DDS files that incorrectly encode the DXTn block compression mipchain surface blocks smaller than 4x4. This switch causes the loader to tolerate the slightly too short file length and to copy the 4x4 blocks to the smaller ones. The result is not identical to re-computing computing the mipchain fully, but does provide non-corrupted data.
--permissive: Allows some malformed and variant header files to be loaded.
--ignore-mips: Loads only the top-level mipmap, which is useful for some malformed files that are missing data.
-xlum, --expand-luminance: DDS files with L8, A8L8, or L16 formats are expanded to 8:8:8:8 or 16:16:16:16. Without this flag, they are converted to 1-channel (red) or 2-channel (red/green) formats.
DIFF options
-f format, --format format: Provides the desired output format for a diff command. Defaults to BRGA32.
-c color, --diff-color color: Provide a 'highlight color' to use for the diff command. By default, no highlight is used. For example, use -c 00FF00 for a green highlight where the absolute difference exceeds a threshold.
-t float, --threshold float: Provides the threshold value in 0..1 for the diff command to control color highlighting (-c). Defaults to 0.25.
DUMPBC options
--target-x num, --target-y num: Provides a target pixel location for the dumpbc command. For DDS files with mipmap chains it will match the block that maps to the pixel location in subsequently lower mip-levels. By default dumpbc dumps out all blocks.
DUMPDDS options
-ft file-type, --file-type file-type: (dumpdds command only) A file type for the output texture. Use one of the following. The default value is bmp.
bmp: Windows BMPhdr: Radiance RGBEjpg,jpeg: Joint Photographic Experts Grouppng: Portable Network Graphicstga: Truevision Graphics Adaptertif,tiff: Tagged Image File Formatjxr: Windows Media Photo
Miscellaneous options
-nologo: Suppress copyright message.
Examples
The basic use for this tool is just printing out the metadata for the image:
texdiag info reftexture.dds
Results in the following output:
reftexture.dds
width = 256
height = 256
depth = 1
mipLevels = 9
arraySize = 1
format = B8G8R8A8_UNORM
dimension = 2D
alpha mode = Unknown
The analyzer computes statistics for the image:
texdiag analyze tex_dxt1.DDS
Results in the following output:
tex_dxt1.DDS
Results by item ( 1) and mip ( 8)
Result item 0, mip 0:
Minimum - (0.000000 0.000000 0.000000 1.000000)
Average - (0.046211 0.051364 0.043492 1.000000)
Maximum - (0.870968 0.825397 0.806452 1.000000)
Variance - (438.820526 402.858032 295.667084 0.000000)
Std Dev - (20.948044 20.071323 17.194973 0.000000)
Luminance - 0.794695 (maximum)
Compression - BC1_UNORM
Total blocks - 1024
4 color blocks - 132
3 color blocks - 892
Result item 0, mip 1:
Minimum - (0.000000 0.000000 0.000000 1.000000)
Average - (0.046072 0.051374 0.043398 1.000000)
Maximum - (0.838710 0.746032 0.677419 1.000000)
Variance - (108.159210 98.821289 71.980316 0.000000)
Std Dev - (10.399962 9.940889 8.484121 0.000000)
Luminance - 0.762739 (maximum)
Compression - BC1_UNORM
Total blocks - 256
4 color blocks - 45
3 color blocks - 211
Result item 0, mip 2:
Minimum - (0.000000 0.000000 0.000000 1.000000)
Average - (0.046266 0.051228 0.043741 1.000000)
Maximum - (0.806452 0.698413 0.612903 1.000000)
Variance - (26.114519 23.424675 17.333866 0.000000)
Std Dev - (5.110237 4.839904 4.163396 0.000000)
Luminance - 0.721418 (maximum)
Compression - BC1_UNORM
Total blocks - 64
4 color blocks - 14
3 color blocks - 50
Result item 0, mip 3:
Minimum - (0.000000 0.000000 0.000000 1.000000)
Average - (0.045741 0.050141 0.042297 1.000000)
Maximum - (0.677419 0.650794 0.645161 1.000000)
Variance - (6.148984 5.431025 3.997676 0.000000)
Std Dev - (2.479715 2.330456 1.999419 0.000000)
Luminance - 0.602960 (maximum)
Compression - BC1_UNORM
Total blocks - 16
4 color blocks - 8
3 color blocks - 8
Result item 0, mip 4:
Minimum - (0.000000 0.000000 0.000000 1.000000)
Average - (0.044355 0.052497 0.041667 1.000000)
Maximum - (0.666667 0.544974 0.451613 1.000000)
Variance - (1.234477 0.926867 0.652908 0.000000)
Std Dev - (1.111070 0.962739 0.808027 0.000000)
Luminance - 0.568846 (maximum)
Compression - BC1_UNORM
Total blocks - 4
4 color blocks - 4
3 color blocks - 0
Result item 0, mip 5:
Minimum - (0.000000 0.015873 0.032258 1.000000)
Average - (0.044355 0.051587 0.056452 1.000000)
Maximum - (0.354839 0.301587 0.225806 1.000000)
Variance - (0.164383 0.106576 0.048907 0.000000)
Std Dev - (0.405442 0.326460 0.221150 0.000000)
Luminance - 0.309227 (maximum)
Compression - BC1_UNORM
Total blocks - 1
4 color blocks - 1
3 color blocks - 0
Result item 0, mip 6:
Minimum - (0.000000 0.031746 0.032258 1.000000)
Average - (0.048387 0.055556 0.048387 1.000000)
Maximum - (0.096774 0.079365 0.064516 1.000000)
Variance - (0.009365 0.002268 0.001041 0.000000)
Std Dev - (0.096774 0.047619 0.032258 0.000000)
Luminance - 0.082954 (maximum)
Compression - BC1_UNORM
Total blocks - 1
4 color blocks - 0
3 color blocks - 1
Result item 0, mip 7:
Minimum - (0.048387 0.055556 0.048387 1.000000)
Average - (0.048387 0.055556 0.048387 1.000000)
Maximum - (0.048387 0.055556 0.048387 1.000000)
Variance - (0.000000 0.000000 0.000000 0.000000)
Std Dev - (0.000000 0.000000 0.000000 0.000000)
Luminance - 0.052616 (maximum)
Compression - BC1_UNORM
Total blocks - 1
4 color blocks - 0
3 color blocks - 1
The tool can be used to compute an error metric between two images:
texdiag.exe compare reftexture.dds reftexture_dxt1.DDS
Results in the following output:
1: reftexture.dds
2: reftexture_dxt1.DDS
Results by item ( 1) and mip ( 9)
[ 0, 0]: 0.000007 (0.000003 0.000001 0.000003 0.000000) PSNR 56.426357 dB
[ 0, 1]: 0.000094 (0.000033 0.000029 0.000033 0.000000) PSNR 45.034111 dB
[ 0, 2]: 0.000240 (0.000083 0.000073 0.000083 0.000000) PSNR 40.974899 dB
[ 0, 3]: 0.005770 (0.000604 0.000579 0.004586 0.000000) PSNR 27.159737 dB
[ 0, 4]: 0.067044 (0.033618 0.001000 0.032426 0.000000) PSNR 16.507608 dB
[ 0, 5]: 0.014921 (0.007250 0.000319 0.007352 0.000000) PSNR 23.033331 dB
[ 0, 6]: 0.001642 (0.000840 0.000101 0.000701 0.000000) PSNR 32.618088 dB
[ 0, 7]: 0.000287 (0.000125 0.000012 0.000151 0.000000) PSNR 40.190742 dB
[ 0, 8]: 0.000425 (0.000208 0.000009 0.000208 0.000000) PSNR 38.488575 dB
Minimum MSE: 0.000007 (0.000003 0.000001 0.000003 0.000000) PSNR 56.426357 dB
Average MSE: 0.010048 (0.004751 0.000236 0.003603 0.000000) PSNR 25.431186 dB
Maximum MSE: 0.067044 (0.033618 0.001000 0.032426 0.000000) PSNR 16.507608 dB
The tool can be used to create a difference image:
texdiag.exe diff reftexture.dds reftexture_dxt1.DDS
This results in a file reftexture.bmp with the absolute value of the differences in RGB (alpha is always fully opaque).
For block-compressed (BC) DDS files, the tool can dump out details about particular blocks in the compressed image for more detailed debugging:
texdiag.exe dumpbc -targetx 8 -targety 12 tex_dxt1.DDS
Results in the following output:
tex_dxt1.DDS
Compression: BC1_UNORM
Results by item ( 1) and mip ( 8)
[ 0, 0]:
Block 2 (pixel: 8 x 12)
Transparent - E0: (R: 0.000, G: 0.000, B: 0.000)
E1: (R: 0.000, G: 0.000, B: 0.032)
Index: 0 0 0 0 | 0 0 0 0 | 0 0 0 0 | 0 0 0 0
[ 0, 1]:
Block 1 (pixel: 4 x 4)
Transparent - E0: (R: 0.000, G: 0.000, B: 0.000)
E1: (R: 0.000, G: 0.000, B: 0.032)
Index: 0 0 0 0 | 0 0 0 0 | 0 0 0 0 | 0 0 0 0
[ 0, 2]:
Block 0 (pixel: 0 x 0)
Transparent - E0: (R: 0.000, G: 0.000, B: 0.000)
E1: (R: 0.000, G: 0.000, B: 0.032)
Index: 0 0 0 0 | 0 0 0 0 | 0 0 0 0 | 0 0 0 0
[ 0, 3]:
Block 0 (pixel: 0 x 0)
Transparent - E0: (R: 0.000, G: 0.000, B: 0.000)
E1: (R: 0.000, G: 0.000, B: 0.032)
Index: 0 0 0 0 | 0 0 0 0 | 0 0 0 0 | 0 0 0 0
[ 0, 4]:
Block 0 (pixel: 0 x 0)
Opaque - E0: (R: 0.000, G: 0.206, B: 0.194)
E1: (R: 0.000, G: 0.000, B: 0.000)
Index: 1 1 1 1 | 1 1 1 0 | 1 1 1 2 | 1 1 1 1
[ 0, 5]:
Block 0 (pixel: 0 x 0)
Opaque - E0: (R: 0.355, G: 0.302, B: 0.226)
E1: (R: 0.000, G: 0.016, B: 0.032)
Index: 1 1 1 1 | 1 1 1 1 | 1 0 2 1 | 1 1 3 1
[ 0, 6]:
Block 0 (pixel: 0 x 0)
Transparent - E0: (R: 0.000, G: 0.032, B: 0.032)
E1: (R: 0.097, G: 0.079, B: 0.065)
Index: 0 0 3 3 | 1 1 3 3 | 3 3 3 3 | 3 3 3 3
[ 0, 7]:
Block 0 (pixel: 0 x 0)
Transparent - E0: (R: 0.032, G: 0.048, B: 0.032)
E1: (R: 0.065, G: 0.063, B: 0.065)
Index: 2 3 3 3 | 3 3 3 3 | 3 3 3 3 | 3 3 3 3
In addition to analyzing images, the tool can also be used to dump out individual images:
texdiag dumpdds reftexture.dds
This results in a set of 9 image files, one for each miplevel:
reftexture_item000_mip000.BMP
reftexture_item000_mip001.BMP
reftexture_item000_mip002.BMP
reftexture_item000_mip003.BMP
reftexture_item000_mip004.BMP
reftexture_item000_mip005.BMP
reftexture_item000_mip006.BMP
reftexture_item000_mip007.BMP
reftexture_item000_mip008.BMP
Remarks
Support for OpenEXR (EXR) can be added to the texdiag utility. Uncomment #define USE_OPENEXR in the source, and add the DirectXTex auxiliary module to the project. See Adding OpenEXR for more details including building the OpenEXR library.
The texdiag tool supports any additional installed WIC codec. For example, if you install the HEIF WIC Codec, the tool can successfully read .HEIF or .HEIC images.