tex-decoder

tex-decoder

A pure typescript texture decoder for most image compression types without the use of WebGL. Includes a color profile converter, unswizzler, image flipper and resizer plus a TGA and PNG file maker. Great for Node or web browsers.

Fully supports the following formats:

• ETC - ETC1, ETC2 and EAC decoding. Includes options for alpha in ETC1.
• DXTn - DTX1 (aka BC1), DXT2 (aka BC2), DXT3 (aka BC2), DXT4 (aka BC3) and DXT5 (aka BC3).
• BCn - BC1 (aka DTX1), BC2 (aka DXT3), BC3 (aka DXT5), BC4 (aka ATI1), BC5 (AKA ATI2), BC6 (signed and unsigned) and BC7.
• ATI - ATI1 and ATI2.
• ATC - ATC 4 and 8.
• PVRTC - PVRTC in 2 bit or 4 bit mode.
• ASTC - ASTC 4x4 to 12x12.
• CRN - Crunch data supporting all DXT.

Also includes:

• Color Profile Converter - Convert an image color profile.
• Unswizzler - Unswizzle, untile or mortonize image data.
• Image Flipper - Flips a RGB or RGBA image.
• Image Cropper - Crops a RGB or RGBA image.
• TGA Maker - Create a TGA file from a RGB or RGBA image.
• PNG Maker - Create a PNG file from a RGB or RGBA image. Built on pngjs.
• zlib algo - Simple compression / decompresson zlib port of pako in typescript.

Installation

npm install tex-decoder

Provides CommonJS and ES modules.

Example

Decoding ETC data with supplied format selector and create a TGA file.

import {
    decodeETC,
    ETC_FORMAT,
    makeTGA
    } from 'tex-decoder';

//read file data
const data = fs.readFileSync(__dirname + '/ETC2_RGBA8_image.bin');

//decode compressed data
const decodedData = decodeETC(data,512,512,ETC_FORMAT.ETC2_RGBA8);
//or use preset format function decodeETC2RGBA(data,512,512);

//write raw RGBA output
fs.writeFileSync(__dirname + '/ETC2_RGBA8.dat',decodedData);

//or create a TGA file
const tga = makeTGA(decodedData,512,512,true);

//write .tga file
fs.writeFileSync(__dirname + '/ETC2_RGBA8.tga',tga);

ETC

Decodes compressed ETC and EAC data. Source must be Uint8Array or Buffer. Returns the same type.

Use provided ETC_FORMAT.Format to specify format unless using presets. Use ETC_PROFILE.RGB/RGBA to force a profile different than packed.

	Functions / Enum (bold requires)	Desc
