SpecialFX 1.01
==============

by David Pilling

with SpecialFX Setup by Richard Hallas

--------------------------------------

SpecialFX is a desktop enhancement module which provides three
basic functions:

1. SpecialFX causes calls to the Draw module to be redirected
   to Computer Concepts' GDraw module, thus providing an
   anti-aliased display in applications that make use of
   vector graphics (such as Draw, Draw Plus, Ovation Pro etc).

   Anti-aliasing is applied only to screen output; the Draw
   module continues to be used for printing. This option is
   enabled for all applications by default.

2. SpecialFX causes outline font painting operations to be
   performed with background blending (a feature introduced in
   the RISC OS 3.7 font manager) in applications which do not
   provide support for this feature (such as the Impression
   family of DTP programs).

   Background blending is applied to screen plotting only;
   printing is not affected. This option is enabled for all
   applications by default (though it will only work on
   machines running RISC OS 3.7 or later).

3. SpecialFX can cause all printing to occur from low memory
   in applications which use dynamic areas. This provides a
   work-around for a problem in certain printer drivers, such
   as those for Calligraph direct drive laser printers, which
   do not work correctly with particular applications. If you
   find that some items vanish when printing (particularly
   text embedded within Draw files), enabling SpecialFX's
   low-memory printing feature should cure the bug.

   Low-memory printing applies to printing operations only,
   and does not affect screen output. This option is disabled
   for all applications by default. Enabling it globally
   should not have any adverse effects, even with printers
   that do not suffer from the bug.

SpecialFX is a replacement for the earlier FontFix module. If
FontFix is present on your system, you should delete it before
installing SpecialFX.

FontFix performed the same three basic operations as
SpecialFX, but was a blunt instrument by comparison, in that
the options could only be turned on or all for the whole
desktop (i.e. all running applications) at once.

SpecialFX is much more refined because it allows the options
to be set for individual applications. Therefore, applications
which are incompatible with individual SpecialFX enhancements
can continue to work harmoniously alongside other applications
that do benefit from them, with the enhancements appearing in
compatible applications' windows and not in others.

Installation
============

IMPORTANT: be sure to read the note about additional support
modules towards the end of this help file.

If you have been using version 1.00 of SpecialFX, it is
recommended that you delete it from your system to avoid
problems, as the way in which SpecialFX is structured has
changed significantly. However, if you have edited the
SpecialFX choices, you may retain your changes. To do so,
simply run SFXSetup (it will tell you that your version 1.00
choices have been imported) and click Save. Then delete your
old copy of SpecialFX.

SpecialFX 1.01 consists of two components: the module itself
and a configuration tool. These should be installed as
follows:

- !SpecialFX

  This is the resource application containing the SpecialFX
  module. It should be kept in the !Boot.Resources directory.

- !SFXSetup

  SpecialFX Setup is compatible with RISC OS 4 Configure, so
  on a RISC OS 4+ machine it is recommended that it should be
  kept within the Configure application. However, it may be
  used independently of Configure and hence may be stored
  anywhere convenient.

If you are using the latest version of RISC OS (as supplied on
a RISC OS Select CD, for example), the SpecialFX components
should have been pre-installed correctly on your system. If
not, simply drag !SFXSetup into the Configure>Extensions
window to install it into that group.

If you are using RISC OS version 4.0x, you will need to copy
!SFXSetup into the !Boot.RO400Hook.Res.Configure directory in
order to install it into Configure.

If you are using the initial Web-download version of Select
(RISC OS 4.24), you will need to copy the supplied !ExtnSetup
application into !Boot.RO420Hook.Res.Configure, and then copy
!SFXSetup into the newly-installed !ExtnSetup.

Once the two applications have been placed into appropriate
locations, run the SpecialFX Setup tool and ensure that the
'Always load SpecialFX' switch has been turned on. This will
cause the SpecialFX module to be loaded whenever the computer
is booted up.

