Texassemble
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 DDS file can be further processed by the Texconv utility. Any texture compressed input file is decompressed on load.
Texassemble.exe uses the following command syntax:
texassemble <command>
[-r] [-w width] [-h height] [-f format]
[-if filter] [-srgb | -srgbi | -srgbo]
[-sepalpha] [-wrap | -mirror] [-alpha]
[-o <outputfile>] [-y] [-dx10] [-tonemap]
[-nologo] [-flist <filename>]
[-bgcolor]
<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.).
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: Creates a horizontal/vertical cross image from an input cubemap dds file
h-strip, v-strip: Creates a horizontal/vertical strip image from an input cubemap dds file
merge: Creates a texture using two input images: RGB coming from the first image, A (via the Blue channel) from the second image.
The
mergecommand matches the legacy DirectX Texture Tool behavior when doing "Open Alpha onto Surface..."
gif: Converts an animated gif into a texture array with properly composed frames.
-r: Input file names can contain wildcard characters (? or *). If this switch is used, subdirectories are also searched.
-w number: Width of the output texture in pixels.
-h number: Height of the output texture in pixels. If no size is given, the size is taken from the first input image.
-f 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.
-if 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.
-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.
-sepalpha: Separates alpha channel for resize.
-wrap, -mirror: Sets the texture addressing mode for filtering to wrap or mirror, otherwise defaults to clamp.
-alpha: Converts a premultiplied alpha image to non-premultiplied alpha (a.k.a. straight alpha).
-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.
-y: overwrite existing output file if any. By default, the tool will abort if the output file already exists.
-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.
-tonemap: Applies tonemap operator based on maximum luminosity to ensure HDR image data is adjusted to an LDR range.
-nologo: Suppress copyright message.
-flist 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.
-bgcolor: 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.
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. Note that 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.
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.