Name (master)	decodeETC(src, width, height, ETC_FORMAT, ETC_PROFILE)	Returns the data profile based on the format. Can force an RGB or RGBA with ETC_PROFILE.
ETC Formats	ETC_FORMAT = { ETC1_RGB, ETC2_RGB, ETC1_RGBA8, ETC2_RGBA8, ETC2_RGBA1, ETC2_SRGB, ETC2_SRGBA8, ETC2_SRGBA1, EAC_R11, EAC_RG11, EAC_R11_SIGNED, EAC_RG11_SIGNED, }	For use in 3rd argument of master function.
ETC Profiles	ETC_PROFILE = { RGB, RGBA }	For use in 4th argument of master function and 3rd in presets.
Presets	decodeETC1RGB(src, width, height, ETC_PROFILE)	Returns the data profile based on the format. Can force an RGB or RGBA with ETC_PROFILE.
Presets	decodeETC1RGBA(src, width, height, ETC_PROFILE)	Returns the data profile based on the format. Can force an RGB or RGBA with ETC_PROFILE. Note: This is a special case as ETC1 can't do alpha. Some packers create the alpha as a second image under the first (double the height). This function will decode all the data and fold the image onto itself creating the alpha channel. It will return the image with half the height supplied.
Presets	decodeETC2RGB(src, width, height, ETC_PROFILE)	Returns the data profile based on the format. Can force an RGB or RGBA with ETC_PROFILE.
Presets	decodeETC2RGBA(src, width, height, ETC_PROFILE)	Returns the data profile based on the format. Can force an RGB or RGBA with ETC_PROFILE.
Presets	decodeETC2RGBA1(src, width, height, ETC_PROFILE)	Returns the data profile based on the format. Can force an RGB or RGBA with ETC_PROFILE.
Presets	decodeETC2sRGB(src, width, height, ETC_PROFILE)	Returns the data profile based on the format. Can force an RGB or RGBA with ETC_PROFILE.
Presets	decodeETC2sRGBA1(src, width, height, ETC_PROFILE)	Returns the data profile based on the format. Can force an RGB or RGBA with ETC_PROFILE.
Presets	decodeETC2sRGBA8(src, width, height, ETC_PROFILE)	Returns the data profile based on the format. Can force an RGB or RGBA with ETC_PROFILE.
Presets	decodeEACR11(src, width, height, ETC_PROFILE)	Returns the data profile based on the format. Can force an RGB or RGBA with ETC_PROFILE.
Presets	decodeEACR11_SIGNED(src, width, height,ETC_PROFILE)	Returns the data profile based on the format. Can force an RGB or RGBA with ETC_PROFILE.
Presets	decodeEACRG11(src, width, height, ETC_PROFILE)	Returns the data profile based on the format. Can force an RGB or RGBA with ETC_PROFILE.
Presets	decodeEACRG11_SIGNED(src, width, height, ETC_PROFILE)	Returns the data profile based on the format. Can force an RGB or RGBA with ETC_PROFILE.

DTX

Decodes compressed DXT data. Source must be Uint8Array or Buffer. Returns the same type.

	Functions (bold requires)	Desc
Name	decodeDXT1(src, width, height)	Returns RGBA data. Same function as decodeBC1.
Name	decodeDXT2(src, width, height)	Returns RGBA data.
Name	decodeDXT3(src, width, height)	Returns RGBA data. Same function as decodeBC2.
Name	decodeDXT4(src, width, height)	Returns RGBA data.
Name	decodeDXT5(src, width, height)	Returns RGBA data. Same function as decodeBC3.

BC

Decodes compressed BC1-7 data. Source must be Uint8Array or Buffer. Returns the same type.

	Functions (bold requires)	Desc
Name	decodeBC1(src, width, height)	Returns RGBA data. Same function as decodeDXT1.
Name	decodeBC2(src, width, height)	Returns RGBA data. Same function as decodeDXT3.
Name	decodeBC3(src, width, height)	Returns RGBA data. Same function as decodeDXT5.
Name	decodeBC4(src, width, height)	Returns RGBA data. Same function as decodeATI1.
Name	decodeBC5(src, width, height)	Returns RGBA data. Same function as decodeATI2.
Name (Master)	decodeBC6(src, width, height, unsigned)	Returns RGBA data. Set unsigned as false if data is signed (defaults true)
Preset	decodeBC6H(src, width, height)	Returns RGBA data. Unsigned data.
Preset	decodeBC6S(src, width, height)	Returns RGBA data. Signed data.
Name	decodeBC7(src, width, height)	Returns RGBA data.

ATI

Decodes compressed ATI1 or ATI2 data. Source must be Uint8Array or Buffer. Returns the same type.

	Functions (bold requires)	Desc
Name (Master)	decodeATI(src, width, height, Do2)	Returns RGBA data. Will run ATI2 if Do2 is true (default ATI1).
Preset	decodeATI1(src, width, height)	Returns RGBA data. Same function as decodeBC4.
Preset	decodeATI2(src, width, height)	Returns RGBA data. Same function as decodeBC5.

ATC

