

                            SwiftJPEG User Manual


                 A fast JPEG viewer for RISC OS 3.1 or higher
      Version 1.02 (4th December 2002)  Copyright Hipposoft 1995 - 2002


SwiftJPEG uses Acorn's SpriteExtend module in RISC OS 3.6 or higher, to allow
access to the extremely fast JPEG display facilities of the operating system.
Because the SpriteExtend module creates a 'Dynamic Area', a concept that did
not exist before RISC OS 3.5, this application normally only works on Risc
PCs. However, it can be run on RISC OS 3.1 - see the dedicated "RISC OS 3.1"
section of this manual for details.

SwuftJPEG is useful because although !Paint and !Draw will both load JPEGs,
they have drawbacks for general picture viewing and don't provide full screen
slideshow capabilities.

RISC OS 3.5 users will need the updated SpriteExtend module, which can be
downloaded if you don't already have a copy. See the SpriteExtend section for
more details.

This manual contains the following sections (but please carefully read the
Disclaimer and Credits section at the end before any others):


** Overview:

   Quick Start guide
   Drawbacks of !Paint and !Draw
   What's new in this version?

** In Detail:

   Main Menu items
   The Display window
   Full Screen display
   SwiftJPEG and ViewFinder
   General Choices
   Loading groups of pictures
   Running several copies
   Handling errors
   Problems

** General information:

   What is a JPEG?
   About SpriteExtend
   About Dynamic Areas
*   RISC OS 3.1

** Finishing Off:

   Contact Addresses
   Thanks

** Disclaimer and Credits.


The quick way to find a section is to search for its name, preceeded by two
spaces (since section titles are centered to the text by placing several
spaces in front, and using two spaces will ensure you don't accidentally find
a general reference to the section within some other part of the text).

If you've any suggestions for additions to SwiftJPEG, any bugs to report, or
any other comments relating to the software, feel free to EMail me. Please see
the Contact Addresses page for details.



                              Quick Start guide

                   Simple instructions for using SwiftJPEG



This section of the manual is intended to get you 'up-and-running' with
SwiftJPEG, with more advanced information being held elsewhere. A knowledge of
basic RISC OS conventions (such as 'double-clicking' and the 'icon bar') is
assumed. If these terms are unfamiliar to you, please look at the RISC OS user
guide supplied with your machine before proceeding. Note that Acorn's
interactive !Help application is not supported, to keep the memory required by
SwiftJPEG to a minimum.

Start SwiftJPEG by double-clicking on the !SwiftJPEG icon in a Filer window.
SwiftJPEG will appear on the icon bar. To load a JPEG file, drag it to the
icon bar icon. The picture will be displayed in a window on the Desktop. The
picture's full name and dimensions are shown in the window's title bar.
Increasing the number of colours available on-screen will improve the quality
of the image. The speed with which the image is drawn depends on the number of
colours. It is slowest when using a 256-colour display mode, and fastest when
using a true colour (16 million colours) display mode.

You can change the size of the image by pressing the middle mouse button over
either the icon bar icon, or the picture. The Main Menu will open. The second
menu item is called Zoom; move the pointer right to display a Zoom Box.
Increasing the first number will scale the picture up (make it look bigger);
increasing the second number will scale it down (make it look smaller).

If you want to look at the picture without the rest of the Desktop visible,
choose the fourth menu item, Full Screen... The screen will clear, and the
picture will then be displayed against a black background. The display
resolution is chosen to fit the picture as best as possible, and any zooming
you did (see above) will be ignored (though this behaviour can all be changed
with the General Choices window).

To discard the image, close the window. To then reload the same image again,
you could drag it back to the icon bar icon, or select the fifth menu item,
Reload image.

To get information on the picture or to save it, move the pointer right from
the third menu item, Picture. A submenu appears; move right again from either
'Info' or 'Save'. The picture can be saved in the normal RISC OS way, and
saves directly to or from other applications are supported.

To quit SwiftJPEG altogether, choose the last menu item, Quit.



                          Why use SwiftJPEG at all?

                        Problems with !Draw and !Paint



Under RISC OS 3.6 or later, JPEG files are supported natively. This means that
applications like !Draw and !Paint can load and display JPEGs, using the JPEG
plotting support built into RISC OS through SpriteExtend.

However, although other applications can display JPEGs, they don't offer the
customised viewing facilities of SwiftJPEG. For example, if you drop a JPEG
into !Draw, it will be placed on a page of a certain size - the usual default
is A4. If the picture is a big one, it won't all fit on the page and you'll
have to change the page size from !Draw's Main Menu. The effect isn't
aesthetically pleasing in any event. With !Paint, the whole picture is
displayed, but to allow editing of the picture !Paint converts the JPEG into a
RISC OS Sprite - basically, this means the amount of memory required by !Paint
to store the picture is much larger than the size of the original JPEG file.

SwiftJPEG is designed to keep the JPEG as a JPEG, reducing memory
requirements, and offer various options for display of the picture not
available in !Draw and !Paint. You can easily zoom in and out of pictures,
display them full screen, save them to other applications and so forth. So
SwiftJPEG is a small, fast utility ideal for just viewing JPEGs.

RISC OS 3.5 users can also take advantage of the fast JPEG routines, but
!Draw and !Paint won't load JPEGs at all - SwiftJPEG is currently the only
way to utilise the fast routines for that version of the operating system. By
loading support modules specially designed for RISC OS 3.1, even that version
of the operating system can view JPEGs with the native routines - this may
allow you to view JPEG files that if fully decompressed would not fit in
available RAM.



                                 What's New?

             A history of SwiftJPEG from newest to oldest version
             This manual covers up to version 1.02 (04 Dec 2002).



** Version 1.02 (04-Dec-2002)


