1 <!doctype linuxdoc system> <!-- -*- text-mode -*- -->
4 <title>sp65 Users Guide
5 <author>Ullrich von Bassewitz, <htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">
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 --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--help">
80 <tag><tt>-h, --help</tt></tag>
82 Print the short option summary shown above.
85 <label id="option--list-conversions">
86 <tag><tt>-lc, --list-conversions</tt></tag>
88 Print a list of possible conversions.
91 <label id="option--pop">
92 <tag><tt>--pop</tt></tag>
94 Restore the working copy of the bitmap from the one originally loaded from
95 the file. This may for example be used when creating several output files
99 <label id="option--read">
100 <tag><tt>-r, --read filename[,attrlist]</tt></tag>
102 Read an input file. The option argument must at least contain the "name"
103 attribute. See <ref id="input-formats" name="input formats"> for more
107 <label id="option-v">
108 <tag><tt>-v, --verbose</tt></tag>
110 Increase verbosity. Usually only needed for debugging purposes. You may use
111 this option more than one time for even more verbose output.
114 <label id="option-V">
115 <tag><tt>-V, --version</tt></tag>
117 Print the version number of the assembler. If you send any suggestions or
118 bugfixes, please include the version number.
121 <label id="option--write">
122 <tag><tt>-w, --write filename[,attrlist]</tt></tag>
124 Write an output file. The option argument must at least contain the "name"
125 attribute. See <ref id="output-formats" name="output formats"> for more
133 <sect>Processing pipeline<label id="processing-pipeline"><p>
138 <item>Front ends that read graphics data,
139 <item>processors for graphics data,
141 <item>and output modules for several formats.
144 These modules can be combined to a pipeline that reads data, does some
145 optional bitmap processing, converts the bitmap into a target format, and
146 writes this binary data to disk in one of several forms.
150 <sect>Attribute lists<label id="attr-lists"><p>
152 As described in <ref id="processing-pipeline" name="Processing pipeline">,
153 sp65 consists of lots of different modules that may be combined in different
154 ways, to convert an input bitmap to some output.
156 Many of the processors and converters have options to change the way, they're
157 working. To avoid having lots of command line options that must be parsed on
158 high level and passed down to the relevant parts of the program, sp65 features
159 something called "attribute lists". Attribute lists are lists of
160 attribute/value pairs. These lists are parsed by the main program module
161 without any knowledge about their meaning. Lower level parts just grab the
162 attributes they need.
164 In general, attribute lists look like this:
167 attr1=val1[,attr2=val2[,...]]
170 Instead of the comma, colons may also be used (even mixed).
172 To simplify things and to make the most common options look "normal", some
173 mandatory attributes may be given without an attribute name. If the attribute
174 name is missing, the default name is determined by the position. For example,
175 the option <tt/<ref id="option--read" name="--read">/ does always need a file
176 name. The attribute name for the file name is "name". To avoid having to type
179 sp65 --read name=ball.pcx ...
182 the first attribute gets the default name "name" assigned. So if the first
183 attribute doesn't have a name, it is assumed that it is the file name. This
184 means that instead of the line above, one can also use
187 sp65 --read ball.pcx ...
190 The second attribute for <tt/--read/ is the format of the input file. So when
194 sp65 --read ball.pic:pcx ...
197 a PCX file named "ball.pic" is read. The long form would be
200 sp65 --read name=ball.pic:format=pcx ...
203 Changing the order of the attributes is possible only when explicitly
204 specifying the names of the attributes. Using
207 sp65 --read pcx:ball.pic ...
210 will make sp65 complain, because it tries to read a file named "pcx" with an
211 (unknown) format of "ball.pic". The following however will work:
214 sp65 --read format=pcx:name=ball.pic ...
217 The attributes that are valid for each processor or converter are listed
222 <sect>Input formats<label id="input-formats"><p>
224 Input formats are either specified explicitly when using <tt/<ref
225 id="option--read" name="--read">/, or are determined by looking at the
226 extension of the file name given.
230 While sp65 is prepared for more, this is currently the only possible input
231 format. There are no additional attributes for this format.
235 <sect>Conversions<label id="conversions"><p>
237 <sect1>GEOS bitmap<p>
239 The current bitmap working copy is converted to a GEOS compacted bitmap. This
240 format is used by several GEOS functions (i.e. 'BitmapUp') and is described
241 in 'The Official GEOS Programmers Reference Guide', chapter 4, section
242 'Bit-Mapped Graphics'.
247 The current bitmap working copy is converted to GEOS icon format. A GEOS icon
248 has the same format as a C64 high resolution sprite (24x21, monochrome, 63
249 bytes). There are no additional attributes for this conversion.
252 <sect1>Koala image<p>
255 <sect1>Lynx sprite<p>
258 <sect1>VIC2 sprite<p>
263 <sect>Output formats<label id="output-formats"><p>
265 Using <tt/<ref id="option--write" name="--write">/ it is possible to write
266 processed data to an output file. An attribute "name" is mandatory, it is used
267 as the file name for the output. The output format can be specified using an
268 attribute named "format". If this attribute doesn't exist, the output format
269 is determined by looking at the file name extension.
274 For this format, the processed data is written to the output file in raw
275 binary format. There are no additional attributes (besides "name" and
276 "format") for this output format.
279 <sect1>Assembler code<p>
281 For this format, the processed data is written to the output file in ca65
282 assembler format. There are several attributes for this output format:
287 The value for this attribute specifies the numeric base for the data
288 values. It may be either 2, 10 or 16. The default is 16. If the base is
289 2, the numbers are prefixed by '%', if the base is 16, the numbers are
290 prefixed by '$'. For base 10, there is no prefix.
293 The value for this attribute specifies the number of bytes output in one
294 line of the assembler file. The default is 16.
297 This is an optional attribute. When given, the output processor will wrap
298 the data into a <tt/.PROC/ with the given name. In addition, three constants
299 are added as local symbols within the <tt/.PROC/: <tt/COLORS/, <tt/WIDTH/
308 When using C output format, a small piece of C source code is generated that
309 defines the data containing the output in an array of <tt/unsigned char/.
311 Possible attributes for this format are:
315 The value for this attribute specifies the numeric base for the data values.
316 It may be either 10 or 16. The default is 16. If the base is 16, the numbers
317 are prefixed by 0x. For base 10, there is no prefix.
320 The value for this attribute specifies the number of bytes output in one
321 line of the C source code. The default is 16.
324 This is an optional attribute. When given, the output processor will wrap
325 the data into an array of unsigned char with the given name. In addition,
326 three <tt/#define/s are added for <tt/<ident>_COLORS/,
327 <tt/<ident>_WIDTH/ and <tt/<ident>_HEIGHT/.
333 <sect>Bugs/Feedback<p>
335 If you have problems using the assembler, if you find any bugs, or if
336 you're doing something interesting with the assembler, I would be glad to
337 hear from you. Feel free to contact me by email
338 (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">).
344 sp65 (and all cc65 binutils) are (C) Copyright 1998-2012 Ullrich von Bassewitz
345 and others. For usage of the binaries and/or sources the following conditions
348 This software is provided 'as-is', without any expressed or implied
349 warranty. In no event will the authors be held liable for any damages
350 arising from the use of this software.
352 Permission is granted to anyone to use this software for any purpose,
353 including commercial applications, and to alter it and redistribute it
354 freely, subject to the following restrictions:
357 <item> The origin of this software must not be misrepresented; you must not
358 claim that you wrote the original software. If you use this software
359 in a product, an acknowledgment in the product documentation would be
360 appreciated but is not required.
361 <item> Altered source versions must be plainly marked as such, and must not
362 be misrepresented as being the original software.
363 <item> This notice may not be removed or altered from any source