|
Rendering into Windows
Introduction
The RedrawManager module, together with the FilterManager and recent versions of the Window Manager, provides a mechanism for drawing into a window as part of the Window Manager's redraw process. This allows clients to implement complex rendering transparently without requiring the application to be updated to explicitly call the rendering routines as part of their redraw loop. Complex gadget redraws are made much simpler through the use of the RedrawManager. With RedrawManager, Gadgets may redrawing their content without any application-specific support.
The functions of the RedrawManager are used by the more recent Window toolbox objects to allow gadgets to redraw more complex gadgets. This document covers RedrawManager 0.11 and later.
Technical details
In some instances it is necessary to have a complex graphic in a window which cannot be represented as text or a sprite and so requires an external source to redraw it. This is achieved via the Wimp's Post-Rectangle Filters. The Filter Manager (version 0.13 and above) makes these filters available to other modules so that they can draw directly into a Wimp window. Filter Manager 0.15, in conjunction with version 3.86 of the Wimp also provides Post-Icon Filters.
Post-Rectangle filters are available in Window Manager modules 3.86 or later. On versions 3.16-3.85 of the Wimp, the Filter Manager will simulate the post-rectangle filter using the rectangle filter. (The original rectangle filter itself is not useful for this application because it is called for the window tools as well as window contents, and is also called before the Window Manager draws the window background).
Post-Icon filters are only are only available in Window Manager modules 3.86 or later; they are not simulated on older Window Managers.
Post-Rectangle and Post-Icon filters are quite low level and there are a number of complications when using them directly, so a new module, the Redraw Manager has been written. This enables a module to 'register interest' in a region of a wimp window and then be called back whenever this region has been invalidated. Note that Rectangle filters work even if the window is 'auto-redraw' and so the client does not need to know that the Gadget is being provided in this way.
When the callback is made, the module is told which part of the window is being updated and how this intersects with the region that was registered. A data pointer is also passed back so that the module can access the required information for redrawing the region. As a result the call will be made separately for each region that is currently invalid that the module has registered an interest in.
The callback is made during a redraw loop (so Wimp_PlotIcon takes work area coordinates). Do not call Wimp_GetRectangle or Wimp_UpdateWindow in your callback routine. The order of actions for each rectangle being redrawn is:
- The Filter Manager calls rectangle filters.
- The Window Manager draws the window tools and the window background.
- The Filter Manager calls post-rectangle filters, including the Redraw Manager.
- The Redraw Manager calls 'early' callback routines for the areas of interest intersecting the rectangle being drawn
- The Window Manager sets the graphics foreground and background colours according to the window definition.
- The application owning the window draws any contents in its redraw loop.
- The Window Manager draws the icons.
- The Filter Manager calls post-icon filters, including the Redraw Manager.
- The Redraw Manager calls 'late' callback routines for the areas of interest intersecting the rectangle being drawn.
Thus anything your callback routine redraws will appear behind the rest of the window contents, unless you ask for a 'late' callback (bit 3 of R0 set in Redraw_AddCallBack), in which case what you draw will appear in front of the rest of the window contents. It is generally recommended that you do not use 'late' callbacks unless your application/gadget will only ever run on version 3.86 or later of the Wimp.
Notes:
Wimps prior to 3.86 have a bug which means that rectangle filters (and hence the simulated post-rectangle filters) are erroneously called when the caret moves. This can result in strange effects if, for example, a writable icon is placed in front of a graphic drawn via the Redraw Manager. This shouldn't normally affect gadget authors, as gadgets shouldn't normally overlap. A fix for this may be implemented in future releases of the Filter Manager.
When post-rectangle filters are being simulated on Wimps prior to 3.86, the Window Manager will set up graphics colours between stages 2 and 3 above as well as in step 5. This does not happen with Wimp 3.86 or later, so do not rely on this behaviour.
Toolbox window gadgets
Whilst it is possible to implement Toolbox Window Gadgets directly using these interfaces, it is recommended that gadget authors use the interface provided by the Window module to provide gadget rendering callbacks. The Window module provides a redraw entry through the regular gadget entry point with similar parameters to those provided by the RedrawManager, thus simplifying the process of extending such gadgets.
SWIs
Redraw_AddCallBack (SWI &82C80)
On entry
R0 = flags:
bit 0 reserved
bit 1 set, set up graphics rectangle before making SWI
bit 2 set, return co-ordinates to callback in screen co-ordinates
bit 3 set, call after plotting icons, else before user contents
bit 4 set, R2 is the address of the routine to call
bits 5-31 reserved
R1 = Wimp window handle
R2 = SWI number, or pointer to code address to call for redraw requests
R3 = pointer to bounding box of region (in work area coordinates)
R4 = data to associate with region, passed in R4
R5 = private word for direct call (bit 4 of flags set)
On exit
All registers preserved
This SWI registers an 'interest' in a region of a window so that the module will be called whenever the region is updated. Setting bit 1 will ensure that a suitable graphics window will have been set up before the module is called (restricting output to within both the redraw rectangle and the area of interest). If bit 1 isn't set the graphics window will be the whole redraw rectangle.
Setting bit 3 means that you will be called after the Wimp has plotted any icons in the window, so that what you draw will appear on top of anything else (a 'late' redraw). This behaviour is only available with version 3.86 or later of the Window Manager.
Setting bit 4 means that the call will be made to a routine, rather than to a SWI as a direct call. This allows modules without SWIs to use the RedrawManager interface without having to obtain a SWI chunk for this single entry. The overheads for this form of call will typically be lower than those of a SWI.
SWI Redraw_RemoveCallBack (&82C81)
On entry
R0 = flags (must match flags passed to Redraw_AddCallBack)
R1 = Wimp window handle
R2 = SWI number, or pointer to code address to call for redraw requests
R3 = pointer to bounding box of region (in work area coordinates)
R4 = data to associate with region, passed in R4
R5 = private word for direct call (bit 4 of flags set)
On exit
All registers preserved
This SWI deregisters an 'interest' in a region of a window. In order to deregister successfully, all the parameters must match in the way that the region was registered.
Callback entry point
Redraw_CallbackEntry
On entry
R0 = flags:
bit 0 set, your region is entirely inside the area being updated
bits 1-31 reserved
R1 = pointer to bounding box of region being updated (in work area coordinates or
screen coordinates depending on bit 2 of flags in call to Redraw_AddCallBack)
R2 = pointer to 'state' for this window as returned from Wimp_GetWindowState
R3 = pointer to bounding box of registered region (in work area coordinates)
R4 = data associated with region as passed in R4 to RedrawManager_AddCallBack
R12 = private word value for direct called routines as passed in R5 to Redraw_AddCallBack
On exit
All registers preserved
Flags are ignored
The Redraw Manager calls a module when a region requires redrawing with the above registers set up.
Services
Service_RedrawManagerInstalled (&A5)
On entry
R0 = Redraw Manager version x 100
R1 = &A5
On exit
All registers preserved
This service call is issued when the Redraw Manager starts up. You may then register areas of interest using Redraw_AddCallBack.
Service_RedrawManagerDying (&A6)
On entry
R1 = &A6 (reason code)
On exit
All registers preserved
This service call is issued as a broadcast to inform Redraw Manager clients that they have been deregistered and that the Redraw Manager is about to die.
|
![[Select]](../imgs/seldoc.png)
