6502/6502bench
1
0
Fork 0
mirror of https://github.com/fadden/6502bench.git synced 2024-12-28 01:29:29 +00:00
Code Issues Projects Releases Wiki Activity

Document visualizations

Browse Source
This commit is contained in:
Andy McFadden 2019-12-06 13:35:38 -08:00
parent 4696132dfa
commit af4ec49c9b
4 changed files with 165 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
SourceGen/RuntimeData/Help/advanced.html
View File

@ -164,9 +164,10 @@ Interfaces.cs in the PluginCommon directory. <b>Bear in mind that this
feature is still evolving, and the interfaces may change significantly
in the near future.</b></p>
<p>The current interfaces can be used to identify inline data that follows
JSR, JSL, or BRK instructions, and to format operands. The latter can be
useful for replacing immediate load operands with symbolic constants.</p>
<p>The current interfaces can be used to generate visualizations, to
identify inline data that follows JSR, JSL, or BRK instructions, and to
format operands. The latter can be useful for replacing immediate
load operands with symbolic constants.</p>
<p>Scripts may be loaded from the RuntimeData directory, or from the directory
where the project file lives. Attempts to load them from other locations
@ -190,16 +191,17 @@ for IntelliSense completion, and get all the usual syntax and compile
checking in the editor. (This is why there's a RuntimeData project for
Visual Studio.)</p>
<p>If you have the solution configured for debug builds, SourceGen will set
the IncludeDebugInformation flag to true when compiling scripts. This
<p>If you have the solution configured for debug builds, SourceGen will pass
<code>IncludeDebugInformation=true</code> to the script compiler. This
causes a .PDB file to be created. While this can help with debugging,
it can sometimes get in the way: if you edit the script source code and
reload the project, SourceGen will recompile the script, but the old .PDB
file will still be open by VisualStudio and you'll get error messages.</p>
reload the project without restarting the app, SourceGen will recompile
the script, but the old .PDB file will still be open by VisualStudio
and you'll get error messages.</p>
<p>Some commonly useful functions are defined in the PluginCommon.Util class,
which is available to plugins. These call into the CommonUtil library,
which is shared with SourceGen.
<p>Some commonly useful functions are defined in the
<code>PluginCommon.Util</code> class, which is available to plugins. These
call into the CommonUtil library, which is shared with SourceGen.
While plugins can use CommonUtil directly, they should avoid doing so. The
APIs there are not guaranteed to be stable, so plugins that rely on them
may break in a subsequent release of SourceGen.</p>
@ -338,9 +340,9 @@ not help you debug 6502 projects.</p>
symbols loaded from .sym65 files and find addresses that fall within
the bounds of the file. If it finds an address that is the start
of a code/data line and doesn't already have a user-supplied label,
the platform symbol's label will be applied. Useful for
disassembling ROM images or other code with an established set of
public entry points.
and the platform symbol's label isn't already defined elsewhere, the
platform label will be applied. Useful when disassembling ROM images
or other code with an established set of public entry points.
(Tip: disable "analyze uncategorized data" from the project
properties editor first.)</li>
</ul>

7
SourceGen/RuntimeData/Help/index.html
View File

@ -69,6 +69,13 @@ and 65816 code. The official web site is
</ul></li>
</ul></li>
<li><a href="visualization.html">Visualizations</a>
<ul>
<li><a href="visualization.html#overview">Overview</a></li>
<li><a href="visualization.html#vis-and-sets">Visualizations and Visualization Sets</a></li>
<li><a href="visualization.html#runtime">Scripts Included with SourceGen</a></li>
</ul></li>
<li><a href="editors.html">Editors</a>
<ul>
<li><a href="editors.html#address">Edit Address</a></li>

6
SourceGen/RuntimeData/Help/mainwin.html
View File

@ -5,12 +5,12 @@
<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>Main Window - 6502bench SourceGen</title>
<title>Using SourceGen - 6502bench SourceGen</title>
</head>
<body>
<div id="content">
<h1>6502bench SourceGen: Main Window</h1>
<h1>6502bench SourceGen: Using SourceGen</h1>
<p><a href="index.html">Back to index</a></p>
<h2><a name="starting-new">Starting a New Project</a></h2>
@ -192,6 +192,8 @@ enabled will depend on what you have selected in the main window.</p>
<li><a href="editors.html#lvtable">Edit Prior Local Variable Table</a>.
Modify or delete entries in the most recently defined local
variable table.</li>
<li><a href="visualization.html#vis-and-sets">Create/Edit Visualization Set</a>.
Create a new visualization set or edit an existing set.</li>
<li><a href="#hints">Hinting</a> (Hint As Code Entry Point, Hint As
Data Start, Hint As Inline Data, Remove Hints). Enabled when one or more

139
SourceGen/RuntimeData/Help/visualization.html Normal file
View File

@ -0,0 +1,139 @@
<!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 if the set of loaded extension
scripts changes.</p>
<p>Visualizations are not included in generated assembly output. They
may be included in HTML exports.</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.</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.</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>
<h3>Apple II - 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.</li>
<li><b>Hi-Res Screen Image</b> - used for 8KiB screen images. The
data is linearized and converted to a 280x192 bitmap.</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>
</div>
<div id="footer">
<p><a href="index.html">Back to index</a></p>
</div>
</body>
<!-- Copyright 2019 faddenSoft -->
</html>