Acorn Filter Manager v0.18:
Functional Specification

Document Status

Distribution:   General Release
Title:   Acorn Filter Manager v0.18: Functional Specification
Drawing Number:   1215,102/FS
Issue:   1
Author(s):   Ben Avison
  Andrew Hodgkinson
Date:   08/04/98
Change Number:   N/A
Last Issue:   N/A

Contents

  1. Document Status
  2. Issue History

  3. Overview
  4. Technical Background
  5. User Interface
  6. Programmer's Interface
    1. Service calls
      1. Service_FilterManagerInstalled
    2. SWI calls
      1. Filter_RegisterPreFilter
      2. Filter_RegisterPostFilter
      3. Filter_DeRegisterPreFilter
      4. Filter_DeRegisterPostFilter
      5. Filter_RegisterRectFilter
      6. Filter_DeRegisterRectFilter
      7. Filter_RegisterCopyFilter
      8. Filter_DeRegisterCopyFilter
      9. Filter_RegisterPostRectFilter
      10. Filter_DeRegisterPostRectFilter
      11. Filter_RegisterPostIconFilter
      12. Filter_DeRegisterPostIconFilter
  7. Dependencies
  8. Memory usage
  9. Future enhancements
  10. References

Issue history

Document 1309,218/FS describes various changes to the Filter Manager module but not in the same context as the (at the time of writing) recently released Nested Window Manager functional specification. This document has been derived from 1309,218/FS to fill the gap. It effectively stands as a companion to the aforementioned window manager specification.

1215,102/FS (General release)
1 08/04/98 HTML version built from 1309,218/FS for publishing on the Web as a companion document to the Nested Window Manager function specification.

Overview

This document covers the differences between the RISC OS 3.60 to 3.71 Filter Manager (version 0.11) and the newest release version to date (version 0.18). The changes are required to support the old Window Manager "get rectangle" and "rectangle copy" filters (previously unsupported by the Filter Manager), and the new Window Manager "post-rectangle" and "post-icon" filters. There are also some minor bug fixes.

Technical Background

The reader should have an understanding of the use of the conventional Filter Manager and the Wimp window redraw procedure, and also have read the Wimp_RegisterFilter section of the PRMs and the Nested Window Manager Functional Specification.

User Interface

The Filter Manager deals with low-level events, and thus does not have much of a user interface. However, it does have a single * command to list the installed filters, and this has been enhanced; the list now includes get rectangle, rectangle copy, post-rectangle and post-icon filters. For example: 

    *Filters

    Filters called on entry to Wimp_Poll:
    Filter          Task

    Clip            All tasks
    tbox_pre        ResTest
    tbox_pre        ToolboxProgram

    Filters called on exit from Wimp_Poll:
    Filter          Task                    Mask

    Clip            ARMovie Playing...      FFFFFFFB
    tbox_post       ResTest                 00000000
    tbox_post       ToolboxProgram          00000000

    Filters called on entry to Wimp_GetRectangle:
    Filter          Task

    Clip            All tasks

    Filters called on exit from Wimp_GetRectangle:
    Filter          Task


    Filters called after plotting icons in Wimp_GetRectangle:
    Filter          Task


    Filters called on entry to Wimp_BlockCopy:
    Filter

    Clip

Any task or filter names that are control-character-terminated (rather than null-terminated) will now be printed correctly.

The command line interface will now attempt to look up its Messages file using the system variable FilterManager$Path in preference to using 'Resources:$.Resources.FilterMgr.Messages'.

Programmer's interface

The service call interface has not changed much, whereas the SWI interface has been extended significantly.

Service calls

Service_FilterManagerInstalled (&87)

An undocumented feature of the FilterManager present in RISC OS 3.1 upwards was that R0 held the version number of the Filter Manager module multiplied by 100.

This behaviour can now be relied upon.

SWI calls

Filter_RegisterPreFilter (&42640)