RISC OS 3.1 support (does not use dynamic areas internally). Source code
indented for clarity. Minor bug fixes in mode selection routines. Avoids
setting Wimp palette to fix "pinboard re-caches the backdrop sprite once for
every viewed image" problem in full screen mode. Does not do strict "is this
a JPEG we can handle?" check for RISC OS 4 upwards. On-screen displays in
full screen mode work for 4 OS unit per pixel modes now (e.g. mode 13). Better
behaviour in 16 colours or less. Supports JPEG Render or Sprite Extend modules
for JPEG rendering. On-the-fly conversion of EXIF and unidentified images to
JFIFs - digital camera output now viewable directly. Help file reformatted to
fit in 78 characters wide - seemed like a good idea at the time...


** Version 1.01 (24-Oct-2002)


Bug fix - SWI JPEG_Info was being called with R0:0 clear, which according
to the PRMs means it should not return size information. In RISC OS
versions prior to 4.32 it does, but in 4.32 or later it does not, resulting
in a failure to display JPEGs properly. This was reported in newsgroup
comp.sys.acorn.apps with Andr Timmermans finding the bug (thanks).

Changed date format within this !Help file to DD-MMM-YYYY.


** Version 1.00 (25-Apr-1996)


As version 1.00 (below), with additions of the new Dynamic Area for filenames
of groups. This allows a 'Next image' menu item, where a group of pictures
dragged on can be viewed one by one in the Desktop rather than ending up with
the last picture. You can drop in and out of Full Screen views of a group or
cycle round all the files repeatedly Full Screen. So revision of Full Screen
procedure, error handling and loading mechanisms, plus addition and completion
of HTML documentation and rebuilding of the text and Junior manuals was
conducted.

As such this version shows some of the most radical internal changes in the
version history so far. Unfortunately the WimpSlot had to increase as a result
of the added functionality (mostly the new loading procedures - gamma fades
have little memory overhead which is why they're still present). It's only
gone up to 56K (from 52K), which is the size it was at in earlier versions
anyway... There's also a reasonable amount of room left in the extra 4K for
small future additions or fixes should they be required. Documentation (and
perhaps sources) may well be released 'officially' in separate archives with
filenames making the format of their contents obvious...


** Version 1.00 (Unreleased)


Radical revision to Choices arrangements, including support for hardware
fade/flash in, and checking for presence of the Compo_ReadGamma SWI to
maintain any previous Desktop gamma settings. Dithering and Full Screen
options moved to menus, the latter with a specific mode selection added.
Problems with reopening Display window solved as far as possible.

A few minor bugs cured and documentation is now in HTML form.

Minor improvements to polling system and way the return to the Desktop screen
mode is both handled and prompted - PollIdle now restored (an unstable
intermediate between version 0.09 and 1.00 which was not completed and given
no version number had to have PollIdle replaced by Poll - less efficient).


** Version 0.09 (21-Jan-1996)


Major changes are slideshow time delay and an 'always plot at 1:1' option. A
'Reload image' menu item has been added and there's been 'debouncing' on a few
buttons. The Choices I/O mechanism had to be adapted to cope with the new
stuff in the Choices window. Memory handling changed (see below). Save/App-app
load (see below).

With multiple file loads and auto Full Screen, can now click Adjust to 'pause'
the image when slideshow wait isn't zero - that is, the image will stay on
screen until a key/button is pressed. A pause symbol is flashed 3 times in the
bottom left of the screen to indicate this.

App-to-SwiftJPEG transfer supported through !Scrap; JPEG can be saved out.
Allows e.g. UUDecodes from !TTFN to be dropped straight into SwiftJPEG and
saved out if liked.

WimpSlot taken down from 56 to 52K, and JPEGs now placed in a Dynamic Area.

Changes to many accompanying texts/manuals, and any files where 'Hipposoft
1995' appears have been altered for '1995,1996'...! Noticed Info window had
'1993-1995' in it, this now reads '1995-1996'. Remembered to spellcheck the
manual and found quite a few errors... Now corrected.


** Version 0.09i


Unreleased intermediary. A couple of additions made over version 0.08 which
gave me new ideas for the 'proper' version 0.09. (The 'i' stands for
'internal').


** Version 0.08 (12-Dec-1995)


Changed loader routine to be filetype-independent. JPEG (C85) filetype now
only needed for double-click loading. Also added proper error handler; various
circumstances will force a quit but most of the time, there is a choice of OK
or Cancel buttons. Or just OK, if it's only a message. These changes were
suggested by Stephen Borrill.

Added 'Auto Filetype' option, to set the filetype of a non-JPEG filetype JPEG
file if it was loaded. Noticed a minor bug in the Choices save routine
connected with diagnostics, which was fixed (this would never have lead to
incorrect preferences saves though).

Fixed minor bug in window centering routine (!) which manifested itself when I
set CMOS RAM to allow windows off-screen in all directions. Single pixel
errors when accounting for scroll and title bars also fixed.

Updated manuals and the odd minor change to above History text.


** Version 0.07


The original text History file itself was created on the same day as Version
0. 07 was first saved to disc.

On request of Stuart Halliday, the title bar of the display window now holds
all or part of the pathname of the JPEG file loaded.

A 'true' ellipsis was tried instead of '...' for display of pathnames to long
to fit in either the Picture window or the title bar of the Display window.
However, this doesn't look good for system font users, and only lets you see
another 2 characters of the pathname. I decided to stick with three full stops.

The REMs at the start of the application's crunched !RunImage (which are
inserted manually after the crunching process) have been made a little more
informative.

Fixed a rather stunningly silly bug where Adjust-clicking on the close icon
would open progressive parent directories, and Shift-Adjust-Clicking would
result in a crash as soon as the JPEG tried to subsequently redraw...


** Version 0.06


First 'Release' version, distributed to a few people over EMail by specific
requests following a mention of the software in an Acorn-related newsgroup.

This was the first version that conformed to the original design specification
drawn up prior to starting to build the application.


** Versions 0.05 to 0.01


Development versions. A new version number was assigned after a complete,
working copy of the software had been established (v0.01 was the version name
used for all initial development). None of these versions were released.
Fairly major additions were generally made between version numbers.

None of these versions fully implemented the original design specification for
the software.



                               Main Menu items

               Detailed descriptions of what the menu items do



