BMExport 2.03 (07-May-03)

Name:     ArtWorks BMExport module
Purpose:  ArtWorks module for bitmap (Sprite, GIF, TIFF) export
Author:   Martin Wrthner
Requires: RISC OS 3.5 or higher, ArtWorks 2 or higher
Status:    2000-2003 Martin Wrthner; all rights reserved; see [4] below
WWW:      http://www.mw-software.com/

Welcome to the BMExport module.

This module allows you to export ArtWorks documents as Sprite, GIF and TIFF
files. It offers an extensive set of options including exporting with a
transparent background, export in 16, 256, 32k and 16M colours with standard
Acorn, greyscale, browser-safe and optimized palettes, including error-diffused
dithering. There is comfortable support for choosing the scaling to use: You
can enter the desired width, height, scaling or dpi value for the bitmap.

This module makes internal use of InterGIF, an excellent application written by
Peter Hartley (pdh@chaos.org.uk) and released under a very generous licence,
allowing me to enhance it with the features needed for BMExport, e.g., error
diffusion and grey scale output. If you do not have InterGIF, do not worry
because BMExport contains the parts of InterGIF that it needs, so you do not
need to have the full version of InterGIF installed in order to use BMExport.
However, you may find it useful to have the full version of InterGIF anyway.
The InterGIF home page can be found at:
  http://utter.chaos.org.uk/~pdh/software/intergif.htm

1) The BMExport module

After installing this module, you will find an additional entry "Bitmap..." in
the "Export" menu. The three dots indicate that unlike the other export
facilities, this menu entry does not lead to a save box submenu, but instead a
dialogue box is opened. You can also use the keyboard shortcut Ctrl-Shift-E to
open the bitmap export dialogue box.

1.1) The bitmap export dialogue box

The bitmap export dialogue box works like a save box: Enter a file name for the
bitmap in the input field beneath the Sprite, GIF or TIFF file icon, then drag
the icon to a Filer window. Alternatively, fill in a full path to save to and
click on the OK button. Please note that in contrast to usual RISC OS
conventions, you can only export to a Filer window (i.e., to some storage
device), not directly to another application. As BMExport sometimes needs to
write an intermediate file to the destination directory (for GIF export or
sprite export with 256 colours or less), you should avoid exporting directly to
a slow device or one with a very limited capacity, such as a floppy disc or an
archive managed by SparkFS.

If you want the dialogue box to stay on screen, you can click on the OK button
with the Adjust mouse button or use the Adjust button to drag the file icon.
Otherwise (if you use Select or if you enter a path name into the writable
field and press Return) the dialogue box is closed after the export is
complete.

The dialogue box offers a powerful range of options:

Output format
-------------
Sprite, GIF and TIFF format are supported. Future versions may support PNG
format as well, as this format is supposed to eventually replace the GIF format
in the World Wide Web. However, the overwhelming majority of graphics files on
the Web are still in GIF format.

Please note that there are various limitations depending on the output format
chosen. For example, GIF files can only be in 256 colours or less. TIFF files
are most restricted in that they can only be exported in 16M colours without a
transparent background, so many options below do not apply to TIFF output.

Interlaced
----------
For GIF export, you can choose whether the GIF should be interlaced or not (for
use with the Web, you should normally select 'Interlaced' as it allows browsers
to render the picture progressively).

Transparent background (masked)
-------------------------------
If you select this option, then the background (i.e. the "page" in ArtWorks)
will be transparent in the exported image. If you export as Sprite, then it
will have a mask. If you export as GIF, this will result in a transparent GIF.
Please note that ChangeFSI does not understand transparent GIFs (it will render
the transparent part of the picture black), but you can use a browser (e.g.,
Acorn Browse) or IGViewer (comes with InterGIF) to view GIF files with
transparency.

Please note that anti-aliasing (enabled when exporting with maximum quality,
i.e. the value in the 'Quality' field is 11) always takes the page colour into
account, irrespective of the transparency option. This means that even if you
export a bitmap with a transparent background, you can still control the anti-
aliasing background by changing the page background colour (in the document
choices window opened by choosing 'File => Choices...' in the document menu).

