AWViewer 2.18 (12-Apr-2018)
AWRender 2.16 (12-Nov-2011) "Plus" version, 32-bit compatible,
                            ARMv7 safe, supports all ArtWorks 2.X objects,
                            supports transparency and shadows,
                            multi-page API, LTRGB-mode-enabled

Contents: 1. Introduction
            1.1 AWRender
            1.2 Transparency
          2. Installation
            2.1 General instructions
            2.2 Notes for specific applications
              2.2.1 OvationPro
              2.2.2 Easi/TechWriter
              2.2.3 Impression
            2.3 Advanced options
          3. Technical details
            3.1 Limitations
            3.2 Support modules
            3.3 Updated AWRender API
          4. Distributing the renderer modules with your application
          5. History
          6. Contact information

Preface
=======
This file contains installation instructions for AWViewer and the ArtWorks
rendering modules. Please read at least sections 1. and 2. in order to ensure
optimal ArtWorks rendering support in your applications. The subsequent
sections provide details for programmers that can be safely ignored by users.

You can find information on how to use AWViewer in the file !Help and details
about the copyright status of AWViewer and the rendering modules in !ReadMe.

Warning: This copy of AWViewer is suitable for RISC OS 3.5 or higher ONLY,
i.e., RiscPC, A7000[+], RS7500, Omega, Iyonix, A9Home, VirtualRPC, BeagleBoard,
ARMini, Raspberry Pi, Pandaboard, ARMiniX, IGEPv5, Titanium.

This version renders correctly to the new "LTRGB" screen modes used by the
IGEPv5 (RapidO) and Titanium platforms (in 32 thousand, 64 thousand and 16
million colours), by the Raspberry Pi (in 64 thousand colours) and by the
Iyonix when driving a monitor via DVI (in 32 thousand, 64 thousand and 16
million colours).

Distributing the renderer modules with your application
-------------------------------------------------------
Publicly released versions of AWViewer as available from the MW Software web
site (see next paragraph) can be distributed 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

Any licensing agreement you may have with Computer Concepts that used to allow
you to ship the ArtWorks rendering modules inside your application does not
cover the 32-bit compatible versions of the rendering modules. This means that
when converting your application to 32-bit, you may have to change the way the
modules are loaded: Please make sure that the application loads the rendering
modules from !AWViewer using the standard *LoadArtWorksModules command.

1. Introduction
===============
1.1 AWRender
============
The most important component of AWViewer is AWRender, the ArtWorks rendering
module. It is a cut-down version of the main ArtWorks application containing
rendering code only. This module enables third-party applications to render
ArtWorks files.

This version of AWRender supports *all* currently defined ArtWorks 2.6 object
and fill types including Hatch(Pro) fills, 256 colour sprites in deep colour
modes, deep sprites (32k or 16M colours), JPEG objects, replicates, text areas,
ClipView objects, rainbow blends, the new ArtWorks 2.6 arrowheads, files with
multiple pages and shadows.

See the section "Technical details" below for further details and for a list of
limitations of AWRender. This is particularly relevant if you require colour
separated output (if you do not know what this is you will not need it).

1.2 Transparency
================
This version of AWRender supports transparency (Crystal). This means that
third-party applications render your ArtWorks files in exactly the same
way as ArtWorks even including advanced transparency effects.

Please note: Transparency support is limited to transparency *within* the
ArtWorks file. AWRender cannot blend transparent ArtWorks objects into graphics
drawn by the client application, e.g., into the contents of an OvationPro frame
underneath the frame holding the ArtWorks file. AWRender can blend transparent
objects into the frame background of the client application, but that requires
some extra support currently only available in Easi/TechWriter 8.60 (though
other applications will probably follow, most notably OvationPro).

In general, best results are obtained with transparency if the frame holding
the ArtWorks file has a solid colour background that is the same as the page
colour stored in the ArtWorks file (usually white).

