6502bench SourceGen: Visualizations

Back to index

Overview

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.

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 extension scripts. 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.

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.

Visualizations are not included in generated assembly output. They may be included in HTML exports.

Visualizations and Visualization Sets

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.

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.

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.

Bitmap Visualization Editor

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.

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.

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.

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.

Scripts Included with SourceGen

A number of visualization generation scripts are included with SourceGen, in the platform-specific runtime data directories.

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:

Apple II - VisHiRes

There is no standard format for small hi-res bitmaps, but certain arrangements are common. The script defines three generators:

Widths are specified in bytes, not pixels. Each byte represents 7 pixels (with some hand-waving).

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.

The converter generates one output pixel for every source pixel, so half-pixel shifts are not rendered.