This SWI is not re-entrant.

If the internal call to Wimp_RegisterFilter during this SWI returned an error for any reason, previous versions of the FilterManager would corrupt R0. This is fixed.

Filter_RegisterPostFilter (&42641)

This SWI is not re-entrant.

If the internal call to Wimp_RegisterFilter during this SWI returned an error for any reason, previous versions of the FilterManager would corrupt R0. This is fixed.

As of WindowManager 3.96, post-filters are also called (with a null event) when Wimp_StartTask returns control back to the parent task; this allows filters to keep track of which is the current task. Any attempt to claim the event in this case is safely ignored. However, be warned that in older Wimps, such a filter call was generated on return to the parent task if and only if the task did not call Wimp_Poll. Claiming the event is not safe in these circumstances.

Filter_DeRegisterPreFilter (&42642)

This SWI is not re-entrant.

Filter_DeRegisterPostFilter (&42643)

This SWI is not re-entrant.

Filter_RegisterRectFilter (&42644)

Add a Get Rectangle filter to the list of Get Rectangle filters

The old Filter Manager makes assumptions about the internal workings of the Wimp (and in particular the state of the stack) in order to obtain the window handle for Get Rectangle filter calls, because the Wimp does not provide the information itself. Both the Wimp and the Filter Manager will now pass the window definition pointers (i.e. the window handle minus one) directly, like all the other rectangle filters do.

As of WindowManager 3.86, this filter is no longer called during caret updates (the Post-Rectangle and Post-Icon filters never have been).

On entry

R0 = pointer to filter name (control terminated)
R1 = pointer to filter routine
R2 = value to be passed in R12 when filter is called
R3 = task handle to which to apply filter (or 0 for all tasks)
On exit
All registers preserved
Interrupts
Interrupt state is undefined. Fast interrupts are enabled.
Processor mode
Processor is in SVC mode.
Re-entrancy
SWI is not re-entrant.
Use
This call registers a Get Rectangle filter routine (pointed to by R1), which will be called before the redrawing of a rectangle belonging to the specified task begins, before the window background has been filled (if appropriate), and even before the VDU graphics window has been set up. Note that the Get Rectangle filter is called for window tools as well as the visible area, while the Post-Rectangle and Post-Icon filters are only ever called for the visible area.

The entry and exit conditions of the filter routine are:

On entry

R0 window handle
R2 task handle
R6-R9 rectangle about to be redrawn
(min x, min y, max x, max y; screen coordinates)
R12 value of R2 on entry to Filter_RegisterRectFilter

On exit
All registers must be preserved.

The routine should exit using the instruction:

MOVS PC,R14

Related SWIs
Filter_DeRegisterRectFilter
Filter_RegisterPostRectFilter
Filter_RegisterPostIconFilter
Related vectors
None

Filter_DeRegisterRectFilter (&42645)

Remove a Get Rectangle filter from the list of Get Rectangle filters

On entry

R0 = pointer to filter name (control terminated)
R1 = pointer to filter routine
R2 = value to be passed in R12 when filter is called
R3 = task handle to which to apply filter (or 0 for all tasks)
On exit
All registers preserved
Interrupts
Interrupt state is undefined. Fast interrupts are enabled.
Processor mode
Processor is in SVC mode.
Re-entrancy
SWI is not re-entrant.
Use
This call removes a Get Rectangle filter from the list of Get Rectangle filters. All values on entry must be the same as those used to originally register the filter (i.e. those that were passed to Filter_RegisterRectFilter).
Related SWIs
Filter_RegisterRectFilter
Related vectors
None

Filter_RegisterCopyFilter (&42646)

Add a Rectangle Copy filter to the list of Rectangle Copy filters

For the window handle passed to the registered routine to be valid requires a nested Wimp of version 3.90 or later. If a version 3.90 or later Wimp is ever present without nested window support, the window handle passed to the filter routine will be invalid.