1.3 Printing with transparency
==============================
Please note that *printing* with transparency requires additional application
support so client applications might have to be updated. Please make sure that
you read the section titled "Notes for specific applications" below.

PostScript printing
-------------------
For on-screen rendering of documents with transparency AWRender behaves as if
the paper background was fully transparent, i.e., in areas that are not covered
by ArtWorks objects, the underlying graphics drawn by the client application
can be seen through. This is not guaranteed for PostScript printing though,
which may introduce additional areas filled with the background colour. This
does not cause any problems as long as the frame holding the file has a solid
background in the same colour as advised above.

Since PostScript level 2 does not support any transparency, ArtWorks files with
transparency are printed as a large bitmap. The resolution of this bitmap is
usually 300dpi but this can be changed (see "2.3 Advanced options" below).

Usually, PostScript printing with transparency does not use any anti-aliasing,
but it can be switched on if desired (see "2.3 Advanced options" below).


2. Installation
===============
2.1. General instructions
=========================
Preferred location of !AWViewer
-------------------------------
The preferred location for !AWViewer for all versions of RISC OS is in the
directory !Boot.Resources.

Apart from the copy in !Boot.Resources you should remove all other copies of
!AWViewer from your hard disc to make future updates easier.

The only drawback of having !AWViewer in !Boot.Resources is that it is not easy
to find it if you want to launch it to display ArtWorks files without the help
of any other application. Therefore, you may want to add !AWViewer to your Apps
directory on the icon bar. This is done as follows: Double-click on !Boot, then
click on "Boot", then "Add to Apps" and drag !AWViewer from the !Boot.Resources
directory to the list in the "Add to Apps folder" window. This makes !AWViewer
appear in the Apps folder on the icon bar.

Installation under RISC OS 5
----------------------------
The correct place for !AWViewer to live under RISC OS 5 is in the directory
!Boot.Resources. Simply move it there.

You may have a CCShared directory set up to run Impression under Aemulor. This
may be at !Boot.Resources.!CCShared or !Boot.Resources.!System.!CCShared. If
so, it contains an RMStore directory with modules that need to be updated as
well. Simply copy the modules from !AWViewer.RMStore to !CCShared.RMStore.

Please note that Impression under Aemulor on the Iyonix requires some special
attention to allow it to use 32-bit versions of AWRender to display ArtWorks
files. See "Impression, Aemulor and AWRender" in section 2.2.3 below.

Installation under RISC OS 3.5, 3.6, 3.7, 4, Select/Adjust and RISC OS 6
------------------------------------------------------------------------
The correct place for !AWViewer to live is in the directory !Boot.Resources. If
you run Select, there is a copy in this place anyway. Otherwise, you are
advised to copy !AWViewer to !Boot.Resources.

Then, you need to run the obey file !InstMods inside !AWViewer.

This script updates your copy of !AWViewer in !Boot.Resources (only if there is
a copy in this directory already) and it does its best to update the modules in
other places, too.

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.

Unfortunately, some applications keep their own versions of the support
modules. In order to make these applications use the latest modules, these
modules need to be updated. The obey 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 1, !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 replace the modules manually.

There are other applications that come 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, but there are likely to be more.

Installation on the A9Home
--------------------------
Proceed as above for RISC OS Select.

Please note that Impression under Aemulor on the A9Home requires some special
attention to allow it to use 32-bit versions of AWRender to display ArtWorks
files. See the section "Impression, Aemulor and AWRender" below.

Installation under RISC OS 3.1
------------------------------
This copy of AWViewer is only suitable for RISC OS 3.5 or higher. You can find
a copy that works with RISC OS 3.1 (and possibly/partly with RISC OS 2) on the
MW Software web site:
  http://www.mw-software.com/software/awmodules/awrender.html#download

2.2 Notes for specific applications
===================================
AWRender 2 enables all applications that support ArtWorks files to *display*
files with transparency on screen. Transparent *printing* requires a bit of
extra support from client applications. Without this extra support, files are
printed without transparency.

