gbp-decode

A set of functions to decode gameboy printer code generated by mofosyne's 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
• parsePackets
• parseReducedPackets
• getImageDataStream
• decompressDataStream
• decodePrintCommands
• harmonizePalettes
• transformToClassic

It also exports the helpers

• unpack
• parsePaletteByte
• harmonizePalette
• completeFrame
• logPackets

An example of how to read a file and transform it can be found here src/index.js

toByteArray

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.
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) which should be looking like this:

[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 / parseReducedPackets

accepts the result of toByteArray.
It returns an array of actual data packets which can be separately parsed.
Each packet is shaped like this:

{
  command: 1,
  data: [],
  hasCompression: 0,
  dataLength: 0,
  checksum: 1
},

parseReducedPackets accepts an incoming datastream which has been shortened by the pico-gb-printer.

getImageDataStream

accepts the result of 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

accepts the result of 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.
It returns an array of packets in which compressed packets are now uncompressed.

decodePrintCommands

accepts the result of 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 to get the parsed palette info.

{
  "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

accepts the result of decodePrintCommands
Applies palette harmonization to all packets by calling 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

accepts the result of harmonizePalettes
It returns an array of array representing an image where each line can be handled as a default gameboy tile:

[
  [
    '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

decompresses the simple RLE of a compressed data packet as documented here

parsePaletteByte

splits the one palette byte into 4 2-bit values representing the 4 available grey scales.

harmonizePalette

returnes image data of a packet so that the 'default' palette is used.
Parsing/applying palette data is documented here in § 5.7

completeFrame

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

logs all received packets

Resources used:

• https://shonumi.github.io/articles/art2.html
• https://www.mikrocontroller.net/attachment/34801/gb-printer.txt