1
0
mirror of https://github.com/fadden/6502bench.git synced 2024-12-03 05:49:48 +00:00
6502bench/docs/sgmanual/visualization.html
Andy McFadden ed4cc84782 Relocate manual
Move the SourceGen manual to a subdirectory in "docs", so that it can
be accessed directly from the 6502bench web site.  The place where
it's installed in the distribution doesn't change.
2021-10-08 08:43:12 -07:00

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 &gt; 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 &amp; 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">&nbsp;black&nbsp;</span></li>
<li><span style="color:#000000;background-color:#ffffff">&nbsp;white&nbsp;</span></li>
<li><span style="color:#ffffff;background-color:#67372b">&nbsp;red&nbsp;</span></li>
<li><span style="color:#ffffff;background-color:#70a4b2">&nbsp;cyan&nbsp;</span></li>
<li><span style="color:#ffffff;background-color:#6f3d86">&nbsp;purple&nbsp;</span></li>
<li><span style="color:#ffffff;background-color:#588d43">&nbsp;green&nbsp;</span></li>
<li><span style="color:#ffffff;background-color:#352879">&nbsp;blue&nbsp;</span></li>
<li><span style="color:#000000;background-color:#b8c76f">&nbsp;yellow&nbsp;</span></li>
<li><span style="color:#ffffff;background-color:#6f4f25">&nbsp;orange&nbsp;</span></li>
<li><span style="color:#ffffff;background-color:#433900">&nbsp;brown&nbsp;</span></li>
<li><span style="color:#ffffff;background-color:#9a6759">&nbsp;light red&nbsp;</span></li>
<li><span style="color:#ffffff;background-color:#444444">&nbsp;dark grey&nbsp;</span></li>
<li><span style="color:#ffffff;background-color:#6c6c6c">&nbsp;grey&nbsp;</span></li>
<li><span style="color:#000000;background-color:#9ad284">&nbsp;light green&nbsp;</span></li>
<li><span style="color:#ffffff;background-color:#6c5eb5">&nbsp;light blue&nbsp;</span></li>
<li><span style="color:#ffffff;background-color:#959595">&nbsp;light grey&nbsp;</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>