mirror of
https://github.com/fadden/6502bench.git
synced 2025-02-28 10:29:02 +00:00
eef1710d5d
Two main changes: - "Seek nearby targets" is no longer enabled by default. - The application asks the user to save new projects immediately. Various minor edits were also made. A couple of the images are slightly stale, showing ".org" rather than ".addrs", but they're in the advanced section and the difference isn't notable.
391 lines
16 KiB
HTML
391 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<!-- START: /incl-head.html -->
|
|
<!-- common head elements -->
|
|
<meta charset="utf-8"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
|
|
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"
|
|
integrity="sha384-vtXRMe3mGCbOeY7l30aIg8H9p3GdeSe4IFlP6G8JMa7o7lXvnz3GFKzPxzJdPfGK" crossorigin="anonymous"></script>
|
|
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css"/>
|
|
<link rel="stylesheet" href="../main.css"/>
|
|
<!-- END: /incl-head.html -->
|
|
|
|
<title>Visualizations - SourceGen Tutorial</title>
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<!-- START: /incl-masthead.html -->
|
|
<div id="masthead">
|
|
<!--<div class="masthead-title" style="background-image: url('images/screenshot-mainwin.png');">-->
|
|
<div class="masthead-title">
|
|
6502bench
|
|
</div>
|
|
</div>
|
|
<!-- END: /incl-masthead.html -->
|
|
|
|
<!-- START: /incl-topnav.html active:#topnav-sgtutorial -->
|
|
<div id="topnav">
|
|
<!-- top navigation bar contents -->
|
|
<nav>
|
|
<a id="topnav-home" href=".././">HOME</a>
|
|
<a id="topnav-sgtutorial" class="active" href="../sgtutorial">SourceGen Tutorial</a>
|
|
<a id="topnav-menuicon" href="javascript:void(0);" class="icon" onclick="toggleSidenav()">
|
|
<i class="fa fa-bars"></i>
|
|
</a>
|
|
</nav>
|
|
<script>
|
|
// Sidenav toggle function.
|
|
//
|
|
// Use a jQuery function to toggle the sidenav bar. The initial state
|
|
// is undefined / inherited, so it will pop in and out as the screen
|
|
// resizes around the "large" breakpoint.
|
|
function toggleSidenav() {
|
|
$("#sidenav").toggle("fast");
|
|
}
|
|
</script>
|
|
</div>
|
|
<!-- END: /incl-topnav.html -->
|
|
|
|
<!-- START: incl-sidenav.html active:#sidenav-visualizations -->
|
|
<div id="sidenav">
|
|
<!-- side navigation bar contents -->
|
|
<ul>
|
|
<li id="sidenav-index"><a href="./">Introduction</a></li>
|
|
<li id="sidenav-about-disasm"><a href="about-disasm.html">About Disassembly</a></li>
|
|
<li id="sidenav-using-sourcegen"><a href="using-sourcegen.html">Using SourceGen</a>
|
|
<ul>
|
|
<li id="sidenav-moving-around"><a href="moving-around.html">Moving Around</a></li>
|
|
<li id="sidenav-making-edits"><a href="making-edits.html">Making Edits</a></li>
|
|
<li id="sidenav-labels-symbols"><a href="labels-symbols.html">Labels & Symbols</a></li>
|
|
<li id="sidenav-editing-data"><a href="editing-data.html">Editing Data Operands</a></li>
|
|
<li id="sidenav-generating-code"><a href="generating-code.html">Generating Code</a></li>
|
|
</ul></li>
|
|
<li id="sidenav-digging-deeper"><a href="digging-deeper.html">Digging Deeper</a>
|
|
<ul>
|
|
<li id="sidenav-string-formatting"><a href="string-formatting.html">String Formatting</a></li>
|
|
<li id="sidenav-local-variables"><a href="local-variables.html">Local Variables</a></li>
|
|
<li id="sidenav-inline-data"><a href="inline-data.html">Inline Data</a></li>
|
|
<li id="sidenav-odds-ends"><a href="odds-ends.html">Odds & Ends</a></li>
|
|
</ul></li>
|
|
<li id="sidenav-advanced-topics"><a href="advanced-topics.html">Advanced Topics</a>
|
|
<ul>
|
|
<li id="sidenav-address-tables"><a href="address-tables.html">Address Tables</a></li>
|
|
<li id="sidenav-extension-scripts"><a href="extension-scripts.html">Extension Scripts</a></li>
|
|
<li id="sidenav-visualizations" class="active"><a href="visualizations.html">Visualizations</a></li>
|
|
</ul></li>
|
|
<li id="sidenav-suggestions"><a href="suggestions.html">Suggestions</a></li>
|
|
</ul>
|
|
</div>
|
|
<!-- END: incl-sidenav.html -->
|
|
|
|
<div id="main">
|
|
|
|
<h2>Visualizations</h2>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>Many programs contain a significant amount of graphical data. This is
|
|
especially true for games, where the space used for bitmaps is often
|
|
larger than the space required for the code. When disassembling a program
|
|
it can be very helpful to be able to see the contents of the data
|
|
regions in graphical form.</p>
|
|
|
|
<p>Start a new project with the <samp>Generic 6502</samp> profile,
|
|
and from the SourceGen Tutorial directory select "Tutorial5".
|
|
We'll need to load an extension script from
|
|
the project directory, so go ahead and save the project, using the
|
|
default name ("Tutorial5.dis65").</p>
|
|
|
|
<p>Normally a project will give you some sort of hint as to the data
|
|
format, e.g. the graphics might be a platform-specific sprite. For
|
|
non-standard formats you can glean dimensions from the drawing code. For
|
|
the purposes of this tutorial we're just using a simple monochrome bitmap
|
|
format, with 8 pixels per byte, and we know that our images are for
|
|
a Tic-Tac-Toe game. The 'X' and the 'O' are 8x8, the game board is 40x40.
|
|
The bitmaps are sprites with transparency, so pixels are either solid
|
|
or transparent.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-add-vis.png" alt="t5-add-vis"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>The first thing we need to do is load an extension script that can
|
|
decode this format. The SourceGen "RuntimeData" directory has a few,
|
|
but for this tutorial we're using a custom one. Select
|
|
<samp>Edit > Project Properties</samp>, select the
|
|
<samp>Extension Scripts</samp> tab, and click
|
|
<samp>Add Scripts from Project</samp>.
|
|
Double-click on "<samp>VisTutorial5.cs</samp>",
|
|
then click </samp>OK</samp>.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-new-vis.png" alt="t5-new-vis"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>The addresses of the three bitmaps are helpfully identified by the
|
|
load instructions at the top of the file. Select the line at
|
|
address $100A, then
|
|
<samp>Actions > Create/Edit Visualization Set</samp>. In
|
|
the window that opens, click <samp>New Visualization</samp>.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>We're going to ignore most of what's going on and just focus on the
|
|
list of parameters at the bottom. The file offset indicates where in
|
|
the file the bitmap starts; note this is an offset, not an address
|
|
(that way, if you change the address, your visualizations don't break).
|
|
This is followed by the bitmap's width in bytes, and the bitmap's height.
|
|
Because we have 8 pixels per byte, we're currently showing an 8x1 image.
|
|
(We'll come back to look at row stride in a bit.)</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-set-height-8.png" alt="t5-set-height-8"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>We happen to know (by playing the game and/or reading the fictitious
|
|
drawing code) that the image is 8x8, so change the value in the
|
|
<samp>Height</samp>
|
|
field to 8. As soon as you do, the preview window shows a big blue 'X'.
|
|
(The 'X' is 7x7; the last row/column of pixels are transparent so adjacent
|
|
images don't bump into each other.)</p>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-set-height-80.png" alt="t5-set-height-80"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>Let's try doing it wrong. Add a '0' in the <samp>Height</samp>
|
|
field to make the
|
|
height 80. You can see some additional bitmap data.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-set-height-800.png" alt="t5-set-height-800"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>Add another 0 to make it 800. Now you get
|
|
a big red X, and the <samp>Height</samp> parameter is shown in red.
|
|
That's because the maximum value for the height is 512, as shown
|
|
by "<samp>[1,512]</samp>" on the right.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-addvis1.png" alt="t5-addvis1"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>Change it back to 8, and hit <samp>OK</samp>.
|
|
Hit <samp>OK</samp> in the <samp>Edit Visualization Set</samp>
|
|
window as well. You should now see the blue 'X' in the code listing
|
|
above line $100A.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-addvis2.png" alt="t5-addvis2"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>Repeat the process at line $1012: select the line, create a visualization
|
|
set, create a new visualization. The height will default to 8 because
|
|
that's what you used last time, so you shouldn't have to
|
|
make any changes to the initial values.
|
|
Click <samp>OK</samp> in both dialogs to close them.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-101a-mess.png" alt="t5-101a-mess"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>Repeat the process at line $101A, but this time the image is 40x40
|
|
rather than 8x8. Set the width to 5, and the height to 40. This makes
|
|
a mess.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-101a-good.png" alt="t5-101a-good"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>In this case, the bitmap data is 5 bytes wide, but the data is stored
|
|
as 8 bytes per row. This is known as the "stride" or "pitch" of the row.
|
|
To tell the visualizer to skip the last 3 bytes on each row, set the
|
|
<samp>Row stride (bytes)</samp> field to 8.
|
|
Now we have a proper Tic-Tac-Toe grid.
|
|
Note that it fills the preview window just as the 'X' and 'O' did, even
|
|
though it's 5x as large. The preview window scales everything up. Hit
|
|
<samp>OK</samp> twice to create the visualization.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-fmt-dense.png" alt="t5-fmt-dense"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>Let's format the bitmap data. Select line $101A, then shift-click the
|
|
last line in the file ($1159). <samp>Actions > Edit Operand</samp>. Select
|
|
<samp>Densely-packed bytes</samp>, and click <samp>OK</samp>.
|
|
This is perhaps a little too
|
|
dense. Open the operand editor again, but this time select the
|
|
densely-packed bytes sub-option <samp>...with a limit</samp>, and set the limit
|
|
to 8 bytes per line. Instead of one very dense statement spread across
|
|
a few lines, you get one line of source code per row of bitmap.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>To change whether or not commas appear between bytes in the operand,
|
|
open <samp>Edit > Settings</samp>, select the
|
|
<samp>Display Format</samp> tab, and check
|
|
<samp>Use comma-separated format for bulk data</samp>.
|
|
This trades off compactness for ease of reading.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<hr style="width:80%;"/>
|
|
|
|
<h4>Bitmap Animations</h4>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-bitmap-anim-editor.png" alt="t5-bitmap-anim-editor"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>Some bitmaps represent individual frames in an animated sequence.
|
|
You can convert those as well. Double-click on the blue 'X' to open
|
|
the visualization set editor, then click "New Bitmap Animation". This
|
|
opens the Bitmap Animation Editor.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-xo-anim.png" alt="t5-xo-anim"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>Let's try it with our Tic-Tac-Toe board pieces. From the list
|
|
on the left, select the blue 'X' and click <samp>Add</samp>, then
|
|
click the 'O' and click <samp>Add</samp>. Below the list, set the
|
|
frame delay to 500 msec. Near the bottom, click
|
|
<samp>Start / Stop</samp>. This causes the animation to play in a loop.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>You can use the controls to add and remove items, change their order, and change
|
|
the animation speed. You can add the grid bitmap to the animation set, but the
|
|
preview scales the bitmaps up to full size, so it may not look the way
|
|
you expect.</p>
|
|
<p>Hit <samp>OK</samp> to save the animation, then
|
|
<samp>OK</samp> to update the visualization set.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-list-xanim.png" alt="t5-list-xanim"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>The code list now shows two entries in the line: the first is the 'X'
|
|
bitmap, the second is the animation, which is shown as the initial frame
|
|
with a blue triangle superimposed. (If you go back into the editor and
|
|
reverse the order of the frames, the list will show the 'O' instead.)
|
|
You can have as many bitmaps and animations on a line as you want.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>If you have a lot of bitmaps it can be helpful to give them meaningful
|
|
names, so that they're easy to identify and sort together in the list.
|
|
The <samp>Tag</samp> field at the top of the editor windows lets you
|
|
give things names. Tags must be unique.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<hr style="width:80%;"/>
|
|
|
|
<h4>Other Notes</h4>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-text">
|
|
<p>The visualization editor is intended to be very dynamic, showing the
|
|
results of parameter changes immediately. This can be helpful if you're
|
|
not exactly sure what the size or format of a bitmap is. Just keep
|
|
tweaking values until it looks right.</p>
|
|
|
|
<p>Visualization generators are defined by extension scripts. If you're
|
|
disassembling a program with a totally custom way of storing graphics,
|
|
you can write a totally custom visualizer and distribute it with the
|
|
project. Because the file offset is a parameter, you're not limited to
|
|
placing visualizations at the start of the graphic data -- you can put
|
|
them on any code or data line.</p>
|
|
|
|
<p>Visualizations have no effect on assembly source code generation,
|
|
but they do appear in code exported to HTML. Bitmaps are converted to GIF
|
|
images, and animations become animated GIFs.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="grid-container">
|
|
<div class="grid-item-image">
|
|
<img src="images/t5-wireframe-sample.png" alt="t5-wireframe-sample"/>
|
|
</div>
|
|
<div class="grid-item-text">
|
|
<p>You can also create animated visualizations of wireframe objects
|
|
(vector graphics, 3D shapes), but that's not covered in this tutorial.</p>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
</div> <!-- #main -->
|
|
|
|
<div id="prevnext">
|
|
<a href="extension-scripts.html" class="btn-previous">« Previous</a>
|
|
<a href="suggestions.html" class="btn-next">Next »</a>
|
|
</div>
|
|
|
|
<!-- START: /incl-footer.html -->
|
|
<div id="footer">
|
|
<hr/>
|
|
<p>Copyright 2021 faddenSoft</p>
|
|
<!-- <p id="screen-size"></p>
|
|
<script>
|
|
var w = window.innerWidth;
|
|
var h = window.innerHeight;
|
|
var x = document.getElementById("screen-size");
|
|
x.innerHTML = "DEBUG: initial window size " + w + "x" + h;
|
|
</script> -->
|
|
</div>
|
|
<!-- END: /incl-footer.html -->
|
|
|
|
</body>
|
|
</html>
|