2.2.1) OvationPro
-----------------
In order to print with transparency, OvationPro requires an updated ArtWorks
applet. This applet is included in the AWRender 2 archive.

2.2.2) Easi/TechWriter
----------------------
Easi/TechWriter 8.6 supports printing with transparency. If you have an earlier
version, please contact Icon Technology to enquire about update options:
  http://www.icontechnology.co.uk/

2.2.3) Impression
-----------------
At the time of writing, Impression has not been updated to support printing
with transparency on all versions of RISC OS. Using AWRender 2.08, Impression
can print with transparency under RISC OS 6, but not yet under other versions
of RISC OS. A patch might be supplied later, or alternatively, an updated
PDriver module for other versions of RISC OS to add support for the new
RISC OS 6 "current rectangle" interface used by AWRender.

Impression, Aemulor and AWRender
--------------------------------
Impression (Style, Publisher or Publisher+) under Aemulor (Lite or Pro) on the
Iyonix or A9Home cannot make use of 32-bit versions of AWRender. This is a
limitation of Aemulor. Future versions of Aemulor may address this issue. Until
then, some special action has to be taken to convince Impression (or other
26-bit programs with ArtWorks support) to display ArtWorks files.

The way to do this is to load a copy of AWRender that claims to be 26-bit
only. This can then be emulated by Aemulor and used by Impression (or other
emulated 26-bit programs that use AWRender). Such a copy has been provided
as AWRender26 in the RMStore directory.

To load it, add the following line to the beginning of Impression's !Run file:
If "<ArtWorksModules$Path>" <> "" Then RMLoad ArtWorksModules:AWRender26

If you have other emulated 26-bit programs that use AWRender, you need to add
the above line to their !Run files, too.

Impression and JPEG images
--------------------------
This version of AWRender allows you to use JPEG images in your Impression
documents. All you need is ArtWorks and the JPEGObject plug-in module or
ArtWorks 2. 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. This
only applies to ArtWorks files without transparency.

Limitations of AWRender operation with Impression
-------------------------------------------------
Impression does not display JPEGs in irregular frames correctly. This is 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.

Impression does not render ArtWorks files with transparency in irregular
frames. Please use a standard rectangular frame instead. You can clip the
ArtWorks illustration to any shape in ArtWorks using a ClipView.

Impression does not display text lines in irregular frames. This feature has
been inadvertently switched off when producing the 32-bit version and might be
switched on in a future version of AWRender.

See the section "Technical details" below for further limitations, in
particular regarding colour separation and colour processing.

2.3 Advanced options
=====================
AWRender 2 supports system variables to set the options one would normally in
the Crystal preferences dialogue box in ArtWorks:
- AWRender$DontScan - when set, no matter to which value, then files are not
                      scanned for transparency. Instead, the state of Crystal's
                      "Display" option as saved with the file (only saved by
                      ArtWorks 2.3 and above, else the option is considered
                      off) is consulted.
- AWRender$PSRes - when set, specifies the resolution in dpi to use when
                   printing with transparency to PostScript; the value can
                   be a string or a number (i.e., set using *Set or *SetEval);
                   when unset, the default value of 300dpi is used
- AWRender$PrintAntiAliased - when set, no matter to which value, then
                              illustrations with transparency are printed with
                              anti-aliasing, which improves PostScript/PDF
                              generation in particular


3. Technical details
====================
3.1. Limitations
================
For files *without* transparency, AWRender 2.05 has the following limiations:
  - 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 or the Colour map feature in
    Impression) 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 or the Colour map
    feature in Impression) are ignored.
  - CMYK sprites are displayed correctly on screen in all colour depths (like
    other deep sprites, without colour separation and colour processing), but
    *cannot* be printed. This will be addressed in a future AWRender release.

These limitations do not apply to files *with* transparency because
transparency causes the file to be rendered to a bitmap internally, which is
then printed with colour separation if required.