Transparency (Crystal)
----------------------
This option is only available if the Crystal tool is installed. Crystal allows
you to make any object on the page transparent by applying a transparency type
and a percentage to it. The "Transparency (Crystal)" option corresponds to the
"Display" option in the Crystal Info Bar. This option allows you to choose
whether or not to take the transparency properties of objects into account when
exporting. It is independent of Crystal's "Display" option, so you can view a
document without transparency and export it with transparency or vice versa.

Colour depth
------------
The supported colour depths are 16 colours (4bpp), 256 colours (8bpp), 32k
colours (16bpp) and 16M colours (32bpp). The colour depth of GIF files can not
exceed 8bpp (256 colours). TIFF files can only be exported with 16M colours.

Palette
-------
There are two methods for representing colour information in a bitmap file:
"Direct colour" and "indexed colour". In the "direct colour" system, each pixel
value specifies the red, blue and green intensities of the pixel's colour
directly. In the "indexed colour" system, each pixel value is an index into a
table that holds the actual colour values. Such a table is called a palette. It
represents the choice of colours used for the pixels of the bitmap image.

RISC OS Sprites with 32k or 16M colours (16bpp or 32bpp) use the "direct
colour" system and therefore do not have a palette. On the other hand, RISC OS
16 or 256 colour sprites (4bpp or 8bpp) and all GIF files use the "indexed
colour" system and therefore need a palette that can be specified in the
"Palette" section of the dialogue box.

