mirror of https://github.com/fadden/6502bench.git
316 lines
16 KiB
HTML
316 lines
16 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>Visualization Editor</h4>
|
|
|
|
<p>The combo box at the top of the screen lists every 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>There are two categorizes of visualization generator: bitmap, and
|
|
wireframe. Bitmaps are simple 2D images, but wireframes are 2D or 3D
|
|
meshes that can be viewed from different angles. When you select a
|
|
wireframe generator, additional view controls will be added at the bottom.
|
|
(See below.)</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 bitmaps 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>
|
|
|
|
<p>The "Export" button at the top right can be used to save a copy of
|
|
the bitmap or wireframe rendering with the current parameters.</p>
|
|
|
|
<h5>Wireframe View Controls</h5>
|
|
|
|
<p>The wireframe generator may offer the choice of perspective vs.
|
|
orthographic projection, and whether or not to enable backface
|
|
culling. These are declared in the visualization generator script,
|
|
but implemented in the viewer. If the generator doesn't
|
|
declare them, the default is to render with a perspective projection
|
|
and without culling.</p>
|
|
<p>The viewer allows you to rotate the image about the X, Y, and Z
|
|
axes. The viewer provides a left-handed coordinate system,
|
|
with +X toward the right, +Y toward the top of the screen, and +Z
|
|
going into the screen. The object will be placed a short distance
|
|
down the Z axis and scaled to fit the window.
|
|
Positive rotations cause a counter-clockwise rotation when the axis
|
|
about which rotations are performed points toward the viewer. The
|
|
rotations are performed with a matrix using Euler angles, and are
|
|
subject to gimbal lock (e.g. if you set Y to 90 degrees, X and Z rotate
|
|
about the same axis).</p>
|
|
<p>If you check the "Animated" box, you can add a simple spin. Choose
|
|
the number of degrees to rotate per frame, how many frames to generate before
|
|
resetting, and the delay between each frame. Clicking the "Auto" button
|
|
will automatically select the number of frames needed to display the
|
|
animation in an unbroken loop (useful for animated GIFs). Click
|
|
the "Test Animation" button to see it in action.</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>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 (col_stride = 1).</li>
|
|
<li><b>Row stride</b> - number of bytes between the start of each
|
|
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,
|
|
or when bitmap data is interleaved. If you set this to zero the
|
|
visualizer will default to no padding
|
|
(row_stride = width * column_stride).</li>
|
|
<li><b>Cell stride</b> - for multi-bitmap data like a font or sprite
|
|
sheet, this determines the number of bytes between the start of
|
|
one item and the next. If set to zero a "dense" arrangement is
|
|
assumed (cell_stride = row_stride * item_height).</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 and Apple/VisShapeTable</h3>
|
|
|
|
<p>There is no standard format for small hi-res bitmaps, but certain
|
|
arrangements are common. The VisHiRes script defines four generators:</p>
|
|
|
|
<ul>
|
|
<li><b>Hi-Res Bitmap</b> - converts an MxN row-major bitmap.</li>
|
|
<li><b>Hi-Res Sprite Sheet</b> - converts a series of bitmaps and
|
|
renders them in a grid. Useful for games that use cell
|
|
animation. The generated bitmap has a 1-pixel transparent gap
|
|
between elements.</li>
|
|
<li><b>Hi-Res Bitmap Font</b> - a simplified version of the
|
|
Sprite Sheet, intended for the common 7x8 monochrome fonts.
|
|
Most fonts have 96 or 128 glyphs, though some drop the last
|
|
character.
|
|
(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 two checkboxes
|
|
that affect the color. The first causes the first byte to be treated
|
|
as being in an odd column rather than an even one, which affects
|
|
green vs. purple and orange vs. blue. The second flips the high bits
|
|
on every byte, switching green vs. orange and purple vs. blue.
|
|
Neither has any effect on black & white bitmaps.</p>
|
|
<p>The converter generates one output pixel for every source pixel, so
|
|
half-pixel shifts are not represented.</p>
|
|
|
|
<p>The VisShapeTable script renders Applesoft shape tables, which can
|
|
have multiple vector shapes. The only parameter other than the offset
|
|
is the shape number.</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 doesn't attempt
|
|
to emulate this behavior, but works well for data stored in a
|
|
straightforward fashion.</p>
|
|
|
|
<ul>
|
|
<li><b>Sprite</b> - basic 1xN sprite, converted to an image 8 pixels
|
|
wide. Square pixels are assumed.</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.
|
|
The "Reflected" checkbox determines whether the right-side image is
|
|
repeated as-is or flipped.</li>
|
|
</ul>
|
|
|
|
<h3>Atari Arcade - Atari/VisAVG </h3>
|
|
|
|
<p>Different versions of Atari's Analog Vector Graphics were used in
|
|
several games, notably Battlezone, Tempest, and Star Wars. The commands
|
|
drove a vector display monitor. SourceGen visualizes them as 2D
|
|
wireframes, which isn't a perfect fit since they can describe points as
|
|
well as lines, but works fine for annotating a disassembly.</p>
|
|
<p>The visualizer takes two arguments: the offset of the start of
|
|
the commands to visualize, and the base address of vector RAM. The latter
|
|
is necessary to convert AVG JMP/JSR commands into offsets.</p>
|
|
|
|
<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>
|
|
|
|
<h3>Nintendo Entertainment System - Nintendo/VisNES</h3>
|
|
|
|
<p>NES PPU pattern tables hold 8x8 tiles with 2 bits of color per pixel.
|
|
Converting the full collection to a reference bitmap is straightforward.
|
|
A few color palette options are offered.</p>
|
|
|
|
<p>Sprites and backgrounds are formed from collections of tiles. In
|
|
some cases this is straightfoward, in others it's not. A visualization
|
|
generator that renders a "tile grid" is available for simpler cases.</p>
|
|
|
|
</div>
|
|
|
|
<div id="footer">
|
|
<p><a href="index.html">Back to index</a></p>
|
|
</div>
|
|
</body>
|
|
<!-- Copyright 2019 faddenSoft -->
|
|
</html>
|