JPEGObject 1.18 (30-Sep-03)

Name:     ArtWorks JPEGObject module
Purpose:  ArtWorks module providing JPEG objects
Author:   Martin Wrthner
Requires: RISC OS 3.6 (or RISC OS 3.5 with SpriteExtend 0.99 or higher);
          ArtWorks 2
Status:    2003 Martin Wrthner; all rights reserved; see [5] below
WWW:      http://www.mw-software.com/

Welcome to the JPEGObject module! This module allows you to embed JPEG images
in your ArtWorks documents without having to convert them to sprites (and
thereby decompress them).

Please note that this module requires SpriteExtend 0.99 or higher.
SpriteExtend is part of RISC OS. Starting from version 0.99, SpriteExtend
is able to display JPEG files directly without them having to be converted
to sprites first. JPEG-enabled versions of SpriteExtend are supplied in
ROM with RISC OS 3.6 or higher. There is a soft-loadable version of
SpriteExtend 0.99 for RISC OS 3.5. You can find out about the version of
SpriteExtend by entering the command line (press F12) and typing "Help
SpriteExtend" (without the double quotes).


1) The JPEGObject module
------------------------
The JPEGObject module introduces a new object type to ArtWorks: JPEG objects.

Like some other modules, the JPEGObject module does not provide a new tool in
the ArtWorks tool box. In order to create a JPEG object, simply drop a JPEG
file onto an ArtWorks document window. This inserts the JPEG at the position
where you dropped it.

The imported JPEG is scaled according to its pixel density as specified in the
file (i.e., the pixel aspect ratio or the number of dots per inch). If you hold
down Ctrl while dragging the JPEG, then the density information stored in the
JPEG is ignored (useful in case it is wrong) and the file is scaled according
to the assumption of square pixels at 90dpi.

If the imported JPEG is not understood by SpriteExtend, you will see an error
message "Incomplete or corrupt JPEG data". In this case, try feeding the JPEG
image through CleanJPEG: This free utility cleans non-standard JPEGs to make
them compatible with SpriteExtend (see section 2 for a download address).

1.1) Interaction with external graphics filters
-----------------------------------------------
Please note that automatic graphics converters, such as the Computer Concepts
JPEG loader or ImageFS may convert the JPEG to a sprite before ArtWorks even
gets to see it. In that case, you have to switch the graphic converter off
before trying to import the JPEG into ArtWorks. In the case of ImageFS, check
the Status setting for the JPEG filetype (in the Options window): If it is
"Auto", then ImageFS will convert JPEG images in the background, and there is
no way of importing the JPEG file into ArtWorks as a JPEG. In that case, simply
change the Status to "Active". This way, you can still use ImageFS to convert
JPEGs to sprites (by holding down Alt and double-clicking on the image) when
working with other applications, but it allows ArtWorks to see JPEG files
dragged to it.

1.2) Transforming JPEG objects
------------------------------
You can move and scale JPEG objects like other ArtWorks objects. In contrast to
Draw, you can even rotate and skew them! Displaying transformed JPEGs that are
no longer upright (i.e., either skewed, rotated or flipped) takes a lot of
processing power and memory, so make sure you have both before trying to
transform JPEGs this way. If ArtWorks runs out of memory when rendering a
transformed JPEG object, it is displayed as an empty shape with a cross.

If you find that rendering is too slow this way, then you can always convert
the JPEG to a sprite and use that instead. This, however, will increase the
size of your ArtWorks document a lot, and if you have more than one image in a
document, using sprites instead of JPEGs consumes significant amounts of extra
main memory.

The reason for JPEG objects being rendered more slowly than sprites is that the
JPEGs are stored in their uncompressed form in the document, so they are
decompressed on the fly every time they are rendered on screen. As soon as the
JPEGs are rotated or skewed, even more work is necessary because the OS cannot
render them directly.

Similar to sprites you can resize JPEG objects by dragging any of the four
selection handles at the corners of the image.

1.2.1) The JPEG Object Info Box

You can find out details about the JPEG's position and scaling if you select it
and press Shift-F1. This opens the JPEG Object Info Box for the image. The box
is very similar to that of sprite objects: It shows the JPEG's horizontal and
vertical pixel sizes, its size in bytes, its position and dimensions, its scale
and aspect factors and its effective resolution in dpi (dots per inch) taking
into account the JPEG's scaling on the page (but not any scaling you may apply
when printing the document).

You can reposition or resize the JPEG by entering new values and clicking on OK
or pressing Return. You can either enter new values for width and height or for
scale and aspect. Resizing a JPEG this way retains its rotation and skewing
angles.

At any time, you can reset the selected JPEG object to its original state (1:1
scaling, unrotated, unskewed) by clicking the button labelled "Reset JPEG" in
the JPEG Object Info Box.

1.2.2) JPEG Objects and the envelope and perspective tools

JPEG objects cannot be perspectivized or enveloped. Unfortunately, there is no
way for the JPEGObject module to tell the Perspective and Envelope tools. All
JPEGObject can do is display an error message when you select either tool while
a JPEG object is selected. You should then simply select some other tool
without moving any of the control points (you will just get another error if
you nevertheless try this). Please note that if you have several JPEG objects
selected while selecting the Perspective and Envelope tool, then you will get
one error message for each object.

