NEWS: This project is now hosted on GitHub https://github.com/Microsoft/DirectXTex. This site is being maintained for now, but please move to using GitHub. https://github.com/Microsoft/DirectXTex/wiki/Texassemble

This DirectXTex sample is a command-line texture utility for creating DDS files containing cubemaps, volume maps, or texture arrays 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.

Syntax

Texassemble.exe uses the following command syntax:

texassemble [-cube | - volume | -array | -cubearray] [-w width] [-h height] [-f format] [-if filter] [-sepalpha] [-o <outputfile>] [-dx10]  [-nologo] <files>
The file-name parameter indicates the file(s) to use to create the image.

The optional command-line switches are described in the following table.

Optional Switches Description

  • -cube Creates a cubemap. Must have six images to form each of the six faces.
  • -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.
  • -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.
  • -o Output filename. The default name is a .DDS file based on the first input image file.
  • -sepalpha Separates alpha channel for resize.
  • -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.

Feature Level Notes

Cubemaps must always have six faces to support Direct3D 10.x/11.x. Direct3D 9 allowed partial cubemaps (less than six faces) defined, but texassemble does not support building these files.

Texture arrays require Feature Level 10.0 or later hardware. They are not supported by 9.x feature levels.

Cubemap arrays (i.e. 12 or more images defining two or more cubemaps in the same resource) require Feature Level 10.1 or later hardware. They are not supported by 10.0 or 9.x feature levels.

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. Note that loading 'array.dds' requires feature level 10.0 or better hardware.

Last edited Jul 30, 2015 at 12:56 AM by walbourn, version 17