Some notes and stuff on NWN Crunch Enhanced Edition.
The crunch program will generate good DDS files for your textures from source files such as PNG, TGA, BMP and JPG.
Recommended input file is PNG for obvious reasons - 32 bit with alpha is usual.
You can also convert any format to, say, PNG for use in other programs. This is the easiest way to get NWN DDS (a sorta weird NWN only DDS format no longer required in NWN:EE) back to a usable format, which many of the game files and much Custom Content uses.
Compressed PNG files should be 32bit with alpha. We've found having a simply blank; eg entirely transparent for some reason texture doesn't load properly.
There is an option to have the usual batch scripts check and truncate filenames; it is really however recommended to have all filenames 16 characters or less, or in the case of diffuse textures you want to have _d after, to have them 14 characters (or have the _d already apended).
Read the notes in the vault page for some tips on MTR creation as well: https://neverwintervault.org/project/nwnee/other/tool/nwn-crunch-enhanced-edition
You can create your own simplified batch or powershell scripts using the original ones as a basis, or check the options out further down.
This is essentially the readme in the program. Some pertinent options will be described below.
NWN Crunch: Texture Compression Tool
Based on crunch by Richard Geldreich, Jr. and Binomial LLC - https://github.com/BinomialLLC/crunch
libcrn version v1.04 x64 Built May 16 2021, 19:40:17
Error: No command line parameters specified!
Command line usage:
crunch [options] -file filename
-file filename - Required input filename, wildcards, multiple -file params OK.
-file @list.txt - List of files to convert.
Supported source file formats: dds,ktx,crn,tga,bmp,png,jpg/jpeg,psd
Note: Some file format variants are unsupported.
See the docs for stb_image.c: http://www.nothings.org/stb_image.c
Progressive JPEG files are supported, see: http://code.google.com/p/jpeg-compressor/
Path/file related parameters:
-out filename - Output filename
-outdir dir - Output directory
-outsamedir - Write output file to input directory
-deep - Recurse subdirectories, default=false
-nooverwrite - Don't overwrite existing files
-timestamp - Update only changed files
-forcewrite - Overwrite read-only files
-recreate - Recreate directory structure
-fileformat [dds,ktx,crn,tga,bmp,png,nwn] - Output file format, default=crn or dds
Modes:
-compare - Compare input and output files (no output files are written).
-info - Only display input file statistics (no output files are written).
Misc. options:
-helperThreads # - Set number of helper threads, 0-16, default=(# of CPU's)-1
-noprogress - Disable progress output
-quiet - Disable all console output
-ignoreerrors - Continue processing files after errors. Note: The default
behavior is to immediately exit whenever an error occurs.
-logfile filename - Append output to log file
-pause - Wait for keypress on error
-window <left> <top> <right> <bottom> - Crop window before processing
-clamp <width> <height> - Crop image if larger than width/height
-clampscale <width> <height> - Scale image if larger than width/height
-nostats - Disable all output file statistics (faster)
-imagestats - Print various image qualilty statistics
-mipstats - Print statistics for each mipmap, not just the top mip
-lzmastats - Print size of output file compressed with LZMA codec
-split - Write faces/mip levels to multiple separate output PNG files
-yflip - Always flip texture on Y axis before processing
-unflip - Unflip texture if read from source file as flipped
-invertcolors - Invert image colors, default=disabled
-normalize - Normalize for normal maps, default=disabled
-minvalue <int> - Minimum value for all channels [0,255], default=0
-setRGBtoY - Set RGB channels to luminosity, default=disabled
-setAtoY - Set Alpha Channel to luminosity, default=disabled
-setRGBAtoR - Set RGBA channels to Red channel, default=disabled
Image rescaling (mutually exclusive options)
-rescale <int> <int> - Rescale image to specified resolution
-relscale <float> <float> - Rescale image to specified relative resolution
-rescalemode <nearest | hi | lo> - Auto-rescale non-power of two images
nearest - Use nearest power of 2, hi - Use next, lo - Use previous
DDS/CRN compression quality control:
-quality # (or /q #) - Set Clustered DDS/CRN quality factor [0-255] 255=best
DDS default quality is best possible.
CRN default quality is 128.
-bitrate # - Set the desired output bitrate of DDS or CRN output files.
This option causes crunch to find the quality factor
closest to the desired bitrate using a binary search.
Low-level CRN specific options:
-c # - Color endpoint palette size, 32-8192, default=3072
-s # - Color selector palette size, 32-8192, default=3072
-ca # - Alpha endpoint palette size, 32-8192, default=3072
-sa # - Alpha selector palette size, 32-8192, default=3072
Mipmap filtering options:
-mipMode [UseSourceOrGenerate,UseSource,Generate,None]
Default mipMode is UseSourceOrGenerate
UseSourceOrGenerate: Use source mipmaps if possible, or create new mipmaps.
UseSource: Always use source mipmaps, if any (never generate new mipmaps)
Generate: Always generate a new mipmap chain (ignore source mipmaps)
None: Do not output any mipmaps
-mipFilter [box,tent,lanczos4,mitchell,kaiser], default=kaiser
-gamma # - Mipmap gamma correction value, default=2.2, use 1.0 for linear
-blurriness # - Scale filter kernel, >1=blur, <1=sharpen, .01-8, default=.9
-wrap - Assume texture is tiled when filtering, default=clamping
-renormalize - Renormalize filtered normal map texels, default=disabled
-maxmips # - Limit number of generated texture mipmap levels, 1-16, default=16
-minmipsize # - Smallest allowable mipmap resolution, default=1
Compression options:
-alphaThreshold # - Set DXT1A alpha threshold, 0-255, default=128
Note: -alphaThreshold also changes the compressor's behavior to
prefer DXT1A over DXT5 for images with alpha channels (.DDS only).
-uniformMetrics - Use uniform color metrics, default=use perceptual metrics
-noAdaptiveBlocks - Disable adaptive block sizes (i.e. disable macroblocks).
-compressor [CRN,CRNF,RYG,ATI] - Set DXTn compressor, default=CRN
-dxtQuality [superfast,fast,normal,better,uber] - Endpoint optimizer speed.
Sets endpoint optimizer's max iteration depth. Default=uber.
-noendpointcaching - Don't try reusing previous DXT endpoint solutions.
-grayscalsampling - Assume shader will convert fetched results to luma (Y).
-forceprimaryencoding - Only use DXT1 color4 and DXT5 alpha8 block encodings.
-usetransparentindicesforblack - Try DXT1 transparent indices for dark pixels.
Ouptut pixel format options:
-usesourceformat - Use input file's format for output format (when possible).
All supported texture formats:
-DXT1
-DXT2
-DXT3
-DXT4
-DXT5
-3DC
-DXN
-DXT5A
-DXT5_CCxY
-DXT5_xGxR
-DXT5_xGBR
-DXT5_AGBR
-DXT1A
-ETC1
-ETC2
-ETC2A
-ETC1S
-ETC2AS
-R8G8B8
-L8
-A8
-A8L8
-A8R8G8B8
Note: .CRN only supports DXTn pixel formats, NWN only support DXT1 and DXT5 formats.
Exit status: 1
PS E:\SVN\Tools and Utilities\Crunch\nwn_crunch_windows64_EE> .\nwn_crunch.exe
NWN Crunch: Texture Compression Tool
Based on crunch by Richard Geldreich, Jr. and Binomial LLC - https://github.com/BinomialLLC/crunch
libcrn version v1.04 x64 Built May 16 2021, 19:40:17
Error: No command line parameters specified!
Command line usage:
crunch [options] -file filename
-file filename - Required input filename, wildcards, multiple -file params OK.
-file @list.txt - List of files to convert.
Supported source file formats: dds,ktx,crn,tga,bmp,png,jpg/jpeg,psd
Note: Some file format variants are unsupported.
See the docs for stb_image.c: http://www.nothings.org/stb_image.c
Progressive JPEG files are supported, see: http://code.google.com/p/jpeg-compressor/
Path/file related parameters:
-out filename - Output filename
-outdir dir - Output directory
-outsamedir - Write output file to input directory
-deep - Recurse subdirectories, default=false
-nooverwrite - Don't overwrite existing files
-timestamp - Update only changed files
-forcewrite - Overwrite read-only files
-recreate - Recreate directory structure
-fileformat [dds,ktx,crn,tga,bmp,png,nwn] - Output file format, default=crn or dds
Modes:
-compare - Compare input and output files (no output files are written).
-info - Only display input file statistics (no output files are written).
Misc. options:
-helperThreads # - Set number of helper threads, 0-16, default=(# of CPU's)-1
-noprogress - Disable progress output
-quiet - Disable all console output
-ignoreerrors - Continue processing files after errors. Note: The default
behavior is to immediately exit whenever an error occurs.
-logfile filename - Append output to log file
-pause - Wait for keypress on error
-window <left> <top> <right> <bottom> - Crop window before processing
-clamp <width> <height> - Crop image if larger than width/height
-clampscale <width> <height> - Scale image if larger than width/height
-nostats - Disable all output file statistics (faster)
-imagestats - Print various image qualilty statistics
-mipstats - Print statistics for each mipmap, not just the top mip
-lzmastats - Print size of output file compressed with LZMA codec
-split - Write faces/mip levels to multiple separate output PNG files
-yflip - Always flip texture on Y axis before processing
-unflip - Unflip texture if read from source file as flipped
-invertcolors - Invert image colors, default=disabled
-normalize - Normalize for normal maps, default=disabled
-minvalue <int> - Minimum value for all channels [0,255], default=0
-setRGBtoY - Set RGB channels to luminosity, default=disabled
-setAtoY - Set Alpha Channel to luminosity, default=disabled
-setRGBAtoR - Set RGBA channels to Red channel, default=disabled
Image rescaling (mutually exclusive options)
-rescale <int> <int> - Rescale image to specified resolution
-relscale <float> <float> - Rescale image to specified relative resolution
-rescalemode <nearest | hi | lo> - Auto-rescale non-power of two images
nearest - Use nearest power of 2, hi - Use next, lo - Use previous
DDS/CRN compression quality control:
-quality # (or /q #) - Set Clustered DDS/CRN quality factor [0-255] 255=best
DDS default quality is best possible.
CRN default quality is 128.
-bitrate # - Set the desired output bitrate of DDS or CRN output files.
This option causes crunch to find the quality factor
closest to the desired bitrate using a binary search.
Low-level CRN specific options:
-c # - Color endpoint palette size, 32-8192, default=3072
-s # - Color selector palette size, 32-8192, default=3072
-ca # - Alpha endpoint palette size, 32-8192, default=3072
-sa # - Alpha selector palette size, 32-8192, default=3072
Mipmap filtering options:
-mipMode [UseSourceOrGenerate,UseSource,Generate,None]
Default mipMode is UseSourceOrGenerate
UseSourceOrGenerate: Use source mipmaps if possible, or create new mipmaps.
UseSource: Always use source mipmaps, if any (never generate new mipmaps)
Generate: Always generate a new mipmap chain (ignore source mipmaps)
None: Do not output any mipmaps
-mipFilter [box,tent,lanczos4,mitchell,kaiser], default=kaiser
-gamma # - Mipmap gamma correction value, default=2.2, use 1.0 for linear
-blurriness # - Scale filter kernel, >1=blur, <1=sharpen, .01-8, default=.9
-wrap - Assume texture is tiled when filtering, default=clamping
-renormalize - Renormalize filtered normal map texels, default=disabled
-maxmips # - Limit number of generated texture mipmap levels, 1-16, default=16
-minmipsize # - Smallest allowable mipmap resolution, default=1
Compression options:
-alphaThreshold # - Set DXT1A alpha threshold, 0-255, default=128
Note: -alphaThreshold also changes the compressor's behavior to
prefer DXT1A over DXT5 for images with alpha channels (.DDS only).
-uniformMetrics - Use uniform color metrics, default=use perceptual metrics
-noAdaptiveBlocks - Disable adaptive block sizes (i.e. disable macroblocks).
-compressor [CRN,CRNF,RYG,ATI] - Set DXTn compressor, default=CRN
-dxtQuality [superfast,fast,normal,better,uber] - Endpoint optimizer speed.
Sets endpoint optimizer's max iteration depth. Default=uber.
-noendpointcaching - Don't try reusing previous DXT endpoint solutions.
-grayscalsampling - Assume shader will convert fetched results to luma (Y).
-forceprimaryencoding - Only use DXT1 color4 and DXT5 alpha8 block encodings.
-usetransparentindicesforblack - Try DXT1 transparent indices for dark pixels.
Ouptut pixel format options:
-usesourceformat - Use input file's format for output format (when possible).
All supported texture formats:
-DXT1
-DXT2
-DXT3
-DXT4
-DXT5
-3DC
-DXN
-DXT5A
-DXT5_CCxY
-DXT5_xGxR
-DXT5_xGBR
-DXT5_AGBR
-DXT1A
-ETC1
-ETC2
-ETC2A
-ETC1S
-ETC2AS
-R8G8B8
-L8
-A8
-A8L8
-A8R8G8B8
Note: .CRN only supports DXTn pixel formats, NWN only support DXT1 and DXT5 formats. |
The basic usage would be, eg in powershell to convert all PNGs in the "in" folder, to a DDS DTX1 (no alpha) image, with a yflip, quietly:
.\nwn_crunch.exe -file -i "in\*.png" -outdir "out" -fileformat dds -DXT1 -yflip -quiet |
The main thing might be what DDS options you want to use, primarily you want to use these as per the convert_dds_mtr batch and convert_dds_portrait files:
| File Type | DTX type | Other options | Notes |
|---|---|---|---|
| Diffuse | -DXT5A | Not all diffuse textures require the alpha channel (ie if no transparency) so can use DTX1 for those | |
| Normal | -DXN | -normalize -uniformMetrics | DXN appears to be "3DC" compression |
| Specular | -DXT5A | ||
| Metallicness | -DXT5A | -minvalue 5 | |
| Roughness | -DXT5A | -invertcolors | |
| Glossiness | -DXT5A | ||
| Height | -DXT5A | ||
| Illumination | -DXT1 | No transparency allowed on illumination | |
| Portrait | |||
| Portrait | -DXT1 | -deep -recreate -mipmode none |
Some of these are not in the readme or not clear from the readme how they work. I've found these to be the most relevant for most texture work on diffuse textures (the other MTR ones it is recommended to use the settings above).
| Option Name | Values (if any) | Example | Description and Notes |
|---|---|---|---|
| i | folder name | -i "in\*.*" | The input - in the example all files in the "in" folder in the same location as the exe, of any file extension |
| outdir | folder name | -outdir "out" | The output directory, in the example it is the "out" on in the same location as the exe |
| nostats | -nostats | Removes stats from the output to the console | |
| noprogress | -noprogress | Removes progress on converting things from the output to the console | |
| quiet | -quiet | Removes all console information (use this wisely - it really doesn't tell you what it's doing at all!) | |
| logfile | file name | -logfile log.txt | Log file, which contains all the progress and any issues |
| fileformat | dds / png / nwn then the type if DDS | -fileformat dds -DXT1 | Output file format. Don't use "nwn" anymore, that's for 1.69 only, use DDS instead. Use PNG usually when converting from DDS or similar. |
| DXT1 | -fileformat dds -DXT1 | Standard DDS file with no alpha transparency. Saves a significant magnitude of space compared to DXT5A if you don't need alpha. | |
| DXT5A | -fileformat dds -DXT5A | Standard DDS file with alpha transparency | |
| quality | 0 - 255 | -quality 10 | The DDS quality factor to use; it defaults to 255 so no need to include usually. |
| rescale | X Y | -rescale 512 512 | This is useful for doing all the rescaling of a large image into a smaller one (eg; for a portrait H, L, M, S, T variants all at once). Can produce the best results compared to doing the resizing out of crunch from my experiments - if you use powers of two! If you don't use powers of two look at the rescalemode option. |
| yflip | -yflip | Will flip on the Y axis, which can be required for converting to DDS files if your original image is "the right way up". | |
| deep | -deep | Recurse subdirectories | |
| recreate | -recreate | Recreate the subdirectories if "-deep" is used | |
| mipmode | UseSourceOrGenerate, UseSource, Generate, None | -mipmode none | The default is UseSourceOrGenerate, which is fine for 99% of NWN content, but for portraits you might want to use "-mipmode none" since it saves a lot of disk space and portraits don't use mipmaps by default. CAVEAT HOWEVER: Portraits can use mipmaps if the TXI file that changes this setting is overriden, meaning mipmaps plus the UI scaling of the game can correctly use them at different mipmap sizes as needed. The space saving isn't huge anyway, even at high resolutions, so probably not worth disabling since it can crash the game if a DDS file doesn't have a mipmap when it should. |