gb-image-decoder 1.3.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,82 +1,104 @@
1
1
  # GameBoy-Tile format Image Decoders
2
2
 
3
- This package renders GameBoy-encoded images to a canvas element.
3
+ This package renders GameBoy-encoded images.
4
4
 
5
- You may need the [gbp-decode package](https://npmjs.com/gbp-decode) to decode various sources.
5
+ You may use the [gbp-decode package](https://npmjs.com/gbp-decode) to decode various sources.
6
6
  Or you may want to use the [arduino-gameboy-printer-emulator](https://github.com/mofosyne/arduino-gameboy-printer-emulator).
7
7
  There are a lot more similar projects for aquiring raw tile data.
8
8
 
9
9
  ## Usage
10
- Import within your Project
11
- ```typescript
12
- import { RGBNDecoder, Decoder, RGBNTiles } from 'gb-image-decoder';
13
- ```
14
10
 
15
- Have a canvas element inside your DOM
11
+ ### Browser
12
+ #### Monochrome images
16
13
  ```typescript
17
- const myCanvas: HTMLCanvasElement = document.createElement('canvas');
18
- ```
19
-
20
- ### For monochrome images:
14
+ import { getMonochromeImageUrl, ExportFrameMode } from 'gb-image-decoder';
21
15
 
22
- Have a set of tiles (each string represents a 8x8 tile)
23
- ```typescript
24
- // For classic monochrome images:
25
- const myTiles: string[] = [ // need 360 of these for a 160x144 image
16
+ const tiles: string[] = [ // need 360 of these for a 160x144 image
26
17
  '7D FF 0A FF 7D FF FF FF 5F FF BB FF 5D FF FF FF', '75 FF A2 FF 44 FF FF FF 5D FF FF FF FF FF FF FF', '55 FF 1F FF 57 FF FF FF 7D FF FF FF FF FF FF FF', '77 FF FD FF 57 FF FF FF 75 FF FF FF DF FF FF FF',
27
18
  ];
28
- ```
29
-
30
- Have a palette for your monochrome image
31
- ```typescript
32
19
  const monoPalette = ['#ffffff', '#aaaaaa', '#555555', '#000000'];
33
- ```
34
20
 
35
- Initialize the decoder:
36
- ```typescript
37
- const decoder = new Decoder();
38
- decoder.update({
39
- canvas: myCanvas,
40
- tiles: myTiles,
41
- palette: monoPalette,
42
- framePalette: monoPalette,
43
- lockFrame: false,
44
- });
21
+ const imageSrc = await getMonochromeImageUrl({
22
+ imagePalette: monoPalette,
23
+ tiles,
24
+
25
+ // Optional parameters (with it's defaults):
26
+ // framePalette: monoPalette,
27
+ // imageStartLine: 2,
28
+ // tilesPerLine: 20,
29
+ // scaleFactor: 1,
30
+ // handleExportFrame: ExportFrameMode.FRAMEMODE_KEEP,
31
+ })
45
32
  ```
46
33
 
47
- ### For RGBN images:
48
- RGB(N) Images can contain any of the channels. All channels are optional, but the r,g,b channels are recommended.
49
-
50
- Your image needs a set of RGBN tiles:
34
+ #### RGB(N) images
35
+ `getRGBNImageUrl` provides a convenience function to combine separate monochrome tile sets into one colored image.
36
+ the `RGBNTiles` type contains the four possible channels (`r`, `g`, `b`, `n`)
37
+ The optional neutral layer will be overlayed on the previously combined rgb image.
51
38
  ```typescript
52
- // For RGBN images
53
- const myTilesRGBN: RGBNTiles = { // need 360 of each for a 160x144 image
39
+ import { getRGBNImageUrl, ExportFrameMode, RGBNTiles, RGBNPalette, defaultRGBNPalette } from 'gb-image-decoder';
40
+
41
+ const tiles: RGBNTiles = {
54
42
  r: ['7D FF 0A FF 7D FF FF FF 5F FF BB FF 5D FF FF FF', '75 FF A2 FF 44 FF FF FF 5D FF FF FF FF FF FF FF', '55 FF 1F FF 57 FF FF FF 7D FF FF FF FF FF FF FF', '77 FF FD FF 57 FF FF FF 75 FF FF FF DF FF FF FF'],
55
43
  g: ['7F FF BF FF FF FF FF FF DF FF FF FF FF FF FF FF', 'A2 D5 FC C3 4C D3 FE C1 D8 E4 ED F2 FF F1 DB FC', 'EA 55 83 FC 48 F5 07 F8 A4 53 A8 07 A3 5C FE 01', 'FF 3F FF 3F FF 3F 7F BF FF 3F FF 7F 7D FF FF FF'],
56
44
  b: ['F7 FF A3 FF FF FF FF FF FF FF FF FF FF FF FF FF', '0A F5 80 FF 40 FF F1 FE FB FD F0 FF 52 FD E1 FE', '88 77 40 BF 2A D5 18 EF 88 77 04 FB AA 55 17 E8', 'A0 5F 51 AE AA 55 54 AB AA 55 05 FA AA 55 67 98'],
57
45
  // neutral image is optional
58
46
  };
47
+
48
+ const imageSrc = await getRGBNImageUrl({
49
+ palette: defaultRGBNPalette,
50
+ tiles,
51
+
52
+ // Optional parameters (with it's defaults):
53
+ // imageStartLine: 2,
54
+ // tilesPerLine: 20,
55
+ // scaleFactor: 1,
56
+ // handleExportFrame: ExportFrameMode.FRAMEMODE_KEEP,
57
+ })
59
58
  ```
60
59
 
61
- For RGBN there is a default blend palette available:
60
+ ### Nodejs
61
+ Within a node environment, `getMonochromeImageUrl` and `getRGBNImageUrl` cannot be called, as they rely on the use of `URL.createObjectURL(blob)`.
62
+
63
+ Instead the internally used functions need to be called. All parameters are mandatory.
64
+ The resulting data and dimensions can be used to create an image e.g. by using the [canvas package](https://www.npmjs.com/package/canvas)
65
+
66
+ #### Monochrome images
62
67
  ```typescript
63
- import { defaultPalette as rgbnPalette } from 'gb-image-decoder';
68
+ import { getRawMonochromeImageData, FullMonochromeImageCreationParams, ExportFrameMode } from 'gb-image-decoder';
69
+
70
+ const monoPalette = ['#ffffff', '#aaaaaa', '#555555', '#000000'];
71
+
72
+ const fullParams: FullMonochromeImageCreationParams = {
73
+ framePalette: monoPalette,
74
+ imagePalette: monoPalette,
75
+ tiles, // as in browser example
76
+ imageStartLine: 2,
77
+ tilesPerLine: 20,
78
+ scaleFactor: 1,
79
+ handleExportFrame: ExportFrameMode.FRAMEMODE_KEEP,
80
+ };
81
+
82
+ const { data, dimensions } = getRawMonochromeImageData(fullParams);
64
83
  ```
65
84
 
66
- Initialize the decoder:
85
+ #### RGB(N) images
67
86
  ```typescript
68
- const decoder = new RGBNDecoder();
69
- decoder.update({
70
- canvas: myCanvas,
71
- tiles: myTilesRGBN,
72
- palette: rgbnPalette,
73
- lockFrame: false,
74
- });
75
- ```
87
+ import { getRawRGBNImageData, FullRGBNImageCreationParams, defaultRGBNPalette, ExportFrameMode } from 'gb-image-decoder';
88
+
89
+ const monoPalette = ['#ffffff', '#aaaaaa', '#555555', '#000000'];
76
90
 
77
- ## ToDos
78
- * improve docs
79
- * tests
91
+ const fullParams: FullRGBNImageCreationParams = {
92
+ palette: defaultRGBNPalette,
93
+ tiles, // as in browser example
94
+ imageStartLine: 2,
95
+ tilesPerLine: 20,
96
+ scaleFactor: 1,
97
+ handleExportFrame: ExportFrameMode.FRAMEMODE_KEEP,
98
+ };
99
+
100
+ const { data, dimensions } = getRawRGBNImageData(fullParams);
101
+ ```
80
102
 
81
103
  ## License: MIT
82
104
  [LICENSE](./LICENSE)