AWViewer 1.51c (16-Jan-2003)
AWRender 1.51  (21-Sep-2002) "Plus" version

This version of AWViewer runs under RISC OS 3.1 to RISC OS 4 and RISC OS
Select. It does not run under RISC OS 5.

Under RISC OS 3.5 or higher, AWViewer 1.61 or higher should be used in
preference. The only reason this version is still available is for RISC OS 3.1
compatibility.

AWRender
========
This copy of AWViewer contains an updated AWRender module. AWRender is the core
module of the ArtWorks viewer. It is a cut-down version of the main ArtWorks
application containing rendering code only.

This version of AWRender "Plus" supports ALL currently defined ArtWorks objects
and fill types (but see below under "Limitations") including Hatch(Pro) fills,
deep sprites (32k or 16M colours), JPEG objects, replicates and text areas.
This means that your ArtWorks files are rendered in the same way in third-party
applications like OvationPro as in ArtWorks (with transparency switched off).

See the section "Technical details" below for further details.

Installation
============
Third-party applications that display ArtWorks files should load the required
support modules from the AWViewer application. This means that you need not
take any special action to enable applications such as OvationPro to use the
updated version of the AWRender module: You only need to remove any outdated
versions of !AWViewer from your hard disc and make sure that this version of
AWViewer has been 'seen' by the Filer before you run OvationPro or any other
application rendering ArtWorks files.

Impression Style and Publisher keep their own versions of the support modules
in !Style.RMStore or !Publisher.RMStore respectively. In order to make these
applications use the latest modules, the modules from inside !AWViewer.RMStore
need to be copied to Impression's RMStore directory. In addition, there are
copies of the modules in !System.!CCShared.RMStore that should be replaced by
the new versions inside !AWViewer.RMStore.

The file !InstMods within the !AWViewer application does this automatically:
Simply double-click on !InstMods to update your copy of Impression Style,
Impression Publisher(+), Spacetech's OHP2, Thump, Thumbnail, ArtWorks, AWViewer
(if present in Boot:Resources as under Select) and CCShared. If you get the
error message "File 'IfThere' not found", then you do not have the IfThere
utility that is supplied with the RISC OS boot sequence. In this case, you have
to do the installation manually as described in the previous paragraph.

There are other applications that came with their own copies of the ArtWorks
rendering modules. You have to replace copies of the ArtWorks rendering modules
manually. Known applications are !Genesis (in !GenLib), DrawWorks Millennium
(in Resources), HyperStudio (!HStudio, !HSPLAYERF and !HSPLAYER), OHP-Demo
(!OHP_SHOW) and !PickAPic.

After installing this updated AWViewer application you should reboot your
machine to avoid any problems in case older versions of the modules are already
in memory.

AWRender 1.51 has been successfully tested with AWViewer, Impression Publisher,
OvationPro, PhotoDesk and ArtToSpr. If you have written an application that uses
AWRender and you experience any problems, please contact me.

Making sure that GSpriteExtend is loaded
========================================
Please note that you really should have GSpriteExtend loaded when using
AWRender 1.38 or higher. The GSpriteExtend module is supplied as
!AWViewer.RMStore.SpriteExt. Applications that load the ArtWorks rendering
modules in the recommended way (using *LoadArtWorksModules) automatically load
GSpriteExtend as well. Most applications, however, do not. This includes OHP,
Impression and OvationPro.

You can either fix these individual applications (see below), or, if you want
to avoid the complexity of doing this and if you do not mind wasting 28k of
memory, then you can simply load GSpriteExtend in your boot sequence. To do so,
put !AWViewer in !Boot.Resources. Then, put an Obey file called "SpriteExt"
containing the following line in !Boot.Choices.Boot.Tasks:

If "<ArtWorksModules$Path>" <> "" Then RMEnsure GSpriteExtend 0.68 RMLoad ArtWorksModules:SpriteExt

Making individual applications load GSpriteExtend
-------------------------------------------------
If you do not want to load GSpriteExtend in your boot sequence, you can make
applications (other than OvationPro) load GSpriteExtend by adding the
following two lines to their !Run files:

If "<ArtWorksModules$Path>" = "" Then Error 0 AWViewer has not been seen!
RMEnsure GSpriteExtend 0.68 RMLoad ArtWorksModules:SpriteExt

