dca3-game/dreamcast/pvrtex/README

pvrtex converts images to Dreamcast PowerVR textures.

It is designed to work similarly to tvspelsfreak's texconv, so it can
be used in place of texconv will minimal changes. It might be helpful
to read the readme for texconv for additional information not covered
here. In particular, there are explainations of the types of textures
supported by the Dreamcast.

Compared to texconv, pvrtex has the following enhancements:

	* Faster texture compression and palette generation
	* Can generate small codebook VQ textures
	* No Qt dependency
	* Support for compressed stride textures
	* Better mipmap generation
	* Dithering
	* Support for additional output file types (adds .PVR and .DT)

--------------------------------------------------------------------------

Usage Examples:

pvrtex -i source.png -o texture.dt
	Converts a PNG file to a DT file that is twiddled, uncompressed
	texture, without mipmaps. The format is automatically chosen
	depending on alpha content of source.png (See description for
	AUTO texture format in command option listing).

pvrtex -i source.png -o texture.dt -f argb4444 -d -c 64 -m quality -r -R
	Converts a PNG file to a DT file that is twiddled, compressed
	texture, with mipmaps. The texture will use the ARGB4444 color
	format, and dithered. If the source image is not already a
	square power-of-two, it will be resized to be the nearest square
	power-of-two. The codebook used by the compression will be limited
	to 64 entries out of the potential 256; this reduces quality, but
	reduces the size of the texture by 1.5 KB, and improves fillrate.

pvrtex -i source.png -o texture.dt -f normal -m
	Converts a PNG file containing a normal map to a DT file,
	with mipmaps.

pvrtex -i source.png -o texture.dt -s
	Converts a PNG file to a nontwiddled texture. source.png is not
	required to be a power-of-two width, and can also be any multiple
	of 32 that is <= 1024.

pvrtex -i source.png -o texture.dt -f pal8bpp -C 64 -d -p preview.png
	Converts a PNG file to a DT file with 8-bit color. The resulting
	image will not use more than 64 colors out of the potential 256,
	and will be dithered. The pallete for the texture will be written
	to texture.dt.pal. A preview of the resulting texture will be
	written to preview.png.

pvrtex -i mip256.png -i mip128.png -i mip64.png -i mip32.png -i mip16.png
-o texture.dt -m
	Generates a mipmapped texture, using the different input images
	as user defined mipmap levels instead of automatically generating
	all of them. If a mipmap level is not defined by the user, it
	will be generated from a higher level. By default, the higher
	level will not be the level above, but three levels above; if you
	want to use the level above, use fast mipmaps (-m fast) instead.

--------------------------------------------------------------------------

Building:

	Run "make".

	:-|

	To generate the proper README with linebreaks, from
	readme_unformatted.txt, run "make README" or "make all". Requires
	"fmt".

--------------------------------------------------------------------------

Command Line Options:

--help, -h
	Displays help

--version, -V
	Displays version

--in [filename], -i [filename]
	Input image file. This option is required.

	If multiple input images are specified, they are currently
	assumed to be different mipmap levels for a single texture. Resize
	options can not be used for custom mipmaps, so all images must
	be a square power-of-two.

	Uses stb_image library for reading the image. The supported
	formats are:
		JPEG, PNG, TGA, BMP, PSD, GIF, HDR, PIC, PMN

--out [filename], -o [filename]
	Sets the file name of the converted texture. The extension of
	this filename controls the file format.

	The supported formats are:

	.PVR
		Official PowerVR texture. This is incomplete as was
		created to help test the output of the converter, by
		using PC PVR viewing programs to check the resulting
		texture. There are likely incompatiblities with .PVR
		handling of official games (for example, pvrtex does
		not add a GBIX chunk).
	.TEX
		Format used by tvspelsfreak's texconv. pvrtex will
		generate certain formats not supported by texconv but
		representable in the file format (like compressed stride
		textures).
	.DT
		New file format used by this program. Supports small
		codebook VQ, and texture data is aligned to a 32-byte
		boundry to make DMA easier.

	It's possible to specify no output file if only a preview image
	is desired.

