RasterUtils V 2.60 (18 Oct 1993)                          by Toby Duckworth
--------------------------------                          (0278) 684508

What is it?
-----------

   The Raster utilities module allows the display of beautiful raster bars (known as copper bars on the Amiga) on an Archimedes, thus brightening up a sometimes boring desktop.  It looks especially nice with one of Acorn's backdrops.
   The raster module allows many changes to be made to the appearance of these bars, such as the colour changed by them, the size of the bars, and the colours displayed by the module.
   



* Commands
----------

*RasterOn       -     As its name suggests, this command switches the raster
                      bars on.

*RasterOff      -     Switches the raster bars off.

*RasterCol <0-16>  -  Changes the logical colour changed by the module.
                      In desktop, the colours, and their numbers can be
                      viewed by opening the palette.  The desktop background
                      is normally logical colour 4.  The border is colour
                      number 16.

                      If you ask for a colour that cannot be handled by
                      the current mode, such as asking for a colour other
                      than the border in a 256 colour mode, the module will
                      inform you of your mistake, and wait until a suitable
                      mode is selected before using your colour selection.

                      Similarly, if you change into a mode in which the
                      current raster colour cannot be used, the module will
                      change the border colour, until a suitable mode is
                      chosen.

*RasterTime <n> -     Changes the time between the rasterbars.  The default
                      value is 800.  Changing this value to a larger value
                      will result in larger bars, and a smaller value will
                      result in smaller bars.  This will obviously alter the
                      number of bars on screen.

*RasterCycle <n>  -   This effectively changes the speed at which the bars
                      cycle.  The default value is 1.  A value of 0 will
                      cause static rasters, and larger values will increase
                      the speed at which the rasters fly by.

*RasterStatus     -   This command will display the current status of the
                      raster module.  Information such as time between bars                        colour changed, and whether the module is waiting for
                      a mode change to process a colour request are included.




SWI commands
------------

SWI "Raster_State"
    &D3940

On Entry   -   R0 = new state of rasterbars...
                    0 to switch off
                    1 to switch on
                   -1 to read current state

On Exit    -   R0 = current state if requested, otherwise preserved

Use        -   To change, or read the state of the raster bars



SWI "Raster_Colour"
    &D3941

On Entry   -   R0 = VIDC palette register to be changed (0-16)
                    -1 to read current colour and colour request
                   
On Exit    -   If colour change was successful
               R0  preserved
               
               If colour change was unsuccessful
               R0 = -1
               R1 = number of colours supported by current mode
               & a colour request is set up to be serviced on mode change

               If -1 was issued on entry
               R0 = current logical colour changed (0-16)
               R1 = current requested colour (-1 if none)

Use        -   To change the VIDC palette register altered by the module.  Or
               to read the current register changed and the current colour
               request pending a mode change. Or to set up a new colour
               request to be serviced on mode change



SWI "Raster_Time"
    &D3942

On Entry   -   R0 = Time between buffers (0 - 1<<16)
                    -1 to read current setting

On Exit    -   R0 = preserved if successful
                    -1 if an illegal value (i.e. > 1<<16) was input
                    the current setting if requested on entry

Use        -   Effectively changes the size of the raster bars by changing
               value used by IOC's timer 1.  Note that values under 100 may
               cause a machine crash, as timer 1 may interrupt its own
               handler code.


SWI "Raster_Cycle"
    &D3943

On Entry   -   R0 = new cycle value (0 - 255)
                    -1 to read current setting

On Exit    -   R0 = preserved if successful
                    -1 if an illegal value was input
                    current setting if it was requested

Use        -   Effectively changes the speed at which the raster bars cycle
               by changing the amount added to the colour look up table.
               This allows for stationary rasters, and rasters of any speed.


SWI "Raster_Report"
    &D3944

On Entry   -   R0 = pointer to 7 word (28 byte) block

