SpecialFX 1.05
==============

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.05 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
  on all systems, regardless of the operating system version.

- !SFXSetup

  SpecialFX Setup is compatible with RISC OS Configure, so on
  on a RISC OS 4, RISC OS Select or RISC OS 5 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.


Installing !SFXSetup in Configure
=================================

(You only need to follow these instructions if you wish to
use !SFXSetup as a Configure plug-in.)

If you are using a recent version of RISC OS (as supplied on
a RISC OS Select CD, for example), the SpecialFX components
may already have been pre-installed on your system. If not,
proceed as follows:

RISC OS 3.5, 3.6 or 3.7
-----------------------

!SFXSetup must be used as a stand-alone utility because
RISC OS 3 Configure does not support plug-ins. Store !SFXSetup
anywhere you wish on your hard disc.

RISC OS 4.0x
------------

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.

RISC OS 4.2+
------------

If you are using RISC OS Select (RISC OS 4.2x or later),
simply drag !SFXSetup into the Configure>Extensions
window to install it into that group. Configure will place a
copy in an appropriate place on your hard drive by itself.

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

RISC OS 5.0x
------------

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

Optional step: RISC OS 4.0/Select/5 Configure
---------------------------------------------

The versions of Configure supplied with RISC OS 4.0x, RISC OS
Select and RISC OS 5 all have different sprite styles for the
plug-ins. RISC OS 4.0 uses jigsaw-puzzle icons; RISC OS Select
uses more refined-looking jigsaw-puzzle icons (with elongated
lugs); RISC OS 5 uses icons without jigsaw puzzle borders.

Unfortunately, there is no way to make a Configure plug-in
adapt its Configure icon for the version of Configure
currently in use. As supplied, SFXSetup has RISC OS 5-style
icons preinstalled.

So, to make SFXSetup match the appearance of your other
plug-ins, as an extra step you can install appropriate icons
for your version of RISC OS. Look in the Extras directory; it
contains "RISC OS 4", "RISC OS 4S" (i.e. RISC OS Select: 4.2
or later versions) and "RISC OS 5" folders. Open the folder
relating to the OS installed on your machine and drag the
copy of SFXSetup that you find there over the copy that you
have already installed on your own hard disc. This will update
the sprites inside it to match your system.

(The RISC OS 5 directory is supplied for completeness: the
sprites in its copy of SFXSetup are identical to those stored
in the 'main' copy.)

Then...
-------

Once the two applications have been installed in 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 or RISC OS 5 machine,
it will behave as a plug-in and will not install an icon on
the icon bar.

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 by
various Computer Concepts products, such as the Impression DTP
family and ArtWorks, but their primary source on modern
systems is now the ArtWorks Viewer (AWViewer) program.

When SpecialFX is run, the computer attempts to load these
modules (if they're not present already) from one of the usual
locations; primaryly AWViewer, followed by CCShared (which may
be present inside the System application).

It is strongly recommended that all users should install a
copy of AWViewer inside the !Boot.Resources directory. Modern
systems (those running RISC OS Select or RISC OS 5) will have
the software pre-installed in the right place as standard.
Should you need to download your own copy of AWViewer from the
Web, the latest version of AWViewer can be found here:

<http://www.mw-software.com/software/awmodules/awrender.html>


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 minor cosmetic problems. This will usually take one
of three common forms:

1. Text looks blotchy: this is caused by the background
   blending option being turned on;

2. An expected graphic (probably line of text) fails to appear
   (perhaps a window is blank when it should contain text):
   this is caused by the vector anti-aliasing option being
   turned on;

3. When dragging, coloured ghosts of the dragged object are
   left behind in the window: this is also caused by the
   vector anti-aliasing option being turned on.

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 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 enforced, 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.)

Cerilica Vantage performs its own anti-aliasing, so there
would be no point in invoking the GDraw module (and failing
to do so avoids potential problems).

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

The other applications included in the default exclusions all
exhibit either the 'vanishing text preview' problem (point 2,
above, in the EFF utilities) or the 'ghost dragging' problem
(point 3 above).

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

It is possible that other applications which have not been
tested will have also problems if SpecialFX is in use, and may
exhibit one of the three problems listed above.

If you suspect a problem, then run SpecialFX Setup, 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 and/or
Blending switch(es) and click on Set; then try the operation
in the problem application again. If the problem no longer
occurs, save your new choices in the SFXSetup application.
If you do still get the problem, try again, this time turning
off the other option (or both options).

In the specific case of Draw, entering new outline font text
within a Draw window can produce initially blotchy-looking
text. However, the improved appearance of background-blended
letters 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.05 (27 May 2004)
------------------

Version 1.05 is another quite important upgrade that fixes a
significant long-standing problem with the module.

- The SpecialFX module now observes a service call to modify
  its behaviour if output has been switched to a sprite or
  mask rather than the screen. If outputting to a sprite or
  mask, GDraw anti-aliasing is turned off unless the output
  is to a 32-thousand or 16-million colour sprite, as these
  are the only colour depths that are correctly supported by
  GDraw and DitherExtend.