Future versions of AWRender are likely to add support for JPEG colour
separation, deep sprites colour separation and CMYK sprite printing, even for
files without transparency.

For files *with* transparency, AWRender 2.05 has the following limitations:
  - As in the main ArtWorks application, transparent rendering causes the file
    to be rendered to an RGB bitmap internally. Therefore, subsequent colour
    separation does not always produce the expected results for CMYK colours,
    even in areas that are not affected by transparency.

Other limitations of AWRender 2.05:
- It no longer runs under RISC OS 3.1. - RISC OS 3.5 or higher is required
- Please note that this software breaks Computer Concept's !FaxView. You can
  work around this issue by replacing the module !AWViewer.RMStore.ImageExtnd
  by an old version from an AWViewer before 1.60 and run !InstMods.

Limitations of older versions that do no longer apply:
- AWRender 1.36 and above can be called from SVC mode, so they can be called by
  relocatable module code (e.g., PhotoFiler)
- 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 "Updated AWRender API" below for further details on both changes.

3.2. Support modules
====================
This copy of AWViewer contains bug-fixed versions of GDraw, DitherExtend and
GSpriteExtend. The changes are:

GSpriteExtend 0.74
------------------
GSpriteExtend 0.74 works correctly on ARMv7 architectures (e.g., the Cortex-A8
as used in the BeagleBoard).

GSpriteExtend 0.71 works correctly in 64 thousand colour modes (as introduced
with RISC OS 6.14/Select 5i1).

GSpriteExtend 0.70 is 32-bit compatible and has a few StrongARM and XScale
optimisations (conditional LDM and LDR stall optimisations).

GSpriteExtend 0.68 and above contain a bug fix for rendering masked deep
sprites (32k or 16M colours). This bug not only surfaced in ArtWorks, but also
in Impression. Earlier 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. When AWRender 1.78 is loaded it tries to load GSpriteExtend
automatically.

DitherExtend 0.62
-----------------
DitherExtend 0.63 works correctly on ARMv7 architectures (e.g., the Cortex-A8
as used in the BeagleBoard).

DitherExtend 0.62 works correctly in 64 thousand colour modes (as introduced
with RISC OS 6.14/Select 5i1).

DitherExtend 0.60 is 32-bit compatible.

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 3.03
----------
GDraw 3.12 works correctly on ARMv7 architectures (e.g., the Cortex-A8 as used
in the BeagleBoard).

GDraw 3.03 and higher are 32-bit compatible.

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 and FontDraw
------------------------
These modules are needed for RISC OS 2 support only and have been replaced by
dummy versions for the sake of applications that insist on loading them.

Making sure that GSpriteExtend is loaded
----------------------------------------
GSpriteExtend (supplied as !AWViewer.RMStore.SpriteExt) is one of the support
modules required by AWRender. The documentation supplied with AWViewer 1.76 and
earlier suggested workarounds to make sure that GSpriteExtend is always loaded
(e.g., loading it in the boot sequence). This is no longer necessary because
AWRender 1.78 loads GSpriteExtend itself. It does not do any harm to load
GSpriteExtend separately, so there is no need to change anything if you have
previously arranged to load GSpriteExtend in the boot sequence.

JPEG printing
-------------
Older versions of AWRender suffered from a bug in Printers 1.64 that causes
JPEGs to be printed at half size. There used to be a workaround controlled by
the system variable AWRender$DisableJPEGPrintFix. This is all obsolete now
since AWRender 1.76 has vastly improved JPEG printing code that is no longer
affected by this problem. Hence the above variable no longer has any use.

3.3. Updated AWRender API
=========================
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.

