mirror of
https://github.com/fadden/6502bench.git
synced 2024-07-31 07:29:00 +00:00
6913558f4a
Visualization animations are now exported as animated GIFs. The Windows stuff is a bit lame so I threw together some code that stitches a bunch of GIFs together. The GIF doesn't quite match the preview, because the preview scales the individual frames, while the animated GIF uses the largest frame as the size and is then scaled based on that. Animating frames of differing sizes together is bound to be trouble anyway, so I'm not sure how much to fret over this.
244 lines
12 KiB
HTML
244 lines
12 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
|
|
<head>
|
|
<meta content="text/html; charset=utf-8" http-equiv="Content-Type" />
|
|
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
|
<link href="main.css" rel="stylesheet" type="text/css" />
|
|
<title>Visualizations - 6502bench SourceGen</title>
|
|
</head>
|
|
|
|
<body>
|
|
<div id="content">
|
|
<h1>6502bench SourceGen: Visualizations</h1>
|
|
<p><a href="index.html">Back to index</a></p>
|
|
|
|
<h2><a name="overview">Overview</a></h2>
|
|
|
|
<p>Programs are generally a combination of code and data. Sometimes
|
|
the data is graphical in nature, e.g. a bitmap used as a font or
|
|
game sprite. Being able to see the data in graphic form can make it
|
|
easier to determine the purpose of associated code.</p>
|
|
<p>While modern systems use GIF, JPEG, and PNG to hold 2D bitmaps,
|
|
graphical elements embedded in 6502 applications are almost always
|
|
in a platform-specific form. For this reason, the task of generating
|
|
images from data is performed by
|
|
<a href="advanced.html#extension-scripts">extension scripts</a>. Some
|
|
scripts for common formats are included in the SourceGen runtime directory.
|
|
If these don't do what you need, you can write your own scripts and
|
|
include them in your project.</p>
|
|
<p>The project file doesn't store the converted graphics. Instead, the
|
|
project file holds a string that identifies the converter, and a list of
|
|
parameters that are passed to the converter. Images are generated when
|
|
the project is first opened, and updated when certain things change in
|
|
the project.</p>
|
|
<p>Visualizations are not included in generated assembly output. They
|
|
may be included in HTML exports.</p>
|
|
<p>Because visualizations are associated with a specific file offset,
|
|
they will become "hidden" if the offset isn't at the start of a line,
|
|
e.g. it's in the middle of a multi-byte instruction or data item. The
|
|
editors will try to prevent you from doing this.</p>
|
|
<p>Bitmaps will always be scaled up as much as possible to make them
|
|
easy to see. This means that small shapes and large shapes may appears
|
|
to be the same size when displayed as thumbnails in the code list.</p>
|
|
<p>The role of a visualization generator is to take a collection of input
|
|
parameters and generate graphical data. It's most useful for graphical
|
|
sources like bitmaps, but it's not limited to that. You could, for example,
|
|
write a script that generates random flowers, and use it to make your
|
|
source listings more cheerful.</p>
|
|
|
|
|
|
<h2><a name="vis-and-sets">Visualizations and Visualization Sets</a></h2>
|
|
|
|
<p>Visualizations are essentially decorative: they do not affect the
|
|
assembled output, and do not change how code is analyzed. They are
|
|
contained in sets that are placed at arbitrary offsets. Each set can
|
|
contain multiple items. For example, if a file has data for
|
|
10 bitmaps, you can place a visualization near each, or create a single
|
|
visualization set with all 10 items and put it at the start of the file.
|
|
You can display a visualization near the data or near the instructions
|
|
that perform the drawing. Or both.</p>
|
|
|
|
<p>To create a visualization set, select a code or data line, and use
|
|
Actions > Create/Edit Visualization Set. To edit a visualization set,
|
|
select it and use the same menu item, or just double-click on it. This
|
|
opens the Visualization Set Editor window.</p>
|
|
|
|
<p>The visualization set editor shows a list of visualizations associated
|
|
with the selected file offset. You can create a new visualization, edit
|
|
or remove an existing entry, or rearrange them.
|
|
If you select "New Bitmap" or edit an existing bitmap entry, the
|
|
Bitmap Visualization Editor window will open.
|
|
Similarly, if you select "New Bitmap Animation" or edit an existing
|
|
bitmap animation, the Bitmap Animation Editor will open.</p>
|
|
|
|
<h4>Bitmap Visualization Editor</h4>
|
|
|
|
<p>The combo box at the top of the screen lists every bitmap visualization
|
|
generator defined by an active extension script. Select the one that is
|
|
appropriate for the data you're trying to visualize. Every visualizer may
|
|
have different parameters, so as you select different entries the set of
|
|
input parameters below the preview window may change.</p>
|
|
|
|
<p>The "tag" is a unique string that will be shown in the display list.
|
|
This is not a label, and may contain any characters you want (but leading
|
|
and trailing whitespace will be trimmed). The only requirement is that
|
|
it be unique across all visualizations (bitmaps, animations, etc).</p>
|
|
<p>The preview window shows the visualizer output. The generated image is
|
|
expanded to fill the window, so small images will be shown with very
|
|
large pixels.
|
|
If you resize the editor window, the preview window will expand, which
|
|
can make it easier to see detail on larger images.
|
|
If the generator fails, the preview window will show a red 'X', and an
|
|
error message will appear below it.</p>
|
|
<p>Parameters may be numeric or boolean. The latter use a simple checkbox,
|
|
the former a text entry field that accepts decimal and hexadecimal values.
|
|
The range of allowable values is shown to the right of the entry field.
|
|
If you enter an invalid value, the parameter description will turn red.</p>
|
|
|
|
|
|
<h4>Bitmap Animation Editor</h4>
|
|
|
|
<p>Bitmap animations allow you to create a simple animation from a
|
|
collection of other visualizations. This can be useful when a program
|
|
stores animated graphics as a series of frames.</p>
|
|
<p>The "tag" is a unique string that will be shown in the display list.
|
|
The same rules apply as for bitmap visualizations.</p>
|
|
<p>The list at the top left holds all visualizations. Select items on
|
|
the left and use the "Add" button to add them to the list on the right,
|
|
which has the set that is included in the animation. You can reorder
|
|
the list with the up/down buttons. Adding the same frame multiple times
|
|
is allowed.</p>
|
|
<p>The "frame delay" field lets you specify how long each frame is shown
|
|
on screen, in milliseconds. Some animation formats may use a different
|
|
time resolution; for example, animated GIFs use units of 1/100th of a
|
|
second. The closest value will be used. Note also that some viewers
|
|
(notably web browsers) will cap the update rate.</p>
|
|
<p>When you have one or more frames in the animation list, you can preview
|
|
the result in the window at the bottom. The actual appearance may be
|
|
slightly different, especially if the frames are different sizes. For
|
|
example, the preview window scales individual frames, but animated GIFs
|
|
will be scaled to the size of the largest frame.</p>
|
|
|
|
|
|
<h2><a name="runtime">Scripts Included with SourceGen</a></h2>
|
|
|
|
<p>A number of visualization generation scripts are included with
|
|
SourceGen, in the platform-specific runtime data directories.</p>
|
|
|
|
<p>Most generators will take the file offset, bitmap width, and bitmap
|
|
height as parameters. Offsets are handled as they are elsewhere, i.e.
|
|
always in hexadecimal, with a leading '+'.
|
|
Some less-common parameters include:</p>
|
|
<ul>
|
|
<li><b>Row stride</b> - number of bytes used to hold a row. This
|
|
is used when a row has padding on the end, e.g. a bitmap that's
|
|
7 bytes wide might be padded to 8 for easy indexing. If you set
|
|
this to zero the visualizer will default to no padding
|
|
(stride == width).</li>
|
|
<li><b>Column stride</b> - number of bytes used to hold a column.
|
|
This is uncommon, but could be used if (say) a pair of bitmaps
|
|
was stored with interleaved bytes. If you set this to zero the
|
|
visualizer will default to no interleave (stride == 1).</li>
|
|
</ul>
|
|
|
|
<p>Remember that this is a disassembler, not an image converter. The
|
|
results do not need to be perfectly accurate to be useful when disassembling
|
|
code.</p>
|
|
|
|
|
|
<h3>Apple II - Apple/VisHiRes</h3>
|
|
|
|
<p>There is no standard format for small hi-res bitmaps, but certain
|
|
arrangements are common. The script defines three generators:</p>
|
|
|
|
<ul>
|
|
<li><b>Hi-Res Bitmap</b> - converts an MxN row-major bitmap.</li>
|
|
<li><b>Hi-Res Bitmap Font</b> - converts a series of MxN row-major
|
|
bitmaps. This is intended for hi-res fonts, which are typically
|
|
8 bytes per entry, stored one after another. These are always
|
|
converted as monochrome, and have a 1-pixel transparent gap
|
|
between elements. (This also works for Apple /// fonts, but
|
|
currently ignores the high bit in each byte.)</li>
|
|
<li><b>Hi-Res Screen Image</b> - used for 8KiB screen images. The
|
|
data is linearized and converted to a 280x192 bitmap. Because
|
|
images are relatively large, the generator does not require them
|
|
to be contiguous in the file, i.e. two halves of the image can be
|
|
in different parts of the file so long as they end up contiguous
|
|
in memory.</li>
|
|
</ul>
|
|
|
|
<p>Widths are specified in bytes, not pixels. Each byte represents 7
|
|
pixels (with some hand-waving).</p>
|
|
|
|
<p>In addition to offset, dimensions, and stride values, the bitmap
|
|
converter has a checkbox for monochrome or color, and a checkbox that
|
|
will cause the first byte to be treated as an odd column rather than
|
|
an event one. The odd/even setting affects green/purple and orange/blue,
|
|
but has no effect on black or white.</p>
|
|
<p>The converter generates one output pixel for every source pixel, so
|
|
half-pixel shifts are not rendered.</p>
|
|
|
|
<h3>Atari 2600 - Atari/Vis2600</h3>
|
|
|
|
<p>The Atari 2600 graphics system has registers that determine the
|
|
appearance of a sprite or playfield on a single row. The register
|
|
values are typically changed as the screen is drawn to get different
|
|
data on successive rows. The visualization generator works for data
|
|
stored in a straightforward fashion.</p>
|
|
|
|
<ul>
|
|
<li><b>Sprite</b> - basic 1xN sprite, converted to an image 8 pixels
|
|
wide.</li>
|
|
<li><b>Playfield</b> - assumes PF0,PF1,PF2 are stored in that order,
|
|
multiple entries following each other. Specify the number of
|
|
3-byte entries as the height.
|
|
Since most playfields aren't the full height of the screen,
|
|
it will tend to look squashed. Use the "row thickness" feature
|
|
to repeat each row N times to adjust the proportions.</li>
|
|
</ul>
|
|
|
|
<h3>Commodore 64 - Commodore/VisC64</h3>
|
|
|
|
<p>The Commodore 64 has a 64-bit sprite format defined by the hardware.
|
|
It comes in two basic varieties:</p>
|
|
<ul>
|
|
<li><b>High-resolution sprite</b> - 24x21 monochrome. Pixels are either
|
|
colored or transparent.</li>
|
|
<li><b>Multi-color sprite</b> - 12x21 3-color. The width of each pixel
|
|
is doubled to make it 24x21.
|
|
</ul>
|
|
<p>Sprites can be doubled in width and/or height.</p>
|
|
<p>Colors come from a hardware-defined palette of 16:</p>
|
|
<ol start="0" style="columns:2; -webkit-columns:2; -moz-columns:2;">
|
|
<li><span style="color:#ffffff;background-color:#000000"> black </span></li>
|
|
<li><span style="color:#000000;background-color:#ffffff"> white </span></li>
|
|
<li><span style="color:#ffffff;background-color:#67372b"> red </span></li>
|
|
<li><span style="color:#ffffff;background-color:#70a4b2"> cyan </span></li>
|
|
<li><span style="color:#ffffff;background-color:#6f3d86"> purple </span></li>
|
|
<li><span style="color:#ffffff;background-color:#588d43"> green </span></li>
|
|
<li><span style="color:#ffffff;background-color:#352879"> blue </span></li>
|
|
<li><span style="color:#000000;background-color:#b8c76f"> yellow </span></li>
|
|
<li><span style="color:#ffffff;background-color:#6f4f25"> orange </span></li>
|
|
<li><span style="color:#ffffff;background-color:#433900"> brown </span></li>
|
|
<li><span style="color:#ffffff;background-color:#9a6759"> light red </span></li>
|
|
<li><span style="color:#ffffff;background-color:#444444"> dark grey </span></li>
|
|
<li><span style="color:#ffffff;background-color:#6c6c6c"> grey </span></li>
|
|
<li><span style="color:#000000;background-color:#9ad284"> light green </span></li>
|
|
<li><span style="color:#ffffff;background-color:#6c5eb5"> light blue </span></li>
|
|
<li><span style="color:#ffffff;background-color:#959595"> light grey </span></li>
|
|
</ol>
|
|
|
|
<p>Bear in mind that the editor scales images to their maximum size, so
|
|
a sprite that is doubled in both width and height will look exactly like
|
|
a sprite that is not doubled at all.</p>
|
|
|
|
</div>
|
|
|
|
<div id="footer">
|
|
<p><a href="index.html">Back to index</a></p>
|
|
</div>
|
|
</body>
|
|
<!-- Copyright 2019 faddenSoft -->
|
|
</html>
|