--format [type], -f [type]
	Sets the pixel format of the resulting texture.

	[type] can be one of the following:

	RGB565
		Best color out of standard formats without sacrificing
		speed, but can have rainbowing on grayscale images.
	ARGB1555
		Allows for fully transparent texels. Better choice for
		grayscale than RGB565, which can have rainbowing.
	ARGB4444
		Allows for alpha gradients, but poorest color depth with
		noticable banding.
	YUV422 / YUV
		Better than RGB565 or ARGB1555 for gradients, but
		bi/trilinear filtering has worse performance.
	PAL8BPP
		Maximum of 256 colors. Palette is generated as a seperate
		file. Must be twiddled. If compression, mipmapping,
		and bi/trilinear are used, a hardware bug causes some
		texels to be filtered incorrectly on the top left/bottom
		right corners of a 4x2 block.
	PAL4BPP
		Maximum of 16 colors. Palette is generated as a seperate
		file. Must be twiddled. If compression, mipmapping,
		and bi/trilinear are used, a hardware bug causes some
		texels to be filtered incorrectly on the top left/bottom
		right corners of a 4x4 block
	BUMPMAP
		Generates PVR normal map. Source image is treated as a
		height map.
	NORMAL
		Generates PVR normal map. Source image is treated as a
		DOT3 normal map, with RGB channels corresponding to the
		normal's XYZ.
	AUTO
		Selects RGB565, ARGB1555, or ARGB4444 depending on alpha
		content of input image. If fully opaque, RGB565 is used,
		all pixels have either fully opaque or fully transparent
		alpha, ARGB1555 is used, and if some pixels have non-fully
		opaque or transparent pixels, ARGB4444 is used.
	AUTOYUV
		Same as AUTO, but usage of RGB565 is replaced with YUV422.

--preview [filename], -p [filename]
	Generates a preview of the resulting texture file. You can
	see the results of bit depth reduction, dithering, mipmaps,
	and compression.

	The preview is can be a PNG, JPG, BMP, or TGA file. Preview
	JPGs are generally not a good choice do to the lack of alpha,
	and possiblility of compression artifacts.

--compress [codebook_size / "small"], -c [codebook_size / "small"]
	Generates a VQ compressed texture.

	codebook_size is an optional parameter adjusts the size of the
	codebook generated for the texture. Reducing the codebook_size
	can improve fillrate, and, with .PVR and .DT files, improve the
	compression ratio of small textures. By default, a full codebook
	is used to generate the best quality texture. codebook_size can
	be a number from 1 to 256, or the string "small".

	For .PVR files, using a number will never reduce the size of
	the texture, but can improve fillrate. Specifying "small" as the
	codebook size will reduce the texture size for certain textures
	smaller than 64x64 without mipmaps, or 32x32 with mipmaps.

	For .TEX files, codebook_size will never reduce the size of the
	texture, but can still improve performance.

	For .DT files, reducing the codebook_size will reduce the size
	of the texture.  Specifying "small" as the codebook size will
	select a smaller codebook automatically for textures that are
	128x128 or smaller, with a size of 192 for a 128x128 mipmapped
	texture, down to 10 for an 8x8 non-mipped texture.

--max-color [colors], -C [colors]
	This limits the number of colors used for a PAL8BPP or PAL4BPP
	format texture. This option could be used to generate an 8BPP
	texture that only uses 64 colors, and the unused colors could
	be used for other textures.

--mipmap ["fast"], -m ["fast"]
	With this option, the resulting file will have mipmaps.

	By default, a Mitchell-Netravalli filter will be used on a level
	3 steps above. (e.g. 64x64 will be generated from 512x512)

	Adding the parameter "fast" to this option, each mipmap level
	is generated by downsampling the level above. (e.g. 64x64 level
	will be generated from 128x128) This speeds up mipmap generation
	for large textures.

	When generating high quality mipmaps for a resized image,
	the largest mips will be generated directly from the source
	image. (i.e. with a 1600x500 source image, converted with "-m
	-r near -R x2", pvrtex will create a 1024x1024 texture, with
	mipmap levels 512x512 and 256x256 generated directly from the
	1600x500 source, and not the 1024x1024 top most level).

--no-mip-shift, -S
	When generating mipmaps, by default, pvrtex will preform a
	subpixel adjustment during downsampling to ensure the mipmaps
	line up correctly. This option will disable this.

