--------------------------------
The All-New PPM2BBC
        by SeDi (vmgsedi@msn.com)
--------------------------------


** I do not accept any liability or responsability for any damage or other
** consequences of using/misusing this program. There are no guarantees or
** warranties involved anywhere along the line.


0. CONTENTS

        1. Introduction
        2. Usage
        3. Options
        4. Examples
        5. Viewing the Screendumps


1. INTRODUCTION

PPM2BBC converts 24-bit PPM6 (binary-encoded PPM) files into BBC Micro
screendumps.

I wrote this program to replace a similar program I found on the net, which I
couldn't get working. This new PPM-to-BBC converter, however, also has many
features that the older program didn't.

Part of this program is based on a Public Domain PPM file loading routine.


2. USAGE

First off, if you don't have the "PPM2BBC" executable for your computer, you'll
have to compile it from the C source. Once that's done, it can be used in the
following manner:-
        ppm2bbc [<options>]<ppm-file> ...

<ppm-file> is the name of the PPM file to convert. PPM2BBC will write out two
files
during the conversion. One is named "<ppm-file>.bbc", which is the BBC Micro
screendump file, suitable for *LOADing into a BBC's screen memory (see section
5
below). The other is named "<ppm-file>.bbc.inf", which is a BBCIm archive file,
giving the correct *LOAD address. (All archive files generated by PPM2BBC
describe
a BBC file called "$.SCREEN".)

The PPM file can be any size, but only the top-left 320x256 pixels will be
converted
(unless you're not using the "a" option, in which case the size will vary). For
PPM files smaller than 320x256, the converted picture will be positioned in the
top-left of the BBC's screen.

If options are specified, there must be no space between them and the PPM
filename.
If you just type "ppm2bbc" without any options or PPM filenames, you'll get a
short
help text which describes the available options.


3. OPTIONS

Here is the options template (spaced for clarity). All options in [] brackets
are
optional. (If this looks confusing, there are some examples below.)

            - [h [s] <dither>] [a] <mode>
               |  |       |     |     |
          /----/  |      see    |    see
          |       |     below   |   below
   specifies    staggers        |
   halftoning     RGB        aspect
    pattern      values     correction

You should normally use the "a" switch (aspect correction) if you're converting
to
MODEs 0, 2 or 5. The pixels in these modes are rectangular (not square) and,
without aspect correction, pictures displayed in MODE 0, 2 or 5 will look
squashed
or stretched. Use "a" to keep them square.

<dither> specifies the halftoning dither pattern to be used. It is a number
from 0
to 4:-
        0 = no halftoning
        1 = fine halftoning (default)
        2 = coarse halftoning
        3 = spiral halftoning
        4 = diagonal halftoning

Note: Using the "s" switch to stagger the RGB values can improve dithering
quality
in MODE 2. Using it for other MODEs often obscures the picture.

<mode> specifies the BBC Micro graphics MODE to produce. This can be 0, 1, 2, 4
or
5. The default is MODE 2.


4. EXAMPLES

ppm2bbc dog.ppm
        Converts the PPM file "dog.ppm" into a BBC Micro MODE 2 screendump with
        fine halftone dithering, named "dog.ppm.bbc", which *LOADs at 3000.

ppm2bbc -0photograph.ppm
        Converts the PPM file "photograph.ppm" into a BBC Micro MODE 0
screendump
        named "photograph.ppm.bbc", which *LOADs at 3000.

ppm2bbc -a2house.ppm
        Converts the PPM file "house.ppm" into a MODE 2 screendump, with aspect
        correction.

ppm2bbc -h04cat.ppm
        Converts the PPM file "cat.ppm" into a MODE 4 screendump, with no
        halftone dithering.

ppm2bbc -hs3a2castle.ppm
        Converts the PPM file "castle.ppm" into a MODE 2 screendump, with
        aspect correction and spiral halftoning with staggered RGB values.


5. VIEWING THE SCREENDUMPS

If you're going to be using BeebEm, then run BBCIm like this:-
        bbcim -a myscreen.ssd <ppm-file>.bbc
where <ppm-file> was the name of the original PPM file. Load the resulting disk
image "myscreen.ssd" into BeebEm, and type
        MODE <mode>:*LOAD SCREEN
Where <mode> is the MODE into which you converted the PPM file. It's as simple
as
that.

If you're using another emulator, you may have to type one of the following:-
        MODE    :       WHAT YOU TYPE
        -------+-----------------------
        0       :       MODE 0:*LOAD SCREEN 3000
        1       :       MODE 1:*LOAD SCREEN 3000
        2       :       MODE 2:*LOAD SCREEN 3000
        4       :       MODE 4:*LOAD SCREEN 5800
        5       :       MODE 5:*LOAD SCREEN 5800

I've also loaded PPM2BBC screendumps successfully into Tom Seddon's emulator,
and the Devenport emulator. It should theoretically also be possible to
load them into the XBeeb emulator, but I haven't tried it yet.

