ImageDDS

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

To invoke ImageDDS, run imagedds_x86.exe (for Windows) or imagedds_x86 (for Linux) from a command-line console (the 64-bit version has a _x64 postfix).

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 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 (DXT, JPG, etc.), for example, GUI textures with thin lines that need to be rendered with pixel precision. The following formats are supported:

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

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

  r8 rg8 rgb8 rgba8 r16 rg16 rgb16 rgba16 r32f rg32f rgb32f rgba32f r5g6b5 rgba4 rgb5a1

  rgb10a2 dxt1 dxt3 dxt5 ati1 ati2 etc1 etc2 etc5 eac1 eac2 pvr4 atc1 atc3 atc5

• -s SCALE — downscale an image using a given factor. The default is 1.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 is 0.
• -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.
• -fb — use box filtration for mipmaps (the default setting).
• -g GAMMA — make gamma corrected mipmaps. The default value is 2.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, ETC1, ETC2, ETC5, EAC1, EAC2, PVR4, ATC1, ATC3, ATC5, ZLC1 or ZLC2 formats.
• -atc — automatically compress an image into ATC1 (for RGB8 images) or ATC5 (for RGBA8 images) format.
• -etc1 — automatically compress an image into ETC1 format (for RGB8 images).
• -etc2 — automatically compress an image into ETC2, ETC5, EAC1, EAC2 formats.

  R8 to EAC1 RG8 to EAC2 RGB8 to ETC2 RGBA8 to ETC5

• -pvr — automatically compress an image into PVR4 format (for RGB8 or RGBA8 square images).
• -zlc1 — automatically compress an image into ZLC1 format.
• -zlc2 — automatically compress an image into ZLC2 format.

The following input formats are supported:

• Targa (TGA)
• Portable Network Graphics (PNG)
• JPEG (JPG)
• PhotoShop Document (PSD)
• Direct Draw Surface (DDS)

Use the imagedds_x86.py or imagedds_x64.py script accordingly to your operating system extention (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
• _m — mask
• _dr — raw diffuse texture
• _nr — raw 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
• _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

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_x86.py (or imagedds_x64.py) script from this folder.

As a result, compressed textures with .dds extension are placed in the textures folder. This storage structure 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 -c 
					

imagedds_x64.py -s 0.5 -atc
					

The syntax for Windows is:

imagedds_x86.exe OPTIONS FILE

The syntax for Linux is:

imagedds_x86 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 -e option.

Examples

The following creates an uncompressed DDS image:

Shell commands

imagedds_x86 file.tga

The following creates a compressed DDS image:

Shell commands

imagedds_x86 -c file.tga

The following creates a compressed DDS image with mipmaps:

Shell commands

imagedds_x86 -m -c file.tga

The following converts the image format and creates a compressed DDS image (DXT1) with mipmaps:

Shell commands

imagedds_x86 -f rgb8 -m -c file.tga

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

Shell commands

imagedds_x86.py -s 0.5

The following rotates a cube texture counter-clockwise:

Shell commands

imagedds_x86 -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_x86 -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