--perfect-mip [levels], -M [levels]
	When using mipmaps and compression, small mipmap levels will be
	loselessly compressed.

	The levels parameter controls how many levels are lossless. 1
	means only the 1x1 level will be losslessly compressed, 2 means
	1x1 and 2x2 will be loselessly compressed, and so on.

	Generating lossless mipmaps use up VQ codebook slots. These are
	the total number of codebook entries used for a given number of
	lossless mipmaps:

			 16-bit    8-bit    4-bit
	1 level   (1x1)    1	     1	      1
	2 levels  (2x2)    2	     1	      1
	3 levels  (4x4)    6	     3	      2
	4 levels  (8x8)   22	    11	      6
	5 levels (16x16)  86	    43	     22
	6 levels (32x32)  --	   171	     86

--high-weight [levels], -H [levels]
	When using mipmaps and compression, this increases the weight
	the compressor gives smaller mipmap levels, to encourage the
	compressor to generate them at higher quality, at the cost of
	lower quality higher levels. Not currently supported for 4BPP
	textures.

	The levels parameter controls how many levels below the largest
	have extra weight. A value of 1 means every level besides the
	top has boosted weight, a value of 2 means the two largest levels
	have normal weight, while every smaller level is boosted.

--dither [amount], -d [amount]
	Enables dithering. Currently, Floyd-Steinberg is used.

	Amount is an optional parameter that adjusts the amount of
	dithering, and is a decimal value from 0 to 1. 0 will result in
	no dithering, while 1 results in full dithering. If dithering
	is enabled but an amount is not specified, full dithering is used.

	This option has no effect on YUV textures, but is valid on
	all others.

--stride, -s
	Output a non-twiddled texture. This also allows for
	non-power-of-two sized textures. Width must still 8, 16, or
	a multiple of 32 less than or equal to 1024. Any height can be
	used, from 1 to 1024.

	If a texture has a power-of-two dimensions and --stride is
	used, the resulting texture will be a nontwiddled texture that
	can be rendered without stride, for formats that support such
	textures. (.DT and .TEX support this, .PVR does not.)

	Stride textures do not wrap as normal if the width is not
	a power-of-two, and have worse rendering performance than
	twiddled textures (especially when filtered or rotated). It
	is not possible to generate palettized or normal textures with
	stride. .PVR files cannnot use stride.

	Valid widths for stride texture:
		8, 16, 32, 64, 96, 128, 160, 192, 224, 256, 320, 352,
		384, 416, 480, 512, 544, 576, 608, 640, 672, 704, 736,
		768, 800, 832, 864, 896, 928, 960, 992, 1024

--resize [method], -r [method]
	Resize a input image that is not a supported PVR texture size
	to a valid size.

	If the texture is not strided, the texture will be resized to
	a power-of-two on both dimensions. For stride textures, width
	will be adjusted to an appropriate stride size, and the height
	will always be resized to a power-of-two.

	Method controls how the image will be resized.

	NONE
		Generates an error if input image is not a valid
		size. This is the default.
	NEAR
		Round size up or down to nearest valid size. If resize is
		enabled, but no method is specified, this is the default.
	UP
		Round size up to next valid size
	DOWN
		Round size down to next valid size

	Examples for non-stride textures:
	Source size	 NONE	  NEAR	      UP       DOWN
	 256x256       256x256	 256x256   256x256   256x256
	 260x260	Error	 256x256   512x512   256x256
	 200x200	Error	 256x256   256x256   128x128
	 200x260	Error	 256x256   256x512   128x256
	2000x2000	Error	1024x1024 1024x1024 1024x1024
	   1x1		Error	   8x8	     8x8       8x8

--mip-resize [method], -R [method]
	When using mipmaps, resizes nonsquare images to be square. This
	option does nothing if not using mipmaps or the image is already
	square (after --resize). This new size calculation occurs after
	the standard --resize. Source images are only resized once. This
	option will not resize the image to a power-of-two size if it's
	not already (use --resize for that).

	Method controls how the image will be resized.

	NONE
		Generates an error if input image is not a valid mipmap
		size. This is the default.
	X2
		Doubles the narrower dimension. A 256x32 image will
		be resized to 64x64. If mip-resize is enabled, but no
		method is specified, this is the default.
	X4
		Quaduples or doubles the narrower dimension. A 256x32
		image will be resized to 128x128.
	UP
		Resizes the narrower dimension to be the same size as
		the wider. A 256x32 image will be resized to 256x256.
	DOWN
		Resizes the wider dimension to be the same size as the
		narrower. A 256x32 image will be resized to 32x32.

	Examples:

	Source size	 X2	  X4	    UP	     DOWN
	 256x256      256x256	256x256   256x256   256x256
	 256x128      256x256	256x256   256x256   128x128
	 256x64       128x128	256x256   256x256    64x64
	 256x32        64x64	128x128   256x256    32x32
	1024x8	       16x16	 32x32	 1024x1024    8x8

