1 <!doctype linuxdoc system> <!-- -*- text-mode -*- -->
4 <title>sp65 Users Guide
5 <author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
8 sp65 is a sprite and bitmap utility that is part of the cc65 development suite.
9 It is used to convert graphics and bitmaps into the target formats of the
13 <!-- Table of contents -->
16 <!-- Begin the document -->
20 sp65 is a tool that converts images from common formats into formats used
21 on the 6502 platforms that are the targets of the cc65 compiler suite. In
22 addition, it allows some very simple operation with loaded graphics data, like
23 using part of an image for further processing.
25 The utility has been designed in a way that adding additional source or target
26 formats is easy. The final output is either binary, or C/assembler source.
33 <sect1>Command line option overview<p>
35 The sp65 utility accepts the following options:
38 ---------------------------------------------------------------------------
39 Usage: sp65 [options] file [options] [file]
41 -V Print the version number and exit
42 -c fmt[,attrlist] Convert into target format
44 -lc List all possible conversions
45 -r file[,attrlist] Read an input file
47 -w file[,attrlist] Write the output to a file
50 --convert-to fmt[,attrlist] Convert into target format
51 --dump-palette Dump palette as table
52 --help Help (this text)
53 --list-conversions List all possible conversions
54 --pop Restore the original loaded image
55 --read file[,attrlist] Read an input file
56 --slice x,y,w,h Generate a slice from the loaded bitmap
57 --verbose Increase verbosity
58 --version Print the version number and exit
59 --write file[,attrlist] Write the output to a file
60 ---------------------------------------------------------------------------
64 <sect1>Command line options in detail<p>
66 Below is a description of all the command line options. For the concept of
67 attribute lists see <ref id="attr-lists" name="below">.
71 <label id="option--convert-to">
72 <tag><tt>-c, --convert-to format[,attrlist]</tt></tag>
74 Convert a bitmap into one of the supported target formats. The option
75 argument must at least contain the "format" attribute. For more attributes,
76 see section <ref id="conversions" name="Conversions">.
79 <label id="option--dump-palette">
80 <tag><tt>--dump-palette</tt></tag>
82 Dump palette as table.
85 <label id="option--help">
86 <tag><tt>-h, --help</tt></tag>
88 Print the short option summary shown above.
91 <label id="option--list-conversions">
92 <tag><tt>-lc, --list-conversions</tt></tag>
94 Print a list of possible conversions.
97 <label id="option--pop">
98 <tag><tt>--pop</tt></tag>
100 Restore the working copy of the bitmap from the one originally loaded from
101 the file. This may for example be used when creating several output files
105 <label id="option--read">
106 <tag><tt>-r, --read filename[,attrlist]</tt></tag>
108 Read an input file. The option argument must at least contain the "name"
109 attribute. See <ref id="input-formats" name="input formats"> for more
113 <label id="option-v">
114 <tag><tt>-v, --verbose</tt></tag>
116 Increase verbosity. Usually only needed for debugging purposes. You may use
117 this option more than one time for even more verbose output.
120 <label id="option-V">
121 <tag><tt>-V, --version</tt></tag>
123 Print the version number of the assembler. If you send any suggestions or
124 bugfixes, please include the version number.
127 <label id="option--write">
128 <tag><tt>-w, --write filename[,attrlist]</tt></tag>
130 Write an output file. The option argument must at least contain the "name"
131 attribute. See <ref id="output-formats" name="output formats"> for more
139 <sect>Processing pipeline<label id="processing-pipeline"><p>
144 <item>Front ends that read graphics data,
145 <item>processors for graphics data,
147 <item>and output modules for several formats.
150 These modules can be combined to a pipeline that reads data, does some
151 optional bitmap processing, converts the bitmap into a target format, and
152 writes this binary data to disk in one of several forms.
156 <sect>Attribute lists<label id="attr-lists"><p>
158 As described in <ref id="processing-pipeline" name="Processing pipeline">,
159 sp65 consists of lots of different modules that may be combined in different
160 ways, to convert an input bitmap to some output.
162 Many of the processors and converters have options to change the way, they're
163 working. To avoid having lots of command line options that must be parsed on
164 high level and passed down to the relevant parts of the program, sp65 features
165 something called "attribute lists". Attribute lists are lists of
166 attribute/value pairs. These lists are parsed by the main program module
167 without any knowledge about their meaning. Lower level parts just grab the
168 attributes they need.
170 In general, attribute lists look like this:
173 attr1=val1[,attr2=val2[,...]]
176 Instead of the comma, colons may also be used (even mixed).
178 To simplify things and to make the most common options look "normal", some
179 mandatory attributes may be given without an attribute name. If the attribute
180 name is missing, the default name is determined by the position. For example,
181 the option <tt/<ref id="option--read" name="--read">/ does always need a file
182 name. The attribute name for the file name is "name". To avoid having to type
185 sp65 --read name=ball.pcx ...
188 the first attribute gets the default name "name" assigned. So if the first
189 attribute doesn't have a name, it is assumed that it is the file name. This
190 means that instead of the line above, one can also use
193 sp65 --read ball.pcx ...
196 The second attribute for <tt/--read/ is the format of the input file. So when
200 sp65 --read ball.pic:pcx ...
203 a PCX file named "ball.pic" is read. The long form would be
206 sp65 --read name=ball.pic:format=pcx ...
209 Changing the order of the attributes is possible only when explicitly
210 specifying the names of the attributes. Using
213 sp65 --read pcx:ball.pic ...
216 will make sp65 complain, because it tries to read a file named "pcx" with an
217 (unknown) format of "ball.pic". The following however will work:
220 sp65 --read format=pcx:name=ball.pic ...
223 The attributes that are valid for each processor or converter are listed
228 <sect>Input formats<label id="input-formats"><p>
230 Input formats are either specified explicitly when using <tt/<ref
231 id="option--read" name="--read">/, or are determined by looking at the
232 extension of the file name given.
236 While sp65 is prepared for more, this is currently the only possible input
237 format. There are no additional attributes for this format.
241 <sect>Conversions<label id="conversions"><p>
243 <sect1>GEOS bitmap<p>
245 The current bitmap working copy is converted to a GEOS compacted bitmap. This
246 format is used by several GEOS functions (i.e. 'BitmapUp') and is described
247 in 'The Official GEOS Programmers Reference Guide', chapter 4, section
248 'Bit-Mapped Graphics'.
253 The current bitmap working copy is converted to GEOS icon format. A GEOS icon
254 has the same format as a C64 high resolution sprite (24x21, monochrome, 63
255 bytes). There are no additional attributes for this conversion.
258 <sect1>Koala image<p>
261 <sect1>Lynx sprite<p>
263 Lynx can handle 1, 2, 3 and 4 bits per pixel indexed sprites. The maximum size
264 of a sprite is roughly 508 pixels but in reality the Lynx screen is only 160 by
265 102 pixels which makes very large sprites useless.
267 The number per pixels is taken from the number of colors of the input bitmap.
269 There are a few attributes that you can give to the conversion software.
274 The first is what kind of encoding to use for the sprite. The attribute for
275 this is called "mode" and the possible values are "literal", "packed" or
276 "transparent". The default is "packed" if no mode is specified.
278 The "literal" is a totally literal mode with no packing. In this mode the
279 number of pixels per scanline will be a multiple of 8 both right and left from
282 If the source bitmap edge ends with a color where the least significant bit is
283 one then there will be an extra 8 zero bits on that scan line.
285 So if you are using totally literal sprites and intend to change them at
286 runtime then please add a single pixel border far left and far right with
287 zeros in order to prevent graphical glitches in the game.
289 The standard encoding is called "packed". In this mode the sprite is packed
290 using run-length encoding and literal coding mixed for optimisation to
291 produce a small sprite.
293 The last encoding mode "transparent" is like packed. But here we know that
294 the index 0 will be transparent so we can clip off all 0 pixels from the left
295 and right edge of the sprite. This will produce the smallest sprite possible
296 on the Lynx. The sprite is not rectangular anymore.
299 The sprite is painted around the Anchor point. The anchor point x can be
300 between 0 and the width of the sprite - 1. If anchor point x is zero then
301 painting the sprite in location 10,20 will set the left edge of the sprite
302 10 pixels from the left of the Lynx screen. When the sprite is scaled by
303 hardware the anchor point stays in place and the sprite grows or shrinks
304 around the anchor point. The default value is 0 (left).
307 The sprite is painted around the Anchor point. The anchor point y can be
308 between 0 and the height of the sprite - 1. If anchor point y is zero then
309 painting the sprite in location 10,20 will set the top of the sprite 20
310 pixels from the top of the Lynx screen. When the sprite is scaled by
311 hardware the anchor point stays in place and the sprite grows or shrinks
312 around the anchor point. The default value is 0 (top).
316 <sect1>VIC2 sprite<p>
321 <sect>Output formats<label id="output-formats"><p>
323 Using <tt/<ref id="option--write" name="--write">/ it is possible to write
324 processed data to an output file. An attribute "name" is mandatory, it is used
325 as the file name for the output. The output format can be specified using an
326 attribute named "format". If this attribute doesn't exist, the output format
327 is determined by looking at the file name extension.
332 For this format, the processed data is written to the output file in raw
333 binary format. There are no additional attributes (besides "name" and
334 "format") for this output format.
337 <sect1>Assembler code<p>
339 For this format, the processed data is written to the output file in ca65
340 assembler format. There are several attributes for this output format:
345 The value for this attribute specifies the numeric base for the data
346 values. It may be either 2, 10 or 16. The default is 16. If the base is
347 2, the numbers are prefixed by '%', if the base is 16, the numbers are
348 prefixed by '$'. For base 10, there is no prefix.
351 The value for this attribute specifies the number of bytes output in one
352 line of the assembler file. The default is 16.
355 This is an optional attribute. When given, the output processor will wrap
356 the data into a <tt/.PROC/ with the given name. In addition, three constants
357 are added as local symbols within the <tt/.PROC/: <tt/COLORS/, <tt/WIDTH/
366 When using C output format, a small piece of C source code is generated that
367 defines the data containing the output in an array of <tt/unsigned char/.
369 Possible attributes for this format are:
373 The value for this attribute specifies the numeric base for the data values.
374 It may be either 10 or 16. The default is 16. If the base is 16, the numbers
375 are prefixed by 0x. For base 10, there is no prefix.
378 The value for this attribute specifies the number of bytes output in one
379 line of the C source code. The default is 16.
382 This is an optional attribute. When given, the output processor will wrap
383 the data into an array of unsigned char with the given name. In addition,
384 three <tt/#define/s are added for <tt/<ident>_COLORS/,
385 <tt/<ident>_WIDTH/ and <tt/<ident>_HEIGHT/.
393 sp65 (and all cc65 binutils) are (C) Copyright 1998-2012 Ullrich von Bassewitz
394 and others. For usage of the binaries and/or sources the following conditions
397 This software is provided 'as-is', without any expressed or implied
398 warranty. In no event will the authors be held liable for any damages
399 arising from the use of this software.
401 Permission is granted to anyone to use this software for any purpose,
402 including commercial applications, and to alter it and redistribute it
403 freely, subject to the following restrictions:
406 <item> The origin of this software must not be misrepresented; you must not
407 claim that you wrote the original software. If you use this software
408 in a product, an acknowledgment in the product documentation would be
409 appreciated but is not required.
410 <item> Altered source versions must be plainly marked as such, and must not
411 be misrepresented as being the original software.
412 <item> This notice may not be removed or altered from any source