On entry

R0 = pointer to filter name (control terminated)
R1 = pointer to filter routine
R2 = value to be passed in R12 when filter is called
On exit
All registers preserved
Interrupts
Interrupt state is undefined. Fast interrupts are enabled.
Processor mode
Processor is in SVC mode.
Re-entrancy
SWI is not re-entrant.
Use
This call registers a Rectangle Copy filter routine (pointed to by R1), which will be called before the Wimp copies a rectangle across the screen. The current and previous graphics cursor positions are describing the area to be copied, ready for the VDU block copy operation, but the actual operation has not yet been performed. Note that filters cannot currently specify which task handle to receive rectangle copy filter calls about.

The entry and exit conditions of the filter routine are:

On entry

R0 window handle
R2-R5 destination rectangle
(min x, min y, max x, max y; screen coordinates)
R6-R9 source rectangle
(min x, min y, max x, max y; screen coordinates)
R12 value of R2 on entry to Filter_RegisterCopyFilter

On exit
All registers must be preserved.

The routine should exit using the instruction:

MOVS PC,R14

Related SWIs
Filter_DeRegisterCopyFilter
Related vectors
None

Filter_DeRegisterCopyFilter (&42647)

Remove a Rectangle Copy filter from the list of Rectangle Copy filters

On entry

R0 = pointer to filter name (control terminated)
R1 = pointer to filter routine
R2 = value to be passed in R12 when filter is called
On exit
All registers preserved
Interrupts
Interrupt state is undefined. Fast interrupts are enabled.
Processor mode
Processor is in SVC mode.
Re-entrancy
SWI is not re-entrant.
Use
This call removes a Rectangle Copy filter from the list of Rectangle Copy filters. All values on entry must be the same as those used to originally register the filter (i.e. those that were passed to Filter_RegisterCopyFilter).
Related SWIs
Filter_RegisterCopyFilter
Related vectors
None

Filter_RegisterPostRectFilter (&42648)

Add a Post-Rectangle filter to the list of Post-Rectangle filters

This filter type requires WindowManager 3.86 or later for full support, but will work acceptably on versions 3.16 through 3.85 (even though those Wimps did not officially support post-rectangle filters) with minor inconsistencies - e.g. the colours will be be set differently.

On entry

R0 = pointer to filter name (control terminated)
R1 = pointer to filter routine
R2 = value to be passed in R12 when filter is called
R3 = task handle to which to apply filter (or 0 for all tasks)
On exit
All registers preserved
Interrupts
Interrupt state is undefined. Fast interrupts are enabled.
Processor mode
Processor is in SVC mode.
Re-entrancy
SWI is not re-entrant.
Use
This call registers a Post-Rectangle filter routine (pointed to by R1), which will be called after the window background has been drawn as part of the rectangle redraw code, i.e. shortly before Wimp_GetRectangle or Wimp_RedrawWindow (or their internal equivalents) reset the VDU state and return, unless the call is returning with "no more to do" status. Redraw loops initiated by Wimp_UpdateWindow never cause this filter to be called, because they do not cause the window background to be redrawn. However, the filter is called after a "transparent" window background would have been filled.

The entry and exit conditions of the filter routine are:

On entry

R0 window handle
R2 task handle
R6-R9 rectangle being redrawn
(min x, min y, max x, max y; screen coordinates)
R12 value of R2 on entry to Filter_RegisterPostRectFilter

On exit
All registers must be preserved.

The routine should exit using the instruction:

MOVS PC,R14

Related SWIs
Filter_RegisterRectFilter
Filter_DeRegisterPostRectFilter
Filter_RegisterPostIconFilter
Related vectors
None

Filter_DeRegisterPostRectFilter (&42649)

Remove a Post-Rectangle filter from the list of Post-Rectangle filters

On entry

