1 <!doctype linuxdoc system> <!-- -*- text-mode -*- -->
4 <title>sp65 Users Guide
5 <author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
9 sp65 is a sprite and bitmap utility that is part of the cc65 development suite.
10 It is used to convert graphics and bitmaps into the target formats of the
14 <!-- Table of contents -->
17 <!-- Begin the document -->
21 sp65 is a tool that converts images from common formats into formats used
22 on the 6502 platforms that are the targets of the cc65 compiler suite. In
23 addition, it allows some very simple operation with loaded graphics data, like
24 using part of an image for further processing.
26 The utility has been designed in a way that adding additional source or target
27 formats is easy. The final output is either binary, or C/assembler source.
34 <sect1>Command line option overview<p>
36 The sp65 utility accepts the following options:
39 ---------------------------------------------------------------------------
40 Usage: sp65 [options] file [options] [file]
42 -V Print the version number and exit
43 -c fmt[,attrlist] Convert into target format
45 -lc List all possible conversions
46 -r file[,attrlist] Read an input file
48 -w file[,attrlist] Write the output to a file
51 --convert-to fmt[,attrlist] Convert into target format
52 --dump-palette Dump palette as table
53 --help Help (this text)
54 --list-conversions List all possible conversions
55 --pop Restore the original loaded image
56 --read file[,attrlist] Read an input file
57 --slice x,y,w,h Generate a slice from the loaded bitmap
58 --verbose Increase verbosity
59 --version Print the version number and exit
60 --write file[,attrlist] Write the output to a file
61 ---------------------------------------------------------------------------
65 <sect1>Command line options in detail<p>
67 Below is a description of all the command line options. For the concept of
68 attribute lists see <ref id="attr-lists" name="below">.
72 <label id="option--convert-to">
73 <tag><tt>-c, --convert-to format[,attrlist]</tt></tag>
75 Convert a bitmap into one of the supported target formats. The option
76 argument must at least contain the "format" attribute. For more attributes,
77 see section <ref id="conversions" name="Conversions">.
80 <label id="option--dump-palette">
81 <tag><tt>--dump-palette</tt></tag>
83 Dump palette as table.
86 <label id="option--help">
87 <tag><tt>-h, --help</tt></tag>
89 Print the short option summary shown above.
92 <label id="option--list-conversions">
93 <tag><tt>-lc, --list-conversions</tt></tag>
95 Print a list of possible conversions.
98 <label id="option--pop">
99 <tag><tt>--pop</tt></tag>
101 Restore the working copy of the bitmap from the one originally loaded from
102 the file. This may for example be used when creating several output files
106 <label id="option--read">
107 <tag><tt>-r, --read filename[,attrlist]</tt></tag>
109 Read an input file. The option argument must at least contain the "name"
110 attribute. See <ref id="input-formats" name="input formats"> for more
114 <label id="option-v">
115 <tag><tt>-v, --verbose</tt></tag>
117 Increase verbosity. Usually only needed for debugging purposes. You may use
118 this option more than one time for even more verbose output.
121 <label id="option-V">
122 <tag><tt>-V, --version</tt></tag>
124 Print the version number of the assembler. If you send any suggestions or
125 bugfixes, please include the version number.
128 <label id="option--write">
129 <tag><tt>-w, --write filename[,attrlist]</tt></tag>
131 Write an output file. The option argument must at least contain the "name"
132 attribute. See <ref id="output-formats" name="output formats"> for more
140 <sect>Processing pipeline<label id="processing-pipeline"><p>
145 <item>Front ends that read graphics data,
146 <item>processors for graphics data,
148 <item>and output modules for several formats.
151 These modules can be combined to a pipeline that reads data, does some
152 optional bitmap processing, converts the bitmap into a target format, and
153 writes this binary data to disk in one of several forms.
157 <sect>Attribute lists<label id="attr-lists"><p>
159 As described in <ref id="processing-pipeline" name="Processing pipeline">,
160 sp65 consists of lots of different modules that may be combined in different
161 ways, to convert an input bitmap to some output.
163 Many of the processors and converters have options to change the way, they're
164 working. To avoid having lots of command line options that must be parsed on
165 high level and passed down to the relevant parts of the program, sp65 features
166 something called "attribute lists". Attribute lists are lists of
167 attribute/value pairs. These lists are parsed by the main program module
168 without any knowledge about their meaning. Lower level parts just grab the
169 attributes they need.
171 In general, attribute lists look like this:
174 attr1=val1[,attr2=val2[,...]]
177 Instead of the comma, colons may also be used (even mixed).
179 To simplify things and to make the most common options look "normal", some
180 mandatory attributes may be given without an attribute name. If the attribute
181 name is missing, the default name is determined by the position. For example,
182 the option <tt/<ref id="option--read" name="--read">/ does always need a file
183 name. The attribute name for the file name is "name". To avoid having to type
186 sp65 --read name=ball.pcx ...
189 the first attribute gets the default name "name" assigned. So if the first
190 attribute doesn't have a name, it is assumed that it is the file name. This
191 means that instead of the line above, one can also use
194 sp65 --read ball.pcx ...
197 The second attribute for <tt/--read/ is the format of the input file. So when
201 sp65 --read ball.pic:pcx ...
204 a PCX file named "ball.pic" is read. The long form would be
207 sp65 --read name=ball.pic:format=pcx ...
210 Changing the order of the attributes is possible only when explicitly
211 specifying the names of the attributes. Using
214 sp65 --read pcx:ball.pic ...
217 will make sp65 complain, because it tries to read a file named "pcx" with an
218 (unknown) format of "ball.pic". The following however will work:
221 sp65 --read format=pcx:name=ball.pic ...
224 The attributes that are valid for each processor or converter are listed
229 <sect>Input formats<label id="input-formats"><p>
231 Input formats are either specified explicitly when using <tt/<ref
232 id="option--read" name="--read">/, or are determined by looking at the
233 extension of the file name given.
237 While sp65 is prepared for more, this is currently the only possible input
238 format. There are no additional attributes for this format.
242 <sect>Conversions<label id="conversions"><p>
244 <sect1>GEOS bitmap<p>
246 The current bitmap working copy is converted to a GEOS compacted bitmap. This
247 format is used by several GEOS functions (i.e. 'BitmapUp') and is described
248 in 'The Official GEOS Programmers Reference Guide', chapter 4, section
249 'Bit-Mapped Graphics'.
254 The current bitmap working copy is converted to GEOS icon format. A GEOS icon
255 has the same format as a C64 high resolution sprite (24x21, monochrome, 63
256 bytes). There are no additional attributes for this conversion.
259 <sect1>Koala image<p>
262 <sect1>Lynx sprite<p>
264 Lynx can handle 1, 2, 3 and 4 bits per pixel indexed sprites. The maximum size
265 of a sprite is roughly 508 pixels but in reality the Lynx screen is only 160 by
266 102 pixels which makes very large sprites useless.
268 The number per pixels is taken from the number of colors of the input bitmap.
270 There are a few attributes that you can give to the conversion software.
275 The first is what kind of encoding to use for the sprite. The attribute for
276 this is called "mode" and the possible values are "literal", "packed" or
277 "transparent". The default is "packed" if no mode is specified.
279 The "literal" is a totally literal mode with no packing. In this mode the
280 number of pixels per scanline will be a multiple of 8 both right and left from
283 If the source bitmap edge ends with a color where the least significant bit is
284 one then there will be an extra 8 zero bits on that scan line.
286 So if you are using totally literal sprites and intend to change them at
287 runtime then please add a single pixel border far left and far right with
288 zeros in order to prevent graphical glitches in the game.
290 The standard encoding is called "packed". In this mode the sprite is packed
291 using run-length encoding and literal coding mixed for optimisation to
292 produce a small sprite.
294 The last encoding mode "transparent" is like packed. But here we know that
295 the index 0 will be transparent so we can clip off all 0 pixels from the left
296 and right edge of the sprite. This will produce the smallest sprite possible
297 on the Lynx. The sprite is not rectangular anymore.
300 The sprite is painted around the Anchor point. The anchor point x can be
301 between 0 and the width of the sprite - 1. If anchor point x is zero then
302 painting the sprite in location 10,20 will set the left edge of the sprite
303 10 pixels from the left of the Lynx screen. When the sprite is scaled by
304 hardware the anchor point stays in place and the sprite grows or shrinks
305 around the anchor point. The default value is 0 (left).
308 The sprite is painted around the Anchor point. The anchor point y can be
309 between 0 and the height of the sprite - 1. If anchor point y is zero then
310 painting the sprite in location 10,20 will set the top of the sprite 20
311 pixels from the top of the Lynx screen. When the sprite is scaled by
312 hardware the anchor point stays in place and the sprite grows or shrinks
313 around the anchor point. The default value is 0 (top).
317 <sect1>VIC2 sprite<p>
322 <sect>Output formats<label id="output-formats"><p>
324 Using <tt/<ref id="option--write" name="--write">/ it is possible to write
325 processed data to an output file. An attribute "name" is mandatory, it is used
326 as the file name for the output. The output format can be specified using an
327 attribute named "format". If this attribute doesn't exist, the output format
328 is determined by looking at the file name extension.
333 For this format, the processed data is written to the output file in raw
334 binary format. There are no additional attributes (besides "name" and
335 "format") for this output format.
338 <sect1>Assembler code<p>
340 For this format, the processed data is written to the output file in ca65
341 assembler format. There are several attributes for this output format:
346 The value for this attribute specifies the numeric base for the data
347 values. It may be either 2, 10 or 16. The default is 16. If the base is
348 2, the numbers are prefixed by '%', if the base is 16, the numbers are
349 prefixed by '$'. For base 10, there is no prefix.
352 The value for this attribute specifies the number of bytes output in one
353 line of the assembler file. The default is 16.
356 This is an optional attribute. When given, the output processor will wrap
357 the data into a <tt/.PROC/ with the given name. In addition, three constants
358 are added as local symbols within the <tt/.PROC/: <tt/COLORS/, <tt/WIDTH/
367 When using C output format, a small piece of C source code is generated that
368 defines the data containing the output in an array of <tt/unsigned char/.
370 Possible attributes for this format are:
374 The value for this attribute specifies the numeric base for the data values.
375 It may be either 10 or 16. The default is 16. If the base is 16, the numbers
376 are prefixed by 0x. For base 10, there is no prefix.
379 The value for this attribute specifies the number of bytes output in one
380 line of the C source code. The default is 16.
383 This is an optional attribute. When given, the output processor will wrap
384 the data into an array of unsigned char with the given name. In addition,
385 three <tt/#define/s are added for <tt/<ident>_COLORS/,
386 <tt/<ident>_WIDTH/ and <tt/<ident>_HEIGHT/.
394 sp65 (and all cc65 binutils) are (C) Copyright 1998-2012 Ullrich von Bassewitz
395 and others. For usage of the binaries and/or sources the following conditions
398 This software is provided 'as-is', without any expressed or implied
399 warranty. In no event will the authors be held liable for any damages
400 arising from the use of this software.
402 Permission is granted to anyone to use this software for any purpose,
403 including commercial applications, and to alter it and redistribute it
404 freely, subject to the following restrictions:
407 <item> The origin of this software must not be misrepresented; you must not
408 claim that you wrote the original software. If you use this software
409 in a product, an acknowledgment in the product documentation would be
410 appreciated but is not required.
411 <item> Altered source versions must be plainly marked as such, and must not
412 be misrepresented as being the original software.
413 <item> This notice may not be removed or altered from any source