SwiftJPEG has only got one major menu, accessed either from a displayed
picture or from the icon bar icon by pressing the middle mouse button. Other
menus are connected with the General Choices window, and are dealt with there.

When no picture is loaded, any button can in fact be used on the icon bar icon
to open the menu. However, once a picture is being displayed, clicks on the
icon bar will work differently. The middle button will still open the menu,
but the left button will ensure that the Display window is fully visible and
the right button will show the picture Full Screen (see below).


** Info


Move the pointer to the right to see the application's Info window, which
gives brief information about the application's purpose, author, and version.
The version number should always be quoted if you want to contact the author
about SwiftJPEG for any reason.


** Zoom


Move the pointer to the right to show a standard 'Zoom box', through which you
can change the magnification applied to the displayed picture. If you use the
arrow icons, then the picture (if one is displayed) will be scaled
immediately; else you can enter values via the keyboard and the scaling is
only done when you move from one writable icon to the other, or press Return.
Any scale factor set in this window when a picture is not being displayed will
apply when you next load one. Scale factors will not, by default, be applied
to images when shown Full Screen, but this can be changed from the General
Choices window if you wish.


** Picture


Move the pointer to the right to show a submenu, with two items; Info and
Save. Moving the pointer right off the Info item will show a window giving
information on the picture being displayed. You can also click on the Picture
or Info items themselves to show this. Moving the pointer right off the Save
item, or clicking on the Save item itself, gives a standard save box; type in
a pathname or drag the icon somewhere to save the current picture. If there is
no picture loaded, the Picture menu item will be greyed out.


** Full Screen...


Again this is greyed out if there is no picture loaded. With a picture loaded,
select this item to plot the picture in the middle of a black screen. Press a
key or click any mouse button to get back to the Desktop. There is a separate
page on Full Screen viewing as it is one of the more important features of
SwiftJPEG, and there's quite a lot to say about it. This menu item will only
place the picture being shown in the Display window into a Full Screen view,
it will not load any others.


** Reload image


This is greyed out until an image is loaded, and stays available whilst one is
being shown and after it has been removed. Selecting it will reload the
picture being displayed, or the one just removed. This is most useful if you
have set the General Choices up so that an image is automatically removed
after being shown in Full Screen mode, but you decide you want it back again.


** Next image


This is greyed out unless a group of pictures has been dragged to SwiftJPEG.
If SwiftJPEG has been instructed to show an image in Full Screen view as soon
as it is loaded with the General Choices window, then the images might all be
shown and this menu item would remain greyed out. However, should an image
give an error, you can continue viewing the rest of the images by then
selecting this menu item - Reload image, if not greyed out, would load the
picture prior to the one that gave the error. Alternatively, you can drag on
a group of pictures and view them in the Desktop, one after another, using the
menu item to prompt loading of the next picture. At any time you could set
SwiftJPEG to display all further pictures Full Screen, which is handy if
you've forgotten to set the option and then dragged on a group of pictures.
More information is in the Loading groups of pictures section.


** Choices...


Select this menu item to open the General Choices window (see the General
Choices section for more information).


** Quit


Selecting this item quits the application, closing the Display window and
releasing any memory claimed by SwiftJPEG itself. Note however that the
SpriteExtend module is obviously not removed when you Quit and any memory in
Dynamic Areas or the RMA that the module may have claimed will, consequently,
still be in use.



                              The Display Window

                  How pictures are displayed in the Desktop



When a picture is loaded into SwiftJPEG, it will be placed in a window on the
desktop, known as the Display window, unless you have told it to do otherwise
through the General Choices window. This section describes how the Display
window behaves.

A JPEG can be loaded either by dragging it to the SwiftJPEG icon on the icon
bar or onto one of SwiftJPEG's windows, or, if the file has the appropriate
filetype ('JPEG', C85) by double-clicking on it, assuming nothing else loaded
before SwiftJPEG will try to load a JPEG file. SwiftJPEG may also be started
by double-clicking on a JPEG, though again, this assumes nothing else (for
example !ChangeFSI) tries to load the file first.

When a picture is loaded the Display window will be opened in the middle of
the screen, fitting the size of the picture as best it can. For unusually
small pictures or at small magnifications, there may be a black border along
the right hand side or bottom edge of the picture.

If you load another picture without closing the Display window first, then the
position of the window will not change and it will not get any bigger, though
if you load a smaller picture it may shrink.

When the Display window is closed the picture is removed from memory, but may
be reloaded easily with the Reload image item on the Main Menu. If you drag a
group of pictures to SwiftJPEG, the first of the group will be displayed, and
the rest may be stepped through with the Next image menu item.

If you were in the middle of looking through a group of pictures in this way
and then dragged one or more new pictures to SwiftJPEG, the old group would be
forgotten and the first picture of the new group would be displayed
immediately.

By default, the Display window is left open if you select a Full Screen view,
though you can tell it to automatically close with the General Choices window.
If the Display window had been dragged partially off screen you will notice
that it gets pushed back on when you return from the Full Screen view. This is
an unavoidable feature of the RISC OS Desktop. It will only affect the
SwiftJPEG Display window. For more information see the Problems section.

Clicking on the SwiftJPEG icon bar icon with the left hand mouse button whilst
a Display window is open, will move the window in front of any others that may
be obscuring it.



                             Full Screen Display

              How pictures are displayed outside of the Desktop



A picture being displayed on the Desktop by SwiftJPEG can be shown Full
Screen, that is, on a black background with no other windows or pictures
visible. SwiftJPEG can also be set up to show pictures this way as soon as
they are loaded. There are a variety of ways in which the Full Screen view can
operate.

A Full Screen view is applied to a picture that is already being displayed
with either the Full Screen item on the Main Menu or by clicking on the
SwiftJPEG icon bar icon with the right hand mouse button. Alternatively, you
can tell SwiftJPEG to show pictures Full Screen as soon as they are loaded,
with the General Choices window.

