-.Dd January 4, 2008
+.Dd September 12, 2021
.Os liblbx
.Dt LBXIMG \&1 "2ooM Reference Manual"
.Sh NAME
.Nm
.Op Fl i Ns | Ns Fl d
.Op Fl v
+.Op Fl n
+.Op Fl F Ar format
.Op Fl p Ar palette_file
.Op Fl O Ar override_file
.Op Fl f Ar path
.Em liblbx .
LBX images are multi-frame, 256-colour paletted images with transparency.
.Nm
-can be used to convert some or all of the frames of an LBX image to PNG.
+can be used to convert some or all of the frames of an LBX image to other image
+formats.
.Sh OPTIONS
.Bl -tag -width indent
.It Fl i , -ident
Sets the operating mode to decode frames to PNG.
.It Fl v , -verbose
Output additional information on standard output.
+.It Fl F , -format Ar format
+Select the desired output format. Some formats may not be available depending
+on the compile-time settings of
+.Nm .
+If this option is not specified, the default is the first in the following list
+which is enabled at build time.
+.Bl -column -offset indent ".Em Format"
+.It Em Format Ta Em Description
+.It png Ta
+Output images in Portable Network Graphics (PNG) format. This is is a
+compressed format which is well-supported by other tools. All features of
+.Nm
+are supported with this format.
+.It pam Ta
+Output images in Netpbm PAM format. This is a simple uncompressed binary image
+format supporting RGB and alpha channels. All features of
+.Nm
+are supported with this format.
+.It ppm Ta
+Output image colour data in Netpbm "plain" PPM format. This is a simple
+7-bit clean uncompressed RGB format. It does not support transparency, so
+images will have transparent pixels replaced with black. This format is
+rather inefficient and provided mainly for testing.
+.It pbm Ta
+Output image mask data in Netpbm "plain" PBM format. This is a simple 7-bit
+clean uncompressed bitmap format. It does not support colour data; instead,
+bitmap values represent whether or not a pixel is transparent. Black (1)
+pixels are transparent, white (0) pixels are opaque. This format is extremely
+inefficient and provided mainly for testing.
+.El
.It Fl f , -file Ar path
Read from the specified
.Ar path
-instead of standard input. If
-.Ar path
-is -,
-.Nm
-will read from standard input anyway.
+instead of standard input.
+.It Fl -output-prefix Ar string
+Prefix each output filename with the given string. Filenames are produced by
+adding a frame number and file extension to the given prefix. The default
+prefix is
+.Li out .
+.It Fl n , -no-palette
+Instead of looking up colour indices in the palette, emit a grayscale image
+where the intensity value of a pixel is equal to the palette index itself.
+This is mainly useful for debugging the image decoder in
+.Em liblbx .
.It Fl p , -palette Ar palette_file
Read the base palette from
.Ar palette_file .
.It Fl O , -override Ar override_file
Use the embedded palette of an LBX image specified by
.Ar override_file
-as the override palette. In Moo2, this is notably used to select the player
-colour for ship images. Colours in the override palette supersede those in
-both the base palette and the embedded palette.
+as the override palette. One example of where this is used is for selecting
+the player colour for ship images. Colours in the override palette supersede
+those in both the base palette and the embedded palette.
+.It Fl V , -version
+Print a version message and exit.
+.It Fl -usage
+Print a short usage message and exit.
+.It Fl -help
+Print a help message and exit
.It Ar frameno ...
Specifies the frames to decode as a sequence of intervals, with frames indexing
from zero. By default, all frames are decoded. Multiplicity is ignored, as is
Decode all frames except the first 3.
.El
.El
+.Sh EXAMPLES
+After extracting fonts.lbx, mainmenu.lbx, logo.lbx and ships.lbx with
+.Xr lbxtool 1 :
+.Bl -tag -width indent
+.It Nm Li -ivf logo.lbx.000
+Print some information about the Simtex logo image.
+.It Nm Li -dvf mainmenu.lbx.000 -p fonts.lbx.006
+Decodes all the frames of the main menu panel into a series of PNGs.
+.It Nm Li -dvf logo.lbx.001
+Decodes all the frames of the Microprose logo into a series of PNGs.
+.It Nm Li -dvf ships.lbx.042 -p fonts.lbx.012 -O ships.lbx.049
+Decodes an image of a red star fortress.
+.El
+.Sh AUTHORS
+Nick Bowler <nbowler@draconx.ca>
+.Sh COPYRIGHT
+Copyright \(co 2008, 2010, 2013, 2021 Nick Bowler
+.Pp
+Permission is granted to copy, distribute and/or modify this manual under the
+terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+.Sh SEE ALSO
+.Xr lbxtool 1 ,
+.Xr lbxgui 1