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>Attribute lists<label id="attr-lists"><p>
137 <sect>Input formats<label id="input-formats"><p>
143 <sect>Conversions<label id="conversions"><p>
146 <sect1>VIC2 sprites<p>
149 <sect1>Koala images<p>
154 <sect>Output formats<label id="output-formats"><p>
156 Using <tt/<ref id="option--write" name="--write">/ it is possible to write
157 processed data to an output file. An attribute "name" is mandatory, it is used
158 as the file name for the output. The output format can be specified using an
159 attribute named "format". If this attribute doesn't exist, the output format
160 is determined by looking at the file name extension.
165 For this format, the processed data is written to the output file in raw
166 binary format. There are not attributes for this output format.
169 <sect1>Assembler code<p>
171 For this format, the processed data is written to the output file in ca65
172 assembler format. There are several attributes for this output format:
177 The value for this attribute specifies the numeric base for the data
178 values. It may be either 2, 10 or 16. The default is 16. If the base is
179 2, the numbers are prefixed by '%', if the base is 16, the numbers are
180 prefixed by '$'. For base 10, there is no prefix.
183 The value for this attribute specifies the number of bytes output in
184 one line of the assembler file. The default is 16.
187 If specified, an assembler label is added in front of the data.
190 If specified, a <tt/.SEGMENT/ directive is used to place the data into
202 <sect>Bugs/Feedback<p>
204 If you have problems using the assembler, if you find any bugs, or if
205 you're doing something interesting with the assembler, I would be glad to
206 hear from you. Feel free to contact me by email
207 (<htmlurl url="mailto:uz@cc65.org" name="uz@cc65.org">).
213 sp65 (and all cc65 binutils) are (C) Copyright 1998-2012 Ullrich von Bassewitz
214 and others. For usage of the binaries and/or sources the following conditions
217 This software is provided 'as-is', without any expressed or implied
218 warranty. In no event will the authors be held liable for any damages
219 arising from the use of this software.
221 Permission is granted to anyone to use this software for any purpose,
222 including commercial applications, and to alter it and redistribute it
223 freely, subject to the following restrictions:
226 <item> The origin of this software must not be misrepresented; you must not
227 claim that you wrote the original software. If you use this software
228 in a product, an acknowledgment in the product documentation would be
229 appreciated but is not required.
230 <item> Altered source versions must be plainly marked as such, and must not
231 be misrepresented as being the original software.
232 <item> This notice may not be removed or altered from any source