The screen mode (number of pixels and number of colours) that SwiftJPEG
chooses for the display varies according to a number of factors. Normally,
SwiftJPEG will look at the size of the picture and find a screen mode that is
closest to the its size; it will always choose one larger than or the same
size as the picture, unless the picture is bigger than the biggest mode your
machine is capable of. It then finds the largest number of colours that your
machine can display that size mode in, and uses the result.

The General Choices window allows you to change this behaviour. SwiftJPEG can
be told to always use the same screen mode that the Desktop is running in; it
can find the largest size (in pixels) screen mode that your machine can do and
use this with the greatest number of colours available at that size; it can
find the largest number of colours your machine can display and then use this
with the largest size available with that number of colours; or you can
specify an exact mode to use. SwiftJPEG can only use a display mode that has
'square pixels' - such as 'X640 Y480 C256' (the old mode 28) but not 'X640
C256 C256' (the old mode 15).

Regardless of what size you have scaled pictures to in the Desktop with the
Zoom item on the Main Menu, SwiftJPEG will normally ignore that for Full
Screen view. This can also be changed from the General Choices window.

Since windows belonging to SwiftJPEG are affected by the mode changes caused
when going to Full Screen view, the Choices window is always closed before
Full Screen mode is entered. The equivalent action to close the window would
be to click on its OK button - i.e. any changes made in the window are
reflected throughout the rest of the application.

When a picture is being viewed, the keys and mouse buttons do the following
(they only work when the picture has finished plotting):


   Pressing Q during a fade will jump to fully faded-in or faded-out
    (depending on which direction the fade was going). This, for example,
    allows you to skip past a picture quickly.

   The I key will place a small box in the bottom left of the screen
    containing some information on the picture. This is useful if you want to
    check what size the image is without exiting the Full Screen view.

   Pressing Escape will exit the Full Screen display and return you to the
    Desktop.

   The action of mouse buttons and other keys depends on whether you are
    viewing only one picture Full Screen or whether you are viewing a group -
    see the Loading groups of files section. If you are just viewing one
    picture, any other key or button will also exit the Full Screen display
    and return to you the Desktop.


SwiftJPEG can be set to fade pictures in and out when displaying them Full
Screen. This is done through a hardware feature of the Risc PC that allows
colour components of the display, rather than the picture itself, to be
modified - in this case, making them all progressively darker or lighter. It
is also possible to make the pictures 'flash' in from bright white, an effect
seen in some demos. Which method to use and the speed at which the fades take
place is again controlled with the General Choices window. Note that you won't
be able to see the JPEG plotting when Full Screen view is going to fade the
picture in, so there may be an appreciable delay whilst the picture plots onto
a completely black screen! If this is disconcerting turn off fading.

For users of !Gamma by Rob Davison, rdavison@es.co.nz, an application which
uses the same feature of hardware as the SwiftJPEG fades, be aware that
SwiftJPEG does notice any settings made in that application and applies them
to the fades. So if you've made everything appear in red-on-black or some
other odd setting, this will be accurately reflected in the fade...! The
!Gamma application is available from, at the time of writing:

AcornSearch FTP archive

<URL:http://www.acornsearch.com/archives/ftp.uni-stuttgart.de/pub/systems/acorn/acornet/long/riscpc/gamma.arc>
<URL:http://www.acornsearch.com/archives/ftp.uni-stuttgart.de/pub/systems/acorn/acornet/long/riscpc/gamma.txt>



                          SwiftJPEG and ViewFinder

               Interactions between SwiftJPEG and ViewFinder



If you are using SwiftJPEG with the ViewFinder graphics card and want to
perform full screen operations, please note that the level of integration that
ViewFinder provides with the OS is insufficient for SwiftJPEG to be able to
determine best available screen modes. It will tend to select only modes that
were available under RISC OS. When returning to the Desktop, SwiftJPEG will
have correctly read the previous mode information, but will not be able to
restore it unless it could be displayed without your ViewFinder card present;
you will be left in the last selected full screen mode.

It is possible to specify ViewFinder-only resolution, colour depth and frame
rate combinations using the mode string in the "Full screen mode" menu in the
General Choices window. Unfortunately, the operating system will claim that
these modes are not available when SwiftJPEG checks for the string's validity,
so you must only directly specify screen modes that would work without your
ViewFinder card being present.