Interface callback
------------------
First of all, AWRender 1.37 and above send a callback to enquire which
interface the client supports. The client should set all the bits it can
support and supply the required information.

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
         bit 4 set => client supplies the full print rectangle in the r1 block on
                      entry to the Render routine - X1/Y1 are supplied at
                      offsets 36 and 40 of the block and the full rectangle is
                      supplied for all types of printing, not just PostScript
         bit 10 set => background colour supplied as an ArtWorks colour word at
                      offset 44 in the r1 block (e.g., &20BBGGRR to supply a
                      literal RGB colour)

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

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.

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

Full clipping rectangle
-----------------------
Transparent printing requires the full print rectangle to be supplied by the
client. The original AWRender documentation only required the X0/Y0 coordinates
to be passed, and only when printing to PostScript.

By setting bit 4 of r0 returned from Callback_Interface the client confirms
that it supplies the full print rectangle for all kinds of printing. The X1/Y1
coordinates are passed at offsets 36 and 40 of the r1 block passed to the
Render entry.

Background colour
-----------------
AWRender 2.03 and above support a new interface that allows client applications
to specify the background colour to composite transparent objects with.

To specify the background colour, applications should set bit 10 of r0 returned
from Callback_Interface and supply the background colour at offset 44 of the r1
block when calling the Render entry. The background colour must be an ArtWorks
colour word as documented in the renderer documentation. To supply a literal
RGB colour, simply pass &20BBGGRR (different from Acorn palette entry!).

Multiple pages
--------------
AWRender 2.07 and above support a new interface that returns information about
the pages present in a file and that allows the client program to switch
between pages.

                                                          AWRender_GetPageInfo
                                                          (SWI &4608A)
    Find out about the pages present in an ArtWorks file

On entry
    R0 => start address of document in memory

On exit
    R0 = number of pages in document
    R1 = page number of active page (range [0..number of pages-1])
    R2 = width of page (same for all pages)
    R3 = height of page (same for all pages)
    R4 = ArtWorks colour index of page colour
    R5 = &BBGGRR00 RGB definition of page colour

Use
    Clients wanting to handle multi-page documents can call this SWI to find
    out about the number of pages present in the file. This call also returns
    the page size as defined in the ArtWorks file. It is recommended that
    clients that allow users to switch between pages use the page size instead
    of the document bounds as returned by AWRender_DocBounds (the document
    bounds are different for every page). The ArtWorks colour index of the page
    colour is unlikely to be of use for third-party applications. The RGB
    definition of the page colour can be used to render the page as in the
    ArtWorks application. Please note that the page background colour as
    defined in the file and returned by this SWI is used for transparency alpha
    blending by AWRender in any case (i.e., for compositing transparent pixels
    onto the page background), but page background pixels that are not covered
    by any graphics are treated as transparent by AWRender. For standalone
    rendering of the graphics it often makes sense to render the page colour,
    but a client who wants that needs to do it itself.

                                                          AWRender_SwitchToPage
                                                          (SWI &4608B)
    Switch to a different page

On entry
    R0 => start address of document in memory
    R1 = number of page to make active (range [0..number of pages-1])

On exit
    Requested page has been made active. AWRender_DocBounds can be called to
    return the bounding box of all objects on the page. Calling the render
    entry renders the page that has been made active.

Use
    Clients wanting to handle multi-page documents can call this SWI to switch
    between pages.


4. Distributing the renderer modules with your application
==========================================================
Publicly released versions of AWViewer as available from the MW Software web
site (see next paragraph) can be distributed 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

Any licensing agreement you may have with Computer Concepts that used to allow
you to ship the ArtWorks rendering modules inside your application does not
cover the 32-bit compatible versions of the rendering modules. This means that
when converting your application to 32-bit, you may have to change the way the
modules are loaded: Please make sure that the application loads the rendering
modules from !AWViewer using the standard *LoadArtWorksModules command.


5. History
==========
AWViewer 2.18 (12-Apr-2018)
- re-issued as public download

AWViewer 2.17b (23-Feb-2018) [commercial]
- fixed version numbers shown in Info Box