Decodes compressed ATC4 or ATC8 data. Source must be Uint8Array or Buffer. Returns the same type.

	Functions (bold requires)	Desc
Name (Master)	decodeATC(src, width, height, Do8bitMode)	Returns RGBA data. Will run 8 bit mode if Do8bitMode is true (default false for 4 bit).
Preset	decodeATC4(src, width, height)	Returns RGBA data.
Preset	decodeATC8(src, width, height)	Returns RGBA data.

PVRTC

Decodes compressed PVRTC data in 2 or 4 bit mode. Source must be Uint8Array or Buffer. Returns the same type.

	Functions (bold requires)	Desc
Name (Master)	decodePVRTC(src, width, height, Do2bitMode)	Returns RGBA data. Will run 2 bit mode if Do2bitMode is true (default false for 4 bit).
Preset	decodePVRTC4bit(src, width, height)	Returns RGBA data.
Preset	decodePVRTC2bit(src, width, height)	Returns RGBA data.

ASTC

Decodes compressed ASTC data in 4x4 to 12x12 bit mode. Source must be Uint8Array or Buffer. Returns the same type.

	Functions (bold requires)	Desc
Name (Master)	decodeASTC(src, width, height, block_width, block_height)	Returns RGBA data. For this function you can pass the block size as arguments.
Preset	decodeASTC_4x4(src, width, height)	Returns RGBA data.
Preset	decodeASTC_5x4(src, width, height)	Returns RGBA data.
Preset	decodeASTC_5x5(src, width, height)	Returns RGBA data.
Preset	decodeASTC_6x5(src, width, height)	Returns RGBA data.
Preset	decodeASTC_6x6(src, width, height)	Returns RGBA data.
Preset	decodeASTC_8x5(src, width, height)	Returns RGBA data.
Preset	decodeASTC_8x6(src, width, height)	Returns RGBA data.
Preset	decodeASTC_8x8(src, width, height)	Returns RGBA data.
Preset	decodeASTC_10x5(src, width, height)	Returns RGBA data.
Preset	decodeASTC_10x6(src, width, height)	Returns RGBA data.
Preset	decodeASTC_10x8(src, width, height)	Returns RGBA data.
Preset	decodeASTC_10x10(src, width, height)	Returns RGBA data.
Preset	decodeASTC_12x10(src, width, height)	Returns RGBA data.
Preset	decodeASTC_12x12(src, width, height)	Returns RGBA data.

CRN

Decodes crunched data in DXT format and can return decoded or coded data. Source must be Uint8Array or Buffer. Returns the same type.

Data must be a vaild .crn file format.

	Functions (bold requires)	Desc
Name	getCRNMeta(src, mipmap_level)	Checks the crunched data and returns width, height, mipmaps, faces and format of compressed data. Can supply mip level if file has more than one to get the right width, height.
Preset	decodeCRN(src, mipmap_level, keepCompressed)	Returns decode RGBA data unless keepCompressed is true (default false). Can supply mip level if file has more than one to get that level returned data.

Color Profile Converter

Converts the data's color profile bit order and data type. You can use supplied COLOR_PROFILE profiles or create your own. You can use BYTE_VALUE to help create your own. Read how below. Source must be Uint8Array or Buffer. Returns the same type.

	Functions / Enum (bold requires)	Desc
