Ursula Filter Manager Changes
Functional Specification
SUBJECT TO CHANGE WITHOUT NOTICE
| Document Ref: | 1309,217/FS |
| Project: | Ursula |
| Revision: | D |
| Date: | 06 March 1998 |
| Author(s): | Ben Avison |
| Changes: |
Contents:
| 1. | Overview |
| 2. | Outstanding Issues |
| 3. | Technical Background |
| 4. | User Interface |
| 5. | Programming Interface |
| 6. | Data Interchange |
| 7. | Dependencies |
| 8. | References |
1. Overview
This document will cover the differences between the RISC OS 3.60 - 3.71 Filter Manager (version 0.11) and the version being specified herein for the Ursula release. 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.
3. Technical Background
The reader should have an understanding of the use of the conventional Filter Manager ( [1] and [2] ) and the Wimp window redraw procedure, and also have read the Wimp_RegisterFilter section of the Nested Window Manager Functional Specification [3].
4. 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 will be enhanced; the list also now includes get rectangle, rectangle copy, post-rectangle and post-icon filters, and the layout will be clarified (including widening of the columns and truncation of filter and task names to make them fit the table). In the example below, there is a filter called "A_Very_Long_Filter_Name":
*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 at the start of a rectangle redraw:
Filter Task
------ ----
Clip All tasks
Filters called after any work area fill in a rectangle redraw:
Filter Task
------ ----
A_Very_Long_Filte All tasks
Filters called after icons are plotted in a rectangle redraw:
Filter Task
------ ----
A_Very_Long_Filte All tasks
Filters called just before a rectangle copy:
Filter
------
Clip
Any task or filter names that are control-character-terminated (rather than null-terminated) will 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, except for the *Filters help and syntax strings, which are always read from ResourceFS.
5. Programming Interface
5.1. Service Calls
5.1.1. Service_FilterManagerInstalled (Service Call &87)
R0 will be documented as holding the version number of the Filter Manager, multiplied by 100. (This has been the case since the service call was introduced in RISC OS 3.10.)
5.2. SWI Calls
5.2.1. Filter_RegisterPreFilter (SWI &42640)
This SWI will be documented as non re-entrant
5.2.2. Filter_RegisterPostFilter (SWI &42641)
This SWI will be documented as non re-entrant.
As of Wimp version 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 tabs on 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 child task did not call Wimp_Poll; claiming the event is not safe in these circumstances.
5.2.3. Filter_DeRegisterPreFilter (SWI &42642)
This SWI will in future be documented as non re-entrant.
5.2.4. Filter_DeRegisterPostFilter (SWI &42643)
This SWI will in future be documented as non re-entrant.
5.2.5. Filter_RegisterRectFilter (SWI &42644)
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 be altered to pass the window definition pointer (ie the window handle minus one) directly, like all the other rectangle filters do.
As of Wimp version 3.86, this filter is no longer called during caret updates.
The SWI will have the following functionality:
Adds a new get rectangle filter to the list of get rectangle filters.
On Entry:
R0 = pointer to filter name (null 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 (low x, low y, high x, high y)
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_RegisterPreFilter, Filter_RegisterPostFilter, Filter_DeRegisterRectFilter, Filter_RegisterCopyFilter, Filter_RegisterPostRectFilter, Filter_RegisterPostIconFilter
Related Vectors:
None
5.2.6. Filter_DeRegisterRectFilter (SWI &42645)
The SWI will have the following functionality:
Removes a get rectangle filter from the list of get rectangle filters.
On Entry:
R0 = pointer to filter name (null 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 (ie those that were passed to Filter_RegisterRectFilter).
Related SWIs:
Filter_RegisterRectFilter
Related Vectors:
None
5.2.7. Filter_RegisterCopyFilter (SWI &42646)
For the window handle passed to the registered routine to be valid requires a nested Wimp of version 3.90 or later - such as Ursula's Wimp.
The SWI will have the following functionality:
Adds a new rectangle copy filter to the list of rectangle copy filters.
On Entry:
R0 = pointer to filter name (null 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 (low x, low y, high x, high y)
R6-R9 = source rectangle (low x, low y, high x, high y)
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_RegisterPreFilter, Filter_RegisterPostFilter, Filter_RegisterRectFilter, Filter_DeRegisterCopyFilter, Filter_RegisterPostRectFilter, Filter_RegisterPostIconFilter
Related Vectors:
None
5.2.8. Filter_DeRegisterCopyFilter (SWI &42647)
The SWI will have the following functionality:
Removes a rectangle copy filter from the list of rectangle copy filters.
On Entry:
R0 = pointer to filter name (null 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 (ie those that were passed to Filter_RegisterCopyFilter).
Related SWIs:
Filter_RegisterCopyFilter
Related Vectors:
None
5.2.9. Filter_RegisterPostRectFilter (SWI &42648)
This filter type requires a Wimp of version 3.86 or later for full support.
The SWI will have the following functionality:
Adds a new post-rectangle filter to the list of post-rectangle filters.
On Entry:
R0 = pointer to filter name (null 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, ie 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 (low x, low y, high x, high y)
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_RegisterPreFilter, Filter_RegisterPostFilter, Filter_RegisterRectFilter, Filter_RegisterCopyFilter, Filter_DeRegisterPostRectFilter, Filter_RegisterPostIconFilter
Related Vectors:
None
5.2.10. Filter_DeRegisterPostRectFilter (SWI &42649)
The SWI will have the following functionality:
Removes a post-rectangle filter from the list of post-rectangle filters.
On Entry:
R0 = pointer to filter name (null 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 (ie those that were passed to Filter_RegisterPostRectFilter).
Related SWIs:
Filter_RegisterPostRectFilter
Related Vectors:
None
5.2.11. Filter_RegisterPostIconFilter (SWI &4264A)
These filter routines require a Wimp of version 3.86 or later in order to function.
The SWI will have the following functionality:
Adds a new post-icon filter to the list of post-icon filters.
On Entry:
R0 = pointer to filter name (null 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 (low x, low y, high x, high y)
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_RegisterPreFilter, Filter_RegisterPostFilter, Filter_RegisterRectFilter, Filter_RegisterCopyFilter, Filter_RegisterPostRectFilter, Filter_DeRegisterPostIconFilter
Related Vectors:
None
5.2.12. Filter_DeRegisterPostIconFilter (SWI &4264B)
The SWI will have the following functionality:
Removes a post-icon filter from the list of post-icon filters.
On Entry:
R0 = pointer to filter name (null 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 (ie those that were passed to Filter_RegisterPostIconFilter).
Related SWIs:
Filter_RegisterPostIconFilter
Related Vectors:
None
6. Data Interchange
Data interchange protocols remain unchanged.
7. 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 filter type filters.
8. References
[1]: RISC OS 3 PRM 3 §53: The Window Manager, pp 3-224 - 3-225
[2]: RISC OS 3 PRM 3 §56: The Filter Manager, pp 3-303 - 3-312 and erratum, p 5a-668
[3]: Document Ref 1215,401/FS: Acorn Nested Window Manager Functional Specification