AWViewer 2.17 (26-Oct-17) [commercial]
- DitherExtend 0.64 with LTRGB rendering support
- GSpriteExtend 0.75 with LTRGB rendering support

AWViewer 2.16 (12-Nov-11)
- AWRender 2.16 with ARMv7 compatible graduation profile rendering

AWViewer 2.15 (15-Apr-11)
- added ARMv7 compatible rendering modules
  - GDraw 3.12
  - DitherExtend 0.63
  - GSpriteExtend 0.74

AWViewer 2.14b (18-May-10)
- fixed AWRender26 - the copy distributed with 2.14 was still version 2.13
  with incomplete shadow support

AWViewer 2.14 (22-Apr-10)
- AWRender 2.14 with shadow support

AWViewer 2.12 (23-Apr-09)
- DitherExtend 0.62 and GSpriteExtend 0.71
  - render correctly in 64 thousand colour modes as introduced with RISC 6.14
    (Select 5i1)
- GDraw 3.11, AWRender 2.12 (identical to previous versions, new version
  numbers for administrative reasons)
- adapted the !InstMods script so that it tolerates RISC OS 6
- adapted documentation for RISC OS 6
- part of ArtWorks 2.9, may not be distributed to the public

AWViewer 2.11 (12-Apr-08)
- AWRender 2.11
  - fixed printing of multi-page documents (used to print all pages on top of
    each other, now prints visible page only)
  - when asked to return the used fonts, only the fonts used in text lines on
    the current page are returned (fonts used in text areas are still returned
    for the complete document)
- AWRender26 provided directly in RMStore directory rather than requiring it to
  be created explicitly by running a script (makes upgrading AWViewer easier)
AWViewer 2.10 (05-Jul-07)
- holding down Alt while loading a file switches to "Outline" quality
- "WYSIWYG" entry renamed to "View quality"
- various minor user interface enhancements
AWViewer 2.09 (04-Jul-07)
- Pressing Shift-Escape closes the current document (both in full screen and
  windowed mode)
- added "Close document" menu entry
- added keyboard shortcuts F5-F8 for the WYYSIWYG menu entries (the shortcuts
  Ctrl-Shift-F5 to Ctrl-Shift-F8 as in ArtWorks are also supported) and F9 to
  switch between full screen and windowed mode
- AWRender 2.09
  - fixed background blending of text lines and text areas (was sometimes
    switched off randomly in earlier versions)
AWViewer 2.08 (02-Jul-07)
- Pressing Escape switches out of full screen mode
- AWRender 2.08
  - fixed rotated rendering/printing of documents with transparency
  - enabled non-AWRender2 aware applications (e.g., Impression) to print with
    transparency on printing systems that supply the required information
    (currently, this is RISC OS 6 only)
AWViewer 2.07 (26-Jun-07)
- massive viewer front-end update
  - title bar displays scaling factor
  - clicking on icon bar icon brings window to front (if there is one) or loads
    startup document (if no window open)
  - added support for multi-page documents (display of page number and overall
    number of pages in the title bar, Previous/Next page menu entries)
  - initial document window is vertically centred in screen minus icon bar,
    window is allowed to fill that space exactly if larger than that
  - added "Full screen" mode
  - document window gets focus, PageUp/Down keyboard shortcuts
  - page background colour as defined in ArtWorks is used
- AWRender 2.07
  - offers new SWIs AWRender_GetPageInfo and AWRender_SwitchToPage for
    multi-page support
AWViewer 2.06b (17-May-07)
- includes DitherExtend 0.61
AWViewer 2.06 (08-May-07)
- AWRender 2.06:
  - accepts multi-page files created by ArtWorks 2.07 and renders
    the page that was active when the file was saved
- first free version of AWRender 2
AWViewer 2.05 (11-May-06)
- AWRender 2.05:
  - renders transparency (Crystal)
  - renders internal arrowheads (introduced in ArtWorks 2.6)
  - renders new arrowhead types introduced in ArtWorks 2.6
  - supports background blending in text lines and text areas
  - automatically loads GSpriteExtend when it is loaded
  - improved document version checks (not only when first importing the
    document but also when rendering it)