Desktop operation
=================

The easiest way to operate SpecialFX is via SpecialFX Setup.
This tool is intuitive to use and provides full support for
interactive help.

The Setup application may be used on any machine running
RISC OS 3.5 or later. If run directly with a double-click, it
will install an icon on the icon bar.

If run through Configure on a RISC OS 4 machine, it will
behave as a plug-in and will not install an icon bar icon.

When loaded, SpecialFX Setup presents a window listing the
SpecialFX default settings and a set of overrides for certain
individual applications. It is recommended that the default
selection of applications, and their settings, be left 'as
is', but you may wish to delete the entries for applications
which you do not possess. To add a new application to the
list, click the Add button and then either choose a running
application from the resulting menu or type in a task name.

You may click on application names in the scrolling window to
highlight them (use the Adjust button to choose more than one
at once). To update current SpecialFX settings without saving
your choices to disc, click the Set button. If any entries are
highlighted, only the highlighted settings will be applied;
otherwise SpecialFX Setup will apply all the SpecialFX
settings listed in the window.

Clicking Save will update your SpecialFX choices on disc and
act on all the settings displayed in the window. It will also
remove any SpecialFX settings for applications which have been
deleted in the SpecialFX Setup window since it was launched.

The Reset button will restore either the previously saved
SpecialFX choices if clicked with Select, or, if clicked with
Adjust, the factory defaults. In either case, any settings in
memory which are different than those saved on disc will be
ignored; i.e. settings for which you have used the Set button
but have not saved, or settings which have been created
directly via *SpecialFX commands (see below). If you wish to
reset the contents of the window to reflect all settings
currently in force (those saved on disc, overridden by any
changes read frm memory), choose Refresh from the main window
menu. This has the same effect as quitting and reloading the
SpecialFX Setup program.

Operating the module manually
=============================

SpecialFX itself is a module which may be operated manually by
issuing *commands.

The most important *command is as follows:

  *SpecialFX <flags> [task name]

where the available flags are:

B - set background blending flag (only when not printing)
L - move font paints to low memory (only when printing)
G - use CC GDraw module (only when not printing)

Each flag can be preceded by a ~ to disable the effect.
There must be no spaces between the flags.

If no task name is specified, then global behaviour is set for
the module, and will be applied to all tasks. If a task name
is specified, then plotting will be performed according to the
specified flags for that task only, overriding the global
settings (other applications will not be affected).

It is recommended that task names are surrounded by double-
quote characters in the *SpecialFX command; this is essential
for task names which include spaces. Task names should be
entered (within the quotes) exactly as they appear in the Task
Manager's 'Tasks' display.

When loaded initially, the module defaults to '*SpecialFX BG'
('L' option disabled).

The use of SpecialFX may cause problems with a small number of
applications, which is why individual overrides are available.
See below for more details.

Additional commands
-------------------

As well as the main *SpecialFX command, SpecialFX also offers
three further *commands:

- *SpecialFXRemove <task name>
  Removes any application-specific override that has been
  specified by a previous *SpecialFX command.

- *SpecialFXTasks
  Lists all current application-specific overrides, along with
  their flags.

- *SpecialFXFilters
  Lists any SpecialFX filters that are currently in operation
  (i.e. running applications that appear in the list of known
  tasks for which the default SpecialFX behaviour is to be
  overridden).

Note on additional support modules
==================================

For anti-aliasing to work, both the GDraw and DitherExtend
modules must be loaded. It is also beneficial for a third
module, GSpriteExtend, to be loaded, though this is not an
essential requirement. These support modules are provided
within various Computer Concepts products, such as the
Impression DTP family and ArtWorks.

