mirror of
https://github.com/fadden/6502bench.git
synced 2024-11-30 01:50:10 +00:00
218 lines
11 KiB
HTML
218 lines
11 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.</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 among visualization tags.</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>
|
|
|
|
|
|
<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>
|