Generic BMP to Atari/Amiga converter v1.0
Released at Buxton Bytes in the UK - March 16, 2025


Table of contents
-----------------

[1] INTRODUCTION
    1.1 Overview
    1.2 What it can export
        1.2a Raw bitplane dumps with or without palette
        1.2b Truecolour data from images
	      1.2c Truecolour data from palettes
        1.2d Raw byte chunky
        1.2e Raw nibble chunky
        1.2f Offsetmap tables

[2] USAGE

[3] COLOUR FORMATS (PALETTE & TRUECOLOUR)
    3.1 Atari ST 9-bit
    3.2 Atari STe/TT 12-bit
    3.3 Atari Falcon 16-bit
    3.4 Atari Falcon 18-bit
    3.5 Amiga OCS/ECS 12-bit
    3.6 Amiga AGA 24-bit

[4] BITPLANE FORMATS
    4.1 Interleaved bitplanes
    4.2 Bitplane fields

[5] FILE EXTENSIONS
    5.1 Bitplane exports
    5.2 Bitplane exports with palette
    5.3 Truecolour and palette exports
    5.4 Byte chunky export
    5.5 Nibble chunky export
    5.6 Ofsmap export

[6] SUPPORT AND CONTACT
    6.1 Credits
    6.2 Source code
    6.3 Support
    6.4 Feature requests
    6.5 Contact


==============================================================================
[1] INTRODUCTION
==============================================================================

[1.1] Overview
--------------
This program was created to help aid myself when making demos. Instead of
making new tools every time for more or less the same task I thought
collecting the most common conversions into one program could save some time.

What the program does is reading uncompressed 8-bit or 24-bit BMP files and
converts the data to fit Atari/Amiga bitplanes, palettes and truecolour
formats.

The software does NOT do any bitplane reduction, dithering, palette
remapping or sorting. It's only feature is to deliver graphics/colour
data to the native Atari/Amiga formats.

Input BMPs known to work are uncomrpessed 8-bit images from GrafX2 and 24-bit
images from Adobe Photoshop. Files saved from other software not tested and
might not work at all.


[1.2] What it can export
------------------------
 [1.2a] Raw bitplane dumps with or without palette
 8-bit BMP files can be converted to raw bitplane dumps (1 to 8 bitplanes)
 with or without palette in Atari word-interleaved or Amiga-style bitplanes.
 The optional palette can be in ST, STe/TT, Falcon 16-bit, Falcon 18-bit,
 Amiga OCS/ECS and Amiga AGA formats.

 [1.2b] Truecolour data from images
 8-bit and 24-bit BMP files can be converted to truecolour data in ST,
 STe/TT, Falcon 16-bit, Falcon 18-bit, Amiga 12-bit and Amiga 24-bit colour
 formats.

 [1.2c] Truecolour data from palettes
 Palettes of 8-bit BMP files can be converted without image conversion into
 ST, STe/TT, Falcon 16-bit, Falcon 18-bit, Amiga 12-bit and Amiga 24-bit
 colour formats. The user can select how many of the palette entries to
 convert (1-256).

 [1.2d] Raw byte chunky
 8-bit BMP files can be stored without header and palette to form a RAW
 chunky pixel output. Good for textures. It will also get rid of eventual
 BMP line padding.

 [1.2e] Raw nibble chunky
 8-bit BMP files that use max 16 colours can be converted to 4-bit nibble
 chunky (RAW chunky data).

 [1.2f] Offsetmap tables
 24-bit files can be stripped of the header and RED component and only
 store the GREEN and BLUE. Good for exporting offset maps from BMP files
 that have been created with an art- or 3D-package. Will also get rid of
 the BMP line padding.


==============================================================================
[2] USAGE
==============================================================================

The program uses standard text output and only operating system calls, so it
should hopefully work from the earliest TOS 1.0 to the latest FreeMiNT with
or without GEM. It's only tested with TOS 2.06 and 4.04 though.

- For TOS 1.x, double-click "genbmp.ttp" and supply filename for a BMP file.
  Then follow the menus to convert the image as desired.

- For TOS 2.x and later (as well as TOS 1 with replacement desktops) simply
  drag a BMP file onto "genbmp.ttp".

- In each menu it's possible to exit the program by pressing [Q].

- The program will exit automatically after a conversion pass is finished.

- The output filename will be the same as input, with a new extension (see
  section [5]).


==============================================================================
[3] COLOUR FORMATS (PALETTE & TRUECOLOUR)
==============================================================================

[3.1] Atari ST 9-bit
--------------------
Standard ST palette register (word/colour)
%00000RRR0GGG0BBB

[3.2] Atari STe/TT 12-bit
-------------------------
Standard Atari STe/TT palette register (word/colour)
%0000rRRRgGGGbBBB