If you ask SwiftJPEG to enter modes of 4 or 2 colours, it will do so, but of
course under ViewFinder no usable display will be produced. If your previous
Desktop mode was suitable for ViewFinder only, you will then end up stuck in
the 2 or 4 colour mode when you go back to the Desktop. You'll need to use
the command line to restore a usable display (e.g. F12, "WimpMode X800 Y600
C256 F60").

If ViewFinder in future presents a deeper integration with RISC OS, these
problems should go away by themselves. It should be noted that this lack of
integration is not a bug in ViewFinder - it's simply not implemented, and if
it were added in future, it would be added as a feature addition rather than a
bug fix. In the mean time, the best bet is usually to select a resolution and
colour depth you think would be most appropriate for the batch of JPEGs you
wish to view, put the Desktop into that mode, and select "Use current mode"
in the "Full screen mode" menu in the General Choices window.

There should be no such problems with using SwiftJPEG for displaying pictures
with ViewFinder in the Desktop.

These comments refer to using SwiftJPEG v1.02 with ViewFinder firmware
version 1.47. At the time of writing, I have not tested with earlier or later
versions of either.



                               General Choices

                 A description of the General Choices window



A lot of the functionality of SwiftJPEG can be altered in some way through the
General Choices window, accessed by the Choices... item of the Main Menu. It
has options affecting almost every part of the application which is why it has
been referred to by so many other sections of this manual. There are six major
sections to the window - the top section is titled 'Display', the next section
comprises of two groups next to one another connected with fading, there are
two sliders in the third section, the fourth is titled 'Slideshow', the fifth
is titled 'Miscellaneous' and the last section comprises the four buttons at
the bottom of the window.


** 1. Display


This section provides control over the use of dithering and the choice of Full
Screen mode. There are two menu icons with an icon underneath showing the
current choice.

The Dithering method menu lets you choose how a picture is displayed when
there are not as many colours available on-screen as the picture uses.
Dithering is a process where closely spaced, speckled colours are used to
approximate to a colour that isn't there - a bit like mixing alternate red and
yellow dots to give the illusion of orange. Dithering slows down the plotting
of the image so there is an option to turn it off, though this will result in
inferior display quality. Then there is a faster and a slower dithering
option, with the slower one giving a better image. In fact these only produce
a visibly different picture if you are in a mode with 256 colours available.

The Full Screen mode menu controls how the Full Screen routine chooses a
display mode (number of colours and size of display) for the picture. This is
mentioned in the relevant part of the Full Screen section. This section lists
the various options in the order that they appear in the menu, from top to
bottom. Note that for specifying an exact mode for the Full Screen display to
use, you do so by either supplying an 'old-style' mode number or a full mode
string. The latter is the sort of thing you can give to the Display Manager
through it's Mode menu item - you can always change into the mode you want,
write down the string the Display Manager is using, and type that information
into the SwiftJPEG Full Screen menu, if you are unsure how mode strings work
or want to be sure of getting exactly the right mode.


** 2. Fades


This section allows control over which method (if any) of fading is used to
fade the picture in and fade it back out again.

The left hand group of icons controls how pictures fade in, the right hand
controls how they fade out. Both have a No fading at all option, then there is
Fade from/to black and Flash to/from white. The former does a 'conventional'
fade from completely black to full brightness or vice versa; the second will
go to or from a completely bright white screen, darkening to the correct
brightness for the picture. This can be quite eye-catching though some screen
modes may not fill the whole screen and have a black border visible around the
edge.


** 3. Fade speed


There are two sliders beneath the fade-in and fade-out sections to control the
speed at which fading in and fading out takes place. Dragging a bar to the far
left will set the fastest speed; dragging it to the far right sets the
slowest.


** 4. Slideshow


This section gives control over the way in which a series of pictures to be
shown in Full Screen mode are handled. The writeable icon contains a delay in
seconds which SwiftJPEG should wait for between loading successive pictures
into a Full Screen view (see loading groups of files for more information). A
value of zero means SwiftJPEG will wait to be told to move to the next
picture.

Don't zoom picture in Full Screen view controls whether or not SwiftJPEG will
ignore or consider the Zoom factor that has been set from the Main Menu's Zoom
item. If turned on, pictures will always be shown at 'true size', rather than
scaled up or down. Note that the choice of Full Screen mode, if dependant upon
the size of the image, will read the size of the image after zooming if the
option is turned off.

The last option is Repeat pictures until Escape is pressed. If turned on, then
a group of pictures will be shown over and over in Full Screen view rather
than shown once and then forgotten about.


** 5. Miscellaneous


These are various options not easily separated into the above categories. From
top to bottom, Show JPEG in Full Screen mode on loading it should be ticked if
you want pictures to be shown Full Screen rather than in the Display window as
soon as they are loaded.

Close Display window after Full Screen view can be useful if you don't like
having a picture you've just seen left behind in the Display window after
viewing it Full Screen - though if the file isn't stored on the hard drive (it
might have been UUDecoded in some other application and dropped straight into
SwiftJPEG to see if it is worth keeping) you may want to keep this option
deselected - otherwise the picture will be lost after a Full Screen view, as
closing the Display window removes the picture from memory.

Only work out Full Screen modes once is usually left on. Normally SwiftJPEG
only finds the biggest and most colourful display modes available on your
machine when a picture is to be viewed using one of them. However, if you're
likely to be changing the list of modes available (e.g. dropping new Monitor
Definition Files to the Display Manager) then turning this option off will
ensure that SwiftJPEG always notices those changes without needing to be
quitted and restarted.

The final item is Automatically set filetype which if turned on, makes
SwiftJPEG alter the filetype of any file that doesn't have the correct JPEG
filetype of C85, to this correct filetype. If, say, loading pictures from some
odd archive format that doesn't support filetypes, this option can be turned
off to prevent the inevitable errors that would otherwise occur as SwiftJPEG
tried to give the files the JPEG filetype.


** 6. Buttons


The four buttons at the bottom of the window act in a fairly standard way.
From left to right, the Save button saves the choices as they appear in the
General Choices window and makes those changes active, closing the window. The
Default button sets all the choices in the window to their original state -
such as auto filetyping turned on, dithering at 'slow but accurate', and
so-forth.

Cancel will restore the settings present when the window was last opened,
assuming anything has changed - the window will also be closed unless you use
the right hand mouse button. Finally, OK makes the changes active throughout
the application and closes the window.



                          Loading groups of pictures

                   How SwiftJPEG handles groups of pictures



Whilst SwiftJPEG can only display one picture at a time, it is possible to
drag a group of pictures to SwiftJPEG and have them handled in a sensible
manner. This section describes in more detail what happens to groups of
pictures.

Normally SwiftJPEG will not show a picture in a Full Screen view when it is
loaded. In this case, when you drag a group of pictures to SwiftJPEG it will
display the first picture in the group in the Display window on the Desktop.
You can then view subsequent pictures with the Next Image item on the Main
Menu.

If you are in the middle of looking through a group of pictures in this way
and you drag one or more new pictures to SwiftJPEG, the old group will be
forgotten and the first of the new group loaded immediately.

Obviously there is not much difference, in this case, between dragging on a
group of pictures and using the Next Image menu item or dragging on each
picture individually. The important difference comes with Full Screen viewing.
Using the General Choices window it is possible to tell SwiftJPEG to show
pictures in Full Screen mode as soon as they are loaded.

This makes it possible to do a 'slideshow' display by dragging on a group of
pictures. They are shown one by one in Full Screen mode, without returning to
the Desktop in between. Should one of the pictures give an error, the
slideshow can be resumed by selecting the Next Image menu item again. Turning
off the Full Screen option in the General Choices window would allow viewing
to continue in the Desktop.

