# PictConv

Description

PictConv is a tool that can be used to convert pictures created with a standard PC paint program (PaintShopPro, PhotoShop, ...), in a format displayable on the Oric.

Utilisation

To convert a picture:

    	%OSDK%\bin\PictConv [switches] source_picture destination_file

Supported formats for the source picture is everything that FreeImage supports (BMP, PCX, PNG, TGA and TIFF among other).

Switches

- The -m switch is used to define what the target machine is:

      -m0 => Oric [Default]
      -m1 => Atari ST

- The -f switch control the type of picture conversion that will be performed. This is machine dependent:

      Oric:
        -f0 => to hires monochrom format [default]
        -f0z => to hires monochrom format (do not set bit 6) *** Not working in this version ***
        -f1 => precolored picture
        -f2 => RVB conversion
        -f3 => Twilight masks
        -f4 => RB conversion
        -f5 => charactermap generator
        -f6 => Sam method (Img2Oric)
        -f7 => AIC encoding
      Atari ST:
        -f0 => Single palette format [default]
        -f1 => Multi palette format
        -f2 => Monochrome format

- The -o switch defines the final file format:

      -o0 => Tape format, including a BASIC loader
      -o1 => Tape format, simply the picture
      -o2 => RAW format. No header.
      -o3[label name] => C source code
      -o4[label name] => assembler source code
      -o5 => Output a PC picture format
      -o6 => 2 bytes (dx,dy) size followed by RAW picture
      -o7 => palette followed by picture
      -o8[line:step] => BASIC source code

  For -o3 and -o4, if "label name" is not defined, the default "LabelPicture" is used.
  For -o8 you can specify two values that will be taken respectively as the first line number and the step between lines.

  One very useful feature is the -o5 mode which instead of saving to the Oric or Atari format, will save the result of the conversion to a pc format. This is very practical when experimenting with multi-palette or dithering options, because you do not have to try on the real machine, you can just check the result directly on your pc.

  When doing Atari conversion, you typically want to use the -o7 mode, which will save the palette (or palettes) followed by the bitmap. You don't really want to try other formats because they will not work well in this version for the atari conversions (they were made for the Oric and I did not update the code yet.

- The -p switch controls the way palettes are managed:

      -p0 => Generate a palette automatically [default]
      -p1 => Last line of the picture contains the palette
      -p2 => Last pixels of each line of the picture contains the palette

  When using -p0, PictConv will automatically perform the palette generation, using the STe enhanced palettes, eventually reducing the color depth if more than 16 colors are used. If the color conversion is done with the -f0 format, one single palette will be generated in the final picture. If the -f1 format is used, then one palette will be generated for each scanline.

  If you want to use -p1 or -p2, you need to modify your input picture to include palette data. An important point to miss, is that you can use -p1 with -f1. At first glance it would look like you would use the same single palette repeated for every scanline, which seems to be of dubious interest, but it makes sense when you will learn that the palettes you specify do not have to be complete. Only the color indexes defined in the palette will be used in the conversion process, the free indexes will be used by the color reduction routine.

  When using -p1, you need to add two scanlines at the bottom of your picture. So if your picture is 320x200, you will have to make it 320x202, the two last lines will be used by PictConv to figure out which colors to use. (Of course the exported picture will be 320x200). The way it works, is that these two additional lines will contains colors that will be interpreted as either "not set" colors, or "fixed colors". The first pixel of the first additional line will be used as "not set" color, the 16 first pixels of the second additional line will be the palette itself. Each of these 16 pixels that are of the same color as the "not set" color will be ignored. Others will be interpreted as colors that have to be kept at this particular position in the palette. That's particularly useful to make sure that your background color is at index 0, and that this particular sprite is using the color 8 of the palette.

  Some examples will make it easier to understand:
  => =>
  =>
  =>

- The -d switch controls the dithering operation:

      -d0 => No dithering (0/1)
      -d1 => Alternate dithering  (0/0.5/1)
      -d2 => Ordered dithering (4x4 matrix, 8 levels)
      -d3 => Riemersma dithering (based on hilbert curves)

- The -a switch enable the alpha channel detection:

      -a0 => no transparency [default]
      -a1 => encode alpha as zeroes (Only supported for monochrome and AIC pictures)

- The -t switch enables the testing mode:

      -t0 => Testing disabled
      -t1 => Testing enabled

- The -n switch defines the number of entries per line when generating text format:

      -n16 => Output 16 values each line
      -n40 => Output 40 values each line

- -un Update check

      -u0 => Do not check if files are up to date [default]
      -u1 => Perform a date check on the files and only update if needed

- -vn Verbosity.

      -v0 => Silent [default]
      -v1 => Shows information about what PictConv is doing

- The -u switch defines if the source and destination file timestamps should be compared to avoid costly re-exports

      -u0 => Output 16 values each line
      -n40 => Output 40 values each line

