December, 1996

3.1 Command line options

1. Introduction

This is a preliminary document describing TexUS 2.01.

3Dfx Interactive Texture Utility Software (TexUS) is an image processing library and utility program for preparing images for use with the 3Dfx Interactive Glide Library. Features of TexUS include file format conversion, MIPmap creation, and support for 3Dfx Interactive Narrow Channel Compression textures.

The TexUS utility program reads images in several popular image file formats, generates MIPmaps, and writes the images as 3Dfx Interactive Texture Files (.3DF) or as an image file for inspection.

The TexUS library generates in-memory MIPmap textures suitable for use with Glide, with flexible control over color conversion, sampling, and quantization.

Full ANSI compliant 32-bit C source code to TexUS is provided, allowing recompilation on any platform with an ANSI C compiler.

2. About this document

This document assumes that you have read the Glide Programming Guide.

3. Running the Texus utility program

Texus is a command line driven program. Precompiled versions of TexUS for SGI Irix, SunOS 4.x, DOS, Windows NT, and IBM OS/2 Warp are provided on the distribution CD, and versions for other architectures can be built with the provided ANSI C source code.

1. Command line options

1. Resampling the Input image

[-r | -rn | -r<aspect_ratio> | -R <width> <height> ]

Glide expects texture dimensions (width and height) to be powers of 2, with a maximum dimension of 256, and a minimum dimension of 1. Rectangular (i.e, non-square) textures are supported as long as the maximum aspect ratio (width/height or height/width is less than 8:1 or 1:8). The resampling (resizing) options make the process of converting input images to Glide-compliant textures easy. Only one of the options -r, -rn, -r<aspect> or -R may be specified at any time (the last one is used if more than one is specified). The following table explains each resampling option in detail.

-r	Automatically pick the width and height of output image by snapping the dimensions to the next smaller power of 2, constraining the aspect ratio to within the acceptable range for Glide. [Default]
-rn	Do not re-sample the image. This option will preserve the input dimensions. However, if the input width and height are not powers of 2, the resulting 3df file cannot be used by Glide as a texture.
-r<aspect_ratio>	Resample automatically, but force the output image to have the specified <aspect_ratio>. Possible values for <aspect_ratio> are: 8x1, 4x1, 2x1, 1x1, 1x2, 1x4. Note that there are no spaces between -r and the <aspect_ratio>.
-R <width> <height>	Resample input image to match the width and height dimensions specified on the command line. If these are not powers of 2, the resulting output cannot be used by Glide.

 

2. Generating MIPmaps

[ -m | -mn | -m<levels> | -M <size> ]

This option controls the creation of MIPmaps in the output. MIPmaps are generated by repeatedly averaging the 4 nearest pixels to produce a image that is half the width and height of the original. MIPmaps will only be generated if the width and height of the input image (after Resampling) are powers of 2. Each of the -m options is exclusive, and if more than one is specified, the last one is used. The following table describes each option in detail.

-m	Automatically generate all MIPmap levels. The smallest MIPmap will always be 1x1 when this option is used. [Default]
-mn	Do not generate MIPmaps.
-m<levels>	Generate exactly n mipmap levels, where <levels> is in the range 1..9.
-M <size>	Generate MIPmaps till the largest dimension of the smallest MIPmap is less than <size>, which can be any number between 1 and 256. This is useful, for example, when there is not much value in generating a MIPmap that is smaller than 4x4.

 

3. Quantizing the Input Image

[-t <texture_format>] [-ys | -yn ] [-de | -dn | -d4]

Image quantization is the process of converting the input image into the specified texture format and applying the specified image compression algorithm and dithering. The following <texture_format>s are supported:

 

Texture Format	Texel Size (Bits)	Description
argb8888	32	24-bit color + 8 bit alpha. (Default) Warning: The Voodoo Graphics™ hardware can not use this color format. It is provided for archiving purposes only.
i8	8	8-bit intensity Note: In this and other color modes which use intensity, the intensity is determined by the standard formula Intensity = (0.299 * Red) * (0.587 * Green) * (0.114 * Blue).
a8	8	8-bit alpha
ai44	8	4-bit alpha/4-bit intensity
yiq	8	narrow-channel compressed color
rgb332	8	3-bit red, 3-bit green, 2-bit blue
rgb565	16	5-bit red. 6-bit green, 5-bit blue
argb8332	16	8-bit alpha, 3-bit red, 3-bit green, 2-bit blue
argb1555	16	1-bit alpha, 5-bit red, 5-bit green, 5-bit blue
ayiq	16	8-bit alpha + narrow-channel compressed color
argb4444	16	4-bit alpha, 4-bit red, 4-bit green, 4-bit blue
ai88	16	8-bit alpha, 8-bit intensity

 

