Editing Guides/DDS compression with DirectXTex

[https://github.com/microsoft/DirectXTex DirectXTex] is a set of 3 programs that are essential for doing any sort of manipulation of DirectDraw Surface [[Resources/Texture|textures]].

This page will briefly detail both basic and advanced usage of these tools.

The three tools in this set have seperate purposes.

* The main tool, '''texconv''', is simply for converting textures to and from DDS, or for changing the format of DDS files.
* It also contains '''texdiag''', which can be used to analyse DDS textures to find out the format and other metadata.
* Lastly, '''texassemble''' is for constructing DDS textures containing multiple images, such as cubemaps, volume maps or arrays.

== Basic Command-line Usage ==
DirectXTex tools are only operable through the Windows Command Prompt, so first we must understand how to operate the command line.
[[File:Command Prompt after startup.png|alt=The window has a line with the current selected directory, waiting for user input.|left|thumb|Command Prompt window upon opening it.]]
First, open up Command Prompt (you may need to use the search bar). You will be met with a screen like this.

The input line tells you the current selected directory, which by default is your user folder. To run any DirectXTex tool, it is best to navigate to the directory which you have the tools stored in. To change the active directory, you need the '''cd''' (Change Directory) command. Enter:<syntaxhighlight>
cd <filepath-to-directxtex>
</syntaxhighlight>Make sure to replace <filepath-to-directxtex> with the actual filepath, without the angle brackets included. If the tools are on another drive, e.g. D: or E:, you may also need to switch to this drive by simply enter the name of the drive. For example:<syntaxhighlight>
D:
</syntaxhighlight>Once this is done, you should be in the correct directory, ready to run the tools. You could test this by typing the name of the tool's exe (without the .exe extension) and it should show you the tool's help menu:<syntaxhighlight>
texconv
</syntaxhighlight>Extra tip: you can enter filepaths quickly by dragging a file or folder into the command prompt window, it will quickly insert the file or folder's filepath at the cursor's location.

== Using texconv ==
At minimum, texconv must take in one filepath as an input. By default, it outputs a DDS with some variation of B8G8R8A8_UNORM, depending on the input file.<syntaxhighlight>
texconv "D:/My Textures/texture.png"
</syntaxhighlight>You can also convert all the textures in a certain folder by using the wildcard (*) character, and you can select an output directory with the -o input (''Note: the output directory path cannot end with a /)''.<syntaxhighlight>
texconv "D:/My Textures/*.png" -o "D:/Converted Textures"
</syntaxhighlight>

=== Texture Formats ===
The textures output with the default command work fine for most cases, like basic character or stage textures, but may not work correctly or at all for specialised cases like heightmaps or skycubes, and usually ends up with an unnecessarily large file size. To solve these issues, setting image format is required.

Image format can be set with a -f input, followed by the name of the format.<syntaxhighlight>
texconv "D:/My Textures/texture.png" -f BC7_UNORM
</syntaxhighlight>BC7_UNORM is generally the most compatible format, and has good compression. However, other formats may be required for other purposes. A list of the used formats can be viewed on the [[Resources/Texture|texture resource page]].

== Using texdiag ==
Using texdiag is even simpler than texconv. The main command you will need to use is the info command, which takes in the filepath of an image and returns its format and other metadata.<syntaxhighlight>
texdiag info "D:/Converted Textures/texture.dds"
</syntaxhighlight>It should give you an output similar to:<syntaxhighlight>
        width = 1024
       height = 1024
        depth = 1
    mipLevels = 11
    arraySize = 1
       format = BC7_UNORM
    dimension = 2D
   alpha mode = Unknown
       images = 11
   pixel size = 1365 (KB)
</syntaxhighlight>With this information, you can replace specialised textures (like heightmaps, normal maps, skycubes, etc.) much more easily by matching their format, width, height and other metadata.

== Using texassemble ==
The final tool, texassemble has a wide variety of uses. Thankfully, there is only one of these features that is commonly utilised by the Hedgehog Engine, and that is cubemaps.

=== Cubemaps ===
Cubemaps are pretty simple in concept, they're a set of 6 images that are able to be mapped on a cube, usually for the purpose of making a 360° image like a skycube (skybox).
[[File:Layout of textures in a Cubemap.png|alt=This image shows the layout of images in a cubemap|thumb|217x217px|Layout of textures in a Cubemap]]
To start with, you need your 6 images that are going to be assembled into a cubemap. They can be DDS or any other format, it will be output as a DDS regardless. There should be one image for each face of the cube in the layout shown. It is also worth noting that the +Z direction with the cubemap is equivalent to the -Y direction in Blender.

To convert your six textures into one cubemap, run the command:<syntaxhighlight>
texassemble cube "D:/My Textures/+X.png" "D:/My Textures/-X.png" "D:/My Textures/+Y.png" "D:/My Textures/-Y.png" "D:/My Textures/+Z.png" "D:/My Textures/-Z.png"
</syntaxhighlight>As shown, the images should be input in the order +X -X +Y -Y +Z -Z. You may also set the location of the output image, again, without a / at the end of the directory path:<syntaxhighlight>
texassemble cube "D:/My Textures/+X.png" "D:/My Textures/-X.png" "D:/My Textures/+Y.png" "D:/My Textures/-Y.png" "D:/My Textures/+Z.png" "D:/My Textures/-Z.png" -o "D:/Converted Textures"
</syntaxhighlight>

=== Finishing up ===
Usually, texassemble outputs cubemaps in the R16G16B16A16_UNORM format, which is entirely uncompressed and can have a filesize in the range of hundreds of MB, so it's best to run the images through texconv as well to use a better format like BC7_UNORM, BC6H_SF16, BC6H_UF16 or some other format depending on your purposes.