On Exit    -   R0 = preserved

	       R0 + 0 = raster status (0 - on   1 - off)
	       R0 + 4 = time between raster bars
	       R0 + 8 = raster cycle value
	       R0 +12 = VIDC register changed
	       R0 +16 = colour request pending a mode change (-1 if none)
	       R0 +20 = address of the colour table (in RMA)
	       R0 +24 = length of colour table in words

Use        -   To give a full report on the status of the resters which can                 be analysed by the host program.



SWI "Raster_ClearRequest"
    &D3945

On Entry   -   R0 = 0 to read current requested colour
                    -1 to clear colour request

On Exit    -   R0 = previous requested colour if R0 = 0 on entry
                    preserved if R0 = -1 on entry


SWI "Raster_ColourMap"
    &D3946

On Entry   -   R0 = reason code (0 - 4)

                    0  find address of colour map (in RMA)
                    1  find length of colour map in words
                    2  dump colour map to a buffer
                    3  claim a new colour map
                    4  reset to default colour map


SWI "Raster_ColourMap" 0
    &D3946

On Entry   -   R0 = 0 (reason code)

On Exit    -   R0 = address of colour map in RMA

Use        -   To return the address of the colour map.  This allows the host               program to edit the existing colour map if required, or to                   poke values directly to it, although this is not always                      neccessary, as reason code 3 allows a whole new colour map to                be claimed.

SWI "Raster_ColourMap" 1
    &D3946

On Entry   -   R0 = 1 (reason code)

On Exit    -   R0 = length of colour map in words

Use        -   To return the length of the colour map in RMA.  This is useful               if the user wishes to dump the current colour map to memory.



SWI "Raster_ColourMap" 2
    &D3946

On Entry   -   R0 = 2 (reason code)
               R1 = pointer to buffer of appropriate length

On Exit    -   R0 = preserved
               R1 = preserved
               R2 = length of colour map in words

Use        -   To take a copy of the colour map currently used by the raster                module.  This can then be edited, and reclaimed by the module.



SWI "Raster_ColourMap" 3
    &D3946

On Entry   -   R0 = 3 (reason code)
               R1 = address of colour map to claim
               R2 = length of colour map in words

On Exit    -   All registers preserved

Use        -   To tell the raster module to use a new colour map (i.e. to
               display new raster colours).  The module takes a copy of the
               new table, which must be at least 256 words long, this copy
               is put into RMA, the first 256 words are copied onto the end
               of the colour map to allow cycling.

               Each word of data must be of the format &BGR where B G R are
               the red, green, blue components of the colour each with values
               between 0 and 15.  If you are not sure that your data is in
               this format, it can be filtered using SWI "Raster_FilterMap"
               to ensure that it does not cause a system crash.

SWI "Raster_ColourMap" 4
    &D3946

On Entry   -   R0 = 4 (Reason Code)

On Exit    -   R0 = preserved

Use            To reset to the default colour map built into the raster
               module.  This call resets the RMA workspace size, and copies
               the deafault colour map into it.  Always handy if your
               experiments go a little too far!




SWI "Raster_FilterMap"
    &D3947

On Entry   -   R0 = mask (0 - &FFF)
	       R1 = pointer to colour map (0 if RMA table is to be filtered)
	       R2 = map length in words   (redundant if filtering RMA table)
	       R3 = filter type ( 0 for logical AND, 1 for logical ORR)

OnExit     -   All registers preserved

Use        -   This call is particularly useful if you wish to change the
               appearance of the rasters during a program.  For example, the
               Red component of the colour map currently in RMA could be cut
               out by using:

               SWI "Raster_FilterMap",&0FF,0,,0

               Any colour map can be filtered simply by entering its address
               and length in words, this means that if you are not sure that
               your colour map is suitable for the raster module (i.e. if you
               think that other bits apart from 0-11 are set).  This is done
               as follows:

               SWI "Raster_FilterMap",&FFF,<address>,<length>,0

               Another use of this command is to add another colour component               to the map.  For example, if you wanted to add a green
               component of 7 all the way through the map, this would be done
               as follows:

               SWI "Raster_FilterMap",&070,<address>,<length>,1

               or for the current map:

               SWI "Raster_FilterMap",&070,0,,1

 
