The side effect of this method is that if you accidentally forget to tell
SwiftJPEG to display pictures Full Screen as soon as they load, then (unlike
in some earlier versions of SwiftJPEG) you just need to turn this option on
and then select the Next image option to continue Full Screen, though this
will obviously start with the second of your group of images.

It is possible to tell SwiftJPEG to wait a certain amount of time between
pictures and then automatically move onto the next one. You can also tell it
to repeatedly cycle through a group of pictures until you force it to exit
Full Screen view by pressing Escape. If a picture causes certain errors it
will not be viewed again if you resume Full Screen viewing (so you don't get
the same error over and over). Note that running out of memory does not count
as one of the errors where this is true, as you might (for example) free some
memory when the error occurs which would allow the picture to be loaded next
time round without problems.

If a complete group of pictures is shown Full Screen and SwiftJPEG then
returns to the Desktop, the group will then be forgotten about. If you force
it to exit in the middle of a group with Escape, the group is remembered in
case you want to carry on looking at the pictures. The exception is if
SwiftJPEG has been told to repeatedly cycle through the pictures as described
above. In this case the group is forgotten about as otherwise you'd always be
left with a list of files stored in memory after viewing pictures Full Screen.

When loading a group into a Full Screen view with SwiftJPEG set up to
automatically move onto the next picture after a certain time, there are
slight changes to the keyboard and mouse operations as described in the Full
Screen section. The right-hand mouse button will now pause on the current
picture - SwiftJPEG will wait for a key or mouse button to be pressed before
continuing (the usual 'special' keys such as Escape function as normal whilst
paused). A 'tape deck'-style pause icon flashes briefly in the bottom left of
the screen to show this. Using the I key will now also act as a pause
function, whilst still showing the picture information. Other operations
remain unaffected.

SwiftJPEG accomplishes this handling of groups by storing all the picture
names in the group in a Dynamic Area and then loading them 'on demand'. Any
potential errors will thus not be generated until the errant picture is
accessed. SwiftJPEG does have a limit on how many pictures can be remembered
at once, but it shouldn't normally be a problem (around 2,400 files
worst-case). However, if there isn't enough free memory to store all the names
in a group an appropriate error will be generated and only those pictures with
names already in memory will be available.

Note that when loading pictures into Full Screen mode, you may notice a
significant delay upon exiting Full Screen mode before the Desktop redraws.
The drive indicator light for whatever device you loaded the pictures from, if
present, will probably be flashing erratically during this period. So if
you've dragged on a large group of pictures and this happens, be patient - so
long as the drive light is flashing, you'll know the machine hasn't crashed.
For more details see the Problems section.

To create a 'rolling slideshow' of pictures in a specific order, drag the
pictures in the order you want them to the Pinboard. Using the General Choices
window, set up some delay between pictures, make sure the group is displayed
repeatedly, set up fades if you wish, ensure pictures will be shown Full
Screen as they load, and finally select all the pictures you put on the
Pinboard and drag them all to SwiftJPEG in one go. Then sit back and enjoy the
show!



                            Running several copies

               Running more than one copy of SwiftJPEG at once



SwiftJPEG will only display one image at a time, though it can handle groups
of files reasonably well. You may, however, want to view more than one picture
at once.

This can be achieved by running another copy of SwiftJPEG. SwiftJPEG wasn't
given the capability of viewing more than one picture at one time as this
would firstly interfere with the slideshow aspect of the application, and
secondly increase its size and marginally decrease its speed in a manner
disproportionate to the requirement for multiple picture support.

Unlike some applications, when SwiftJPEG starts up it remembers exactly where
its own Choices file is (and so-forth) and stores that internally. So if you
have two copies perhaps set up in different ways in different places on a hard
or floppy disc, both can be run simultaneously and both will still be able to
read and save their own Choices correctly.

If you run the same copy of SwiftJPEG more than once, then each copy will be
using the same Choices file. If you alter the Choices and save it from one
copy, the others will not reflect the changes. This lets you set different
options in each of the SwiftJPEG applications that you ran from the same
place.



                               Handling Errors

                       How SwiftJPEG deals with errors



SwiftJPEG can experience a variety of errors with external causes, such as a
lack of memory or a file being dragged from the Pinboard when the original has
been deleted. Errors can also be generated by a JPEG file itself. This section
describes the way in which errors are handled.

Key to SwiftJPEG's operation is the SpriteExtend module, which does the hard
work of plotting the pictures and handling dithering. The SpriteExtend module
is less tolerant of badly defined or fairly non-standard JPEGs than, say,
ChangeFSI, and does not display some of the more exotic (and rare) kinds of
JPEG files, such as progressive JPEGs or those with no compression. Some files
then, will load but not be displayed, or may show odd traits such as only
redrawing partially. This does not for example occur with any of the JPEGs
supplied on the hard disc of a new Risc PC, and is not necessarily a fault of
either SwiftJPEG or the SpriteExtend module in a strict sense; the problem
lies more with the file itself. You will know if this has happened according
to the following:

   If there is not enough memory to load a picture into SwiftJPEG itself,
    a warning is reported stating that this is the case. However, the
    SpriteExtend module also needs memory for workspace; it creates a Dynamic
    Area the size of which can be altered by the user.

   The amount claimed depends on the size of the JPEG displayed. It can be
    set to 0K (or any other arbitrary size constrained only by the amount of
    free memory) by the user and is automatically increased in size by the
    SpriteExtend module if required.

   If enough memory is present to load the JPEG file into SwiftJPEG, but
    there's then not enough workspace for the JPEG module, the JPEG won't be
    shown - you'll get a blank Display window or (with Full Screen viewing) a
    black screen, because all errors from the JPEG plotting calls themselves
    are ignored. So if nothing plots, check there is enough memory free.

   If nothing plots and there appears to be plenty of memory free then the
    JPEG file is probably at fault. You could try loading it into !ChangeFSI
    to see if that can make sense of the file.

All other errors are generally reported with the option to continue or quit
the application, unless they occur at early startup time; in this case the
application always quits, since incorrect startup would not allow the
application to continue to function correctly.



                                   Problems

                           Problems with SwiftJPEG



