EGAGRAPH chunk shifters (January 31 2025 update)
================================================

NOTE: Use this UNDER YOUR OWN RISK! In particular, IT IS POSSIBLE
THE APP *WILL* CRASH AND *YOU WILL LOSE ALL OF YOUR WORK*, say when
you're shifting a plane far enough such that the shifter app is
trying to read data out of the EGAGRAPH file's bounds.

Licensing and code re-use
-------------------------

These programs use modifications of code from TED5 (e.g., HuffExpand).
As in the case of the TED5 source distribution, this codebase
is provided "AS IS" with no warranty.

A simple modification of BMP256.C/BMP256.H from ModId is used,
renamed bmp256_mod.* here. The former was originally a modification
of BMP16.C on its own. These files are zlib-licensed.
See the specific files' headers for details.

A few more code references in use are the pictabletype and spritetabletype
struct types, borrowed off ID_VW.H from Keen Dreams / Catacomb 3-D.
(They're also found in ID_VH.H from the Wolfenstein 3D sources.)

January 31 2025 update
----------------------

This is an update to the last August 2018 revision, adapting the included
programs for compatibility with SDL3, while still retaining SDL2 compatibility.
The script build_usingsdl2.h was used for making SDL2-enabled Linux builds,
while SDL3-enabled builds were made with the modified build.sh.

The timing of the update was related to K1n9_Duk3's improvements from
December 2024 to the 2017-era recovery work mentioned below back in 2018.
Basically, K1n9_Duk3 further improved upon the preceding recovery
of corrupted graphics in the relevant Bio Menace prototype.
In particular, the newly reconstructed EGAGRAPH.BH1 matched
the original in size and was compatible with the original
EGADICT.BH1 and EGAHEAD.BH1 files from 1992 altogether.

While the programs provided here were not used for K1n9_Duk3's efforts,
I still thought of updating them for SDL3, given its
first official release from Janaury 2025.

What was the original purpose of this
-------------------------------------

Permission to release an old prototype build of Bio Menace, originally
titled Bio Hazard, was secured. However, almost all graphics seemed
to be quite corrupted. Thus, recovery work was done on the
graphics, before the eventual release on August of 2018.

ModId was used in order to export the graphics, at least initially.
It surely assisted to know that this prototype, originally planned
to be BH's first episode i.e., Bio Hazard 1 (BH1), eventually morphed
into Bio Menace's 2nd episode, also known as Bio Menace 2 (BM2).

After taking care of the 16x16 tiles (see below for details), the first
chunk shifter, originally just an EGAGRAPH sprite viewer, was written.
A bit later, each of the sprite's separate EGA planes could be displayed,
along with the sprite itself. Originally, you could not shift (move) the
planes around, but this was added after a short while. You could further
export the shifted planes as separate BMP files.

Eventually, modifications to the sprite shifter were made,
covering pictures and 8x8 tiles, in addition to sprites.
ModId was used for importing the graphics and creating
a new EGAHEAD.BH1 + EGAGRAPH.BH1 pair, while
re-using the original EGADICT.BH1 file.

More details are given further below in this file.

General usage notes
-------------------

During the first run, a new EGAGRAPH chunk offsets file shall
be created. This may take a little while. For sprites, this
file is named egagraph_sprite_shifter_offsets.txt.
Similar names are used for the other chunks.

On quit, changes of observed offsets to compressed chunks are saved
to this file. Next time the same shifter app is run, it shall load
the offsets from the same file.

To quit the app, close the window.

List of keys
------------

Left/Right arrow: Scroll through the chunks,
changing to the preceding/following chunk.

Page up/down: Quickly scroll through the chunks with 30 chunks jumps.

Q/A: Shift all planes' offsets forward/backwards. Here, shifting "forward"
means the EGAGRAPH offset from which compressed data is read is increased,
while "backwards" implies the opposite.

W/S (masked graphics only): Shift just the bitmap planes, not the mask plane.

E/D: Shift plane no. 0. Note that for masked graphics, this is the mask.

R/F: Shift plane no. 1.

T/G: Shift plane no. 2.

Y/H: Shift plane no. 3.

U/J (masked graphics only): Shift plane no. 4, the last *bitmap* plane.

P: Change one of the displayed colors from EGA brown to dark yellow,
and vice-versa. Has NO effect on the contents of exported bitmaps.

/: Export shifted chunks as bitmaps.

Additional key, usable with sprites and unmasked chunks *only*
--------------------------------------------------------------

Shift key: Use this to control how far are the planes shifted,
say with the Q and A keys (see above). While the key is pressed,
planes are shifted by 32 bits of compressed data at a time.
Otherwise, they're shifted by 1 bit (the default).

Don't ask why isn't this available for masked pictures or 8x8 tiles.
This is just how things turned out to be while
originally using the shifters.

More details on restoring the BH prototype's data
-------------------------------------------------

Checking the almost fully-corrupted 16x16 masked tileset, two specific
familiar tiles were identified. This gave the great hint that 7725 bytes
shall be removed from some offset in EGAGRAPH.BH1, which turned out to
be 0x16308.

Virtually all 16x16 tiles were rescued in this way.
They matched the ones from BM2 for most. A few missing or
partially corrupted tiles were basically copied from BM2.

[Side-note: Originally, 7721 bytes had to be removed, rather than 7725.
However, this turned out to come from a misconfiguration of the
.def file for ModId. While seemingly useless, an empty range
of 32x32 tiles had to be added to the .def.]

As stated above, the sprites viewer was written, later to turn into
a sprites shifter. It could let you shift either each of some sprite's
5 planes separately, all 5 EGA planes at once, or just the 4 non-mask
bitmap planes. It would further save the offset used for shifting.
That is, if you shifted some sprite's plane, the shifter
was shut down as expected and you then restarted it, then
the same plane would be shifted in the exact same manner again.

As for the sprite graphics themselves, eventually most of them were simply
copied from BM2 as-is. Manual edits were required for most player sprites,
as well as a few more sprites.

Various hints were used in order to have good guesses for recreating
these player sprites and other graphics. For one very great example, it
was conjectured that the players' pants were originally darker, compared
to the eventual game's release. This came not just from differing
pieces of partially corrupted graphics in sprites' planes, but
also from one occurrence of a copy of one player sprite in
the partially corrupted "This is -NOT- Shareware" picture.

Using a modification of the sprites shifter for handling masked 8x8 tiles,
it turned out they were exactly the same as in BM2. After doing the same
for unmasked 8x8 tiles, it was discovered that no such tile was
edited or removed in-between the BH1 proto. and BM2.
New tiles were added, but that's it.

A portion of the "This is -NOT- Shareware" picture had to be re-filled,
guessing the missing contents using misc. graphical data. Other unmasked
pictures required no change at all. The only masked picture, the
checkerboard pattern used in the menu, was simply imported from BM2.
It's more-or-less the same in the earlier Keen 4-6 games, too.

- NY00123