Users of OvationPro are advised to add the following lines to
!OvnPro.Applets.!OArtWrks.!Install just before the last line that reads
"Set OvationPro$ArtWorks 1":

| Load GSpriteExtend for AWRender 1.38 or higher
Set AWRender138$Present "True"
RMEnsure ArtworksRenderer 1.38 Set AWRender138$Present "False"
Set GSpriteExtend$Needed "False"
If "<AWRender138$Present>" = "True" Then RMEnsure GSpriteExtend 0.68 Set GSpriteExtend$Needed "True"
If "<GSpriteExtend$Needed>" = "True" Then Run "<OArtWrks$Dir>.IfExists" <CCShared$Dir>.RMStore.SpriteExt Then RMLoad <CCShared$Dir>.RMStore.SpriteExt
If "<GSpriteExtend$Needed>" = "True" Then RMEnsure GSpriteExtend 0.68 Run "<OArtWrks$Dir>.IfExists" ArtWorksModules:SpriteExt Then RMLoad ArtWorksModules:SpriteExt
If "<GSpriteExtend$Needed>" = "True" Then RMEnsure GSpriteExtend 0.68 Error 0 The !OArtWrks applet needs GSpriteExtend 0.68 or newer
Unset GSpriteExtend$Needed
Unset AWRender138$Present
| Done

Support modules
===============
This copy of AWViewer contains patched versions of GDraw, DitherExtend and
GSpriteExtend. The patches are:

GSpriteExtend 0.68
------------------
This version of GSpriteExtend contains a bug fix for rendering masked deep
sprites (32k or 16M colours). This bug not only surfaced in ArtWorks, but also
in Impression. Previous versions of GSpriteExtend interpreted the mask in the
wrong way: It was offset by one pixel horizontally. The most obvious symptom
was an additional visible solid pixel column (often white) at the right hand
edge of masked deep sprites, but depending on the source sprite data, there
could also be additional noticeable visual defects.

In contrast to earlier versions of AWRender, versions 1.38 and higher make use
of the GSpriteExtend module if it is loaded: This module allows AWRender to
display deep sprites with error diffused dithering leading to vastly improved
display quality in screen modes with 256 colours or less. It also allows
AWRender to display and print deep sprites under RISC OS 3.1! Finally, it
allows AWRender to render 256 colour sprites correctly in screen modes with
more colours.

Third-party applications loading the rendering modules in a non-standard way do
not normally load GSpriteExtend. See "Making sure GSpriteExtend is loaded"
below for information on how to update such applications.

DitherExtend 0.50
-----------------
DitherExtend 0.50 works with ViewFinder in 16bpp modes - this fix was provided
by David Bryan <D.J.Bryan@cranfield.ac.uk> and slightly optimised by me.

GDraw 2.97
----------
The anti-aliasing code in GDraw 2.95 was limited to 4096 bytes per screen line
- at 16M colours, this limited the screen width to 1024 pixels only. GDraw
rendered incorrectly to larger screen modes and bitmaps exported using BMExport
were corrupted if the width was higher than 1024 pixels. Very large sizes could
even crash the machine (more than 4096 pixels at 16M colors). GDraw 2.97 as
included with this version of AWViewer removes this restriction completely.
This means that GDraw works correctly in any resolution provided by the
ViewFinder card (e.g., 1600x1200 at 16M colours) and high-resolution bitmap
export with BMExport works at any resolution.

GDraw 2.97 supersedes GDraw 2.95 patch 2 and contains its patches, too: The
clipping buffer has been increased from 16k to 256k, so more complex drawings
can be exported as Draw and EPS, more complex shapes can be intersected using
the Intersect tool and more complex shapes can be filled with fill patterns
using the Hatch and HatchPro modules. Credits are due to Matthias Seifert
(M.Seifert@t-online.de) for first disassembling GDraw and providing the
clipping buffer patch.

GDraw 2.96 had problems with very small graphics modes, e.g., when exporting a
document as a sprite with a width of 34 pixels using BMExport. The output
contained a vertical line. This is fixed in GDraw 2.97.

ImageExtend
-----------
There has been some confusion about ImageExtend in that there is a version 0.80
with a later file date than version 0.81. This distribution includes version
0.81 because it is indeed a later version than 0.80. It does not make any
difference, however, because this module is only needed for RISC OS 2 support.

