DXT Compression/Decompression Library
nvDXT is a compression and decompression library to link to your existing projects. You specify compression options in the class CompressionOptions located in nvdxt_options.h. The library will create the MIP map levels for you during compression, or you can specify you own. You can specify your own MIP map compressor callback to receive each of the compressed MIP levels.
The decompressor will decompress all MIP map into one image file where all MIP maps are concatenated together.
The library name is nvDXTLib.lib.
Command Line Compression Tools
nvDXT.exe - command line tool for batch compressing
detach.exe - extracts the MIP maps from a .dds file
stitch.exe - recombine MIP levels to form one .dds
readDXT.exe - reads compressed image and writes .tga file (source)
nvDXT Stand alone batch compressor
type
nvDXT with no options to see the option list
NVDXT
This program
compresses images
creates normal maps from color or alpha
creates DuDv map
creates cube maps
writes out .dds file
does batch processing
reads .tga, .bmp, .gif, .ppm, .jpg, .tif, .cel, .dds
filters MIP maps
Options:
-quick : use fast compression method
-prescale <int> <int>: rescale image to this size first
-rescale <nearest | hi | lo | next_lo>: rescale image to nearest, next highest or next lowest power of two
-rel_scale <float, float> : relative scale of original image. 0.5 is half size Default 1.0, 1.0
-clamp <int, int> : maximum image size. image widht and height are clamped
-nomipmap : don't generate MIP maps
-nmips <int> : specify the number of MIP maps to generate
-fade : fade MIP maps
-dither : add dithering
-sharpen : sharpen MIP maps
-lambda <float>: sharpen lambda value, default 10
-sscale <float>: sharpen scale value, default 1
-mu <float>: sharpen mu value, default 0.01
-edge_radius <int>: sharpen edge radius, default 2
-tc : sharpen two components enable, default disabled
-nms : sharpen non maximal suppression enable, default disabled
-sb : sharpen blur, default disabled
-theta <float>: sharpen theta (used for flavor 2 sharpen), default 0.75
-fv2 : sharpen flavor 2, default off
-flip : flip top to bottom
-timestamp : Update only changed files
-list <filename> : list of files to convert
-cubemap <filename> : create cube map <filename>. Files specified with -list option
positive x, negative x, positive y, negative y, positive z, negative z
-all : all image files in current directory
-outdir <directory>: output directory
-deep [directory]: include all subdirectories
-outsamedir : output directory same as input
-overwrite : if input is .dds file, overwrite old file
-file <filename> : input file to process. Accepts wild cards
-output <filename> : filename to write to
-append <filename_append> : append this string to output filename
-24 <dxt1c | dxt1a | dxt3 | dxt5 | u1555 | u4444 | u565 | u8888 | u888 | u555> : compress 24 bit images with this format
-32 <dxt1c | dxt1a | dxt3 | dxt5 | u1555 | u4444 | u565 | u8888 | u888 | u555> : compress 32 bit images with this format
-swap : swap rgb
-binaryalpha : treat alpha as 0 or 1
-alpha_threshold <byte>: [0-255] alpha reference value
-alphaborder : border images with alpha = 0
-fadeamount <int>: percentage to fade each MIP level. Default 15
-fadecolor : fade map (color, normal or DuDv) over MIP levels
-fadetocolor <hex color> : color to fade to
-fadealpha : fade alpha over MIP levels
-fadetoalpha <byte>: [0-255] alpha to fade to
-border : border images with color
-bordercolor <hex color> : color for border
-force4 : force DXT1c to use always four colors
Texture Format options. Default DXT3:
-dxt1c : DXT1 (color only)
-dxt1a : DXT1 (one bit alpha)
-dxt3 : DXT3
-dxt5 : DXT5
-u1555 : uncompressed 1:5:5:5
-u4444 : uncompressed 4:4:4:4
-u565 : uncompressed 5:6:5
-u8888 : uncompressed 8:8:8:8
-u888 : uncompressed 0:8:8:8
-u555 : uncompressed 0:5:5:5
-p8 : paletted 8 bit (256 colors)
-p4 : paletted 4 bit (16 colors)
-a8 : 8 bit alpha channel
-cxv8u8: normal maps
Optional Mip Map Filtering. Default box filter:
-cubic : cubic filtering
-kaiser : kaiser filtering
-gamma : kaiser gamma filtering
-full : full DFT filtering
***************************
To make a normal or dudv map, specify one of
-n4 : normal map 4 sample
-n3x3 : normal map 3x3 filter
-n5x5 : normal map 5x5 filter
-n7x7 : normal map 7x7 filter
-n9x9 : normal map 9x9 filter
-dudv : DuDv
and source of height info:
-alpha : alpha channel
-rgb : average rgb
-biased : average rgb biased
-red : red channel
-green : green channel
-blue : blue channel
-max : max of (r,g,b)
-colorspace : mix of r,g,b
-norm : normalize mip maps (source is a normal map)
Normal/DuDv Map options:
-aheight : store calculated height in alpha field
-aclear : clear alpha channel
-awhite : set alpha channel = 1.0
-scale <float> : scale of height map. Default 1.0
-wrap : wrap texture around. Default off
-minz <int> : minimum value for up vector [0-255]. Default 0
***************************
To make a depth sprite, specify:
-depth
and source of depth info:
-alpha : alpha channel
-rgb : average rgb (default)
-red : red channel
-green : green channel
-blue : blue channel
-max : max of (r,g,b)
-colorspace : mix of r,g,b
Depth Sprite options:
-aheight : store calculated depth in alpha channel
-aclear : store 0.0 in alpha channel
-awhite : store 1.0 in alpha channel
-scale <float> : scale of depth sprite (default 1.0)
Examples
nvdxt -cubemap cubemap.dds -list cubemapfile.lst
nvdxt -file test.tga -dxt1c
nvdxt -file *.tga
nvdxt -file c:\temp\*.tga
nvdxt -file temp\*.tga
nvdxt -file height_field_in_alpha.tga -n3x3 -alpha -scale 10 -wrap
nvdxt -file grey_scale_height_field.tga -n5x5 -rgb -scale 1.3
nvdxt -file normal_map.tga -norm
nvdxt -file image.tga -dudv -fade -fadeamount 10
nvdxt -all -dxt3 -gamma -outdir .\dds_dir -time
nvdxt -file *.tga -depth -max -scale 0.5
Version 5.74
Send comments, bug fixes and feature requests to doug@nvidia.com
reads
.tga
.bmp
.gif
.ppm
.jpg
.tif
.cel
.dds
Known Bugs
.jpg currently swaps RGB
Usage: detach <base_filename>
do not include the .dds extension
for example to extract MIP maps from wood.dds use
detach wood
Usage: stitch <base_filename>
do not include the .dds extension
for example to recombine MIP maps from wood_00.dds,.. wood_01.dds,...
stitch wood
Compresses an image with a user supplied callback with the data for each MIP level created.
For each MIP level, your callback will be called.
Only supports input of RGB 24 or ARGB 32 bpp.
See nvDXT.cpp for example. This example require the NVSDK to build.
HRESULT
nvDXTcompress(unsigned char * raw_data, // pointer to data (24 or 32 bit)unsigned long w, // width in texels
unsigned long h, // height in texels
DWORD pitch, // in bytes
CompressionOptions * options, // structure defined in nvdxt_options.h
DWORD depth, // 3 or 4
MIPcallback callback = 0); // callback for generated levels
if callback is == 0 (or not specified), then WriteDTXnFile is called with all file info
instead of your callback
typedef HRESULT (*MIPcallback)(
void * data, // pointer to the data to compressed data
int miplevel, // what MIP level this is
DWORD size // size of the data
);
// You must write the routines (or provide stubs)
// void WriteDTXnFile(count, buffer);
// void ReadDTXnFile(count, buffer);
//
//
void WriteDTXnFile(DWORD count, void * buffer);
void ReadDTXnFile(DWORD count, void * buffer);
See the file nvdxt_options.h for the definition of CompressionOptions
// error return codes
#define DXTERR_INPUT_POINTER_ZERO -1
#define DXTERR_DEPTH_IS_NOT_3_OR_4 -2
#define DXTERR_NON_POWER_2 -3
example callback to store compressed image in a
Direct3D texture
LPDIRECT3DTEXTURE8 pCurrentTexture = 0;
HRESULT LoadAllMipSurfaces(void * data,
int iLevel)
{
HRESULT hr;
LPDIRECT3DSURFACE8
psurf;
D3DSURFACE_DESC
sd;
D3DLOCKED_RECT
lr;
hr = pCurrentTexture->GetSurfaceLevel(iLevel, &psurf);
if (FAILED(hr))
return hr;
psurf->GetDesc(&sd);
hr = pCurrentTexture->LockRect(iLevel, &lr, NULL, 0);
if (FAILED(hr))
return hr;
memcpy(lr.pBits, data, sd.Size);
hr = pCurrentTexture->UnlockRect(iLevel);
ReleasePpo(&psurf);
return 0;
}
calling sequence
hr = D3DXCreateTexture(m_pd3dDevice, Width, Height, nMips, 0, D3DFMT_DXT3,
D3DPOOL_MANAGED, &pCurrentTexture);
nvDXTcompress(raw_data, Width, Height, pitch, options, 4,
LoadAllMipSurfaces);
If you have
existing MIP maps you must combine them so each MIP level is followed by its
next MIP level. Conceptually, it looks like this:
in CompressionOptions
MipMapType = dUseExistingMipMaps;
You must specify all MIP levels.
To decompress an image use this call to read all MIP chains into one buffer:
unsigned
char * nvDXTdecompress(int & w, int & h, int & depth, int & total_width, int & rowBytes, int & src_format, int SpecifiedMipMaps)
returns pointer to image data;
w : image width
h : image height
depth : number of bytes per pixel, 3 or 4
row_bytes: pitch of main image
The first image starts at 0, the next MIP map image starts at base + row_bytes, next one starts at base + row_bytes / 2, etc.
src_format: format of the file
SpecifiedMipMaps. Load in only this number of MIP maps. zero means read all MIP levels
pitch = row_bytes * 2
see readdxt.cpp for example