The two texture formats yiq and ayiq specify the Narrow Channel Compressed (NCC) texture format. Narrow Channel Compression converts the input image into an indexed 8-bit image. The 8-bit indices refer to a palette which contains colors encoded in the YIQ color space. The palette is small (< 40 bytes), and is always associated with this texture, and hence can be downloaded with very little overhead, and may be changed per triangle if necessary. The image quality of NCC textures are usually much better than any of the other 8bit texture format (rgb332), and in many cases as good as argb1555 textures. Input images can be converted to NCC textures using three different algorithms, and only a visual inspection can decide which algorithm works best for a particular input image.

The -y<compression> option (either -ys or -yh) determines the compression algorithm used, and the following algorithms are supported:

-ys	A statistical algorithm is used to histogram the colors found in the input image, and optimal values for the NCC table are determined from this histogram.
-yh	A heuristic (neural network) algorithm is used to determine the optimal values for the NCC tables. (Default)

 

In practice, the statistical and neural net algorithms produce comparable quality of output for image with a wide distribution of colors; for images with a narrow range of colors (eg., textures for sky, ground, water etc.) the neural network algorithm produces slightly better quality.

Dithering of textures is controlled using the -d<dither> options. As in the case of NCC textures, only a visual inspection can decide whether a dithered texture is acceptable in a textured image. The following dithering options are supported:

-de	A Floyd-Steinberg error diffusion algorithm is used to dither the output image. Usually produces images with least offensive dithering artifacts.
-dn	Disables dithering. (Default)
-d4	Uses a 4x4 ordered dithering.

 

4. Generating Output Files

1. 3df File Format
1. Overview

A 3df file is a simple ASCII header followed by binary data. In this format specification, ANSI C printf formatting codes are used to specify the format of each of the ASCII header lines.

2. Header

A 3df file’s header consists of a series of ASCII text strings, each of which are delimited by newline characters.

1. Magic cookie

Every 3df file starts with the ASCII string "3df v%d.%d", where the first and second integers represent the major and minor version numbers, respectively, of the 3df file format that the file complies with (eg "3df v1.0"). This value is known as a "magic cookie" since it is used by Glide™ and TexUS for validation.

2. Comment field

After the "magic cookie", zero or more lines in the 3df file may start with the character "#". Any data following the ‘#" is simply ignored.

3. Color format

The first line after the optional comment line of any 3df file states the color format for that file in the form of "color format: %s" where the string can be any of the following:

true, or argb8888	24-bit color + 8 bit alpha. Warning: The Voodoo Graphics hardware can not use this color format.
i8	8-bit intensity
a8	8-bit alpha
ai44	4-bit alpha/4-bit intensity
yiq	narrow-channel compressed color
rgb332	3-bit red, 3-bit green, 2-bit blue
rgb565	5-bit red. 6-bit green, 5-bit blue
argb8332	8-bit alpha, 3-bit red, 3-bit green, 2-bit blue
argb1555	1-bit alpha, 5-bit red, 5-bit green, 5-bit blue
ayiq8422	8-bit alpha + narrow-channel compressed color
argb4444	4-bit alpha, 4-bit red, 4-bit green, 4-bit blue
ai88	8-bit alpha, 8-bit intensity

4. LOD range

After the color format, the next line of the 3df file contains information on the range of image sizes in the form of "lod range: %d %d" where the first and second integers are the minimum and maximum LOD values respectively. These LOD values are the same values that the Voodoo Graphics hardware expects.

5. Aspect Ratio

The aspect ratio is presented in the form "aspect ratio: %d %d", where the first integer divided by the second integer represents the ratio of image width to image height.

3. Image data

After the line containing aspect ratio information, each MIPmap level is stored in order from low to high. Each image is stored left to right, top to bottom, where each texel is written as specified in the color format field. If using an eight bit color format, the image data is written out a byte at a time. If using a sixteen bit color format, the leftmost byte in the color specification (ie alpha and red in the case of ARGB4444) is the first byte in the data stream.

2. Interfacing with the TexUS library
1. Overview

The TexUS library was created to allow Glide users to convert textures from an internal, application specific format to one that Glide can download to texture memory.

2. Example usage

See example program "viewppm.c".

3. Library reference