Distributing the renderer modules with your application
=======================================================
Publicly released versions of the AWViewer utility as available from the MW
Software web site (see next paragraph)  can be distributed freely subject to
the conditions specified in the file !AWViewer.!ReadMe.

You may NOT distribute any of the support modules contained within AWViewer on
their own or embedded in other applications. If your application needs the
ArtWorks rendering modules, simply distribute the latest AWViewer utility with
your application and advise your users that the latest version of AWViewer can
always be found at
  http://www.mw-software.com/software/awmodules/awrender.html#download

If you have a licensing agreement with Computer Concepts and you wish to
continue supplying the ArtWorks rendering modules with your application, you
are strongly encouraged to include the latest versions as contained within the
latest publicly released AWViewer. Please note, this only applies to you if you
have permission from Computer Concepts to distribute the modules in the first
place. If you have this permission, you also have my permission to distribute
the latest publicly released versions of these modules. You may not distribute
modules from versions of AWViewer marked as BETA or the 32-bit safe versions in
AWViewer 1.61 or higher.

Impression and JPEG images
==========================
This updated version of AWRender allows you to finally use JPEG images in your
Impression documents. All you need is ArtWorks and the JPEGObject plug-in
module. Then, you can simply create an ArtWorks document containing a JPEG
image by dropping the JPEG file onto an empty ArtWorks document window. Then,
drop the ArtWorks file into an Impression frame. The JPEG image is then stored
in its compressed native JPEG format in the Impression document.

It is worth noting that PostScript output of (unrotated) JPEG images using the
RISC OS PostScript printer driver usually gives much better results than sprite
output due to the way sprites are printed to PostScript under RISC OS.

Limitations:

Please note that colour separated output is not available for JPEG images
imported into Impression this way. If you need colour separation, then you
will have to convert the JPEG image to a sprite.

Impression does not display JPEGs in irregular frames correctly. This is purely
a limitation in Impression, so this is very unlikely to be addressed. Rotated
JPEGs in irregular frames are displayed with the wrong colours but print
correctly whereas upright JPEGs in irregular frames are not clipped to the
irregular frame border.

JPEG printing
=============
There is a bug in Printers 1.64 that causes JPEGs to be printed at half size.
AWRender 1.35 or above contain code to work around this bug: If the version
number of PDriverDP is 4.49 or higher, then AWRender 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 way to turn this print fix off: In case you experience JPEGs to be
printed at twice the size you expected, then you can disable the JPEG print
fix using the following command:
  *Set AWRender$DisableJPEGPrintFix "True"
The value of the variable is not important, what matters is that it is there
(so setting it to "False" would have the same effect). The command
  *Unset AWRender$DisableJPEGPrintFix
restores AWRender to the default state (print fix enabled). The system
variable is checked every time you start printing.

Technical details
=================

Rendering
---------
Deep sprite rendering in AWRender 1.51:
- If GSpriteExtend is loaded (supplied with this version of AWViewer, but some
  applications may not load it automatically), then deep sprites are even
  rendered and printed on RISC OS 3.1 machines, else on RISC OS 3.5 or higher
  only.
- If GSpriteExtend is loaded, deep sprites are rendered using error diffused
  dithering in screen modes with 256 colours or less for highest display
  quality.
- See below (under the heading "Making sure GSpriteExtend is loaded") for
  further details about making GSpriteExtend available to AWRender.

AWRender 1.51 does NOT support the following ArtWorks features:
- Transparency (created using the Crystal tool) - the file is rendered in the
  same way as when the "Display" option in Crystal is switched off

Limitations in AWRender 1.51:
- JPEG objects cannot be rendered with colour separation - they are always
  rendered in full colour. This also means that external colour processing
  options (e.g., Picture => Process in OvationPro) are ignored.
- Deep sprites (32k or 16M colours) are not rendered with colour separation -
  they are always rendered in full colour. This also means that external colour
  processing options (e.g., Picture => Process in OvationPro) are ignored.

Future versions of AWRender may add support for JPEG colour separation and deep
sprites colour separation. New versions of the modules that will run in 32-bit
mode (i.e., under a 32-bit RISC OS) are under development.

