doc/man/lbximg.1

   1 .Dd September 12, 2021
   2 .Os liblbx
   3 .Dt LBXIMG \&1 "2ooM Reference Manual"
   4 .Sh NAME
   5 .Nm lbximg
   6 .Nd inspect and decode LBX images
   7 .Sh SYNOPSIS
   8 .Nm
   9 .Op Fl i Ns | Ns Fl d
  10 .Op Fl v
  11 .Op Fl n
  12 .Op Fl F Ar format
  13 .Op Fl p Ar palette_file
  14 .Op Fl O Ar override_file
  15 .Op Fl f Ar path
  16 .Op Ar frameno ...
  17 .Sh DESCRIPTION
  18 .Nm
  19 identifies and decodes LBX image files, using
  20 .Em liblbx .
  21 LBX images are multi-frame, 256-colour paletted images with transparency.
  22 .Nm
  23 can be used to convert some or all of the frames of an LBX image to other image
  24 formats.
  25 .Sh OPTIONS
  26 .Bl -tag -width indent
  27 .It Fl i , -ident
  28 Sets the operating mode to identify the image format.
  29 .It Fl d , -decode
  30 Sets the operating mode to decode frames to PNG.
  31 .It Fl v , -verbose
  32 Output additional information on standard output.
  33 .It Fl F , -format Ar format
  34 Select the desired output format.  Some formats may not be available depending
  35 on the compile-time settings of
  36 .Nm .
  37 If this option is not specified, the default is the first in the following list
  38 which is enabled at build time.
  39 .Bl -column -offset indent ".Em Format"
  40 .It Em Format Ta Em Description
  41 .It png Ta
  42 Output images in Portable Network Graphics (PNG) format.  This is is a
  43 compressed format which is well-supported by other tools.  All features of
  44 .Nm
  45 are supported with this format.
  46 .It pam Ta
  47 Output images in Netpbm PAM format.  This is a simple uncompressed binary image
  48 format supporting RGB and alpha channels.  All features of
  49 .Nm
  50 are supported with this format.
  51 .It ppm Ta
  52 Output image colour data in Netpbm "plain" PPM format.  This is a simple
  53 7-bit clean uncompressed RGB format.  It does not support transparency, so
  54 images will have transparent pixels replaced with black.  This format is
  55 rather inefficient and provided mainly for testing.
  56 .It pbm Ta
  57 Output image mask data in Netpbm "plain" PBM format.  This is a simple 7-bit
  58 clean uncompressed bitmap format.  It does not support colour data; instead,
  59 bitmap values represent whether or not a pixel is transparent.  Black (1)
  60 pixels are transparent, white (0) pixels are opaque.  This format is extremely
  61 inefficient and provided mainly for testing.
  62 .El
  63 .It Fl f , -file Ar path
  64 Read from the specified
  65 .Ar path
  66 instead of standard input.
  67 .It Fl -output-prefix Ar string
  68 Prefix each output filename with the given string.  Filenames are produced by
  69 adding a frame number and file extension to the given prefix.  The default
  70 prefix is
  71 .Li out .
  72 .It Fl n , -no-palette
  73 Instead of looking up colour indices in the palette, emit a grayscale image
  74 where the intensity value of a pixel is equal to the palette index itself.
  75 This is mainly useful for debugging the image decoder in
  76 .Em liblbx .
  77 .It Fl p , -palette Ar palette_file
  78 Read the base palette from
  79 .Ar palette_file .
  80 In Moo2, these files are found in
  81 .Pa fonts.lbx .
  82 Without this option, the base palette is filled with a nice hot pink.  Colours
  83 in the base palette are superseded by those in the embedded palette and the
  84 override palette.
  85 .It Fl O , -override Ar override_file
  86 Use the embedded palette of an LBX image specified by
  87 .Ar override_file
  88 as the override palette.  One example of where this is used is for selecting
  89 the player colour for ship images.  Colours in the override palette supersede
  90 those in both the base palette and the embedded palette.
  91 .It Fl V , -version
  92 Print a version message and exit.
  93 .It Fl -usage
  94 Print a short usage message and exit.
  95 .It Fl -help
  96 Print a help message and exit
  97 .It Ar frameno ...
  98 Specifies the frames to decode as a sequence of intervals, with frames indexing
  99 from zero.  By default, all frames are decoded.  Multiplicity is ignored, as is
 100 the order in which frames are specified.  For example:
 101 .Bl -tag -width
 102 .It Nm Li -d 3 6
 103 Decode frames 3 and 6.
 104 .It Nm Li -d 4-9
 105 Decode frames 4 through 9, inclusive
 106 .It Nm Li -d 6-9 1-4
 107 Decode frames 1 through 9, except for frame 5.
 108 .It Nm Li -d 3-
 109 Decode all frames except the first 3.
 110 .El
 111 .El
 112 .Sh EXAMPLES
 113 After extracting fonts.lbx, mainmenu.lbx, logo.lbx and ships.lbx with
 114 .Xr lbxtool 1 :
 115 .Bl -tag -width indent
 116 .It Nm Li -ivf logo.lbx.000
 117 Print some information about the Simtex logo image.
 118 .It Nm Li -dvf mainmenu.lbx.000 -p fonts.lbx.006
 119 Decodes all the frames of the main menu panel into a series of PNGs.
 120 .It Nm Li -dvf logo.lbx.001
 121 Decodes all the frames of the Microprose logo into a series of PNGs.
 122 .It Nm Li -dvf ships.lbx.042 -p fonts.lbx.012 -O ships.lbx.049
 123 Decodes an image of a red star fortress.
 124 .El
 125 .Sh AUTHORS
 126 Nick Bowler <nbowler@draconx.ca>
 127 .Sh COPYRIGHT
 128 Copyright \(co 2008, 2010, 2013, 2021 Nick Bowler
 129 .Pp
 130 Permission is granted to copy, distribute and/or modify this manual under the
 131 terms of the GNU General Public License as published by the Free Software
 132 Foundation, either version 3 of the License, or (at your option) any later
 133 version.
 134 .Sh SEE ALSO
 135 .Xr lbxtool 1 ,
 136 .Xr lbxgui 1