]> git.sur5r.net Git - cc65/blob - doc/sp65.sgml
fix grammar
[cc65] / doc / sp65.sgml
1 <!doctype linuxdoc system>      <!-- -*- text-mode -*- -->
2
3 <article>
4 <title>sp65 Users Guide
5 <author><url url="mailto:uz@cc65.org" name="Ullrich von Bassewitz">
6 <date>2012-03-11
7
8 <abstract>
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
11 supported machines.
12 </abstract>
13
14 <!-- Table of contents -->
15 <toc>
16
17 <!-- Begin the document -->
18
19 <sect>Overview<p>
20
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.
25
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.
28
29
30
31 <sect>Usage<p>
32
33
34 <sect1>Command line option overview<p>
35
36 The sp65 utility accepts the following options:
37
38 <tscreen><verb>
39 ---------------------------------------------------------------------------
40 Usage: sp65 [options] file [options] [file]
41 Short options:
42   -V                            Print the version number and exit
43   -c fmt[,attrlist]             Convert into target format
44   -h                            Help (this text)
45   -lc                           List all possible conversions
46   -r file[,attrlist]            Read an input file
47   -v                            Increase verbosity
48   -w file[,attrlist]            Write the output to a file
49
50 Long options:
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 ---------------------------------------------------------------------------
61 </verb></tscreen>
62
63
64 <sect1>Command line options in detail<p>
65
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">.
68
69 <descrip>
70
71   <label id="option--convert-to">
72   <tag><tt>-c, --convert-to format[,attrlist]</tt></tag>
73
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">.
77
78
79   <label id="option--help">
80   <tag><tt>-h, --help</tt></tag>
81
82   Print the short option summary shown above.
83
84
85   <label id="option--list-conversions">
86   <tag><tt>-lc, --list-conversions</tt></tag>
87
88   Print a list of possible conversions.
89
90
91   <label id="option--pop">
92   <tag><tt>--pop</tt></tag>
93
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
96   from one input file.
97
98
99   <label id="option--read">
100   <tag><tt>-r, --read filename[,attrlist]</tt></tag>
101
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
104   information.
105
106
107   <label id="option-v">
108   <tag><tt>-v, --verbose</tt></tag>
109
110   Increase verbosity. Usually only needed for debugging purposes. You may use
111   this option more than one time for even more verbose output.
112
113
114   <label id="option-V">
115   <tag><tt>-V, --version</tt></tag>
116
117   Print the version number of the assembler. If you send any suggestions or
118   bugfixes, please include the version number.
119
120
121   <label id="option--write">
122   <tag><tt>-w, --write filename[,attrlist]</tt></tag>
123
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
126   information.
127
128 </descrip>
129 <p>
130
131
132
133 <sect>Processing pipeline<label id="processing-pipeline"><p>
134
135 sp65 consists of
136
137 <itemize>
138 <item>Front ends that read graphics data,
139 <item>processors for graphics data,
140 <item>converters
141 <item>and output modules for several formats.
142 </itemize>
143
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.
147
148
149
150 <sect>Attribute lists<label id="attr-lists"><p>
151
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.
155
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.
163
164 In general, attribute lists look like this:
165
166 <tscreen><verb>
167         attr1=val1[,attr2=val2[,...]]
168 </verb></tscreen>
169
170 Instead of the comma, colons may also be used (even mixed).
171
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
177
178 <tscreen><verb>
179         sp65 --read name=ball.pcx ...
180 </verb></tscreen>
181
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
185
186 <tscreen><verb>
187         sp65 --read ball.pcx ...
188 </verb></tscreen>
189
190 The second attribute for <tt/--read/ is the format of the input file. So when
191 using
192
193 <tscreen><verb>
194         sp65 --read ball.pic:pcx ...
195 </verb></tscreen>
196
197 a PCX file named "ball.pic" is read. The long form would be
198
199 <tscreen><verb>
200         sp65 --read name=ball.pic:format=pcx ...
201 </verb></tscreen>
202
203 Changing the order of the attributes is possible only when explicitly
204 specifying the names of the attributes. Using
205
206 <tscreen><verb>
207         sp65 --read pcx:ball.pic ...
208 </verb></tscreen>
209
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:
212
213 <tscreen><verb>
214         sp65 --read format=pcx:name=ball.pic ...
215 </verb></tscreen>
216
217 The attributes that are valid for each processor or converter are listed
218 below.
219
220
221
222 <sect>Input formats<label id="input-formats"><p>
223
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.
227
228 <sect1>PCX<p>
229
230 While sp65 is prepared for more, this is currently the only possible input
231 format. There are no additional attributes for this format.
232
233
234
235 <sect>Conversions<label id="conversions"><p>
236
237 <sect1>GEOS bitmap<p>
238
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'.
243
244
245 <sect1>GEOS icon<p>
246
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.
250
251
252 <sect1>Koala image<p>
253
254
255 <sect1>Lynx sprite<p>
256
257 Lynx can handle 1, 2, 3 and 4 bits per pixel indexed sprites. The maximum size
258 of a sprite is roughly 508 pixels but in reality the Lynx screen is only 160 by
259 102 pixels which makes very large sprites useless.
260
261 The number per pixels is taken from the number of colors of the input bitmap.
262
263 There are a few attributes that you can give to the conversion software.
264
265 <descrip>
266
267   <tag/mode/
268   The first is what kind of encoding to use for the sprite. The attribute for
269   this is called "mode" and the possible values are "literal", "packed" or
270   "transparent". The default is "packed" if no mode is specified.
271
272   The "literal" is a totally literal mode with no packing. In this mode the
273   number of pixels per scanline will be a multiple of 8 both right and left from
274   the action point.
275
276   If the source bitmap edge ends with a color where the least significant bit is
277   one then there will be an extra 8 zero bits on that scan line.
278
279   So if you are using totally literal sprites and intend to change them at
280   runtime then please add a single pixel border far left and far right with
281   zeros in order to prevent graphical glitches in the game.
282
283   The standard encoding is called "packed". In this mode the sprite is packed
284   using run-length encoding and literal coding mixed for optimisation to
285   produce a small sprite.
286
287   The last encoding mode "transparent" is like packed. But here we know that
288   the index 0 will be transparent so we can clip off all 0 pixels from the left
289   and right edge of the sprite. This will produce the smallest sprite possible
290   on the Lynx. The sprite is not rectangular anymore.
291
292   <tag/ax/
293   The sprite is painted around the Anchor point. The anchor point x can be
294   between 0 and the width of the sprite - 1. If anchor point x is zero then
295   painting the sprite in location 10,20 will set the left edge of the sprite
296   10 pixels from the left of the Lynx screen. When the sprite is scaled by
297   hardware the anchor point stays in place and the sprite grows or shrinks
298   around the anchor point. The default value is 0 (left).
299
300   <tag/ay/
301   The sprite is painted around the Anchor point. The anchor point y can be
302   between 0 and the height of the sprite - 1. If anchor point y is zero then
303   painting the sprite in location 10,20 will set the top of the sprite 20
304   pixels from the top of the Lynx screen. When the sprite is scaled by
305   hardware the anchor point stays in place and the sprite grows or shrinks
306   around the anchor point. The default value is 0 (top).
307
308 </descrip>
309
310 <sect1>VIC2 sprite<p>
311
312
313
314
315 <sect>Output formats<label id="output-formats"><p>
316
317 Using <tt/<ref id="option--write" name="--write">/ it is possible to write
318 processed data to an output file. An attribute "name" is mandatory, it is used
319 as the file name for the output. The output format can be specified using an
320 attribute named "format". If this attribute doesn't exist, the output format
321 is determined by looking at the file name extension.
322
323
324 <sect1>Binary<p>
325
326 For this format, the processed data is written to the output file in raw
327 binary format. There are no additional attributes (besides "name" and
328 "format") for this output format.
329
330
331 <sect1>Assembler code<p>
332
333 For this format, the processed data is written to the output file in ca65
334 assembler format. There are several attributes for this output format:
335
336 <descrip>
337
338   <tag/base/
339   The value for this attribute specifies the numeric base for the data
340   values. It may be either 2, 10 or 16. The default is 16. If the base is
341   2, the numbers are prefixed by '%', if the base is 16, the numbers are
342   prefixed by '&dollar;'. For base 10, there is no prefix.
343
344   <tag/bytesperline/
345   The value for this attribute specifies the number of bytes output in one
346   line of the assembler file. The default is 16.
347
348   <tag/ident/
349   This is an optional attribute. When given, the output processor will wrap
350   the data into a <tt/.PROC/ with the given name. In addition, three constants
351   are added as local symbols within the <tt/.PROC/: <tt/COLORS/, <tt/WIDTH/
352   and <tt/HEIGHT/.
353
354 </descrip>
355
356
357
358 <sect1>C code<p>
359
360 When using C output format, a small piece of C source code is generated that
361 defines the data containing the output in an array of <tt/unsigned char/.
362
363 Possible attributes for this format are:
364
365 <descrip>
366   <tag/base/
367   The value for this attribute specifies the numeric base for the data values.
368   It may be either 10 or 16. The default is 16. If the base is 16, the numbers
369   are prefixed by 0x. For base 10, there is no prefix.
370
371   <tag/bytesperline/
372   The value for this attribute specifies the number of bytes output in one
373   line of the C source code. The default is 16.
374
375   <tag/ident/
376   This is an optional attribute. When given, the output processor will wrap
377   the data into an array of unsigned char with the given name. In addition,
378   three <tt/#define/s are added for <tt/&lt;ident&gt;_COLORS/,
379   <tt/&lt;ident&gt;_WIDTH/ and <tt/&lt;ident&gt;_HEIGHT/.
380
381 </descrip>
382
383
384
385 <sect>Copyright<p>
386
387 sp65 (and all cc65 binutils) are (C) Copyright 1998-2012 Ullrich von Bassewitz
388 and others. For usage of the binaries and/or sources the following conditions
389 do apply:
390
391 This software is provided 'as-is', without any expressed or implied
392 warranty.  In no event will the authors be held liable for any damages
393 arising from the use of this software.
394
395 Permission is granted to anyone to use this software for any purpose,
396 including commercial applications, and to alter it and redistribute it
397 freely, subject to the following restrictions:
398
399 <enum>
400 <item>  The origin of this software must not be misrepresented; you must not
401         claim that you wrote the original software. If you use this software
402         in a product, an acknowledgment in the product documentation would be
403         appreciated but is not required.
404 <item>  Altered source versions must be plainly marked as such, and must not
405         be misrepresented as being the original software.
406 <item>  This notice may not be removed or altered from any source
407         distribution.
408 </enum>
409
410
411
412 </article>
413
414
415