Notes on Digitiser module version 1.10 (RiscOs version)
======================================================== 
This version of the digitiser module supports (and only runs under)
RiscOS.

The bugs in SWI Vdig_WriteColumn and *Configure Shades 16 have been fixed.

CHANGES/NOTES FOR RISCOS 
========================

SWI Vdig_Scale now works in ALL graphics modes, and should work in user
defined modes, as long as the VduVariables are set correctly.  SWI
Vdig_Rotate now works in all 16,256 colour modes. SWI Vdig_FastGrab,
*See, *Grab now work in modes 16,17,21,27,28

SWI Vdig_FastGrab (and *See, *Grab) in mode 16/17 only displays 1024
horizontal pixels (512 if q set), not 1056. *ShowPic does use full
width. - this causes *GrabSave to not quite work as expected.
SWI Vdig_FastGrab (and *See, *Grab) in 480 line modes crop 32 lines
from the top of the picture. Quarterscreen grabs in these modes don't
and therefore are a bit bigger then a quarter of a screen (256 lines)

When using a lookup table with SWI Vdig_Scale in 4 colour screen modes,
the 16 colour user lookup table is used. If the table contains values >3
(e.g. after tables are initialised), strange things will happen
onscreen!

Slow operations (*Smooth, *PicLoad, *PicSave,*PicDump) display the
hourglass. *Picdump also indicates the percentage of time through the
dump.

*Section M in modes which aren't 1280 by 1024 OS units in size (e.g. 16)
doesn't work correctly.

Rotate in nonsquare modes (e.g.16) apears to squash the picture

*PicDump in mode 16/24 appears rather elongated. This can be altered
using the W and H parameters.

The above three effects have deliberately not been 'fixed' to retain
conststancy with the OS, as most of the OS graphics facilities treat
Mode 16 (24) as a horizontally extended mode 12 (15), not as a higher
resolution mode. (e.g.circles aren't round on the screen, but will be if
*PicDump'd).  

SWI Vdig_Scale & Vdig_Rotate update the OS_ChangedBox information.
WARNING - grabkey may update box info from background, depending on
GrabOption settings.

SWI Vdig_FastGrab and SWI Vdig_Display DON'T update OS_ChangedBox info,
and you also need great care when diverting FastGrab output to a sprite
(i.e. end of line wrap needs setting if sprite width is different from
the normal screen width).

SWI Vdig_Scale and Vdig_Rotate may be used when diverting VDU output to
a sprite, but be warned of possible rounding/overflow problems when
using BIG sprites, particularly with Rotate. 

System Variables File$Type_DFA and File$Type_DFB are set up as "Picture"
and "LookUp" respectively.

*FastSave and FastLoad are no longer needed, as *ScreenLoad/Save are now
fast. For compatibility, FastLoad/Save are retained, but now simply do
*ScreenLoad and ScreenSave, so error &80030A 'Not a full screen
ScreenSave file' no longer exists.

Due to high video DMA rates in modes 21,24 and 28, The screen needs to
be blanked for 20-40 milliseconds when grabbing, resulting in flicker
(like when using Adfs floppies in these modes). When a MODE change
occurs, the digitiser software runs a CPU speed test to determine
whether DMAs will need disabling whist grabbing. This is done (rather
than looking at mode numbers) to allow correct operation in user defined
screen modes, or with CPUs running at different speeds.  A new SWI is
provided to allow applications to deal sensibly with this situation, and
to allow control over the threshold used to determine whether DMAs will
be disabled : 

SWI Vdig_DMAThreshold  &802D4
On Entry :  R0 = New threshold, or 0 to just read info / do test
On Exit  :  A cpu speed test has been performed.
            R0 = Current threshold (default value is 1000)
            R1 = Current CPU 'speed'
            R2 = Current DMA disable flag state 
            (0=enabled,<>0=disabled)

The CPU 'speed' figure increases with increasing DMA activity or
reducing CPU clock rate. If the speed exceeds the threshold, DMAs will
be disabled whilst grabbing. Reducing the threshold causes screen
blanking in lower resolution screen modes, while increasing it causes
grabbed images to be corrupted in high res screen modes. The CPU speed
is tested (and the disable flag updated) on a MODE change, on
initialisation, and when this SWI is called. Mode independant
applications might use this SWI to suppress continous grabbing in high
res. modes to avoid flicker.
For example : 
 SYS "Vdig_DMAThreshold" TO ,,flick% : IF flick% THEN <disable grabbing>
 

NEW FEATURES
============
*See now has another option V, to ignore 'No video signal' errors.

SWI Vdig_Tables has two extra reason codes to simplify the writing of
screen mode independant applications : 

R0=9 : Sets up the user lookup table for the current screen mode to give
the best approximation to a greyscale, taking into account the current
screen mode and palette settings. In 256 colour modes, the 256 colour
user lookup table is set, and in other modes the 16 colour table is
used). In 256 colour modes, the setting of *Configure Shades is ignored,
and the table is set up assuming a colour monitor is in use. In 2 colour
modes, the table is set up to contain either 0..15 or 15..0, (used to
select the dot pattern number) depending on the relative brightness of
the two available logical colours. This call would typically be used by
digitiser wimp applications on initalisation, and after a mode or
palette change message from the window manager.

R0=10  : as above, but takes a 64 byte translation lookup table pointed
to by R1, and passes each possible pixel value through it before
calculating the nearest logical colour. For example, setting this table
to values 63..0 would produce a negative image. Contrast adjustment is
also possible using this method, without having to worry about the
current mode or palette. 

The above calls use the ColourTrans module (contained in
$.!System.Modules on the applications disk), and if it isn't present, an
error will be reported.

SWI Vdig_VideoParams has a new parameter in R2 - this is the time
threshold used to detect vertical sync. (default 50 arbitary units). The
vertical sync pulse is detected when the time between line sync
transitions exceeds this value. To avoid problems with old applications,
a new value will only be written if R2=&56nnnnnn (=ASC"V"), nnnnnn being
the new value. This will only need changing on machines with different
CPU speeds, silly DMA rates, or with strange video signals.

If The Lingenuity Colour Converter board is fitted, its contrast control
is set to maximum, colour saturation to minimum and input channel set to
green when the digitiser module is initialised. This allows the
converter to be left connected when grabbing mono pictures, as video
will be passed straight through. (Technical note : IC bus address 136
is written 3 times with data [1,0] [2,63] and [8,4] respectively)

________________________________________________________________________

A powerful desktop utility for the digitiser is under development, which
will allow access to most of the digitiser's facilities from the desktop
environment. It will allow images to be grabbed, displayed, and
immediately transferred into applications such as Desktop Publishing and
drawing programs. It also allows continuous display of the incoming
video signal on the screen while other applications are running.
Facilities will be provided for stretching, zooming, contrast adjustment
and smoothing of te image. This will be released as part of a 64Kbyte
ROM upgrade, which will include the updated digitiser module, although
probably with a few more facilities in addition to those described
above.
_________________________________________________________________________