[3.3] Atari Falcon 16-bit
-------------------------
Standard Falcon truecolour pixels (word/colour)
%RRRRRGGGGGGBBBBB

[3.4] Atari Falcon 18-bit
-------------------------
Standard Atari Falcon palette register (longword/colour)
%RRRRRR00GGGGGG0000000000BBBBBB00

[3.5] Amiga OCS/ECS 12-bit
--------------------------
Standard Amiga OCS/ECS palette register (word/colour)
%0000RRRRGGGGBBBB

[3.6] Amiga AGA 24-bit
----------------------
Standard Amiga AGA palette register (double words, high,low nibbles)
%0000RRRRGGGGBBBB,%0000rrrrggggbbbb


==============================================================================
[4] BITPLANE FORMATS
==============================================================================

[4.1] Interleaved bitplanes
---------------------------
- Normal Atari word-interleaved bitplanes
- A one bitplane export will obviously not interleave

Example of 4 bitplane layout (16 pixels)

0000000000000001111111111111111222222222222333333333333


[4.2] Planar fields
-------------------
- Normal Amiga separate bitplane screens.


==============================================================================
[5] FILE EXTENSIONS
==============================================================================

[5.1] Bitplane exports
----------------------
- Input must be 8-bit BMP.
- Width of the source image must be even by 16 pixels.

".1pl" - 1 bitplane no palette
".2pl" - 2 bitplanes no palette
".3pl" - 3 bitplanes no palette
".4pl" - 4 bitplanes no palette
".5pl" - 5 bitplanes no palette
".6pl" - 6 bitplanes no palette
".7pl" - 7 bitplanes no palette
".8pl" - 8 bitplanes no palette


[5.2] Bitplane exports with palette
-----------------------------------
- Input must be 8-bit BMP.
- The palette is stored first in the file
- ST/STe/Amiga 12-bit/Falcon 16-bit palettes are stored as word/colour
- Falcon 18-bit/Amiga 24-bit palettes are stored as longword/colour
- Width of the source image must be even by 16 pixels

".1pp" - 1 bitplane with 2-colour palette
".2pp" - 2 bitplanes with 4-colour palette
".3pp" - 3 bitplanes with 8-colour palette
".4pp" - 4 bitplanes with 16-colour palette
".5pp" - 5 bitplanes with 32-colour palette
".6pp" - 6 bitplanes with 64-colour palette
".7pp" - 7 bitplanes with 128-colour palette
".8pp" - 8 bitplanes with 256-colour palette


[5.3] Truecolour and palette exports
------------------------------------
- Input can be both 8 and 24-bit BMP (truecolour conversion
  of entire image) or 8-bit (palette conversion).
- The output of palettes and truecolour data are the same
  so the extensions are shared. The colour data is compatible to
  the palette registers and Falcon 16-bit display.

".09b" - Stream of Atari ST 9-bit colours in word/colour format
".12b" - Stream of Atari STe 12-bit colours in word/colour format
".12b" - Stream of Amiga OCE/ECS 12-bit colours in word/colour format
".16b" - Stream of Atari Falcon 16-bit colours in word/colour format
".18b" - Stream of Atari Falcon 18-bit colours in longword/colour format
".24b" - Stream of Amiga AGA 24-bit colours in double word/colour format


[5.4] Byte chunky export
------------------------
- Input must be 8-bit BMP.
- The program will flip the image and remove BMP linewidth paddings.

".raw" - 8-bit chunky pixels


[5.5] Nibble chunky export
--------------------------
- Converts 8-bit BMP into 4-bit nibble chunky. The upper 4 bits of each
  pixel(byte) is removed.
- The image must be even even width.

".nib" - 4-bit chunky pixels


[5.6] Ofsmap export
-------------------
- The blue and green components of a 24-bit BMP file are dumped out
  as a raw 16bit/pixel stream.
- In case you make byte.byte ofsmaps in a 3D program or graphics editor
  this will strip away red component as well as BMP linewidth paddings

".ofs" - Raw 8.8 ofsmap


==============================================================================
[6] SUPPORT AND CONTACT
==============================================================================

[6.1] Credits
-------------
- Main Generic BMP code by Anders Eriksson
- Chunky To Planar routine by Mikael Kalms (c2p8pl.s)
- Longword division routine by unknown person (math.s)

[6.2] Source code
-----------------
- Source code will probably be made public on Github one day or the other.

[6.3] Support
-------------
- Generic BMP comes with no support or warranty, use at your own risk!

[6.4] Feature requests
----------------------
- Generic BMP is a tool made for myself when making demos. I don't take any
  requests for new features or changes. So use if it suits you, throw it in the
  bin if not!

[6.5] Contact
-------------
- Contact via e-mail: ae@dhs.nu



eof