This fix should cure certain problems with isolated pieces of
software whose graphical output was corrupted by SpecialFX
(notably members of the EasiWriter/TechWriter family of word
processors).

Thanks to Martin Wrthner for technical feedback and testing.


1.04 (30 Apr 2004)
------------------

Minor corrections but no functional changes; overall version
number remains the same.

- SpecialFX module rebuilt with StubsG; hence 32-bit System
  modules are no longer required.

- 'IfThere' function in the front-end could return the wrong
  results, and hence cause spurious errors, thanks to an
  apparent change to a SWI call in RISC OS Select 3. Checking
  of results is therefore now more stringent.

-The !SFXSetup.Dividers.Ensure program used an archaic SWI
  call that appears to have become invalid in RISC OS Select 3
  (OS_SpriteOp,#,-1,... = Wimp_SpriteOp ...; other versions
  of RISC OS are happy with this, but it crashes Select 3).
  Modified to use Wimp_SpriteOp directly instead.


1.04 (09 Apr 2004)
------------------

Version 1.04 is a very important upgrade that all existing
users of SpecialFX should install, as it corrects a serious
problem with the module, thus improving overall stability and
enabling other recent software to work correctly.

- Bug-fix: the SpecialFX module was causing certain calls that
  were fully supported by the Draw module to be redirected to
  the GDraw module, where they were not fully supported. The
  most serious outcome of this behaviour was that it caused
  the ClipView code in AWRender to fail to work, thereby
  disabling a major new feature of ArtWorks 2.

- Bug-fix: the SpecialFX module now supports the correct
  default behaviour for stroking paths.

- Removed effTTT (EFF TruType Translator) and PDcat, EFFcat
  and EFFcat2 (all CD font catalogue applications by EFF) from
  the list of default settings, as the latest bug-fixes in the
  module apparently enable them to work without problems now.

  Note that it may also be safe to remove Photodesk and
  Sibelius 7 from the list, as they also appear to work as
  expected with default settings. They have been left in the
  list of overrides for possible compatibility with older
  versions that have not been tested, and because the
  presence of the overrides has no detrimental effect on the
  applications' behaviour.

- Added "Sib2Draw" to the default settings, as recent versions
  of the application have been renamed from "SibToDraw", and
  the ~G setting is still required.


1.03 (27 Feb 2003)
------------------

Minor corrections to the front-end (module not changed);
overall version number remains the same.

- Corrected all '11' suffix RISC OS 5 sprites to use 180dpi
  sprites. Hi-res sprites are now supported (by using 180dpi
  sprites only) in RISC OS 5.02.

- Added new 'internal' hi-res sprites for SFXSetup (the
  Sprites511 file) and replaced the Sprites522 file with
  slightly amended sprites derived from the new hi-res ones.
  Added one line of code to !SFXSetup.!RunImage to cause the
  new sprites to be used when appropriate. Increase WimpSlot
  to allow for the use of the larger sprites file.

- Corrected faulty version 1.02 reference in Messages file.


1.03 (22 Jan 2003)
------------------

It is strongly recommended that users of all previous versions
should upgrade to version 1.03, as the major bug-fix listed
below is important, and enhances overall system stability.

- R14 was being corrupted by the interception of Draw SWIs.
  Thanks to Justin Fletcher for spotting this and working out
  the fix.

- FontFX (the utility by The Data Store) has been removed from
  the default settings (it was previously set to have the
  vector anit-aliasing G flag turned off) because the crash
  which used to happen if this flag was enabled no longer
  occurs (i.e. the bug-fix above cures the crashing).

  Anyone with an entry for FontFX in their private SpecialFX
  user choices can now safely remove it and benefit from
  anti-aliasing in FontFX.

- !SpecialFX.!Load file amended to use *LoadArtWorksModules
  if defined.

- New distribution structure (Extras directory etc.) and new
  RISC OS 4.0x-style Configure sprites added.

- Rewrote/updated quite a lot of the documentation.


1.02 (24 Dec 2002)
------------------

Updated for RISC OS 5, as released on the IYONIX pc:

- SpecialFX module now 32-bit compatible.

- Minor update to OS version check in SFXSetup to enable it
  to load on a RISC OS 5 computer.

- New RISC OS 5-style icons added to complement the existing
  RISC OS 4-style versions.

This version is functionally identical to version 1.01, and
is a 32-bit compatibility upgrade. Users of RISC OS 3 or
RISC OS 4 machines do not need to upgrade.


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.

In fact, AWViewer is no longer supplied as standard with
SpecialFX because (a) it's large, (b) most users will have it
installed already, and (c) it would be all too easy to
distribute an out-of-date version. Anyone who does not have
this software already should download it from the Web.

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

If this copy of SpecialFX came from an issue of Foundation
RISC User, then note that the latest copy of AWViewer (at the
time of going to press) is supplied in the Free Software
Archive (Graphics -> View section).

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
