https://github.com/herrzatacke/gbp-decode
A Set of functions to decode gameboy printer code
https://github.com/herrzatacke/gbp-decode
Last synced: about 2 months ago
JSON representation
A Set of functions to decode gameboy printer code
- Host: GitHub
- URL: https://github.com/herrzatacke/gbp-decode
- Owner: HerrZatacke
- Created: 2020-08-13T22:23:08.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2024-05-16T19:59:34.000Z (about 1 year ago)
- Last Synced: 2024-09-20T02:07:07.157Z (8 months ago)
- Language: TypeScript
- Size: 147 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# gbp-decode
A set of functions to decode gameboy printer code generated by [mofosyne's arduino gameboy printer emulator](https://github.com/mofosyne/arduino-gameboy-printer-emulator)
## Install
Install this module in your existing js application with `npm install --save gbp-decode`
## Overwiew
This package exports these functions which are designed to be used in a promise chain:
* [`toByteArray`](#tobytearray)
* [`parsePackets`](#parsepackets)
* [`parseReducedPackets`](#parsereducedpackets)
* [`getImageDataStream`](#getimagedatastream)
* [`decompressDataStream`](#decompressdatastream)
* [`decodePrintCommands`](#decodeprintcommands)
* [`harmonizePalettes`](#harmonizepalettes)
* [`transformToClassic`](#transformtoclassic)
It also exports the helpers
* [`unpack`](#unpack)
* [`parsePaletteByte`](#parsepalettebyte)
* [`harmonizePalette`](#harmonizepalette)
* [`completeFrame`](#completeframe)
* [`logPackets`](#logpackets)
An example of how to read a file and transform it can be found here [`src/index.js`](src/index.js)
### [`toByteArray`](src/toByteArray.js)
takes a string read from a file (or provided by some other ways of input) and strips all comments (lines starting with `//``).
> Note: To get from the 'readable' filedata to an actual bytestream check [`src/loadBytes.js`](src/loadBytes.js).
> The part reading the file (using nodjs's `fs` object) is not being exported in the node module, as this could collide with usage in webpack based projects
It returns an array of bytes ([here: Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)) which should be looking like this:
``` javascript
[136, 51, 1, 0, 0, 0, 1, 0, 129, 0, 136, 51, 4, 0, ...]
```
> Note the first two entries are `136` and `51` which are the two starting indicators of a printer packet (`0x88` and `0x33`)
### [`parsePackets`](src/parsePackets.js) / [`parseReducedPackets`](src/parseReducedPackets.js)
accepts the result of [`toByteArray`](#tobytearray).
It returns an array of actual data packets which can be separately parsed.
Each packet is shaped like this:
``` javascript
{
command: 1,
data: [],
hasCompression: 0,
dataLength: 0,
checksum: 1
},
```
> `parseReducedPackets` accepts an incoming datastream which has been shortened by the [pico-gb-printer](https://github.com/untoxa/pico-gb-printer).
### [`getImageDataStream`](src/getImageDataStream.js)
accepts the result of [`parsePackets`](#parsepackets)
It returns an array of packets which are _print_ `0x2` or _data_ `0x4` packets. Other packets (_init_ `0x1` and _status_ `0xf`) are removed.
### [`decompressDataStream`](src/decompressDataStream.js)
accepts the result of [`getImageDataStream`](#getimagedatastream)
In all _data_ `0x4` packets it checks for the `hasCompression` flag and if present replaces the compressed content of `data` with the value returned by [`unpack`](#unpack).
It returns an array of packets in which compressed packets are now uncompressed.
### [`decodePrintCommands`](src/decodePrintCommands.js)
accepts the result of [`decompressDataStream`](#decompressdatastream)
In all _print_ `0x2` packets the `data` property is transformed to hold the parsed information of the print command.
The `palette` byte is passed to [`parsePaletteByte`](#parsepalettebyte) to get the parsed palette info.
``` javascript
{
"margins": 19, // original value of command (upper and lower nibble)
"marginUpper": 1, // upper nibble of margin
"marginLower": 3, // lower nibble of margin
"palette": 228, // original palette value
"paletteData": [3, 2, 1, 0] // parsed palette data
}
```
It returns an array of packets in which the _print_ packets hold more information
### [`harmonizePalettes`](src/harmonizePalettes.js)
accepts the result of [`decodePrintCommands`](#decodeprintcommands)
Applies palette harmonization to all packets by calling [`harmonizePalette`](#harmonizepalette) on each _data_ packet with the `palette` value of the next following _print_ packet
It returns an array in which all image data follows the 'default' palette.
### [`transformToClassic`](src/transformToClassic.js)
accepts the result of [`harmonizePalettes`](#harmonizepalettes)
It returns an array of array representing an image where each line can be handled as a default gameboy tile:
``` javascript
[
[
'ff ff ff ff fe ff fe fe fe fe fe fe fe fe fe fe',
'ff ff ff ff 1c ff 3e 1c 0c 1c 04 0c 0c 04 24 04',
...
],
...
]
```
### [`unpack`](src/unpack.js)
decompresses the simple RLE of a compressed data packet as [documented here](https://shonumi.github.io/articles/art2.html)
### [`parsePaletteByte`](src/parsePaletteByte.js)
splits the one palette byte into 4 2-bit values representing the 4 available grey scales.
### [`harmonizePalette`](src/harmonizePalette.js)
returnes image data of a packet so that the 'default' palette is used.
Parsing/applying palette data is [documented here in § 5.7](https://www.mikrocontroller.net/attachment/34801/gb-printer.txt)
### [`completeFrame`](src/completeFrame.js)
adds two rows of tiles to the start and end of an (classic format) image if there are exactly 280 lines to begin with.
This restores an image to common size which has been printed with the top and bootom part of the frame missing.
### [`logPackets`](src/logPackets.js)
logs all received packets
## Resources used:
* https://shonumi.github.io/articles/art2.html
* https://www.mikrocontroller.net/attachment/34801/gb-printer.txt