AWViewer 1.76 (06-Jun-05)
- AWRender 1.76: Contains code to work around a bug in Impression's handling of
  certain types of colours which broke the rendering of rainbow blends in
  Impression.
- AWViewer program uses Wimp_PollIdle to consume fewer Null events.
AWViewer 1.75 (18-May-05)
- AWRender 1.75: supports rainbow blends (introduced with ArtWorks 2.4)
- Contains GDraw 3.09 with a stability fix and an optimisation speeding up one
  specific type of rendering on platforms with slow screen read operations
AWViewer 1.74 (01-Jun-04)
- AWRender 1.74: fixed replicate rendering (crashed in certain circumstances)
AWViewer 1.73 (25-May-04)
- AWRender 1.73: fixed transformed PostScript printing of JPEGs (i.e., rotated,
  skewed or reflected JPEGs or printing with a transformation, e.g., landscape)
AWViewer 1.72 (12-May-04)
- AWRender 1.72: bug fixes for JPEG rendering (most notably rendering
  transformed JPEGs in low bpp modes could lead to a crash)
AWViewer 1.71 (07-May-04)
- AWRender 1.71: Supports ClipView objects and has vastly improved JPEG
  printing code. The "JPEG print fix" is no longer required.
- AWViewer Error reporting fixed - trying to load corrupted files now displays
  a proper error message as reported by AWRender instead of an empty error box.
- AWViewer detects buggy versions of FontFix/SpecialFX that can cause problems
  with ClipView display and warns the user. AWRender automatically disables
  these buggy versions as soon as it encounters a ClipView to be rendered.
- Reorganised file structure to enable internationalisation of AWViewer
- Added 180dpi sprites (5Sprites11)
AWViewer 1.61e (13-Feb-03)
- Corrected !InstMods (CCShared booting code)
AWViewer 1.61d (20-Jan-03)
- Corrected !ReadMeMW (Impression, JPEGs and colour separation).
AWViewer 1.61c (16-Jan-03)
- Added new hand pointer designed by Richard Hallas
- Added !Help file with instructions, updated !ReadMeMW.
AWViewer 1.61b (10-Jan-03)
- Added new RISC OS 5 icons designed by Richard Hallas
AWViewer 1.61 (07-Jan-03)
- AWRender 1.61: fixes a problem with AWRender being used by OvationPro and
  other clients (e.g., AWViewer) at the same time, which could lead to AWViewer
  not rendering any shapes in its window after an ArtWorks file was displayed
  in OvationPro.
- Added "iconised" sprites to all sprites files. Thanks to Richard Hallas for
  the RISC OS 5 style iconised icons.
AWViewer 1.60 (23-Dec-02)
- First public release of the 32-bit version
- Corrected RO5 check in the !InstMods script
- Updated documentation and StartUp screen
AWViewer 1.60 BETA (19-Dec-02)
- AWRender 1.60: Better handling of situations where a font is not present.
  Defaults to  Homerton.Medium if the document default font (usually
  AvantG.Book) is not found.
- Contains a 32-bit safe version of GSpriteExtend, so deep sprites are rendered
  error diffused in paletted colour modes and 256 colour sprites are rendered
  correctly in deep colour modes.
- Contains GDraw 3.03 with clipping routine fixed for 32-bit operation, so
  pattern-fills now work in 32-bit mode.
- Contains dummy FontDraw and ImageExtend modules for applications that require
  them in order to start up.
AWViewer 1.59b (10-Dec-02)
- contains GDraw 3.01
AWViewer 1.59 (05-Dec-02)
- First 32-bit beta release
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


6. Contact information
======================
MW Software
Martin Wuerthner
Rudolf-Breitscheid-Str. 54
67655 Kaiserslautern
Germany

Tel +49 631 3608205

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