Further limitations are listed in section 2 (bugs and limitations).

1.3) Rendering quality
----------------------
The rendering quality of the JPEG depends on the WYSIWYG setting: At low values
(3 or below), an outline is shown. Below 9, the JPEG is rendered without colour
dithering, so the image is rendered more quickly at the expense of a low image
quality. At levels 9 or above, colour dithering is used.

At the highest WYSIWYG level (the one giving you anti-aliasing for shapes),
error diffused dithering is used for maximum rendering quality. Error diffusion
requires a lot of procesing power, so you may find the redraw too slow even
on a StrongARM machine. In case you do not want JPEGs to be displayed with
error diffusion even at the highest WYSIWYG level, you can disable error
diffusion in the JPEG choices window (see 1.5).

1.4) Draw and EPS export
------------------------
JPEGObject supports Draw and EPS import and export.

1.4.1) Draw export

ArtWorks JPEG objects are exported either as Draw JPEG objects (suitable for
RISC OS 3.6 or higher) or they can appear as sprite objects in the Draw file.
The exact circumstances are determined by the JPEG choices (see 1.5).
Obviously, representing images as a Draw JPEG objects results in much smaller
Draw files. However, it requires a more recent version of RISC OS to display
the file.

If a JPEG object is exported as a sprite (because either the first option
"Create JPEG objects" has been deselected or because the JPEG is transformed
and the second option "Create transformed JPEG objects" has been deselected),
then this is a true colour (16M colours) sprite. This means that at least RISC
OS 3.5 is required to display the resulting Draw file.

1.4.2) EPS export

JPEG objects only appear in ArtWorks EPS output, not when exporting in any
other EPS flavour. However, in the case of ArtWorks EPS, the exported EPS is
fully renderable in PostScript engines, so the current graphics applications
under Windows and MacOS that contain full PostScript engines (e.g., Adobe
Illustrator) will be able to render the image (although they will probably
decompress the JPEG when importing it).

1.4.3) Draw and EPS import

JPEG objects are correctly imported from Draw files exported by ArtWorks or
created by other applications (e.g., RISC OS 3.6 Draw) and from ArtWorks EPS
files.

1.5) JPEG choices
-----------------
You can find the JPEG choices dialogue box by chosing "Choices..." from the
ArtWorks icon bar menu and clicking on the "JPEGObject" panel in the ArtWorks
choices window.

When exporting to Draw, two choices options determine the format of ArtWorks
JPEG objects in exported Draw files. The reason for such a choice is that the
versions of Draw issued with different versions of RISC OS have different
capabilities: Only the version of Draw issued with RISC OS 3.6 or higher can
render JPEG objects, and even then, it is not capable of rendering rotated,
skewed or flipped JPEGs. Such a capability may be introduced in future versions
of RISC OS, but this has not happened so far (with RISC OS 4.03 at the time of
writing). OvationPro, however, seems to be ahead of its time as it is able to
display transformed JPEG objects.

Therefore, there are two choices: Whether the include any JPEG objects at all
in the exported Draw file (if not, Sprites are used), and whether to include
"transformed" (i.e., rotated, skewed or flipped) JPEG objects (if not, again, a
Sprite is used). If you decide to include transformed JPEGs, then you may find
that currently, very few applications are capable of displaying them,
OvationPro being the most notable exception.

Unless you want to export specifically to OvationPro, it is recommended to use
the standard settings: "Create JPEG objects" ON and "Create transformed JPEG
objects" OFF.

The third option determines whether or not error-diffused dithering is used
when rendering JPEG objects on screen. If you switch this option off, redraw
speed is increased at the expense of lower image rendering quality. Please note
that rendering to a Sprite for Draw export is not affected by this option -
this always uses error diffusion for maximum quality.

1.6) Exporting to Impression, OvationPro, Composition etc.
----------------------------------------------------------
Please note that Impression, Ovation Pro and other programs that claim to
render ArtWorks files are only able to render JPEG objects if version 1.35 or
higher of AWRender (the ArtWorks rendering module) is installed. AWRender is
part of the free AWViewer utility that can be downloaded from:
  http://www.mw-software.com/software/awmodules/awrender.html#download

The original version of AWRender as published by Computer Concepts only copes
with the object types that were known to ArtWorks 1.1, so if such an old
version of AWRender is installed, Impression and other applications do not
display JPEG objects. If you want to make sure that JPEG objects are always
displayed correctly in other applications irrespective of the version of
AWRender that is installed, you have to use Draw export. However, this has
several drawbacks and it should not normally be necessary because it should be
easy enough to make sure that AWRender 1.35 or higher is installed.


2) Bugs and limitations
-----------------------
2.1) Printing
-------------
There is one major limitation when printing: Colour separation does not work
for JPEGs, i.e. you can only display and print them in full colour.

