Files
picovga-cmake/docs/tools.html
2025-08-26 20:52:06 -07:00

380 lines
20 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>PicoVGA: Tools and Palettes</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygen-awesome.css" rel="stylesheet" type="text/css"/>
<link href="custom.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectlogo"><img alt="Logo" src="logo.png"/></td>
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">PicoVGA
&#160;<span id="projectnumber">1.2-cmake</span>
</div>
<div id="projectbrief">VGA/TV display on Raspberry Pico</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.1 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('tools.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="PageDoc"><div class="header">
<div class="headertitle">
<div class="title">Tools and Palettes </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="md_pages_Tools"></a> The <code>tools</code> folder contains the support programs used to prepare images, palettes, and sounds for use with the <b>PicoVGA</b> library. These tools convert standard file formats (BMP, WAV, ACT) into optimized C arrays that can be compiled directly into PicoVGA projects. <br />
</p>
<p>The generated arrays provide graphics and audio data in formats tailored for the Raspberry Pi Picos hardware and the PicoVGA rendering pipeline. By using these utilities, you can ensure that assets created in common editors (e.g., Photoshop, GIMP, Audacity) are correctly formatted and ready to use without additional runtime conversion.</p>
<p>All tools are lightweight console applications that should compile for all platforms. Building the library will build these applications into the <code>tools</code> folder.</p>
<ul>
<li><a href="#picovga_img">picovga_img</a> Image Conversion Tool</li>
<li><a href="#picovga_rle">picovga_rle</a> RLE Compression Tool</li>
<li><a href="#picovga_snd">picovga_snd</a> Sound Import Tool</li>
<li><a href="#picvovga_pal332">picvovga_pal332</a> 8-bit Palette Generator</li>
<li><a href="#palettes">palettes</a> - A collection of <code>.act</code> palette files for use in image editors. <br />
</li>
</ul>
<h1><a class="anchor" id="picovga_img"></a>
Image Conversion Tool</h1>
<p><code>picovga_img</code> is a command-line utility that converts Windows BMP images into C array data for use with the PicoVGA library on the Raspberry Pi Pico. It ensures that images are properly formatted and optimized for 8-bit, 4-bit, 2-bit, or 1-bit palette graphics.</p>
<h2><a class="anchor" id="autotoc_md14"></a>
Usage</h2>
<div class="fragment"><div class="line">picovga_img input.bmp output.cpp arrayname</div>
</div><!-- fragment --><ul>
<li><code>input.bmp</code> Source image file (must be a Windows BMP format). <br />
</li>
<li><code>output.cpp</code> Destination C++ file containing the image data. <br />
</li>
<li><code>arrayname</code> Name of the C++ array that will hold the image data. <br />
</li>
</ul>
<p>The tool reads the BMP image, validates its format, and writes the pixel data into a <code>const u8[]</code> array that can be directly included in PicoVGA projects.</p>
<h2><a class="anchor" id="autotoc_md15"></a>
Supported Image Formats</h2>
<ul>
<li><b>8-bit palette BMP</b> Uses a 256-color palette. <br />
</li>
<li><b>4-bit palette BMP</b> Supports 16-color palettes (e.g., CGA or ZX Spectrum). <br />
</li>
<li><b>2-bit palette BMP</b> Saved as a 4-bit BMP but recognized by picovga_img if the palette only contains 4 colors (CGA modes). <br />
</li>
<li><b>1-bit palette BMP</b> Monochrome images with 2 colors. <br />
</li>
</ul>
<p>All input images must be:</p><ul>
<li><b>Windows BMP format</b> <br />
</li>
<li><b>Uncompressed (BI_RGB)</b> <br />
</li>
<li><b>Saved with flipped row order</b> (so that PicoVGA interprets the image correctly) <br />
</li>
</ul>
<h2><a class="anchor" id="autotoc_md16"></a>
Palettes</h2>
<p>When exporting from your image editor, always apply the correct palette (<code>.act</code> files) before saving: <br />
</p>
<ul>
<li><b>8-bit graphics</b><code>pal332.act</code> (332 RGB palette). <br />
</li>
<li><b>4-bit graphics</b><code>pal4_PC.act</code> (CGA palettes) or <code>pal4_ZX.act</code> (ZX Spectrum). <br />
</li>
<li><b>2-bit graphics</b><code>palcga*.act</code> (CGA palettes, modes 16). <br />
</li>
<li><b>1-bit graphics</b><code>pal1.act</code> (black &amp; white). <br />
</li>
</ul>
<p>⚠️ <b>Note:</b> BMP does not natively support 2-bit images. Save as a 4-bit BMP with a 4-color palette, and RaspPicoImg will automatically detect and convert it to 2-bit format.</p>
<h2><a class="anchor" id="autotoc_md17"></a>
Output</h2>
<p>The generated <code>.c</code> file contains:</p><ul>
<li>Image metadata (bit depth, width, height, pitch). <br />
</li>
<li>A <code>const u8[]</code> array with pixel data aligned to 4 bytes. <br />
</li>
</ul>
<p>Example excerpt: </p><div class="fragment"><div class="line"><span class="comment">// format: 4-bit pixel graphics</span></div>
<div class="line"><span class="comment">// image width: 128 pixels</span></div>
<div class="line"><span class="comment">// image height: 64 lines</span></div>
<div class="line"><span class="comment">// image pitch: 64 bytes</span></div>
<div class="line"><span class="keyword">const</span> u8 myimage[8192] __attribute__ ((aligned(4))) = {</div>
<div class="line"> 0x12, 0x34, 0x56, 0x78, ...</div>
<div class="line">};</div>
</div><!-- fragment --><p>This array can be included in your PicoVGA project and drawn directly to the screen.</p>
<h1><a class="anchor" id="picovga_rle"></a>
RLE Compression Tool</h1>
<p><code>picovga_rle</code> is a command-line utility that compresses 8-bit PicoVGA images into a run-length encoded (RLE) format suitable for use with the PicoVGA library on the Raspberry Pi Pico. The compression significantly reduces image size while maintaining compatibility with the RLE PIO routines in PicoVGA.</p>
<h2><a class="anchor" id="autotoc_md18"></a>
Usage</h2>
<div class="fragment"><div class="line">picovga_rle input.bmp output.c arrayname transparent_color</div>
</div><!-- fragment --><ul>
<li><code>input.bmp</code> Source image file (must be an 8-bit BMP using the PicoVGA palette <code>pal332.act</code>). <br />
</li>
<li><code>output.cpp</code> Destination C++ file containing the compressed image data. <br />
</li>
<li><code>arrayname</code> Name of the generated C array. <br />
</li>
<li><code>transparent_color</code> Index of the color to be used as transparency (0255). Use <code>-1</code> for no transparency. <br />
</li>
</ul>
<p>The tool reads the BMP image, compresses it using RLE, and outputs a set of C arrays containing both pixel data and row offsets.</p>
<h2><a class="anchor" id="autotoc_md19"></a>
Input Requirements</h2>
<ul>
<li><b>Format:</b> Windows BMP. <br />
</li>
<li><b>Bit Depth:</b> 8-bit palettized (must use PicoVGA's <code>pal332.act</code>). <br />
</li>
<li><b>Compression:</b> None (must be saved uncompressed). <br />
</li>
<li><b>Row Order:</b> Reverse line order enabled. <br />
</li>
</ul>
<p>⚠️ If the input image does not meet these conditions, the tool will reject it.</p>
<h2><a class="anchor" id="autotoc_md20"></a>
Transparency</h2>
<p>The fourth parameter specifies which color index should be treated as transparent. <br />
</p>
<ul>
<li>To enable transparency: supply the <b>palette index</b> of the color. For example, if a pixel color in Photoshop is <code>#8080FF</code>, locate it in <code>pal332.csv</code> to find the matching PicoVGA index. <br />
</li>
<li>To disable transparency: set the parameter to <code>-1</code>. <br />
</li>
</ul>
<p>Example: </p><div class="fragment"><div class="line">picovga_rle sprite.bmp sprite.c mysprite 120</div>
</div><!-- fragment --><p> This command compresses <code>sprite.bmp</code>, outputs to <code>sprite.c</code>, creates an array named <code>mysprite</code>, and treats color index 120 as transparent.</p>
<h2><a class="anchor" id="autotoc_md21"></a>
Output</h2>
<p>The generated <code>.cpp</code> file contains:</p><ul>
<li><b>Image metadata</b> format, transparency, width, height, size, and compression ratio. <br />
</li>
<li><b>Row offset table</b> an array of <code>u16</code> values marking where each scanline begins in the compressed data. <br />
</li>
<li><b>RLE data array</b> compressed image data aligned to 4 bytes. <br />
</li>
</ul>
<p>Example excerpt: </p><div class="fragment"><div class="line"><span class="comment">// format: RLE compression</span></div>
<div class="line"><span class="comment">// transparent color: 120</span></div>
<div class="line"><span class="comment">// image width: 64 pixels</span></div>
<div class="line"><span class="comment">// image height: 64 lines</span></div>
<div class="line"><span class="comment">// uncompressed size: 4096 bytes</span></div>
<div class="line"><span class="comment">// compressed size: 1536 bytes</span></div>
<div class="line"><span class="comment">// compression ratio: 37.5%</span></div>
<div class="line"> </div>
<div class="line"><span class="keyword">const</span> u16 mysprite_rows[65] = {</div>
<div class="line"> 0x0000, 0x0012, 0x0028, ...</div>
<div class="line">};</div>
<div class="line"> </div>
<div class="line"><span class="keyword">const</span> u8 mysprite[1536] __attribute__ ((aligned(4))) = {</div>
<div class="line"> 0x34, 0x07, 0x12, 0x56, ...</div>
<div class="line">};</div>
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md22"></a>
Internal Encoding</h2>
<p>The RLE compression encodes pixel sequences into tokens:</p><ul>
<li><b>skip</b> Transparent runs of 2257 pixels. <br />
</li>
<li><b>skip1</b> Single transparent pixel. <br />
</li>
<li><b>run</b> Repeated color runs of 3258 pixels. <br />
</li>
<li><b>raw / raw1</b> Direct copies of pixel values (used when sequences are too short for run-length encoding). <br />
</li>
</ul>
<p>Each scanline is terminated with an <code>idle</code> command and aligned to 32-bit boundaries for efficient processing on the Pico.</p>
<h2><a class="anchor" id="autotoc_md23"></a>
Compatibility Warning</h2>
<p>The compressed output is tightly coupled with the <b>RLE PIO program</b> in PicoVGA. Since the instruction format may change between library versions, <b>always use picovga_rle from the same release as your PicoVGA library</b> to avoid incompatibility issues.</p>
<h1><a class="anchor" id="picovga_snd"></a>
Sound Import Tool</h1>
<p><code>picovga_snd</code> is a command-line utility that converts WAV audio files into C array data for playback with the PicoVGA library on the Raspberry Pi Pico. It ensures that sound effects or music are properly formatted for the Picos audio playback routines.</p>
<h2><a class="anchor" id="autotoc_md24"></a>
Usage</h2>
<div class="fragment"><div class="line">picovga_snd input.wav output.cpp arrayname</div>
</div><!-- fragment --><ul>
<li><code>input.wav</code> Source WAV file. <br />
</li>
<li><code>output.cpp</code> Destination C++ file containing the audio data array. <br />
</li>
<li><code>arrayname</code> Name of the generated C array. <br />
</li>
</ul>
<p>The tool validates the WAV file format and writes its sample data into a <code>const u8[]</code> array that can be directly included in PicoVGA projects.</p>
<h2><a class="anchor" id="autotoc_md25"></a>
Input Requirements</h2>
<p>The input WAV file must meet <b>strict format requirements</b>:</p><ul>
<li><b>Format:</b> PCM (uncompressed). <br />
</li>
<li><b>Channels:</b> Mono (1 channel). <br />
</li>
<li><b>Bit depth:</b> 8-bit unsigned (values 0255, centered at 128). <br />
</li>
<li><b>Sample rate:</b> 22050 Hz. <br />
</li>
</ul>
<p>⚠️ If the file does not meet these conditions, the tool will reject it.</p>
<h3><a class="anchor" id="autotoc_md26"></a>
Recommended Editors</h3>
<ul>
<li><b>Audacity</b> (free) provides full editing and sound effects, and supports exporting WAV in the correct format. <br />
</li>
<li><b>Cool Edit</b> a commercial editor that can also produce compatible WAV files. <br />
</li>
</ul>
<p>These tools allow trimming, resampling, and converting audio to the exact format needed for PicoVGA.</p>
<h2><a class="anchor" id="autotoc_md27"></a>
Output</h2>
<p>The generated <code>.cpp</code> file contains:</p><ul>
<li>A header comment describing the sound format. <br />
</li>
<li>A <code>const u8[]</code> array aligned to 4 bytes, containing all audio samples. <br />
</li>
</ul>
<p>Example excerpt: </p><div class="fragment"><div class="line"><span class="comment">// sound format: PCM mono 8-bit 22050Hz</span></div>
<div class="line"><span class="keyword">const</span> u8 mysound[1024] __attribute__ ((aligned(4))) = {</div>
<div class="line"> 0x80, 0x82, 0x7E, 0x7C, ...</div>
<div class="line">};</div>
</div><!-- fragment --><p>This array can be compiled into your PicoVGA program and played back using the sound routines in the library.</p>
<h1><a class="anchor" id="picvovga_pal332"></a>
8-bit Palette Generator</h1>
<p><code>picvovga_pal332</code> is a utility program used to generate the standard 8-bit PicoVGA palette. This palette is the foundation for all 8-bit graphics in PicoVGA and defines a total of 256 colors based on a <b>3-3-2 bit RGB model</b>:</p><ul>
<li><b>3 bits red (07 levels)</b></li>
<li><b>3 bits green (07 levels)</b></li>
<li><b>2 bits blue (03 levels)</b></li>
</ul>
<p>This RGB332 format allows compact color representation while providing a broad enough spectrum for retro-style graphics.</p>
<h2><a class="anchor" id="autotoc_md28"></a>
Output Files</h2>
<p>When you run <code>picvovga_pal332</code>, it generates two important files:</p>
<ul>
<li><code>pal332.act</code> Adobe Color Table file containing the 256-color PicoVGA palette. This file can be imported into image editors such as Photoshop or GIMP to ensure images are created using PicoVGAs 8-bit colors.</li>
<li><code>pal332.csv</code> A CSV table with detailed color information. Each row includes:<ul>
<li><b>Palette index (0255)</b></li>
<li><b>RGB hex value</b></li>
<li><b>Individual red, green, and blue component values</b></li>
</ul>
</li>
</ul>
<p>Example (excerpt from <code>pal332.csv</code>): </p><div class="fragment"><div class="line">Index, HEX, R, G, B</div>
<div class="line">0, #000000, 0, 0, 0</div>
<div class="line">1, #000055, 0, 0, 85</div>
<div class="line">2, #0000AA, 0, 0, 170</div>
<div class="line">...</div>
</div><!-- fragment --><h2><a class="anchor" id="autotoc_md29"></a>
Usage in Image Editors</h2>
<ul>
<li>In <b>Photoshop</b> or <b>GIMP</b>, load <code>pal332.act</code> as the palette before saving your image as an 8-bit BMP. This ensures the image uses the exact PicoVGA colors.</li>
<li>If you identify a color in an image by its <b>HEX code</b> (e.g., <code>#8080FF</code>), you can use <code>pal332.csv</code> to look up which PicoVGA color index corresponds to that HEX value.</li>
</ul>
<p>This is especially useful when working with transparency or when preparing assets for use with other PicoVGA tools such as <code>picovga_img</code> or <code>picovga_rle</code>.</p>
<h1><a class="anchor" id="palettes"></a>
Palettes</h1>
<p>The PicoVGA project includes a set of predefined palettes located in the <code>tools\palettes</code> folder. These palettes (<code>*.act</code> files) can be used in Photoshop, GIMP, or other graphics editors to ensure images match PicoVGAs supported color sets.</p>
<h2><a class="anchor" id="autotoc_md30"></a>
Available Palettes</h2>
<ul>
<li><code>pal332.act</code> The primary 8-bit PicoVGA palette. This file defines the 256 standard colors used by PicoVGA. <br />
</li>
<li><code>pal4_PC.act</code> Standard CGA 16-color palette. <br />
</li>
<li><code>pal4_ZX.act</code> ZX Spectrumstyle 16-color palette. <br />
</li>
<li><code>palcga*.act</code> Variants of CGA palettes for different modes (used for 2-bit conversions). <br />
</li>
<li><code>pal1.act</code> Black &amp; white palette for 1-bit images. <br />
</li>
</ul>
<h2><a class="anchor" id="autotoc_md31"></a>
Palette Details</h2>
<p>The most important palette is <code>pal332.act</code>, which represents the 3-3-2 bit RGB layout (3 bits red, 3 bits green, 2 bits blue). It is generated by the <code>picovga_pal332</code> tool and comes with an additional CSV file:</p>
<ul>
<li><code>pal332.csv</code> Contains detailed information about each color entry:<ul>
<li>Color index (palette order number). <br />
</li>
<li>RGB value of the color. <br />
</li>
<li>Separate red, green, and blue component values. <br />
</li>
</ul>
</li>
</ul>
<p>This CSV file can be opened in Excel, LibreOffice, or any text editor. It is especially useful if you want to map a color youve selected in Photoshop (by HEX code) to its exact PicoVGA color index. Simply search for the HEX value in <code>pal332.csv</code> and read the index number at the beginning of the corresponding line.</p>
<p>⚠️ <b>Tip:</b> Always apply the correct <code>.act</code> palette before saving your BMP images for conversion with <code>picovga_img</code>. This ensures the tool interprets the colors correctly. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
</ul>
</div>
</body>
</html>