This section contains any information on bugs or difficulties connected with
SwiftJPEG. Some or all may have been mentioned in passing elsewhere, but they
are duplicated here, usually with added detail, to make them easier to find.
All fixes or advice gratefully received...


** The Display window after Full Screen view


The position of the Display window may change after a Full Screen view, if the
window had been dragged partially off screen. This is because the Wimp tries
to gather any windows belonging to SwiftJPEG into the visible area of each
screen mode that Full Screen uses, even though it leaves all other windows
alone. It is apparently not possible to reopen the window partially off the
screen again, hence the movement.


** Interaction with ViewFinder


There are some restrictions on SwiftJPEG operations when it is used in
conjuction with the ViewFinder graphics card. Please see the "SwiftJPEG and
ViewFinder" section for details.



                               What is a JPEG?

                        About JPEG pictures in general



The acronym JPEG stands for 'Joint Pictures Expert Group', and is the name
given to a type of picture file. A JPEG file allows pictures that would
otherwise occupy a lot of memory or disc space to occupy considerably less,
with a trade off between image quality and the memory or disc space required
for that image.

JPEGs are designed for storing photographic images, rather than sharp images
such as a black and white line drawings. To reduce the size of the image,
clever techniques are used to re-encode the image in various space-saving
ways. This re-encoding involves a loss of information (quality). For images
compressed only small amounts, this loss won't be visible. As the image size
decreases, the lost information becomes more and more apparent. The trade off
between image size and quality is known as the 'quality factor', and usually
expressed as a percentage. Most applications use 100% to mean 'best quality'.

The way that this lost information shows up in the final picture is called an
'artifact'; common artifacts of JPEGs are blurred outlines where a sharp
colour changes occur (for example, a silhouette of a building against an
orange sunset) or large blocks of the image reduced to the same colour (most
often seen where there are subtle colour changes, for example in sky or calm
water). The blurring of sharp colour changes is the main reason why JPEGs are
intended for photographic material.

The routines that SwiftJPEG uses to plot the JPEGs are extremely fast, but
this speed is obtained in part through a few compromises. Some of the rare
JPEG formats, such as those with no compression, will not be plotted. In this
case, Acorn's ChangeFSI should be able to display such pictures; if not, the
JPEG file may be damaged in some way.


** How do I know a file is a JPEG?


Since JPEG files have only been supported by the operating system from RISC OS
3.6 onwards, there are a great many icons floating around to represent JPEGs
and what you see will depend on what software you're using and how old it is.
The most likely icon will be a grey picture of a person's eye. If you use the
Filer's Info option over a file, the filetype should be 'C85' and will
probably have the name 'JPEG'. If a file doesn't appear to have the JPEG
filetype but you still think it is a JPEG, try dragging it onto SwiftJPEG
anyway - a message will be given saying if the file is not really a JPEG.



                                 SpriteExtend

                 Native JPEG plotting in RISC OS 3.5 or later



Under RISC OS 3.6 and later, JPEG files are supported natively by the
operating system. This is done through extensions to the SpriteExtend module,
which has been given extra code to deal with these files. RISC OS 3.5 users
can soft-load this extension and give partial support for these files too.

Unfortunately, only Risc PC owners can use such versions of SpriteExtend as
the module creates a Dynamic Area to use as workspace whilst plotting JPEGs.
Dynamic Areas are not available on pre-Risc PC machines. The SpriteExtend's
JPEG code is remarkably fast given how difficult JPEGs are to display, but
there are some limitations in the type of JPEGs that are supported - it does
support the common formats, though. Acorn's ChangeFSI application can always
be used as a fallback if SpriteExtend can't display the picture, albeit a
comparatively slow alternative.

Acorn have released an unsupported version of SpriteExtend for RISC OS 3.5
users, which appears to work with SwiftJPEG well. This will not give !Draw,
!Paint and so-on the ability to load JPEGs! A copy of the module is available
on the AcornSearch archive of Acorn's FTP site; to download it, use the URL:

AcornSearch FTP archive

<URL:http://www.acornsearch.com/archives/ftp.acorn.com/riscos/RELEASES/SPRITEXTND>

Versions 0.99 and later of SpriteExtend are 'JPEG-aware'. Versions prior to
that present in RISC OS 4.32 (RISC OS Select 2) do not handle progressive
JPEGs, so it is recommended that Select 2 or later is used wherever possible.



                                Dynamic Areas

           A new memory management feature in RISC OS 3.5 and later



Under RISC OS 3.5 or later, applications can make use of Dynamic Areas. These
are resizeable blocks of memory which an application can claim and give a
specific name. They can be any size, limited only by free memory.

Previously, applications may have allocated memory in several ways, all of
which worked but were not ideal. The worst was through claiming memory in the
Relocatable Module Area, or RMA. This practice led to increased fragmentation
of the RMA, which basically meant it grew in size over time and you may
eventually have needed to reset the machine to free up the memory it was
using.

The second method was to use the System Sprite area. Applications such as
SparkFS do this on pre-Risc PC machines. This works a little better than the
RMA since fragmentation is less likely to occur, but the sprite area was not
designed for this use and several problems are associated with it.

The last method was to extend the memory allocated to the application
directly, though this can't be done under all circumstances as an
application's memory is handled in a special way. This also has other
problems, and on the Risc PC, a large amount of memory allocated to a single
task will slow down the machine. Furthermore, you can only have up to 28Mb
allocated to any one task.

Dynamic Areas solve all of these problems, giving an area which an application
can name to show the user clearly what it is for (through the Task Manager
display). They are easy to deal with and were thankfully designed for the task
of storing an application's data. As mentioned above, there is no limit to
their size, within the limits of the machine's memory. The way that they are
handled allows Virtual Memory (that is, using hard disc space as 'slow'
memory) solutions to be implemented successfully.