--edge [type], -e [type]
	Controls how the edges of the image are handled when
	resizing. This also affects height map to normal map conversion.

	Valid options:

	CLAMP
		Samples are clamped to edge of image, default if not
		mipmapped.
	WRAP
		Samples wrap around to other side of image, default if
		mipmaps are used. Is works well when the texture is used
		to that it repeats, but might cause noticble bleeding
		around the edge of the texture in certain situations. For
		example, a poster or sign that doesn't repeat across
		the polygon. In that cause, CLAMP should be used.
	REFLECT
		Samples reflect off edge of image back into valid area. If
		you use are planning on using UV mirroring instead of
		wrapping, use this instead of wrap.
	ZERO
		Outside of image is treated as transparent blackness. This
		is not currently supported for images with a --type
		of BUMPMAP.

	The default is CLAMP if not using mipmaps, or WRAP if mipmaps
	are used.

--bilinear, -b
	In texconv, this was used to generate mipmaps with a box
	filter. This option is ignored in pvrtex, which currently always
	uses a Mitchell-Netravalli filter.

--nearest, -n
	In texconv, this was used to generate mipmaps by point
	sampling. This option is not supported in pvrtex, and will cause
	pvrtex to abort.

--vqcodeusage (Not supported)
	This option from texconv is not recognized at all by pvrtex.

--------------------------------------------------------------------------

.DT File Format

	See file_dctex.h for documentation. file_dctex.h can also be used
	as a library to help access information from the file's header.

--------------------------------------------------------------------------

Known bugs

	High weight compressed mips (--high-weight) does not currently
	work with 4BPP textures; the parameter will be ignored if
	specified.

	There is a weird pathological performance issue with compression
	on certain textures. With a 1024x1024 texture with mips that
	is ff000000 on the left side, and ffffffff on the right side,
	performance drops by around 15x. It is apparently cache missing
	constantly, according to cachegrind, in a function that reads
	memory linearly (distance_limited in elbg.c). Doesn't make sense.

--------------------------------------------------------------------------

Future Ideas

	* Code clean up

	* Add Yliluoma dithering

	* Improve error checking

	* It might be possible to improve VQ quality by compressing
	4/5/6 bit color instead of 8 bit (so the compressor won't waste
	codebook space on colors that are too similar to distinguish at
	given bit depth)

	* Speed up compression by not processing alpha for opaque textures

	* Add ability to generate a single palette to be shared for
	multiple textures

	* Allow specifying palette format

	* Allow specifiying custom external palette for texture

	* Add ability to generate animated VQ textures with shared
	codebook for all frames

	* Auto generate output name (e.g. -i image.png -o $.dt will
	output image.dt)

	* Add wildcard input files (e.g. -i *.png)

	* Add VQ index dithering

	* Add KIMG output support

	* Allow texture formats (PVR/TEX/DT/KMG) to be used as input
	formats, to transcode or recompress textures

	* Add per-axis edge sampling control

	* Rework code so that this can be used as a library

	* Allow sizing to arbitary size (i.e. --resize 256x256)

	* Add a filter to try to hide the palettized compressed mipmap bug

--------------------------------------------------------------------------

History:

	Version 1.01
		Program now displays error message when an error occurs
		loading a source image. Previously, the program would
		hit an assertion.

		Fixed "--resize down" option. Previously, the program
		would round down sizes that were already a power-of-two,
		now sizes that are already POT are left unchanged.

		Included a missing FFmpeg header file.

	Version 1.0
		Initial release

--------------------------------------------------------------------------

License:
	This uses code from FFmpeg, which is LGPL, so this project is
	also LGPL. Files not originating from FFmpeg can also be used
	as public domain code/BSD/MIT/whatever.