When SpecialFX is run, the computer attempts to load these
modules (if they're not present already) from inside either
the !CCShared directory within !System or the ArtWorks Viewer
application.

Most RISC OS computers will have at least one Computer
Concepts product installed, and are therefore likely to have a
CCShared directory inside !System already. To check, issue the
command "*Filer_OpenDir <System$Dir>"; the resulting window
should contain a !CCShared application.

If your system does not include CCShared, then you should
ensure that the ArtWorks Viewer application is booted (not
run!) by the filer as part of your boot sequence. If you are
using RISC OS 4.2+, the ArtWorks Viewer application is already
present in the !Boot.Resources directory (where you should
have installed !SpecialFX) so you need take no further action.

IMPORTANT: Compatibility
========================

Most applications benefit greatly from anti-aliased drawing
and background-blended fonts. However, in a small number of
cases, applying these features to an unsuspecting application
can cause problems. In the majority of applications, any
problems are minor, but in a very small number of instances a
crash can occur.

The default choices supplied with SpecialFX are already set up
to disable the module for applications that are known to have
problems with it, or for applications which do not require a
particular feature. Specifically:

Background blending
-------------------

Fresco and Ovation Pro support background blending already, so
SpecialFX is prevented from attempting to enforce a feature
which is already supported (and possibly optional).

WordWorks occasionally plots text in strange colours if
background blending is applied, so it has been disabled
(blending is unnecessary in WordWorks anyway, as the display
background is always a plain colour).

PMS (music typesetting program) produces an unpleasantly
blotchy display if blending is used, so it has been disabled.

The Filer has had blending disabled because it can cause
redraw problems in 'Full info' mode, and the RISC OS 4 Filer
can do its own background blending anyway.

Organizer can 'leak' text colours into other applications in
certain conditions if blending is enforced, so it has been
disabled (and would be of little benefit to Organizer anyway).
Important: if you include Organizer in your boot sequence,
please read the section below about its use with SpecialFX.

Anti-aliasing
-------------

The Impression family, being from Computer Concepts, supports
the GDraw module by default, so SpecialFX is set to ignore
these products; enforcing the feature in Impression can have
strange effects. (ArtWorks is not affected by SpecialFX's G
flag, though it benefits from text background blending.)

Beta versions of Cerilica Vantage can crash extremely badly
(locking up the entire machine) if an attempt is made to use
GDraw with them, so the G flag is disabled by default. This
problem no longer seems to afflict release versions, but as
Vantage performs its own anti-aliasing anyway, there would be
no point in invoking the GDraw module.

Photodesk's drawing tools leave temporary trails in the window
if GDraw is enforced.

The other applications included in the default exclusions all
crash less drastically if GDraw is used (i.e. it is possible
to press <Alt-Break> to kill off the application and escape
from the crash).

Symptoms and fixes
------------------

It is possible that other applications which have not been
tested will have also problems if SpecialFX is in use. The
most likely result will be that the computer appears to hang
up when an attempt is made to draw a vector illustration. If
this happens, press <Alt-Break> to kill off the application,
then proceed as follows.

Run SpecialFX Setup, then re-run the problem application,
click the Add button in SpecialFX Setup, and then choose the
problem application from the resulting menu (or type in its
task name). A new, highlighted entry will appear with the
current default settings for SpecialFX. Turn off the Vector
switch (assuming it's on) and click on Set; then try the
operation in the problem application which previously caused a
crash. If the crash no longer occurs, save your new choices in
the SpecialFX Setup application. If you do still get the
crash, try again with SpecialFX Setup, this time turning off
the Blend switch.

In general, use of background blending is very unlikely to
cause crashes, though it can occasionally produce unpleasant
blotchiness in windows.

In the specific case of Draw, entering new text within a Draw
window can produce initially blotchy-looking letters. However,
the improved appearance of background-blended text on a
variably-coloured background within a Draw window far
outweighs this minor drawback, and so blended text is enabled
for Draw by default. Similar observations may be made about
other applications in which blended text is used.

SpecialFX and Organizer
-----------------------

One known problem can exist with the use of SpecialFX, despite
its provision of on/off switches for all its effects. It has
been found that, on some systems and under certain conditions,
if SpecialFX and Organizer are both loaded during the boot
sequence, there can be 'leakage' of the text colour from
within Organizer's icon to the rest of the desktop. The exact
causes of this problem have not yet been traced, and it only
appears to happen in 256-colour screen modes.

Users of RISC OS 4.2+ are unlikely to experience this problem.

If you do experience the problem, then fortunately there is an
easy work-around. Proceed as follows:

1. Open the following directory inside your !Boot application:
!Boot.Choices.Boot.Tasks

2. Move (Shift-drag) your copy of !Organizer so that it
resides in this directory instead of its previous location.

3. Remove the line that loads Organizer from your desktop
boot file (because Organizer is now in the Tasks directory,
the command to load it is no longer necessary).

On a RISC OS 4.0 machine, this means running Configure,
opening the Boot>Run plug-in, and deleting the line for
Organizer in the resulting window.

On a RISC OS 3.5 to RISC OS 3.7 machine, this means loading
the !Boot.Choices.Boot.Desktop file into a text editor and
deleting any line(s) referring to !Organizer.

The above steps ensure that Organizer will be loaded before
SpecialFX, which cures the problem.

History
=======

1.01 (30 Nov 2001)
------------------

Update issued on Foundation RISC User issue 8

Two fixes applied to the use of the GDraw module for
anti-aliasing:

- GDraw does not support a value of R1=0 for Draw_Fill, so if
  0 is to be used, it is replaced with the default fill style.

- SpecialFX now restores the value of R1 after enabling
  anti-aliasing when passing on calls to GDraw (this fixes a
  potential problem which was not known to produce any actual
  adverse effects).

SpecialFX Setup application introduced, documentation revised
and overall structure of SpecialFX application changed.

1.00 (30 Aug 2001)
------------------

Initial release on Foundation RISC User issue 7

Acknowledgements
================

SpecialFX was inspired by an original idea by Darren Sillett
(the GDPatch module).

Thanks to Kate Moir (Computer Concepts Ltd) and
Martin Wrthner (MW Software) for permission to distribute
the ArtWorks Viewer application with SpecialFX, and to call
the necessary support modules from within it.

The latest version of ArtWorks Viewer may be found at
<http://www.mw-software.com/software/awmodules/awrender.html>.

See the ArtWorks Viewer documentation for full contact
details for Computer Concepts Ltd and MW Software, and for
distribution conditions surrounding the support modules.

SpecialFX documentation, SpecialFX Setup application and
inspiration for certain features by Richard Hallas.

Thanks to Bernard Veasey for helpful testing and feedback.

SpecialFX was first issued within issue 7 of RISCOS Ltd's
Foundation RISC User magazine for RISC OS Foundation members.
This magazine contains an extensive article by David Pilling
about how the software works, along with the full source code.

SpecialFX is copyright material but may be distributed freely
(not for profit).

Contact details
===============

David Pilling software
----------------------

David Pilling
PO Box 22
Thornton Cleveleys
Blackpool
FY5 1LR
United Kingdom

  Fax: +44 (0)870 0520941

  Web: http://www.pilling.demon.co.uk/
       http://www.netlink.co.uk/users/pilling/

Email: david@pilling.demon.co.uk

Foundation RISC User magazine
-----------------------------

(Editor: Richard Hallas, Richard@Hallas.net)

Foundation RISC User
RISCOS Ltd
3 Clarendon Road
Cyncoed
Cardiff
Wales
CF23 9JD
United Kingdom

  Tel: 02920 492324
  Fax: 02920 492326

  Web: RISCOS Ltd:
       http://www.riscos.com/

       Foundation RISC User online sample edition:
       http://foundation.riscos.com/fru.htm

Email: Administration/subscription enquiries:
       Foundation@riscos.com

       Editorial enquiries:
       Editor@riscos.com or Richard@riscos.com