Name (master)	convertProfile(src, srcProfile, dstProfile, width, height)	Returns the data profile based on the COLOR_PROFILE. Se below for the preset or you can make your own.
Color Profiles	COLOR_PROFILE = { A8, R8, G8, B8, RG8, RB8, GR8, GB8, BR8, BG8, RGB8, RBG8, GRB8, GBR8, BRG8, BGR8, ARGB8, ARBG8, AGRB8, AGBR8, ABRG8, ABGR8, RGBA8, RBGA8, GRBA8, GBRA8, BRGA8, BGRA8, RGB565, BGR565, RGBA4, RGBA51, RGB10_A2, RGB10_A2I, A8I, R8I, RG8I, RGB8I, RGBA8I, ARGB8I, BGR8I, BGRA8I, ABGR8I, A16F, R16F, RG16F, RGB16F, RGBA16F, ARGB16F, R16, RG16, RGB16, RGBA16, A16I, R16I, RG16I, RGB16I, RGBA16I, A32F, R32F, RG32F, RGB32F, RGBA32F, A32, R32, RG32, RGB32, RGBA32, R32I, RG32I, RGB32I, RGBA32I, }	Profiles are object with 2 keys, order and value. Order is a string defining the color and bit size and the value is how it is read. Unsigned = 0, Signed = 1, Half Float = 2 and Float = 3 (can also be found in supplied BYTE_VALUE enum). Example: a order string for RGBA8 would be "r8g8b8a8" with a value of 0 and RG32F would be "r32g32" with a value of 3.

Unswizzler

Unswizzle, untile or mortonize data. Source must be Uint8Array or Buffer. Returns the same type.

	Functions (bold requires)	Desc
Name	unswizzle(src, width, height, depth, bytesPerPixel, dstRowPitch, dstSlicePitch)	Note: bytesPerPixel must be 1, 2 or 4.
Name	untile(src, bytesPerBlock, pixelBlockWidth, pixelBlockHeigth, tileSize, width)	Untile block image data. pixelBlockWidth and pixelBlockHeigth are normally 4 unless the image is raw, then it's 1.
Name	mortonize(src, packedBitsPerPixel, pixelBlockWidth, pixelBlockHeigth, width, height, mortonOrder, widthFactor)	Mortonize block image data. pixelBlockWidth and pixelBlockHeigth are normally 4 unless the image is raw, then it's 1. mortonOrder and widthFactor change depending on the system.

Image Flipper

Flips image data of 24 or 32 bit profiles (needed for some types of image files). Source must be Uint8Array or Buffer. Returns the same type.

	Functions (bold requires)	Desc
Name	flipImage(src, width, height, is24)	Use is24 as true for 24 bit profiles

Image Cropper

Crops image data. Bits per pixel must be supplied of source data. Source must be Uint8Array or Buffer. Returns the same type.

	Functions (bold requires)	Desc
Name	cropImage(src, current_width, current_height, bytesPerPixel, startX, startY, cropped_width, cropped_height)	Will crop the image based on cropped_width and cropped_height starting at startX & startX pixel

TGA Maker

Simple TGA file maker. Must be RGB8 or RGBA8 profile. Source must be Uint8Array or Buffer. Returns the same type.

	Functions (bold requires)	Desc
Name	makeTGA(src, width, height, noAlpha)	Use noAlpha as true for 24 bit profiles

PNG Maker

Simple PNG file maker (uses pngjs). Must be RGB8 or RGBA8 profile. Source must be Uint8Array or Buffer. Returns the same type.

	Functions (bold requires)	Desc
Name	makePNG(src, width, height, noAlpha)	Use noAlpha as true for 24 bit profiles
Name	readPNG(src)	Reads .png file and returns meta data like height and width and the unzipped data. Must be Uint8Array or Buffer.

zlib

A Typescript port of pako. Functions inflate, Inflate, deflate, Deflate, deflateRaw, inflateRaw, gzip, ungzip See documentation for how functions work.

Acknowledgements

This project was born from the desire to have a single library that could convert any image format. Having been using tools like Noesis and PVRTool in the past, I wanted something I could translate quickly to a Node app and then use in a web site without having to redo work. Sources for all code can be found in comments.

I'm happy to connect and grow this library if others find it useful. Pull requests or bug reports are welcome!

Disclaimer

All libraries are presented as is, I take no responsibility for outside use.

If you plan to implement these libraries for anything other than personal or educational use, please be sure you have the appropriate permissions from the original owners.

License

MIT