In contrast to earlier versions, AWRender 1.36 and above can be called from SVC
mode, so they can be called by relocatable module code (e.g., PhotoFiler). In
contrast to earlier versions, AWRender 1.37 supports a new colour callback that
works with full 32-bit addresses, which allows applications (e.g., OvationPro)
to hold ArtWorks files in dynamic areas which might be at high addresses. See
the section "Technical details" below for further details on both changes.

SVC mode operation
------------------
AWRender 1.36 and above support SVC mode operation. Both the entry points
returned by AWRender_FileInitAddress and by AWRender_RenderAddress may be
called with the processor in SVC mode. The client callback routine will then
be called in SVC mode as well. Before calling any AWRender entries with the
processor in SVC mode, any client should make sure that AWRender 1.36 or
higher is present. To make this easier, AWRender 1.33 and above support a new
SWI:

                                                            AWRender_Version
                                                            (SWI &46089)
    Find out about the version of AWRender.

On entry
    -

On exit
    R0 = version number of AWRender * 100 (e.g., 136 for AWRender 1.36)

Use
    Clients wanting to call AWRender in SVC mode should call the X-form of this
    SWI to find out whether AWRender supports this feature. If the SWI is
    faulted, then the version of AWRender present is 1.32 or earlier and does
    not support being called in SVC mode. If the SWI returns without an error,
    then R0 contains the version number. If the version number is 136 or
    higher, then AWRender supports being called in SVC mode.

New colour callback
-------------------
AWRender 1.37 and above support a new colour callback that allows colour
pointers to be full 32-bit pointers, so ArtWorks files at high addresses in
dynamic areas can be rendered correctly. Please note that the information below
will not make sense unless you know the AWRender interface. However, if you
have written an application that uses AWRender, you will know it. If you
haven't then this information is not for you anyway.

First of all, AWRender 1.37 sends a callback to enquire which interface the
client supports:

CallBackReason_Interface (3)
entry. r11 = 3
       r0  = 0
exit.  r0 = client interface capabilities mask
         bit 0 set => use CallBackRason_PlateColour2 with full 32-bit
                      pointers for colour definitions

This CallBack will be called once when rendering starts to find out whether the
client is aware of new interface features.

CallBackReason_PlateColour2 is a new colour separation callback with slightly
changed parameters. It is used if the client returns r0 with bit 0 set from
CallBackReason_Interface - in this case, CallBackReason_PlateColour is not used
at all. The idea is that this way, the client can work with both the old and
the new AWRender without changing the existing code. Simply add support for
CallBackReason_Interface and CallBackReason_PlateColour2. Likewise, AWRender
1.37 can work both with clients that support the new interface and with clients
that don't (but of course, clients that don't support the new interface, will
not render ArtWorks files at high addresses properly).

CallBackReason_PlateColour2 (4)

entry. r11 = 4
       r0 = RGB colour word
       r1 see below
       r2 = tint percentage
       r3 see below
       r4 = flags

Flags in r4:

r4 bit 29, 30 or 31 set => colour definition is a literal colour
Then:
       r1 = literal colour definition (including the flags in the top
            byte as before, r4 has copies of bits 29, 30 and 31 only)
       r3 undefined

r4 bits 29, 30 and 31 clear => colour definition is a named colour
Then:
       r1 => base colour definition (in ArtWorks format), all bits of r1
             are significant
       r3 = original colour index (overprint flag in bit 24)

exit.  as before

History
=======
- AWViewer 1.51c (16-Jan-03)
  Public release version.
  Added !Help file, updated !ReadMeMW (this file).
- AWViewer 1.51b (31-Oct-02)
  AWViewer claims the ArtWorks file type if no other application has claimed
  it, so you can now double-click on an ArtWorks file to launch the viewer.
  Thanks to Alex Macfarlane Smith for suggesting this and modifying !RunImage
  accordingly.
  Changed ArtWorks file icons to RO4 style (loaded if RO4 is present), thanks
  to RiscOS Ltd. for designing them.
- AWViewer 1.51 (21-Sep-02)
  AWRender 1.51: fixed crash when the first file loaded contained a deep sprite
  (reloc code register corruption problem), added workaround for PhotoDesk bug
