ImageDDS

ImageDDS is a console tool for compressing/decompressing images into/from the Direct Draw Surface (DDS) container format.

It provides the following functionality:

• Converting images to the DDS format with or without compression.
• Converting images to the specified type.
• Converting images to the specified format.
• Compressing images using ZLIB and LZ4 compression algorithms.
• Compressing textures in batches.

To invoke ImageDDS, run imagedds_x64 from the command prompt.

Compression and decompression is performed according to conversion rules.

The supported image formats can be divided into the following groups:

• Generic formats such as TGA, PNG, PSD, JPEG
• Formats supported by hardware that include all of the formats supported by DDS container (e.g. ATI1, ATI2, DXT1, etc.)

There are compressed (PNG, JPEG) and uncompressed (PSD, TGA) generic image formats. The compressed generic formats can be either lossless (PNG) or lossy (JPEG) compression formats. Usually the source textures are stored in the PSD format, and then they can be exported to the intermediate formats such as TGA or PNG.

The textures of the generic formats can be compressed to the formats supported by hardware. In this case, it is recommended to store all of the textures in the lossless compression format (such as PNG) to avoid an additional loss of the image quality after compression. Despite the fact that the formats supported by hardware are lossy compression formats, they are more preferable for real-time 3D applications, because the textures of such formats can be decompressed by the GPU on-the-fly.

The following compression formats are supported by the DDS container:

ImageDDS supports cube textures, which should be oriented the following way:

If your texture needs rotation to fix orientation, invoke ImageDDS with the -r option. See also an example below.

ZLIB lossless image compression allows for a smaller memory footprint for textures stored in the system memory (these formats are not supported by graphics cards). It is useful for images that cannot be compressed using quality-loss algorithms, for example, GUI textures with thin lines that need to be rendered with pixel precision. ZLIB compression is slower than LZ4 one, however, it provides higher compression ratio.

The following formats are supported:

LZ4 lossless image compression algorithm provides high compression/decompression speed. It is faster than ZLIB compression, however, it provides lower compression ratio. LZ4 compression should be used if you often need to decompress images in run-time.

ImageDDS recognizes the following command line options:

• -o NAME — name of an output file.
• -p PREFIX — prefix to a name of the output file.
• -x POSTFIX — postfix to a name of the output file.
• -e EXT — output file format (.dds, .jpg, .tga, .png, .psd).
• -t TYPE — convert to a given image type:

  2d 3d for a 3D texture. In order to be converted, the input texture should be a number of square layers of equal size that are glued together in a vertical column. Check the example below. cube for a cube map 2d_array for a 2D array cube_array for a cube texture array.

• -f FORMAT — convert to a given image format:

  r8 rg8 rgb8 rgba8 r16 rg16 rgb16 rgba16 r16f rg16f rgb16f rgba16f r32f

  rg32f rgb32f rgba32f rgb565 rgba4 rgb5a1 rgb10a2 dxt1 dxt3 dxt5 ati1 ati2

• -s SCALE — downscale an image using a given factor. The default is1.0, no image downscaling.
• -w WIDTH — resize an image proportionally to match a given width.
• -h HEIGHT — resize an image proportionally to match a given height.
• -z DEPTH — image depth.
• -ms SIZE — if the image is of the specified size or smaller, it will not be resized (a useful option for batch resizing of textures).
• -r ANGLE — rotate an image:
  • 2D texture: values 1, 2, 3, 4 rotate the image clockwise by 90, 180, 270 and 360 degrees respectively. Values -1, -2, -3, -4 rotate the image counter-clockwise by the same degrees.
  • Cube texture: values 1, 2, 3 rotate the image clockwise; values -1, -2, -3 rotate the image counter-clockwise. Image rotation means swapping of axes and rotation of single faces to glue them seamlessly. During clockwise rotation faces are swapped this way: p->pz, n->nz, py->px, ny->nx, pz->py, nz->ny. During counter-clockwise rotation faces are swapped this way: px->py, nx->ny, py->pz, ny->nz, pz->px, nz->nx.
  • 3D texture: cannot be rotated.