- The -s switch sets if the swap mode is enabled or not:

      -s0 => no swapping [default]
      -s1 => generate two pictures instead of one, designed to be swapped each frame

Some picture samples

Here are some conversion samples, with the parameters used.

Buffy

| -f0 | -f2
--- | --- | ---
-d0 |  |
-d1 |  |
-d2 |  |
-d3 |  |

Mire

| -f0 | -f2
--- | --- | ---
-d0 |  |
-d1 |  |
-d2 |  |
-d3 |  |

Moxica

| -f0 | -f2
--- | --- | ---
-d0 |  |
-d1 |  |
-d2 |  |
-d3 |  |

Lena

| -f0 | -f2
--- | --- | ---
-d0 |  |
-d1 |  |
-d2 |  |
-d3 |  |

Frequently Asked Questions

- In colored mode, free size pictures are not accepted. Why ???

  Try to imagine how you could scroll horizontaly a picture containing attributes changes without having huge color changes. This is not possible. Free vertical size is allowed anyway, but it's buggy right now :))

- In colored mode, the converted picture contains some lines that are black and white.

  These scanlines cannot be converted. A colored pictures should use Oric constraints, be in at most 8 colors, no more than 2 colors per 6 pixel bloc, and so on...

- In colored mode, PictConv decided to use strange paper and ink changes.

  Actually PictConv simply tries all the possible combinations of paper, ink, video inverse changes that could work to convert the picture. When it find one working combination, it moves to the next scanline.

History

Here is the list of all releases with a short description of things that changed:

Version 1.0

- When failing to load a picture, the error message will now indicate the name of the file - Fixed the Atari ST multi-palette export mode

Version 0.25

- Fixed the off-by-one error in the tape header when Exporting Oric images to tape format

Version 0.24

- Fixed a problem in the color reduction code failing on a 32bit source image

Version 0.23

- Added the -f2 option to the Atari ST converter, with support for monochrome pictures - Added the -s1 option to generate two pictures that can be swapped each frame to generate more colors

Version 0.22

- Fixed the -f5 (charmap generator) to work correctly without crashing. - Inverted -o0 and -o1 in the description of commands (issue #3)

Version 0.21

- Added support for 32bit picture, to handle things like masking/opacity in the picture formats - The -a1 mode will generate bytes with null value for blocks of 6 pixels with transparent alpha values (only active in monochrome or AIC conversion modes) - Added the -f7 conversion mode for Oric pictures using the AIC coloring method.

Version 0.20

- The -f6 mode can now be used for pictures that are taller than the screen
- Fixed the percentage calculation so it actually goes from 0 to 100 even when pictures are not 200 pixel tall.

Version 0.19

- Fixed a buffer overflow in the -f6 conversion mode happening when images are not 240x200
- Changed the depth mode from 3 to 2 to speed-up the conversion

Version 0.18

- Added the -f6 conversion mode for Oric pictures. This is the method used in Img2Oric/LibPipi and generally gives much better results when converting - albeit much much slower than other methods.

Version 0.17

- Fixed a the update code, was failing if the target file did not exist (facepalm)

Version 0.16

- New option to skip the conversion if the target file is more recent than the source file (-u)
- New option to enable/disable information about what happens (-v)

Version 0.13

- It is now possible to lock some colors index to some particular values.

Version 0.12

- Lot of modifications in the codebase to handle more cleanly the various types of machines.
- The Atari ST now can generate multi-palette pictures.
- Color reduction is now done by PictConv, no need to reduce to 16 colors manually.

Version 0.11

- Added the -o7 format to generate BASIC source codes.
- Removed the constraints in the -f1 mode, pictures just need to be multiple of 6 in width, and no more than 240 pixel wide.

Version 0.10

- If there is something specified after -o3 or -o4 modes, it's used as a label name to use when generating source code data.
- If there is a 'z' specified after -f0 mode (monochrome conversion), it means that bit 6 should not be set in converted bytes
- Added -n switch to set the number of values per line (stolen from Bin2Txt !)

Version 0.9

- New option for generating 'masks' in bits 6 and 7 based on what is presents in bits 0/1/2 and 3/4/5.
(Twilighte's request for his new games)
- Added a way to convert pictures to something that can be used on an Atari ST.
(needed that for my entry to the 20 years anniversary Atari ST compo)

Version 0.8

- Added "test" mode that's usefull to debug a picture in colored mode

Version 0.7

- Removed the timer check in the colored conversion mode. It was producing bad conversion on slow computers. Anyway, if you are unlucky, a conversion could now take hours to perform if the tool has to perform ALL possible combinations.

Version 0.6

- A message is given if the picture is not found or invalid.
- Colored mode had some bugs: all now corrected ???

Version 0.5

- Debugged the -o6 format.
- Debugged the -f1 mode.

Version 0.4

- Allow free size pictures (bigger than screen size except for colored mode)

Version 0.3

- Riemersman dithering implemented

Version 0.2

- New version with basic dithering

Version 0.1

- First beta release