- AWViewer 1.50 (19-Sep-02)
  AWRender 1.50 with text area and replicate object rendering.
- AWViewer 1.40 (27-Aug-02)
  Fixed another bug that caused AWRender to crash when printing (occurred with
  files containing no sprites at all). Fixed incorrect bounding box computation
  if one of the new grid types provided by the Grids module is switched on in
  the file.
- AWViewer 1.39 (13-Aug-02)
  Fixed bug that caused AWRender to crash when rendering deep sprites if
  GSpriteExtend was not loaded. Fixed bug that caused AWRender to crash
  when printing.
- AWViewer 1.38 (12-Aug-02)
  AWRender 1.38 with deep sprite rendering (and rudimentary text area support)
- AWViewer 1.37 (23-Jul-02)
  AWRender 1.37 with new colour callback supporting full 32-bit addresses
- AWViewer 1.36d (03-May-02)
  Added a bit of support for the ArtWorks Updater using the !InstMods script
- AWViewer 1.36c (22-Mar-02)
  !InstMods installs new GSpriteExtend into ArtWorks as well
  Updated this file with some more third-party applications.
- AWViewer 1.36b (26-Feb-02)
  includes GSpriteExtend 0.68
  !InstMods should now correctly update PublisherPlus as well
- AWViewer 1.36 (11-Feb-02)
  Fixed a final problem in SVC mode. So, only AWRender 1.36 or above are
  SVC-safe.
  Added file integrity checking because there are several corrupt files on
  clipart CDs etc. If the file is corrupt AWRender 1.36 is most likely to
  cleanly return an error instead of crashing.
  The !InstMods script updates !AWViewer in Boot:Resources if present
  (standard place in RO Select)
- AWViewer 1.35 (08-Dec-01)
  The JPEG rendering code in AWRender 1.35 has been updated with the changes
  introduced with JPEGObject 1.09. These are:
  - added print fix code to work around a bug in Printers 1.64a (the print fix
    can be disabled by creating the system variable
    AWRender$DisableJPEGPrintFix - see "JPEG printing" above
  - corrected scaling routines (earlier versions of AWRender restricted
    printing resolution of rotated JPEGs to only 90dpi)
  - corrected printing of rotated JPEGs to LaserJet (appeared inverted with
    older versions of AWRender)
- AWViewer 1.34 (06-Dec-01)
  AWRender 1.34 has been extended to run in SVC mode (only of interest to
  developers wanting to call AWRender from relocatable module code)
- AWViewer 1.33 (02-Nov-01)
  Updated required version number for GDraw and AWRender in LoadRMs script
  AWRender 1.33 has a bug fix for rendering user-defined fill patterns.
  AWRender 1.32 or below crashed when they encountered the second file with
  user-defined fill patterns.
- AWViewer 1.32e (14 Aug 01)
  GDraw 2.96 rendered incorrectly to very small graphics modes (e.g., when
  exporting icons with a width of 34 pixels using BMExport) - fixed in GDraw
  2.97 as included in this release
- AWViewer 1.32d (09 Aug 01)
  includes DitherExtend 0.50 with ViewFinder fix
  includes GDraw 2.96 (allows higher resolutions with ViewFinder and BMExport)
  includes ImageExtend 0.81 instead of ImageExtend 0.80 (does not make any real
  difference, just for the sake of including the absolutely latest version)
  updated !InstMods script to install the relevant modules into the ArtWorks
  application as well
- AWViewer 1.32c (12 Jun 01)
  Updated !InstMods script slightly
- AWViewer 1.32b (06 Jun 01)
  AWViewer 1.31 and 1.32 accidentally included an original version of GDraw 2.95
  without Matthias Seifert's patch. The !InstMods script copies GDraw as well,
  so this might have unpatched your copy of GDraw.
- AWRender 1.32 (06 Jun 01)
  fixed bug: Impression failed when loading a document with an embedded
             ArtWorks file (embedding an ArtWorks file in a new doc worked)
- AWRender 1.31 (04 Jun 01)
  first public release of updated AWRender

Contact information
===================
MW Software
Martin Wuerthner
Mannheimer Str. 18
67655 Kaiserslautern
Germany

Tel +49 631 3608205
Fax +49 631 3608203

martin@mw-software.com
http://www.mw-software.com/