There are three fixed-palette options ("Standard", "Greyscale" and "Browser-
safe"). "Fixed" means that the choice of colours is independent of the colours
that actually occur in your ArtWorks drawing. "Standard" refers to the standard
RISC OS colour palette for 16 or 256 colours (i.e., the palette a newly created
colour sprite gets in Paint). Greyscale corresponds to an even range of grey
scales from black to white (same as the palette of a newly created greyscale
sprite in Paint). "Browser-safe" refers to the 216 colour palette used by
Netscape and Internet Explorer under Windows and MacOS. This is usually a good
choice for the WWW.

The last option, "Optimized palette", means that the optimal choice of colours
is made to represent the illustration most closely. It works both for 16 colour
(4pp) or 256 colour (8bpp) output. This palette option most closely preserves
the original information in the ArtWorks document (most closely compared to the
other palette options; if you want to fully preserve the colour information you
have to export as a 16M colour sprite).

In general, the best display quality is achieved by exporting with an optimized
palette, but only if the viewing application, operating system and video
hardware can handle arbitrary palettes well, which is not always the case. The
next best choice is to export with the same palette that is used by the display
on which the file is finally viewed. If you want to view the exported sprite
file in the Acorn 256 colour desktop, then using the Acorn standard palette
will look best. For Web use, the 216 colour "Browser-safe" palette is
recommended as most machines on the Web will be able to display the resulting
file with a reasonable quality.

Whichever palette you use, you should consider switching on "Error diffusion"
(see below).

Error diffusion
---------------
The output quality of images with indexed colours (i.e., with a palette) can be
significantly improved by switching on "Error diffusion". Error diffusion
increases the amount of visually perceived colours by using multiple nearby
pixels to simulate the desired colour of an area. The idea behind it is similar
to the on-screen colour dithering method of ArtWorks but gives superior
results.

Without error diffusion, each pixel is represented by the palette colour that
matches the actual colour most closely. In particular when exporting as a 16
colour bitmap, this often looks poor. Error diffusion enhances the colour
matching by computing the error that is made by mapping a pixel colour to one
of the colours in the palette and distributing this error to the neighbouring
pixels in the image. This is the so-called Floyd-Steinberg algorithm, the same
method that is also used by ChangeFSI (by Acorn, supplied with RISC OS).

For example, if you have a deep purple area and the palette only contains red
and blue, then without error diffusion, the whole area would end up in blue,
the closest matching colour. With error diffusion, the lack of red in the first
pixel would be distributed to its neighbour, so with this additional amount of
red, its closest match is probably red, and so on. Eventually, the purple area
will be approximated by a pattern of red and blue pixels.

Error diffused images should not be scaled afterwards as this can lead to very
poor results.

Scope
-----
There are four options for choosing which part of the ArtWorks illustration
should be exported: If you select, "Whole page", then the complete page is
exported. "Drawing" refers to the area that is actually covered by objects on
the page. "Selection" exports selected objects only. The exported area is only
that covered by selected objects. "Selection box" is similar: Only the
rectangular area enclosing the selected objects is exported but including all
the unselected objects that are (wholly or partially) in this area.

Only visible non-background layers are exported. In the unlikely event that you
want to export background layers as well, move them temporarily to the
foreground.

You can export an arbitrary rectangular area on the page by creating a
rectangle corresponding to the desired area, selecting it and then using the
"Selection box" option to export the image. If you create the rectangle on a
background layer it is not exported itself but you can still see it.
Alternatively, you would have to make the rectangle invisible by giving it
line and fill colours "None".

You can still adjust the selection while the BMExport dialogue box is open. The
values in the dialogue box are updated accordingly. Please note that the sizes
for the "Whole page" and "Drawing" options are determined when you open the
BMExport dialogue box, so if you change the page size or draw additional
objects on the page while the dialogue box is open, these changes are not taken
into account for the computation of the drawing size.

If one or several objects are selected in your ArtWorks document when you open
the BMExport dialogue box or if you select an object while the dialogue box is
open, then the scope option "Selection box" is selected automatically (unless
one of the selection-based scopes was selected already). Of course, you can
then still change the scope by clicking on a different scope option.

Scaling
-------
The "Scaling" group determines the size of the exported bitmap. There are four
possibilities for specifying it: You can either enter the desired target width
or height of the bitmap in pixels, the actual scaling (in %) or the resolution
of the bitmap in dots per inch (dpi).

By selecting one of the radio icons ("Width", "Height", "Scale" and "Dpi"), you
can choose which of the values you want to specify. Unfortunately, the values
in the other input fields are not automatically updated when you change the
value in the currently selected field. This only happens when you press Return,
click on another radio icon or click on the currently selected radio icon
again. So, if you for example change the scaling from 100 to 80 and you want to
know what the resulting width of the bitmap is, simply click on the "Scale"
radio icon again. Then, the values in the width, height and dpi fields are
updated.

The output resolution and sacling values are based on the usual RISC OS
assumption that the RISC OS desktop in a square pixel mode (with Eigen values
EX1 EY1) has 90dpi.

Please note that due to rounding taking place (the width and height values have
to be full pixels), switching between two fields (e.g., width and height)
several times may alter the values every time.

Border
------
The value in this input field determines the width of the border around the
exported image. If "Transparent BG" is selected, then the border pixels are
transparent, otherwise they are in the page background colour. The border is
added to every side of the image, so if you specify a border width of 5 pixels,
then 5 pixels are added to the left, right, top and bottom of the image. Please
note that the width and height values in the "Scaling" group (see previous
section above) include the border pixels.

Quality
-------
The value in the "Quality" field determines the ArtWorks WYSIWYG value to be
used. This should be in the range between 0 (outlines) and 11 (anti-aliased)
and corresponds to the values displayed next to the WYSIWYG control knob in the
ArtWorks Info Bar. Normally, there is no reason to reduce the output quality
from the standard value 11, but you may prefer not to have anti-aliasing, which
can be achieved by using output quality 10. Other values rarely make sense. The
pop-up menu next to the input field offers the most interesting values (these
are same values as those in the corresponding menu in Impression).

Help button
-----------
To the left of the "OK" button, there is a little help button that allows you
to display this help file in a comfortable way.

1.2) Technical details