The only problem with a Dynamic Area is that it can't easily be removed from
the Task Manager list, whereas application tasks can be. Some badly behaved
tasks may leave Dynamic Areas behind if they crash, and you either need to run
another application (e.g. !RemoveDA by Dave Thomas, cmsdthom@livjm.ac.uk,) or
reset the machine to remove them. SwiftJPEG uses its own Dynamic Area, but
it's reasonably well behaved and the area will be removed should the
application crash. Note that if you use the 'Watchdog' (Alt+Break) to kill the
application, then the area will be left behind as SwiftJPEG is not given any
chance to shut down properly before being killed off.

The !RemoveDA application is available from, at the time of writing:

AcornSearch FTP archive

<URL:http://www.acornsearch.com/archives/ftp.uni-stuttgart.de/pub/systems/acorn/acornet/long/tools/memory/removeda.zip>
<URL:http://www.acornsearch.com/archives/ftp.uni-stuttgart.de/pub/systems/acorn/acornet/long/tools/memory/removeda.txt>

This appears to be quite an old version; there may be newer copies to be found
elsewhere.



                                 RISC OS 3.1

                   How SwiftJPEG copes without dynamic areas



RISC OS 3.1 users can use the SpriteExtend 0.99 software using a dynamic
area emulation system called "DummyDDA". This isn't 100% reliable (so make
sure you save any unsaved data before starting a session using the JPEG
plotting routines and DummyDDA) but is generally effective and a good way to
get at the fast JPEG routines. SwiftJPEG 1.02 and later have full support
for RISC OS 3.1 so full screen display etc. should all work correctly. You
will notice that SwiftJPEG creates one or two sprites in the system sprite
area as workspace; this is an internal emulation of dynamic areas which it
uses on RISC OS versions without native dynamic area support. Using this,
rather than relying on DummyDDA, increases system reliability enormously.
When SwiftJPEG is shut down or is viewing no images with no images pending,
these sprites will be deleted and the system sprite area shrunk to a
minimum size. The sprites are called "sjpg_picture" and "sjpg_filelst". Any
sprites of the same names existing when SwiftJPEG starts will be deleted; in
addition, only one copy of SwiftJPEG may be run at a time, as only one sprite
of the same name can be present in the system pool at any time. SwiftJPEG
will refuse to start if it thinks an existing copy is currently running.

SwiftJPEG does not try to load DummyDDA or SpriteExtend 0.99 itself on a RISC
OS 3.1 machine; you must do this manually, or add it to your boot sequence.

For RISC OS 3.1 users with the !Browse application, you may find you have
the JPEGRender and JPEGMsgs modules. These are the JPEG plotting parts of
SpriteExtend 0.99, extracted into independent modules that don't need
dynamic areas at all. If present in !System, SwiftJPEG will load these
modules automatically should the SpriteExtend 0.99 patch not be present.
This gives the most stable way of plotting JPEGs - no dynamic area
emulation modules are needed whatsoever. The only drawback is that dithering
is forcibly turned off in modes supporting 16 colours or less, because of
rendering bugs in the modules. 256 colour operation supports the full range
of dithering settings. It may be possible to distribute the JPEGRender and
JPEGMsgs modules with SwiftJPEG in future, but presently, I cannot do this.



                                Contacting me

                       Snail Mail and E-Mail addresses



Snail mail:

  Andrew Hodgkinson
  52 Beaulands Close
  Cambridge
  CB4 1JA

E-mail:

  ahodgkin@rowing.org.uk

On the web:

  http://nines.rowing.org.uk/
  http://nines.rowing.org.uk/folder/

At the time of writing I recently obtained an NTL broadband account but have
done nothing with the web space yet, so if releases are made I'll hide them
away on the Nines web site somewhere! :-)



                                    Thanks

                       Hipposoft would like to thank...



Graeme Barnett and Neil Coffey for feedback relating to SwiftJPEG in the early
stages, and particularly Stuart Halliday and Stephen Borrill for various
suggestions and bits of info; and everyone else who's EMailed me about various
things since then, including Stuart Bell who made me realise I shouldn't
completely drop the Junior manual format in favour of HTML, and was
instrumental in getting SpriteExtend released for RISC OS 3.5 users.

John Sullivan and Ben Blaukopf for help on user interface and some programming
issues, and for ideas on improving the HTML manual.

Chris Cox of Acorn for a very positive response to my request for a
distribution of the JPEG-aware SpriteExtend for RISC OS 3.5 machines, and
Charles Whyte of ART, to whom the request eventually got transferred
(unfortunately it required a full software license and I couldn't afford the
fee); and of course Tim Caspell who pursuaded ART to do the public
release on the Acorn FTP site!

Ragnar Hafsta and Dick Alstein for !BasCrunch v1.02, which was used to
compress the original BASIC source.

Andr Timmermans for pinning down the Select 2 / 4.32 JPEG_Info call bug.



                            Disclaimer and Credits

                     Please read the following carefully!



If you do not agree with the following text, you may not use SwiftJPEG and
must delete it immediately.

'The software' or 'this software' refers to the !SwiftJPEG application and any
related files distributed with it, including this manual in all its formats.

This software is supplied 'as is'; Hipposoft makes no claims as to its
reliability or suitability for any purpose, regardless of any comments made
elsewhere. No responsibility can be taken for any failure of the software, or
any loss or damage caused directly or indirectly, or not caused, by the
software.

Contents of this manual are not guaranteed to be correct, and may change
without notice.

The SpriteExtend module is Copyright Acorn Computers. Until recently (at the
time of writing) the JPEG aware SpriteExtend was not available for RISC OS 3.5
users; it is now, and you may therefore now use SwiftJPEG on a machine with
the SpriteExtend module soft-loaded on it. This statement superceeds any
contrary information in disclaimers for any prior versions of SwiftJPEG.

This software is Freeware, and must be distributed intact, with all the files
present and in the same form as received by the end user. If being distributed
in any profit-making way, permission must be granted by Andrew Hodgkinson
(Hipposoft) first.

This revision of the Disclaimer and Credits section was made on Monday the
29th of April, 1996 and does not refer to versions of SwiftJPEG or the manual
made prior to this date except where explicitly indicated.

