<article>
<title>sp65 Users Guide
-<author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
-<date>2012-03-11
+<author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
<abstract>
sp65 is a sprite and bitmap utility that is part of the cc65 development suite.
Long options:
--convert-to fmt[,attrlist] Convert into target format
+ --dump-palette Dump palette as table
--help Help (this text)
--list-conversions List all possible conversions
--pop Restore the original loaded image
see section <ref id="conversions" name="Conversions">.
+ <label id="option--dump-palette">
+ <tag><tt>--dump-palette</tt></tag>
+
+ Dump palette as table.
+
+
<label id="option--help">
<tag><tt>-h, --help</tt></tag>
+<sect>Processing pipeline<label id="processing-pipeline"><p>
+
+sp65 consists of
+
+<itemize>
+<item>Front ends that read graphics data,
+<item>processors for graphics data,
+<item>converters
+<item>and output modules for several formats.
+</itemize>
+
+These modules can be combined to a pipeline that reads data, does some
+optional bitmap processing, converts the bitmap into a target format, and
+writes this binary data to disk in one of several forms.
+
+
+
<sect>Attribute lists<label id="attr-lists"><p>
+As described in <ref id="processing-pipeline" name="Processing pipeline">,
+sp65 consists of lots of different modules that may be combined in different
+ways, to convert an input bitmap to some output.
+
+Many of the processors and converters have options to change the way, they're
+working. To avoid having lots of command line options that must be parsed on
+high level and passed down to the relevant parts of the program, sp65 features
+something called "attribute lists". Attribute lists are lists of
+attribute/value pairs. These lists are parsed by the main program module
+without any knowledge about their meaning. Lower level parts just grab the
+attributes they need.
+
+In general, attribute lists look like this:
+
+<tscreen><verb>
+ attr1=val1[,attr2=val2[,...]]
+</verb></tscreen>
+
+Instead of the comma, colons may also be used (even mixed).
+
+To simplify things and to make the most common options look "normal", some
+mandatory attributes may be given without an attribute name. If the attribute
+name is missing, the default name is determined by the position. For example,
+the option <tt/<ref id="option--read" name="--read">/ does always need a file
+name. The attribute name for the file name is "name". To avoid having to type
+
+<tscreen><verb>
+ sp65 --read name=ball.pcx ...
+</verb></tscreen>
+
+the first attribute gets the default name "name" assigned. So if the first
+attribute doesn't have a name, it is assumed that it is the file name. This
+means that instead of the line above, one can also use
+
+<tscreen><verb>
+ sp65 --read ball.pcx ...
+</verb></tscreen>
+
+The second attribute for <tt/--read/ is the format of the input file. So when
+using
+
+<tscreen><verb>
+ sp65 --read ball.pic:pcx ...
+</verb></tscreen>
+
+a PCX file named "ball.pic" is read. The long form would be
+
+<tscreen><verb>
+ sp65 --read name=ball.pic:format=pcx ...
+</verb></tscreen>
+
+Changing the order of the attributes is possible only when explicitly
+specifying the names of the attributes. Using
+
+<tscreen><verb>
+ sp65 --read pcx:ball.pic ...
+</verb></tscreen>
+
+will make sp65 complain, because it tries to read a file named "pcx" with an
+(unknown) format of "ball.pic". The following however will work:
+
+<tscreen><verb>
+ sp65 --read format=pcx:name=ball.pic ...
+</verb></tscreen>
+
+The attributes that are valid for each processor or converter are listed
+below.
+
<sect>Input formats<label id="input-formats"><p>
+Input formats are either specified explicitly when using <tt/<ref
+id="option--read" name="--read">/, or are determined by looking at the
+extension of the file name given.
+
<sect1>PCX<p>
+While sp65 is prepared for more, this is currently the only possible input
+format. There are no additional attributes for this format.
+
<sect>Conversions<label id="conversions"><p>
+<sect1>GEOS bitmap<p>
+
+The current bitmap working copy is converted to a GEOS compacted bitmap. This
+format is used by several GEOS functions (i.e. 'BitmapUp') and is described
+in 'The Official GEOS Programmers Reference Guide', chapter 4, section
+'Bit-Mapped Graphics'.
+
+
+<sect1>GEOS icon<p>
+
+The current bitmap working copy is converted to GEOS icon format. A GEOS icon
+has the same format as a C64 high resolution sprite (24x21, monochrome, 63
+bytes). There are no additional attributes for this conversion.
+
+
+<sect1>Koala image<p>
-<sect1>VIC2 sprites<p>
+<sect1>Lynx sprite<p>
-<sect1>Koala images<p>
+Lynx can handle 1, 2, 3 and 4 bits per pixel indexed sprites. The maximum size
+of a sprite is roughly 508 pixels but in reality the Lynx screen is only 160 by
+102 pixels which makes very large sprites useless.
+
+The number per pixels is taken from the number of colors of the input bitmap.
+
+There are a few attributes that you can give to the conversion software.
+
+<descrip>
+
+ <tag/mode/
+ The first is what kind of encoding to use for the sprite. The attribute for
+ this is called "mode" and the possible values are "literal", "packed" or
+ "transparent". The default is "packed" if no mode is specified.
+
+ The "literal" is a totally literal mode with no packing. In this mode the
+ number of pixels per scanline will be a multiple of 8 both right and left from
+ the action point.
+
+ If the source bitmap edge ends with a color where the least significant bit is
+ one then there will be an extra 8 zero bits on that scan line.
+
+ So if you are using totally literal sprites and intend to change them at
+ runtime then please add a single pixel border far left and far right with
+ zeros in order to prevent graphical glitches in the game.
+
+ The standard encoding is called "packed". In this mode the sprite is packed
+ using run-length encoding and literal coding mixed for optimisation to
+ produce a small sprite.
+
+ The last encoding mode "transparent" is like packed. But here we know that
+ the index 0 will be transparent so we can clip off all 0 pixels from the left
+ and right edge of the sprite. This will produce the smallest sprite possible
+ on the Lynx. The sprite is not rectangular anymore.
+
+ <tag/ax/
+ The sprite is painted around the Anchor point. The anchor point x can be
+ between 0 and the width of the sprite - 1. If anchor point x is zero then
+ painting the sprite in location 10,20 will set the left edge of the sprite
+ 10 pixels from the left of the Lynx screen. When the sprite is scaled by
+ hardware the anchor point stays in place and the sprite grows or shrinks
+ around the anchor point. The default value is 0 (left).
+
+ <tag/ay/
+ The sprite is painted around the Anchor point. The anchor point y can be
+ between 0 and the height of the sprite - 1. If anchor point y is zero then
+ painting the sprite in location 10,20 will set the top of the sprite 20
+ pixels from the top of the Lynx screen. When the sprite is scaled by
+ hardware the anchor point stays in place and the sprite grows or shrinks
+ around the anchor point. The default value is 0 (top).
+
+</descrip>
+
+<sect1>VIC2 sprite<p>
<sect1>Binary<p>
For this format, the processed data is written to the output file in raw
-binary format. There are not attributes for this output format.
+binary format. There are no additional attributes (besides "name" and
+"format") for this output format.
<sect1>Assembler code<p>
prefixed by '$'. For base 10, there is no prefix.
<tag/bytesperline/
- The value for this attribute specifies the number of bytes output in
- one line of the assembler file. The default is 16.
+ The value for this attribute specifies the number of bytes output in one
+ line of the assembler file. The default is 16.
- <tag/label/
- If specified, an assembler label is added in front of the data.
-
- <tag/segment/
- If specified, a <tt/.SEGMENT/ directive is used to place the data into
- the given segment.
+ <tag/ident/
+ This is an optional attribute. When given, the output processor will wrap
+ the data into a <tt/.PROC/ with the given name. In addition, three constants
+ are added as local symbols within the <tt/.PROC/: <tt/COLORS/, <tt/WIDTH/
+ and <tt/HEIGHT/.
</descrip>
-
<sect1>C code<p>
+When using C output format, a small piece of C source code is generated that
+defines the data containing the output in an array of <tt/unsigned char/.
+
+Possible attributes for this format are:
+
+<descrip>
+ <tag/base/
+ The value for this attribute specifies the numeric base for the data values.
+ It may be either 10 or 16. The default is 16. If the base is 16, the numbers
+ are prefixed by 0x. For base 10, there is no prefix.
+ <tag/bytesperline/
+ The value for this attribute specifies the number of bytes output in one
+ line of the C source code. The default is 16.
-<sect>Bugs/Feedback<p>
+ <tag/ident/
+ This is an optional attribute. When given, the output processor will wrap
+ the data into an array of unsigned char with the given name. In addition,
+ three <tt/#define/s are added for <tt/<ident>_COLORS/,
+ <tt/<ident>_WIDTH/ and <tt/<ident>_HEIGHT/.
-If you have problems using the assembler, if you find any bugs, or if
-you're doing something interesting with the assembler, I would be glad to
-hear from you. Feel free to contact me by email
-(<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">).
+</descrip>
projects / cc65 / blobdiff