dranke/microw8
1
0
Fork 0
mirror of https://github.com/exoticorn/microw8.git synced 2026-01-20 11:16:42 +01:00
Code Issues Projects Releases Wiki Activity

work on api documentation

Browse Source
This commit is contained in:
Dennis Ranke
2022-01-09 23:30:14 +01:00
parent f062e545f6
commit 3d79239a01
4 changed files with 255 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
site/content/_index.md
View File

@@ -1,6 +1,23 @@
+++ +++
+++ +++
## Specs
* Screen: 320x240, 256 colors, 60Hz
* Modules: Up to 256KB (WASM)
* Memory: 256KB
* Gamepad input (D-Pad + 4 Buttons)
## Examples
* [Fireworks](v0.1pre5#AgwvgP+M59snqjl4CMKw5sqm1Zw9yJCbSviMjeLUdHus2a3yl/a99+uiBeqZgP/2jqSjrLjRk73COMM6OSLpsxK8ugT1kuk/q4hQUqqPpGozHoa0laulzGGcahzdfdJsYaK1sIdeIYS9M5PnJx/Wk9H+PvWEPy2Zvv7I6IW7Fg==) (127 bytes): Some fireworks to welcome 2022.
* [Skip Ahead](v0.1pre5#AgyfpZ80wkW28kiUZ9VIK4v+RPnVxqjK1dz2BcDoNyQPsS2g4OgEzkTe6jyoAfFOmqKrS8SM2aRljBal9mjNn8i4fP9eBK+RehQKxxGtJa9FqftvqEnh3ez1YaYxqj7jgTdzJ/WAYVmKMovBT1myrX3FamqKSOgMsNedLhVTLAhQup3sNcYEjGNo8b0HZ5+AgMgCwYRGCe//XQOMAaAAzqDILgmpEZ/43RKHcQpHEQwbURfNQJpadJe2sz3q5FlQnTGXQ9oSMokidhlC+aR/IpNHieuBGLhFZ2GfnwVQ0geBbQpTPA==) (229 bytes): A port of my [TIC-80 256byte game](http://tic80.com/play?cart=1735) from LoveByte'21
* [OhNoAnotherTunnel](v0.1pre4#Ag95rdCB5Ww5NofyQaKF4P1mrNRso4azgiem4hK99Gh8OMzSpFq3NsNDo7O7pqln10D11l9uXr/ritw7OEzKwbEfCdvaRnS2Z0Kz0iDEZt/gIqOdvFmxsL1MjPQ4XInPbUJpQUonhQq29oP2omFabnQxn0bzoK7mZjcwc5GetHG+hGajkJcRr8oOnjfCol8RD+ha33GYtPnut+GLe4ktzf5UxZwGs6oT9qqC61lRDakN) (177 bytes): A port of my [entry](http://tic80.com/play?cart=1871) in the Outline'21 bytebattle final
* [Technotunnel](v0.1pre4#AqL8HeK1M9dn2nWNIF5vaq/Vh64pMt5nJIFoFKpBMPUsGtDtpqjo1JbT9LzPhAxCqJ7Yh4TA6oTGd4xhLowf+cWZMY73+7AZmfXJJsBi4cej/hH+4wlAgxFIrnOYnr/18IpnZbsHf0eGm1BhahX74+cVR0TRmNQmYC7GhCNS3mv/3MJn74lCj7t28aBJPjEZhP9fGXdG2u5Egh/Tjdg=) (158 bytes): A port of my [entry](https://tic80.com/play?cart=1873) in the Outline'21 bytebattle quater final
* [Font & Palette](v0.1pre4#AgKaeeOuwg5gCKvFIeiitEwMpUI2rymEcu+DDB1vMu9uBoufvUxIr4Y5p4Jj2ukoNO4PE7QS5cN1ZyDMCRfSzYIGZxKlN2J6NKEWK7KVPk9wVUgn1Ip+hsMinWgEO8ETKfPuHoIa4kjI+ULFOMad7vd3rt/lh1Vy9w+R2MXG/7T61d3c7C6KY+eQNS0eW3ys4iU8R6SycuWZuuZ2Sg3Qxp826s+Kt+2qBojpzNOSoyFqyrVyYMTKEkSl0BZOj59Cs1hPm5bq0F1MmVhGAzMhW9V4YeAe): Just a simple viewer for the default font and palette.
* [Technotunnel B/W](v0.1pre2#AQrDAQHAAQIBfwp9A0AgAUEAsiABQcACb7JDmhkgQ5MiBCAEIASUIAFBwAJtQfgAa7IiBSAFlJKRIgaVIgcgByAAskHQD7KVIgIQAEPNzEw/lCIDlCAHIAeUIAOUIAOUQQGykiADIAOUk5GSIgiUIAOTQQqylCACkiIJqCAFIAaVIAiUQQqylCACkiIKqHMgCEEyspQgBpUiCyACkkEUspSocUEFcbJBArIgC5OUQRaylJeoOgB4IAFBAWoiAUGA2ARIDQALCw==) (199 bytes uncompressed): A port of my [entry](https://tic80.com/play?cart=1873) in the Outline'21 bytebattle quater final (older MicroW8 version with monochrome palette)
* [XorScroll](v0.1pre2#AQovAS0BAX8DQCABIAFBwAJvIABBCm1qIAFBwAJtczoAeCABQQFqIgFBgNgESA0ACws=) (50 bytes uncompressed): A simple scrolling XOR pattern. Fun fact: This is the pre-loaded effect when entering a bytebattle.
* [CircleWorm](v0.1pre2#AQp7AXkCAX8CfUEgEA0DQCABskEEspUiAkECspUgALJBiCeylSIDQQWylJIQAEEBspJBoAGylCACQQOylSADQQSylJIQAEEBspJB+ACylCADQRGylCACQQKylJIQAEECspJBELKUIAFBAmxBP2oQEiABQQFqIgFBP0gNAAsL) (126 bytes uncompressed): Just a test for the circle fill function.
## Versions ## Versions
* [v0.1pre1](v0.1pre1) * [v0.1pre1](v0.1pre1)
@@ -9,100 +26,10 @@
* [v0.1pre4](v0.1pre4) * [v0.1pre4](v0.1pre4)
* [v0.1pre5](v0.1pre5) * [v0.1pre5](v0.1pre5)
## Spec
MicroW8 loads WebAssembly modules with a maximum size of 256kb. You module needs to export
a function `fn upd()` which will be called once per frame.
After calling `upd` MicroW8 will display the 320x240 8bpp framebuffer located
at offset 120 in memory with the 32bpp palette located at 0x13000.
The memory has to be imported as `"env" "memory"` and has a maximum size of 256kb (4 pages).
Other imports provided by the platform, also all in module `env`:
* `fn acos(f32) -> f32`
* `fn asin(f32) -> f32`
* `fn atan(f32) -> f32`
* `fn atan2(f32, f32) -> f32`
* `fn cos(f32) -> f32`
* `fn exp(f32, f32) -> f32`
* `fn log(f32) -> f32`
* `fn sin(f32) -> f32`
* `fn tan(f32) -> f32`
* `fn pow(f32) -> f32`
* `fn fmod(f32, f32) -> f32`
* `fn random() -> i32`
* `fn randomf() -> f32`
* `fn randomSeed(i32)`
* `fn cls(color: i32)`
* `fn setPixel(x: i32, y: i32, color: i32)`
* `fn getPixel(x: i32, y: i32) -> i32`
* `fn hline(left: i32, right: i32, y: i32, color: i32)`
* `fn rectangle(x1: f32, y1: f32, x2: f32, y2: f32, color: i32)`
* `fn circle(cx: f32, cy: f32, radius: f32, color: i32)`
* `fn rectangle_outline(x1: f32, y1: f32, x2: f32, y2: f32, color: i32)`
* `fn circle_outline(cx: f32, cy: f32, radius: f32, color: i32)`
* `fn line(x1: f32, y1: f32, x2: f32, y2: f32, color: i32)`
* `fn time() -> f32`
* `fn isButtonPressed(btn: i32) -> i32`
* `fn isButtonTriggered(btn: i32) -> i32`
* `fn printChar(char: i32)`
* `fn printString(ptr: i32)`
* `fn printInt(num: i32)`
* `fn setTextColor(color: i32)`
* `fn setBackgroundColor(color: i32)`
* `fn setCursorPosition(x: i32, y: i32)`
### Memory map
```
00000-00040: user memory
00040-00044: time since module start in ms
00044-0004c: gamepad state
0004c-00078: reserved
00078-12c78: frame buffer
12c78-13000: reserved
13000-13400: palette
13400-13c00: font
13c00-14000: reserved
14000-40000: user memory
```
## `.uw8` format
The first byte of the file specifies the format version:
#### Format version `00`:
This file is simply a standard WebAssembly module
#### Format version `01`:
The rest of this file is the same as a WebAssembly
module with the 8 byte header removed. This module
can leave out sections which are then taken from
a base module provided by MicroW8.
You can generate this base module yourself using
`uw8-tool`. As a quick summary, it provides all function
types with up to 5 parameters (i32 or f32) where the
`f32` parameters always preceed the `i32` parameters.
Then it includes all imports that MicroW8 provides,
a function section with a single function of type
`() -> void` and an export section that exports
the first function in the file under the name `upd`.
#### Format version `02`:
Same as version `01` except everything after the first byte is compressed
using a [custom LZ compression scheme](https://github.com/exoticorn/upkr).
## Tooling ## Tooling
WARNING: severely out of date. The `uw8` binary includes a lot of the tool features below.
The [Web Assembly Binary Toolkit](https://github.com/WebAssembly/wabt) includes The [Web Assembly Binary Toolkit](https://github.com/WebAssembly/wabt) includes
a few useful tools, eg. `wat2wasm` to compile the WebAssemby text format to binary a few useful tools, eg. `wat2wasm` to compile the WebAssemby text format to binary
wasm and `wasm2wat` to disassemble wasm binaries. wasm and `wasm2wat` to disassemble wasm binaries.
@@ -117,13 +44,3 @@ WebAssembly module that are provided by the MicroW8 platform.
Writing code for MicroW8 in C, Rust, AssemblyScript etc. should absolutely Writing code for MicroW8 in C, Rust, AssemblyScript etc. should absolutely
possible but no examples are provided, yet. possible but no examples are provided, yet.
## Examples
* [Fireworks](v0.1pre5#AgwvgP+M59snqjl4CMKw5sqm1Zw9yJCbSviMjeLUdHus2a3yl/a99+uiBeqZgP/2jqSjrLjRk73COMM6OSLpsxK8ugT1kuk/q4hQUqqPpGozHoa0laulzGGcahzdfdJsYaK1sIdeIYS9M5PnJx/Wk9H+PvWEPy2Zvv7I6IW7Fg==) (127 bytes): Some fireworks to welcome 2022.
* [Skip Ahead](v0.1pre5#AgyfpZ80wkW28kiUZ9VIK4v+RPnVxqjK1dz2BcDoNyQPsS2g4OgEzkTe6jyoAfFOmqKrS8SM2aRljBal9mjNn8i4fP9eBK+RehQKxxGtJa9FqftvqEnh3ez1YaYxqj7jgTdzJ/WAYVmKMovBT1myrX3FamqKSOgMsNedLhVTLAhQup3sNcYEjGNo8b0HZ5+AgMgCwYRGCe//XQOMAaAAzqDILgmpEZ/43RKHcQpHEQwbURfNQJpadJe2sz3q5FlQnTGXQ9oSMokidhlC+aR/IpNHieuBGLhFZ2GfnwVQ0geBbQpTPA==) (229 bytes): A port of my [TIC-80 256byte game](http://tic80.com/play?cart=1735) from LoveByte'21
* [OhNoAnotherTunnel](v0.1pre4#Ag95rdCB5Ww5NofyQaKF4P1mrNRso4azgiem4hK99Gh8OMzSpFq3NsNDo7O7pqln10D11l9uXr/ritw7OEzKwbEfCdvaRnS2Z0Kz0iDEZt/gIqOdvFmxsL1MjPQ4XInPbUJpQUonhQq29oP2omFabnQxn0bzoK7mZjcwc5GetHG+hGajkJcRr8oOnjfCol8RD+ha33GYtPnut+GLe4ktzf5UxZwGs6oT9qqC61lRDakN) (177 bytes): A port of my [entry](http://tic80.com/play?cart=1871) in the Outline'21 bytebattle final
* [Technotunnel](v0.1pre4#AqL8HeK1M9dn2nWNIF5vaq/Vh64pMt5nJIFoFKpBMPUsGtDtpqjo1JbT9LzPhAxCqJ7Yh4TA6oTGd4xhLowf+cWZMY73+7AZmfXJJsBi4cej/hH+4wlAgxFIrnOYnr/18IpnZbsHf0eGm1BhahX74+cVR0TRmNQmYC7GhCNS3mv/3MJn74lCj7t28aBJPjEZhP9fGXdG2u5Egh/Tjdg=) (158 bytes): A port of my [entry](https://tic80.com/play?cart=1873) in the Outline'21 bytebattle quater final
* [Font & Palette](v0.1pre4#AgKaeeOuwg5gCKvFIeiitEwMpUI2rymEcu+DDB1vMu9uBoufvUxIr4Y5p4Jj2ukoNO4PE7QS5cN1ZyDMCRfSzYIGZxKlN2J6NKEWK7KVPk9wVUgn1Ip+hsMinWgEO8ETKfPuHoIa4kjI+ULFOMad7vd3rt/lh1Vy9w+R2MXG/7T61d3c7C6KY+eQNS0eW3ys4iU8R6SycuWZuuZ2Sg3Qxp826s+Kt+2qBojpzNOSoyFqyrVyYMTKEkSl0BZOj59Cs1hPm5bq0F1MmVhGAzMhW9V4YeAe): Just a simple viewer for the default font and palette.
* [Technotunnel B/W](v0.1pre2#AQrDAQHAAQIBfwp9A0AgAUEAsiABQcACb7JDmhkgQ5MiBCAEIASUIAFBwAJtQfgAa7IiBSAFlJKRIgaVIgcgByAAskHQD7KVIgIQAEPNzEw/lCIDlCAHIAeUIAOUIAOUQQGykiADIAOUk5GSIgiUIAOTQQqylCACkiIJqCAFIAaVIAiUQQqylCACkiIKqHMgCEEyspQgBpUiCyACkkEUspSocUEFcbJBArIgC5OUQRaylJeoOgB4IAFBAWoiAUGA2ARIDQALCw==) (199 bytes uncompressed): A port of my [entry](https://tic80.com/play?cart=1873) in the Outline'21 bytebattle quater final (older MicroW8 version with monochrome palette)
* [XorScroll](v0.1pre2#AQovAS0BAX8DQCABIAFBwAJvIABBCm1qIAFBwAJtczoAeCABQQFqIgFBgNgESA0ACws=) (50 bytes uncompressed): A simple scrolling XOR pattern. Fun fact: This is the pre-loaded effect when entering a bytebattle.
* [CircleWorm](v0.1pre2#AQp7AXkCAX8CfUEgEA0DQCABskEEspUiAkECspUgALJBiCeylSIDQQWylJIQAEEBspJBoAGylCACQQOylSADQQSylJIQAEEBspJB+ACylCADQRGylCACQQKylJIQAEECspJBELKUIAFBAmxBP2oQEiABQQFqIgFBP0gNAAsL) (126 bytes uncompressed): Just a test for the circle fill function.

225
site/content/docs.md Normal file
View File

@@ -0,0 +1,225 @@
+++
title = "Docs"
description = "Docs"
+++
# Overview
MicroW8 loads WebAssembly modules with a maximum size of 256kb. You module needs to export
a function `fn upd()` which will be called once per frame.
After calling `upd` MicroW8 will display the 320x240 8bpp framebuffer located
at offset 120 in memory with the 32bpp palette located at 0x13000.
The memory has to be imported as `env` `memory` and has a maximum size of 256kb (4 pages).
# Memory map
```
00000-00040: user memory
00040-00044: time since module start in ms
00044-0004c: gamepad state
0004c-00078: reserved
00078-12c78: frame buffer
12c78-13000: reserved
13000-13400: palette
13400-13c00: font
13c00-14000: reserved
14000-40000: user memory
```
# API
All API functions are found in the `env` module.
## Math
These all do what you'd expect them to. All angles are in radians.
### fn asin(x: f32) -> f32
Returns the arcsine of `x`.
### fn acos(x: f32) -> f32
Returns the arccosine of `x`.
### fn atan(f32) -> f32
Returns the arctangent of `x`.
### fn atan2(y: f32, y: f32) -> f32
Returns the angle between the point `(x, y)` and the positive x-axis.
### fn sin(angle: f32) -> f32
Returns the sine of `angle`.
### fn tan(angle: f32) -> f32
Returns the tangent of `angle`.
### fn cos(angle: f32) -> f32
Returns the cosine of `angle`.
### fn exp(x: f32) -> f32
Returns `e^x`.
### fn log(x: f32) -> f32
Returns the natural logarithmus of `x`. Ie. `e^log(x) == x`.
### fn pow(x: f32, y: f32) -> f32
Returns `x^y`.
### fn fmod(x: f32, y: f32) -> f32
Returns `x` modulo `y`, ie. `x - floor(x / y) * y`. This means the sign of the result of `fmod` is the same as `y`.
## Random
MicroW8 provides a pretty good PRNG, namely xorshift64*. It is initialized to a constant seed at each startup, so if you
want to vary the random sequence you'll need to provide a seed yourself.
### fn random() -> i32
Returns a (pseudo-)random 32bit integer.
### fn randomf() -> f32
Returns a (pseudo-)random float equally distributed in `[0,1)`.
### fn randomSeed(seed: i32)
Seeds the PRNG with the given seed. The seed function is reasonably strong so that you can use
```
randomSeed(index);
random()
```
as a cheap random-access PRNG (aka noise function).
## Graphics
The drawing functions are sub-pixel accurate where applicable (line, circle). Pixel centers lie halfway between integer
coordinates. Ie. the top-left pixel covers the area `0,0 - 1,1`, with `0.5,0.5` being the pixel center.
### fn cls(color: i32)
Clears the screen to the given color index. Also sets the text cursor to `0, 0` and disables graphical text mode.
### fn setPixel(x: i32, y: i32, color: i32)
Sets the pixel at `x, y` to the given color index.
### fn getPixel(x: i32, y: i32) -> i32
Returns the color index at `x, y`. Returns `0` if the given coordinates are outside the screen.
### fn hline(left: i32, right: i32, y: i32, color: i32)
Fills the horizontal line `[left, right), y` with the given color index.
### fn rectangle(x: f32, y: f32, w: f32, h: f32, color: i32)
Fills the rectangle `x,y - x+w,y+h` with the given color index.
(Sets all pixels where the pixel center lies inside the rectangle.)
### fn circle(cx: f32, cy: f32, radius: f32, color: i32)
Fills the circle at `cx, cy` and with `radius` with the given color index.
(Sets all pixels where the pixel center lies inside the circle.)
### fn rectangle_outline(x: f32, y: f32, w: f32, h: f32, color: i32)
Draws a one pixel outline on the inside of the given rectangle.
(Draws the outermost pixels that are still inside the rectangle area.)
### fn circle_outline(cx: f32, cy: f32, radius: f32, color: i32)
Draws a one pixel outline on the inside of the given circle.
(Draws the outermost pixels that are still inside the circle area.)
### fn line(x1: f32, y1: f32, x2: f32, y2: f32, color: i32)
Draws a line from `x1,y1` to `x2,y2` in the given color index.
## Input
MicroW8 provides input from a gamepad with one D-Pad and 4 buttons, or a keyboard emulation thereof.
The buttons are numbered
| Button | Keyboard | Index |
| ------ | ----------- | ----- |
| Up | Arrow-Up | 0 |
| Down | Arrow-Down | 1 |
| Left | Arrow-Left | 2 |
| Right | Arrow-Right | 3 |
| A | Z | 4 |
| B | X | 5 |
| X | A | 6 |
| Y | S | 7 |
In addition to using the API functions below, the gamepad state can also be read as a bitfield of
pressed buttons at address 0x44. 0x48 holds the buttons that were pressed last frame.
### fn isButtonPressed(btn: i32) -> i32
Returns whether the buttons with the given index is pressed this frame.
### fn isButtonTriggered(btn: i32) -> i32
Returns whether the given button is newly pressed this frame.
### fn time() -> f32
Returns the time in seconds since the start of the cart.
The integer time in milliseconds can also be read at address 0x40.
## Text output
### fn printChar(char: i32)
### fn printString(ptr: i32)
### fn printInt(num: i32)
### fn setTextColor(color: i32)
### fn setBackgroundColor(color: i32)
### fn setCursorPosition(x: i32, y: i32)
# `.uw8` format
The first byte of the file specifies the format version:
## Format version `00`:
This file is simply a standard WebAssembly module
## Format version `01`:
The rest of this file is the same as a WebAssembly
module with the 8 byte header removed. This module
can leave out sections which are then taken from
a base module provided by MicroW8.
You can generate this base module yourself using
`uw8-tool`. As a quick summary, it provides all function
types with up to 5 parameters (i32 or f32) where the
`f32` parameters always preceed the `i32` parameters.
Then it includes all imports that MicroW8 provides,
a function section with a single function of type
`() -> void` and an export section that exports
the first function in the file under the name `upd`.
## Format version `02`:
Same as version `01` except everything after the first byte is compressed
using a [custom LZ compression scheme](https://github.com/exoticorn/upkr).

6
site/templates/index.html
View File

@@ -2,12 +2,16 @@
{% block hero %} {% block hero %}
<div> <div>
<section> <section>
<h1 class="text-center heading-text">A WebAssembly based sizecoding platform</h1> <h1 class="text-center heading-text">A WebAssembly based fantasy console</h1>
</section> </section>
<a href="v0.1pre5"> <a href="v0.1pre5">
<div class="demonstration-gif" style="width:640px;height:512px;background-color:black"></div> <div class="demonstration-gif" style="width:640px;height:512px;background-color:black"></div>
</a> </a>
</div> </div>
<div class="explore-more text"
onclick="document.getElementById('features').scrollIntoView({behavior: 'smooth'})">
Explore More ⇩
</div>
{% endblock hero %} {% endblock hero %}
{% block footer %} {% block footer %}

6
src/main.rs
View File

@@ -17,10 +17,16 @@ fn main() -> Result<()> {
let mut args = Arguments::from_env(); let mut args = Arguments::from_env();
match args.subcommand()?.as_ref().map(|s| s.as_str()) { match args.subcommand()?.as_ref().map(|s| s.as_str()) {
Some("version") => {
println!("{}", env!("CARGO_PKG_VERSION"));
Ok(())
}
Some("run") => run(args), Some("run") => run(args),
Some("pack") => pack(args), Some("pack") => pack(args),
Some("filter-exports") => filter_exports(args), Some("filter-exports") => filter_exports(args),
Some("help") | None => { Some("help") | None => {
println!("uw8 {}", env!("CARGO_PKG_VERSION"));
println!();
println!("Usage:"); println!("Usage:");
println!(" uw8 run [-w/--watch] [-p/--pack] [-u/--uncompressed] [-l/--level] [-o/--output <out-file>] <file>"); println!(" uw8 run [-w/--watch] [-p/--pack] [-u/--uncompressed] [-l/--level] [-o/--output <out-file>] <file>");
println!(" uw8 pack [-u/--uncompressed] [-l/--level] <in-file> <out-file>"); println!(" uw8 pack [-u/--uncompressed] [-l/--level] <in-file> <out-file>");