Memory usage
------------
Exporting bitmaps can use large amounts of memory. An A4 page at 90dpi needs
almost 3M of free memory, about 3.1M if you also switch the 'Transparent BG'
option on. Furthermore, memory is needed by InterGIF for post-processing the
exported bitmap (for GIF export and for exporting 16-colour and 256-colour
sprites). However, by the time InterGIF is called, the main dynamic area for
the sprite export has already been released, so the memory requirements do not
add up.

In general, the amount of memory for a true colour sprite (32bpp) is needed
even when exporting in only 16 or 256 colours. This amount can be computed by
the formula <width in pixels> x <height in pixels> x 4 bytes. With
transparency enabled, use the factor 4.125 instead of 4 in the formula above.

If the amount of free memory is insufficient, three types of error messages
can occur:
- the usual ArtWorks error message ("This operation has caused ArtWorks to run
  out of memory")
- a RISC OS error message (e.g., "Cannot change dynamic area - application
  running") indicating that the main dynamic area for sprite export could not
  be set up
- an error by InterGIF displayed in a "command-line" window followed by the
  words "Press SPACE or click mouse to continue"

Overwriting files
-----------------
The bitmap export module follows the normal ArtWorks convention of always
warning you before overwriting an existing file. When exporting using an
intermediate file (GIF export or sprite export with 256 colours or less), the
dialogue box that asks you whether or not to overwrite an existing file is only
displayed after the intermediate file has been written, which might take some
time depending on the complexity of the ArtWorks file and the resolution of the
exported bitmap.

To minimise filename clashes the default leaf name in the export dialogue box
has the suffix "_s", "/gif" or "/tif" (for Sprite, GIF or TIFF export
respectively). If the filing system you are saving to does not support long
filenames, this might still mean that the name of the bitmap clashes with the
name of your original ArtWorks file. In this case, BMExport displays a warning
dialogue box and allows you to abort the bitmap export.

Exporting without dragging
--------------------------
Exporting by entering a full path name and pressing OK should be used with
care: If the name is invalid, ArtWorks displays an error message (actually
about the name of the temporary file, if you export as GIF or as 16/256 colour
sprite) and some internal buffers (e.g., the temporary dynamic area) are not
released until after the next successful export operation.

Limitations
-----------
- The bitmap export module cannot save to an application directly. You have to
  save the file to a disc first.
- "Transparent background (masked)" is not supported in 16bpp modes (32k
  colours). Transparent 32k Sprites can be created by exporting with 16M
  colours and feeding the resulting sprite through ChangeFSI.
- Only 32k and 16M colour sprites are exported directly by ArtWorks. Sprites of
  other colour depths (16 and 256 colours) are rendered in true colour (16M
  colours) by ArtWorks and post-processed by InterGIF. This takes longer than
  direct sprite export and takes as much memory as a full 16M colour sprite
  export.
- Files that are post-processed by InterGIF (all GIF exports and sprite exports
  with 256 colours or less) cannot exceed about 25M in size - this is due to
  the RISC OS WimpSlot limit of 26M.
- TIFF files can only be exported in 16M colours. This restriction may be
  removed in the future.
- "Selection" is not supported in conjunction with "Transparency (Crystal)".
  "Selection box" is used instead. This restriction may be removed in the
  future.

2) History
----------
Version 2.03 (07-May-03)
- no longer requires the 32-bit CLib because the intergif executable is
  included both as 26-bit and 32-bit versions

Version 2.02 (07-Nay-03)
- fixed (probably harmless) remaining 26-bit instructions

Version 2.01 (21-Apr-03)
- fixed minor bug that prevented the palette icons from being unshaded when
  switching from TIFF to GIF

Version 1.19 (09-Apr-03):
- 32-bit compatible (including 32-bit compatible intergif)
- added support for Method_ModuleInfo

Version 1.18 (08-Jan-03):
- two minor user interface changes: the bitmap export dialogue box places the
  caret in the file name box when it is opened
- when there is a selection then the scope option "Selection box" is selected
  automatically unless one of the selection-based scopes was selected already
  ("Selection box" is the only available selection-based option when the
  "Crystal" option is on and it is also generally more frequently used than
  "Selection")

Version 1.17 (23-Jul-02):
- fixed EM00 problems that occurred sometimes when clicking on "Sprite", "GIF"
  or "TIFF" icon in the dialogue box
- introduced path variable to shorten command line - this should reduce problems
  exporting paletted sprites or GIFs to deep directory structures which could
  exceed the RISC OS command line length limit

Version 1.16 (10-Jun-02):
- replaced "Sprite", "GIF" and "TIFF" menu entries by a single "Bitmap" entry
- after a successful export operation, the destination path is remembered and
  put in the save path field for subsequent export operations
- switched from prefixing to suffixing to allow better default file names,
  e.g., "/gif" for GIF and "/tif" for TIFF files
- clicking on the "Sprite", "GIF", "TIFF" options changes the path name
- added file overwrite checks
- various minor user-interface improvements and corrections

Version 1.15 (04-Jun-02):
- added TIFF export
- added Ctrl-Shift-E shortcut

Version 1.14b (03-Apr-02):
- !Help file updated (Limitation section corrected)

Version 1.14 (02-Apr-02):
- corrected bug in GDraw version check

Version 1.13 (26-Mar-02):
- improved 256 colour output - output from earlier versions could have
  disturbing dark pixel areas (could look rather "grainy")
- size of "Crystal" and "Transparent background" icons corrected
- background layers are exported with "Transparency (Crystal)" switched on

Version 1.12 (25-Mar-02):
- new option "Transparency (Crystal)" - only available in conjunction with the
  Crystal tool
- new little help button in the export window that allows you to display the
  BMExport !Help file in a comfortable way

Version 1.11 (20-Nov-01):
- fixed rounding bug that could cause sprites to be offset by one pixel in
  exported bitmaps

Version 1.10 (09-Oct-01):
- major fixes and improvements in greyscale sprite generation (proper greyscale
  reduction using CIE luminance values as opposed to naive palette matching);
  16 and 256 grey scale output are an order of magnitude better than before
- error diffusion option greyed out for 256 grey scale output - there is no
  need for error diffusion because this allows lossless greyscale mapping

Version 1.08b (21-Sep-01):
- updated GDraw warning messages in Messages files

Version 1.08 (24-Aug-01):
- flatness bug fixed: up to 1.07, the window's scale factor determined the
  flatness used by GDraw, now the export scaling is used
- the dialogue box stays on screen if Adjust is used to export (Adjust drag or
  Adjust click) - the pathname to which the file was saved is filled in
- if the selection is changed while the BMExport box is open, the values in the
  box are updated
- GDraw version check
- contains Dutch messages (thanks to Dick Tanis for translating them)
- width and height may be up to 99999 pixels intead of 9999
- an error is displayed if the file icon is dragged to an application (as
  opposed to the Filer)
- a proper error is displayed if export is started by clicking on OK or by
  pressing Return, and the pathname entered is not valid

Version 1.07 (23-Feb-01):
- minor internal stability enhancements

Version 1.06 (01-Oct-00):
- Now asks modules to render in "VDU" mode instead of "Preview" mode as the text
  tool made a mess of some characters in preview mode. The two modes are almost
  identical anyway, but apparently, preview mode is not too well supported.

Version 1.05 (02-Sep-00):
- first release version


3) Contacting me
----------------
Martin Wuerthner
Mannheimer Str. 18
67655 Kaiserslautern
Germany

Phone: +49-(0)631-3608205
Fax:   +49-(0)631-3608203

e-mail: martin@mw-software.com
WWW:    http://www.mw-software.com/


4) Copyright
------------
The ArtWorks BMExport module, related documentation and files are  Copyright
2003 by Martin Wrthner. All rights reserved. The software and documentation
may not, in  whole or part, be copied or transmitted by any means without the
explicit written consent of the copyright owner. Unless you have purchased a
site licence for this  software, it may be used on only one stand-alone
computer system at any time.

In order to use this software, you need a licence from the copyright owner. If
you do not have such a licence, you must delete this software, the BMExport
module and its related files, now.
