Skip to content

Texassemble

Chuck Walbourn edited this page Jul 9, 2020 · 48 revisions

texassemble.exe

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.

Syntax

Texassemble.exe uses the following command syntax:

texassemble <command>
    [-r] [-flist <filename>]
    [-w width] [-h height] [-f format]
    [-if filter] [-srgb | -srgbi | -srgbo]
    [-sepalpha] [-nowic] [-wrap | -mirror] [-alpha]
    [-o <outputfile>] [-l] [-y] [-dx10] [-tonemap]
    [-nologo]
    [-fl feature-level]
    [-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.).

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: 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

Cubemap image layouts

array-strip: Creates a horizontal strip image from an input 1D/2D array 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 merge command 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.

Optional Switches Description

-r: Input file names can contain wildcard characters (? or *). If this switch is used, subdirectories are also searched.

-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.

-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.

-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.

-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.

-l: 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 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.

-fl 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.

-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.

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.

For Use

  • Universal Windows Platform apps
  • Windows desktop apps
  • Windows 11
  • Windows 10
  • Windows 8.1
  • Xbox One
  • Xbox Series X|S
  • Windows Subsystem for Linux

Architecture

  • x86
  • x64
  • ARM64

For Development

  • Visual Studio 2022
  • Visual Studio 2019 (16.11)
  • clang/LLVM v12 - v18
  • GCC 10.5, 11.4, 12.3
  • MinGW 12.2, 13.2
  • CMake 3.20

Related Projects

DirectXTex Rust bindings

DirectX Tool Kit for DirectX 11

DirectX Tool Kit for DirectX 12

DirectXMesh

DirectXMath

Tools

Test Suite

Content Exporter

DxCapsViewer

See also

DirectX Landing Page

Clone this wiki locally