Programming
Fundamentals
Setting Up Development Environment
UnigineScript
High-Level Systems
C++
C#
UUSL (Unified UNIGINE Shader Language)
File Formats
Rebuilding the Engine and Tools
GUI
Double Precision Coordinates
API
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
Rendering-Related Classes

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.

Image Formats

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.

Notice
If the high quality of the texture is important, it is better to use the PNG format instead of TGA. Such an image doesn't save the GPU memory just as TGA, but takes less disk space.

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.

DDS Formats

The following compression formats are supported by the DDS container:

Format Channels Compression ratio Notes
ATI1 R 2:1 compared to uncompressed R8 Compression is the same as the one used for alpha data in the DXT5 format. Supported by all graphics cards compatible with DirectX 11; additionally, all ATI graphics cards since X800.
ATI2 RG 2:1 compared to uncompressed RG8 Compression for each channel is the same as the one used for alpha data in the DXT5 format. Supported by all graphics cards compatible with DirectX 11; additionally, all ATI graphics cards since X800.
DXT1 RGB 6:1 compared to uncompressed RGB8 Uses 4x4 blocks for color interpolation and stores color values in 16 bits per pixel (R5:G6:B5). Can also store 1-bit alpha data; in this case, compresses images by a factor of 8:1 compared to RGBA8. This format is not recommended for storing normal maps.
DXT3 RGBA 4:1 compared to uncompressed RGBA8 Stores RGB color values as the DXT1 format and uses four more bits for alpha data. Color values are interpreted as not having been pre-multiplied by alpha. Alpha values are not interpolated. Recommended for images with sharp alpha transitions.
DXT5 RGBA 4:1 compared to uncompressed RGBA8 Stores RGB color values as the DXT1 format and uses four more bits for alpha data. Color values are interpreted as not having been pre-multiplied by alpha. Alpha values are interpolated. Recommended for images with smooth alpha transitions.
PVR4 RGBA 6:1 compared to uncompressed RGBA8 This format can be used only on mobile devices with PowerVR graphics chip. PVR4 compression is based on Daubechies 6 wavelet. Images of this format need to be at least8 x 8 pixels in size. Alpha values are supported.
Only square textures can be compressed into this format.
ETC1 RGB 4:1 compared to uncompressed R5G6B5 This format is natively supported by all Android devices. It compresses each 4×4 pixel block to precisely 64 bits of binary data, and due to that graphics hardware require exactly one memory access to fetch a texel from the image. ETC1 does not support an alpha channel, so can only be used for opaque textures.
ETC2 RGB Compresses an image with better quality than the ETC1 format, but doesn't support an alpha channel. It compresses each 4×4 pixel block by using the usual ETC1 compression algorithm or one of three algorithms additionally implemented in ETC2. Also a ETC1 texture can be loaded as an ETC2 texture, because the ETC2 is backward compatible with ETC1.
ETC5 RGBA This format is the same as ETC2, but it supports an alpha channel stored in the EAC1 format.
EAC1 R Single-channel texture compression format that is used to store grey-scale values.
EAC2 RG Two-channel texture compression format that is used, for example, for normal maps.
ATC1 RGB Proprietary compressed format used for textures on Qualcomm mobile devices. In addition to color, it is used to store 1-bit alpha data only.
ATC3 RGBA Proprietary compressed format used for textures on Qualcomm mobile devices. In addition to color, it is used to store alpha value with sharp transitions.
ATC5 RGBA Proprietary compressed format used for textures on Qualcomm mobile devices. In addition to color, it is used to store alpha value with smooth transitions.

Cube Textures

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

Cube texture layout

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

ZLIB Compressed Formats

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:

Format Channels Notes
ZLC1 RGBA Compressed format for images in the system memory. It is used for fast compression (for example, in run-time) and uses Z_BEST_SPEED flag.
ZLC2 RGBA Compressed format that provides a smaller file size, if compared to ZLC1 format. It uses Z_BEST_COMPRESSION flag.

Command Line Options

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 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.
  • -fb — use box 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, 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.

Input Formats

The following input formats are supported:

  • Targa (TGA)
  • Portable Network Graphics (PNG)
  • JPEG (JPG)
  • PhotoShop Document (PSD)
  • Direct Draw Surface (DDS)
PSD and DDS textures can be of either of 8-bit or 16-bit precision.

Batch Operations

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
  • _f — fibers texture
  • _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
  • _met — metalness texture
  • _alb — albedo texture
  • _nrgb — RGB normal map
The script uses optimal settings for every texture type. Raw textures will not be compressed.

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

Notice
All of the textures should be stored in the uncompressed generic format (such as TGA) or lossless compression format (PNG) to avoid an additional loss of the image quality after compression.

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

imagedds_x86.py and imagedds_x64.py scripts can take the following basic CLI arguments:

  • -p PREFIX — prefix to names of the output files.
  • -e EXT — output files format (DDS, JPG, TGA, PNG, PSD).
  • -x POSTFIX — postfix to a name of the output file.
  • -f FORMAT — convert to a given image format (see the details).
  • -s SCALE — scale images using a given factor. The default is 1.0, no scaling.
  • -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).
  • -c — compress images into a DXT1, DXT5, ATI1 or ATI2 format:
    • For images that are due to compression:
      • Diffuse, specular, emission textures or light maps will be compressed and gamma corrected (2.2) mipmaps will be created for them.
      • Parallax, height, tessellation or ambient occlusion maps will be compressed into ATI1 format and mipmaps will be created for them.
      • Normal maps will be compressed into ATI2 format.
    • For raw images:
      • For raw diffuse, specular, emission textures or light maps gamma corrected (2.2) mipmaps will be created.
      • Raw parallax, height, tessellation or ambient occlusion maps will be converted into R8 format and mipmaps will be created for them.
      • Raw normal maps will be converted into RG8 format.

Besides the above-listed ones, it can also take the following additional arguments:

  • -chdir DIRECTORY — change the current working directory.
  • -etc1 — compress images into ETC1 format.
  • -etc2 — compress images into ETC2, EAC1, EAC2 format.
  • -atc — compress images into ATC1, ATC5 formats.
  • -pvr — compress images into PVR4 format. The difference between the default conversion and this specific one is as follows:
    • Diffuse, specular, emission textures or light maps will be compressed into PVR4 format.
    • Parallax, height, tessellation or ambient occlusion maps will be converted into R8 format.
    • Normal maps will be scaled down by half and converted into RG8 format.

Examples

For example, you have 4 TGA textures named body_d.tga, body_e.tga, body_n.tga, body_s.tga (diffuse, emission, normal and specular maps respectively) that are stored in the data/my_project/textures/uncompressed folder. To compress them to the format supported by the DDS container, you can type the following:

Shell commands
imagedds_x64.py -c
As a result, you will get 4 files with the .dds extension located in the data/my_project/textures folder that have the following compression formats:
  • body_d.dds - ATI1 format
  • body_e.dds - ATI1 format
  • body_n.dds - ATI2 format
  • body_s.dds - ATI1 format

Now, if you want to build your application for the mobile platforms, you can run the imagedds_x64.py (or imagedds_x64.py) script with the other options. For example, you can downscale the textures and compress them into the ATC1, ATC5 formats:

Shell commands
imagedds_x64.py -s 0.5 -atc

Usage

The syntax for Windows is:

Shell commands
imagedds_x86.exe OPTIONS FILE

The syntax for Linux is:

Shell commands
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
Before rotation
After rotation (correct for usage with Unigine)
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):

Input texture

Texture to be converted into 3D texture
Last update: 2017-07-03