UnigineEditor
Interface Overview
Assets Workflow
Settings and Preferences
Adjusting Node Parameters
Setting Up Materials
Setting Up Properties
Landscape Tool
Using Editor Tools for Specific Tasks
FAQ
Programming
Fundamentals
Setting Up Development Environment
Usage Examples
UnigineScript
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
CIGI Client Plugin
Rendering-Related Classes

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.

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

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 an example below.

ZLIB Compression

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:

Format Channels Notes
ZLC1 RGBA Compressed format for images in the system memory. It is faster than ZLC2, however, it produces less compression: it uses Z_BEST_SPEED flag.
ZLC2 RGBA Compressed format that provides a smaller file size, if compared to ZLC1 format. However, it is slower: it uses Z_BEST_COMPRESSION flag.

Notice
Images compressed by using the ZLIB algorithm can be opened by the engine only.

LZ4 Compression

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.

Format Channels Notes
LZ4 RGBA Compressed format that provides fast compression (for example, in run-time).

Notice
Images compressed by using the LZ4 algorithm can be opened by the engine only.

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

Input Formats

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)

Batch Operations

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

The imagedds_x64.py script 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.
  • -chdir DIRECTORY — change the current working directory.

By default, if no command-line options are specified, the textures will be compressed as follows:

  • For images of the compressed formats:
    • Diffuse, specular, albedo, metalness, shading, emission textures or light maps will be compressed into a DXT1, DXT5, ATI1 or ATI2 format and gamma corrected mipmaps (the default value is 2.2) will be created for them.
    • Parallax, height, tessellation, ambient occlusion maps or microfiber textures will be compressed into ATI1 format and mipmaps will be created for them.
    • Normal maps will be compressed into ATI2 format and mipmaps will be created for them.
    • Mask textures will be compressed into a DXT1, DXT5, ATI1 or ATI2 format and mipmaps will be created for them.
  • For pre-mipmapped compressed images (with the _*m postfix):
    • Diffuse, specular, albedo, metalness, emission, mask textures or light maps will be compressed into a DXT1, DXT5, ATI1 or ATI2 format and combined mipmaps will be created for them.
    • Parallax, height, tessellation, ambient occlusion maps will be compressed into ATI1 format and combined mipmaps will be created for them.
    • Normal maps will be compressed into ATI2 format and combined mipmaps will be created for them.
    • Mask textures will be compressed into a DXT1, DXT5, ATI1 or ATI2 format and mipmaps will be created for them.
  • For raw images (with the _*r postfix):
    • For raw diffuse, specular, metalness, shading, emission textures or light maps gamma corrected mipmaps (the default value is 2.2) will be created.
    • Raw albedo textures will be converted into RGB8 format and gamma corrected mipmaps (the default value is 2.2) will be created for them.
    • 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 and mipmaps will be created for them.
    • Raw normal rgb maps will be converted into RGB8 format and mipmaps will be created for them.
    • For mask textures mipmaps will be created.

Examples

For example, you have 4 TGA textures named body_alb.tga (RGB8), body_e.tga (RGBA8), body_n.tga (RGB8), body_met.tga (RGB8) (albedo, emission, normal and metalness textures 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
As a result, you will get 4 files with the .dds extensions located in the data/my_project/textures folder that have the following compression formats:
  • body_alb.dds - DXT1 format
  • body_e.dds - DXT5 format
  • body_n.dds - ATI2 format
  • body_met.dds - DXT1 format

Usage

The syntax is:

Shell commands
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
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_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):

Input texture

Texture to be converted into 3D texture
Last update: 2018-08-10