• -b SIZE — blur the image with a given blurring factor. The default is0.
• -fx SIZE — flip image horizontally.
• -fy SIZE — flip image vertically.
• -i — print the information about the image.
• -n — create an empty image.
• -m — generate mipmaps.
• -fp — use point filtration for mipmaps.
• -fl — use linear filtration for mipmaps (the default setting).
• -g GAMMA — make gamma corrected mipmaps. The default value is2.2.
• -md — separate mipmaps.
• -mc — combine mipmaps.
• -c — compress an image into the DXT1, DXT5, ATI1 or ATI2 format.

  R8 to ATI1 RG8 to ATI2 RGB8 to DXT1 RGBA8 to DXT5

• -d — decompress an image from DXT1, DXT3, DXT5, ATI1, ATI2, ZLC1, ZLC2, or LZ4 formats.
• -zlc1 — automatically compress an image into ZLC1 format.
• -zlc2 — automatically compress an image into ZLC2 format.
• -lz4 — automatically compress an image into LZ4 format.

The following input formats are supported:

• Targa (TGA)
• Portable Network Graphics (PNG)
• JPEG (JPG)
• PhotoShop Document (PSD)
• Direct Draw Surface (DDS)
• Portable Pixmap (PPM)
• Portable Graymap(PGM)
• High Dynamic Range(HDR)
• Tagged Image File(TIF)
• Silicon Graphics Image(SGI)

Use the imagedds_x64.py script (requires Python) to perform batch operations over all files in a directory. The script detects a type of a texture according to its postfix:

• _d — diffuse texture
• _n — normal map
• _s — specular map
• _p — parallax occlusion map
• _h — height map
• _t — tessellation (density) map
• _a — ambient occlusion map
• _e — emission/glow map
• _l — light map
• _f — microfiber texture
• _m — mask texture
• _alb — albedo texture
• _met — metalness texture
• _sh — shading texture
• _dr — raw diffuse texture
• _nr — raw normal map
• _nrgb — raw RGB normal map
• _sr — raw specular map
• _pr — raw parallax occlusion map
• _hr — raw height map
• _tr — raw tessellation (density) map
• _ar — raw ambient occlusion map
• _er — raw emission/glow map
• _lr — raw light map
• _mr — raw mask texture
• _albr — raw albedo texture
• _metr — raw metalness texture
• _dm — mipmapped diffuse texture
• _nm — mipmapped normal map
• _sm — mipmapped specular map
• _pm — mipmapped parallax occlusion map
• _hm — mipmapped height map
• _tm — mipmapped tessellation (density) map
• _am — mipmapped ambient occlusion map
• _em — mipmapped emission/glow map
• _lm — mipmapped light map
• _mm — mipmapped mask texture
• _metm — mipmapped metalness texture
• _albm — mipmapped albedo texture

It is recommended to create the uncompressed folder in data/my_project/textures to store uncompressed textures of the intermediate format (TGA, PNG).

To compress all of your textures, run the imagedds_x64.py script from this folder.

As a result, compressed textures with .dds extension are placed in the textures folder. Such way of storing textures allows fast texture re-export in case of any changes and also gives the ability to compress the same textures with the other options.

Command Line Options for Batch Operations

Examples

imagedds_x64.py

The syntax is:

imagedds_x64 OPTIONS FILE

• You can specify the path to the input file relative to the binary ( file.tga) or as an absolute path (e.g. "D:\Unigine\data\my_project\file.tga").
• Output files will have the same name as the originals, but with the .dds extension by default. This can be overridden with the -o or -e options.

Examples

The following creates an uncompressed DDS image:

Shell commands

imagedds_x64 file.tga

The following creates a compressed DDS image:

Shell commands

imagedds_x64 -c file.tga

The following creates a compressed DDS image with mipmaps:

Shell commands

imagedds_x64 -m -c file.tga

The following compresses all textures in the current directory into the DDS format and scales them down:

Shell commands

imagedds_x64.py -s 0.5

The following rotates a cube texture counter-clockwise:

Shell commands

imagedds_x64 -r -1 environment.dds

Before rotation

After rotation (suitable for usage with Unigine)

The following creates a 3D texture that can be used, for example, as a terrain mask:

Shell commands

imagedds_x64 -t 3d -f rgb8 mask.png

This input texture will be divided into 2 layers (they should be square and arranged vertically to be sucessfully converted):

Texture to be converted into 3D texture