This DirectXTex sample is a command-line texture utility for creating DDS files containing cubemaps, volume maps, or texture arrays created from individual images.
This utility does not support mipmap generation or texture compression, but the resulting
DDSfile can be further processed by the Texconv utility. Any texture compressed input file is decompressed on load.
Syntax
Texassemble.exe uses the following command syntax:
texassemble <command> [options] [--file-list <filename>] <file-name(s)>
The file-name parameter indicates the file(s) to use to create the assembled image 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
cube: Creates a cubemap. Must have six images to form each of the six faces. Faces are ordered as follows: positive-x, negative-x, positive-y, negative-y, positive-z, negative-z.
volume: Creates a volume map. Must have at least two images and the number of images determines the 'depth'.
array: Creates a 1D or 2D texture array. Must have at least two images. Note that loading the resulting DDS file requires feature level 10.0 or better hardware.
cubearray: Creates a cubemap array. Must have a multiple of six images. Note that loading the resulting DDS file requires feature level 10.1 or better hardware if it contains more than a single cubemap.
h-cross, v-cross, v-cross-fnz: Creates a horizontal/vertical cross image from an input cubemap dds file. v-cross-fnz is the same as v-cross but flips the negative Z face around.
h-strip, v-strip: Creates a horizontal/vertical strip image from an input cubemap dds file
h-tee: Creates a horizontal "T" image from an input cubemap dds file
cube-from-hc, cube-from-vc, cube-from-vc-fnz, cube-from-ht, cube-from-hs, cube-from-vs: Creates a cubemap from one of the layout style images above.
array-strip: Creates a horizontal strip image from an input 1D/2D array dds file.
merge: Creates a texture using two input images. You can control which channels are used with the -swizzle option below.
gif: Converts an animated gif into a texture array with properly composed frames.
from-mips: create a 2D mipmapped texture with custom mip images.
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 Output-filename: The default name is a .DDS file based on the first input image file. For cross/strip generation, the default is a .BMP file and you can specify any of the extensions supported for input.
-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. By default, the tool will abort if the output file already exists.
Pixel format options
-f format, --format format: Output format. Specify the DXGI format without the DXGI_FORMAT_ prefix (i.e. -f R10G10B10A2_UNORM). If no format is given, the format of the first image file is used.
Resizing options
-w number, --width number: Width of the output texture in pixels.
-h number, --height number: Height of the output texture in pixels. If no size is given, the size is taken from the first input image.
Filtering options
-if filter, --image-filter filter: Image filter used for resizing the images. 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.
-wrap, -mirror: Sets the texture addressing mode for filtering to wrap or mirror, otherwise defaults to clamp.
-nowic: Forces filtering to use non-WIC-based code paths. This is useful for working around known issues with WIC depending on which operating system you are using.
Colorspace options
-srgb, -srgbi / --srgb-in, or -srgbo / --srgb-out: 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.
--tonemap: Applies tonemap operator based on maximum luminosity to ensure HDR image data is adjusted to an LDR range.
Alpha options
-alpha: Converts a premultiplied alpha image to non-premultiplied alpha (a.k.a. straight alpha).
-sepalpha, --separate-alpha: Separates alpha channel for resize.
DirectDraw Surface (DDS) file options
-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.
Direct3D options
-fl feature-level, --feature-level feature-level: Sets the target feature level which determines the maximum supported texture size: 9.1, 9.2, 9.3, 10.0, 10.1, 11.0, 11.1, 12.0, or 12.1. Defaults to 11.0 which is 16834, the limit for 11.x and 12.x Direct3D Hardware Feature Level.
GIF options
--gif-bg-color: When doing the gif command, by default it always uses a transparent background color which is consistent with most browsers. You can choose to use the background color metadata in the file with this switch instead, but the results are not likely to match most viewers.
MERGE options
--swizzle rgbamask: When doing the merge command, by default it uses the Blue channel from the second image as the Alpha channel for the output; pulling Red, Green, and Blue from the first image which is same as the mask rgbB. This option lets you provide alternative channel patterns using HLSL-style swizzle masks. Lowercase letters indicate channels pulled from the first image (rgbaxyzw), and uppercase letters indicate the second image (RGBAXYZW). The mask is 1 to 4 characters in length. A 0 indicates setting that channel to zero, a 1 indicates setting that channel to maximum.
The
mergecommand default swizzle mask matches the legacy DirectX Texture Tool behavior when doing "Open Alpha onto Surface..."
Miscellaneous options
--strip-mips: For the cube, array, volume, or cubearray command, the input images are expected to be single images. This option allows mip-mapped 1D or 2D textures to be used as inputs, which removes the mip-chain during processing.
-nologo: Suppress copyright message.
Examples
texassemble volume -w 256 -h 256 -o volume.dds lena.jpg fishingboat.jpg peppers.tiff
This loads the three image files 'lena.jpg', 'fishingboat.jpg', and 'peppers.tiff', resizes them to 256 x 256, and then writes out a volume (3D) texture to 'volume.dds' sized 256 x 256 x 3 with each input image as a depth slice. The result uses a DXGI format derived from the 'lena.jpg' input image, or one could be provided via the '-f' command-line switch.
The result does not have mipmaps but 'volume.dds' could be use as input for texconv to finish the processing such as generating mipmaps or block-compression.
texassemble cube -w 256 -h 256 -o cubemap.dds lobbyxposjpg lobbyxneg.jpg
lobbyypos.jpg lobbyyneg.jpg lobbyzpos.jpg lobbyzneg.jpg
This loads the six image JPEG files, resizes them to 256 x 256, and then writes out a cubemap texture to 'cubemap.dds' sized 256 x 256 with six faces, with each input image as a distinct face (ordered positive-x, negative-x, positive-y, negative-y, positive-z, and negative-z). The result uses a DXGI format derived from 'lobbyxpos.jpg', or one could be provided via the '-f' command-line switch.
The result does not have mipmaps but 'cubemap.dds' could be use as input for texconv to finish the processing such as generating mipmaps or block-compression.
texassemble array -o array.dds lena.jpg peppers.tiff
This loads the two image files 'lena.jpg' and 'peppers.tiff'. It resizes 'peppers.tiff' to the same size as 'lena.jpg', and then writes out an array 2D texture to 'array.dds' using the two input images. The result uses a DXGI format derived from 'lena.jpg', or one could be provided via the '-f' command-line switch.
The result does not have mipmaps but 'array.dds' could be use as input for texconv to finish the processing such as generating mipmaps or block-compression.
Loading 'array.dds' requires feature level 10.0 or better hardware.
texassemble h-cross cubemap.dds
This loads the cubemap, and outputs a cubemap.bmp with the cubemap faces arranged in a horizontal cross.
texassemble merge -o newimage.png baboon.tif texture1.bmp
This will create a new image saved as a png with the RGB values read from the baboon.tif file and the blue channel from texture1.bmp copied to the alpha channel in the new image.
texassemble gif animated.gif -o output.dds
This creates a DDS that contains a texture 2D array with format DXGI_FORMAT_B8G8AR8A8_UNORM with one item for each frame in the animation.
Remarks
Partial cubemaps (where less than 6 faces are specified) are not supported by Direct3D 10 or later. Therefore this tool only supports cubemaps with all six faces defined.
Support for OpenEXR (EXR) can be added to the texassemble 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 texassemble 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. This WIC codec does not support writing these files formats, so texassemble cannot output them.
The Google .WEBP format can also be read by installing the WEBP WIC Codec.