R0 = pointer to filter name (control terminated)
R1 = pointer to filter routine
R2 = value to be passed in R12 when filter is called
R3 = task handle to which to apply filter (or 0 for all tasks)
On exit
All registers preserved
Interrupts
Interrupt state is undefined. Fast interrupts are enabled.
Processor mode
Processor is in SVC mode.
Re-entrancy
SWI is not re-entrant.
Use
This call removes a Post-Rectangle filter from the list of Post-Rectangle filters. All values on entry must be the same as those used to originally register the filter (i.e. those that were passed to Filter_RegisterPostRectFilter).
Related SWIs
Filter_RegisterPostRectFilter
Related vectors
None

Filter_RegisterPostIconFilter (&4264a)

Add a Post-Icon filter to the list of Post-Icon filters

This filter type requires WindowManager 3.86 or later in order to function.

On entry

R0 = pointer to filter name (control terminated)
R1 = pointer to filter routine
R2 = value to be passed in R12 when filter is called
R3 = task handle to which to apply filter (or 0 for all tasks)
On exit
All registers preserved
Interrupts
Interrupt state is undefined. Fast interrupts are enabled.
Processor mode
Processor is in SVC mode.
Re-entrancy
SWI is not re-entrant.
Use
This call registers a Post-Icon filter routine (pointed to by R1), which will be called after the window's icons have been drawn as part of the rectangle redraw code. Note that the icons are drawn after the application has finished its conventional redrawing and called Wimp_GetRectangle, so this is the only way in which an application can draw over its icons.

The entry and exit conditions of the filter routine are:

On entry

R0 window handle
R2 task handle
R6-R9 rectangle being redrawn
(min x, min y, max x, max y; screen coordinates)
R12 value of R2 on entry to Filter_RegisterPostIconFilter

On exit
All registers must be preserved.

The routine should exit using the instruction:

MOVS PC,R14

Related SWIs
Filter_RegisterRectFilter
Filter_RegisterPostRectFilter
Filter_DeRegisterPostIconFilter
Related vectors
None

Filter_DeRegisterPostIconFilter (&4264b)

Remove a Post-Icon filter from the list of Post-Icon filters

Note that FilterManager 0.17 does not correctly deregister Post-Icon filters due to corruption of the task handle. This bug is fixed in FilterManager 0.18.

On entry

R0 = pointer to filter name (control terminated)
R1 = pointer to filter routine
R2 = value to be passed in R12 when filter is called
R3 = task handle to which to apply filter (or 0 for all tasks)
On exit
All registers preserved
Interrupts
Interrupt state is undefined. Fast interrupts are enabled.
Processor mode
Processor is in SVC mode.
Re-entrancy
SWI is not re-entrant.
Use
This call removes a Post-Icon filter from the list of Post-Icon filters. All values on entry must be the same as those used to originally register the filter (i.e. those that were passed to Filter_RegisterPostIconFilter).
Related SWIs
Filter_RegisterPostIconFilter
Related vectors
None

Dependencies

The Filter Manager requires the Window Manager and (for the *Filters command) the Task Manager. Version 3.86 or later of the Window Manager is required for the post-icon filter type and for correct calling of the Get Rectangle filter during caret update. Version 3.90 or later of the (nested) Window Manager is required for passing of the window handle to Rectangle Copy filters.

Memory usage

The RISC OS 3.60 to 3.71 Filter Manager used under 3KB of code. Existing enhancements have brought this figure up to just under 5KB. Workspace requirements and ResourceFS space remain trivially small.

Future enhancements

No enhancements are planned at present.

References

The following references may be of interest:
Acorn Nested Window Manager Functional Specification
Document reference 1215,401/FS.
The Filter Manager
PRM Volume 3, section 56, pp. 303-312 and erratum, Volume 5a, page 668.
The Window Manager: Wimp_RegisterFilter
PRM Volume 3, section 53, pp. 224-225
Last updated 12 November 1998
© Acorn Computers Limited, 1997 		Valid HTML 4.0