From f2d8fa6cef295b0c36595e51f98fe3486cbf1954 Mon Sep 17 00:00:00 2001
From: crc <crc@noemail.net>
Date: Sun, 3 Feb 2019 04:06:16 +0000
Subject: [PATCH] add retro-embedimage in retro

FossilOrigin-Name: 347e9c4f8b25909358903096f110922fe2d278532037eca4445b52edbd739f91
---
 RELEASE_NOTES.md               |  1 +
 example/retro-embedimage.forth | 85 ++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)
 create mode 100755 example/retro-embedimage.forth

diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index a4120bf..a1a7052 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -105,6 +105,7 @@ June 2019.
 - add paste.forth
 - add Paste_to_Sprunge.forth
 - add retro-extend.forth
+- add retro-embedimage.forth
 - add Save_and_Restore_Stack.forth
 - add share.forth and shared.forth
 - add uuencode.forth
diff --git a/example/retro-embedimage.forth b/example/retro-embedimage.forth
new file mode 100755
index 0000000..f7af470
--- /dev/null
+++ b/example/retro-embedimage.forth
@@ -0,0 +1,85 @@
+#!/usr/bin/env retro
+
+Many of the RETRO interface layers embed a copy of the image
+into the binary. This is done by converting the image into a
+C file that can be included or compiled and linked. The source
+includes a tool, `retro-embedimage`, for this. This implements
+the tool in RETRO.
+
+First up, I need to load the image to a buffer, so I allocate
+space for this now.
+
+~~~
+#65535 #4 * 'IMAGE-SIZE const
+'Image d:create
+  IMAGE-SIZE allot
+~~~
+
+Next is reading in the file. This is slightly complicated by
+the need to pack the individual bytes into the memory cells.
+
+So, a variable to track the open file ID.
+
+~~~
+'FID var
+~~~
+
+Then read in a byte.
+
+~~~
+:read-byte (n-)  @FID file:read #255 and ;
+~~~
+
+Reading in four bytes, I can shift and merge them back into
+a single cell.
+
+~~~
+:read-cell (-n)
+  read-byte    read-byte    read-byte  read-byte
+  #-8 shift +  #-8 shift +  #-8 shift + ;
+~~~
+
+The next step is a word to return the size of the file in
+cells.
+
+~~~
+:size (-n) @FID file:size #4 / ;
+~~~
+
+And then, using the above, read in the data from the file
+to the image buffer.
+
+~~~
+:load-image (s-)
+  file:R file:open !FID
+  &Image size [ read-cell over store n:inc ] times drop
+  @FID file:close ;
+~~~
+
+Read in the file.
+
+~~~
+'ngaImage load-image
+~~~
+
+The final part is to export the image as a C array. To keep
+line length to a reasonible length, I have a counter and add
+a newline after 18 values.
+
+~~~
+'Count var
+:EOL? &Count v:inc @Count #18 eq? [ nl #0 !Count ] if ;
+~~~
+
+The rest is easy. Display the relevant header bits, then
+the cells, then the needed footer.
+
+~~~
+'#include_<stdint.h>                     s:put nl
+'int32\_t_ngaImageCells_=_9139; s:format s:put nl
+'int32\_t_ngaImage[]_=_{        s:format s:put nl
+
+&Image #3 + fetch  [ fetch-next n:put $, c:put EOL? ] times
+
+'}; s:put nl
+~~~