There is a bug in Printers 1.64 that causes JPEGs to be printed at half size.
JPEGObject 1.07 and higher contain code to work around this bug: If the version
number of PDriverDP is 4.49 or higher, then JPEGObject simply prints JPEGs at
twice the size to compensate for the Printers bug. To avoid any problems with
future versions of Printers that might have a bug fix for this problem, there
is a configuration option "Printers 1.64+ print fix". If you have a version of
Printers higher than 1.64a and if JPEGs print twice the size, then simply
switch this option off to disable the workaround code.

The RISC OS 5 printer drivers do not have the above bug, but some have a
version number higher than 4.49. Therefore, when running on a 32-bit version of
RISC OS, the print fix is disabled automatically as it is not necessary.

Currently, printing to Computer Concepts Turbo Drivers and Laser Direct is not
supported. This issue may be resolved in a later version of JPEGObject.

2.2) JPEG file support
----------------------
If the pixel density in the JPEG is specified as a pixel aspect ratio instead
of absolute dpi values, then a bug in SpriteExtend prevents JPEGObject from
interpreting the ratio. In this case, square 90dpi pixels are assumed.

JPEGObject uses the SpriteExtend module for JPEG handling. That means that
JPEGObject is only able to render those JPEG images that can be handled by
SpriteExtend. Recently, many non-standard JPEG files have appeared (mainly
created by digital cameras) that are not understood by SpriteExtend. In order
to use them with JPEGObject, you can feed them through !CleanJPEG or any other
utility for cleaning JPEGs. At the time of writing, CleanJPEG is avilable from
http://www.sliced.demon.co.uk/software/cleanjpeg/


3) History
----------
Version 1.18 (30-Sep-03)
- Printers 1.64+ print fix was broken since version 1.16 - fixed

Version 1.17 (24-Sep-03)
- minor internal correction

Version 1.16 (29-Aug-03)
- dpi field in info window
- "Save" button in info window

Version 1.14 (12-Jun-03)
- added skew support

Version 1.13 (04-May-03)
- 32-bit compatible version for ArtWorks 2

Version 1.12 (04-May-03)
- important bug fix: non-upright JPEGs that were scaled down below a certain
  percentage were printed much too large by earlier versions of JPEGObject -
  this is finally fixed!

Version 1.11 (12-May-02):
- tries to support printing to Computer Concepts' LaserDirect - untested and
  most probably, not working

Version 1.10 (28-Mar-02):
- allows Alpha attributes to be applied (support for Crystal tool)

Version 1.09 (06-Dec-01):
- "Printers 1.64+ print fix" option in the dialogue box is working and the flag
  is actually taken into account

Version 1.08 (05-Dec-01):
- beta test version
- workaround for Printers 1.64 printing problem - for some reasons, JPEGs
  printed at half size with Printers 1.64 - JPEGObject 1.07 now simply prints
  JPEGs twice as big if PDriverDP 4.49 or higher is used - if you have a
  version of Printers higher than 1.64a and JPEGs print at twice the size, then
  you can switch off the "Printers 1.64+ print fix" option in the JPEGObject
  preferences dialogue box
- massive improvement for printing rotated JPEGs: previous versions of
  JPEGObject had a bug that constrained printing resolution of rotated JPEGs to
  90dpi leading to very poor print quality
- due to probably another bug in Printers 1.64, rotated JPEGs used to print
  inverted on LaserJet printers - this is fixed now

Version 1.07 (26-Nov-01):
- unreleased test version

Version 1.06 (03-May-01):
- minimal change in object description handling, corrected version number
- fixed bug: reading choices works correctly even if QuickStart is used
  (choices options were ignored due to a bug that only surfaced in
  conjunction with QuickStart)

Version 1.05 (25-Apr-01):
- fixed problem with Replicate: only the original JPEG object could be
  selected, not the replications

Version 1.04 (27-Mar-01):
- fixed Draw export - only the bottom left quarter of exported JPEG images was
  rendered and selectable
- at certain scale factors, rotated JPEGs sometimes had a black border at the
  top an the right - fixed

Version 1.03 (27-Mar-01):
- fixed error handling code to deal with JPEG files that are not understood by
  SpriteExtend - led to "Operation failed" error when importing the next JPEG

Version 1.02 (20-Mar-01):
- ArtWorks EPS parameters include the flag word
- checks the version of T_Draw installed on startup and displays an error if
  T_Draw is too old to support Draw JPEG objects

Version 1.01 (09-Mar-01):
- Object info box Size/Scale radio buttons shade/unshade the input
  fields correctly
- Change scale/aspect works correctly for JPEGs with non-square pixel JPEGs
- Selector shows "JPEGs" instead of "!" when multiple JPEG objects are selected
- Reset JPEG button works correctly
- Interface with T_Draw changed (ajd EPS procedure in both directions, width/
  height always sent in Draw coords)
- JPEG with pixel densities other than 90:90 dpi are import and exported
  correctly from/to Draw format

Version 1.00 (08-Mar-01):
- first full release with choices window, EPS import/export and Draw
  import/export enabled

Version 0.91 (28-Feb-01):
- second beta release with handle dragging and the JEPG object info box enabled

Version 0.90 (25-Feb-01):
- first beta release


4) 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/


5) Copyright
------------
The ArtWorks JPEGObject 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 JPEGObject
module and its related files, now.
