Back to Contents        Previous        Next









19. Displaying Sprites, Drawfiles and JPEGs

The display of these common graphics files is straightforward using Dr Wimp and they all use a common approach designed to involve PROCuser_redraw().

Similarly, generally, the graphic file needs to be loaded into memory first - using the sequence described in Section 2.12 and choosing the correct file-loading wimp-function depending whether the file is a sprite, drawfile or JPEG.

It is worth noting at the outset that the display of graphics and the printing of graphics are very much related in Wimp programs and in many cases the same functions are used for both - under the general heading of ‘rendering a graphic’. This will explain why many of the wimp-functions use “render” rather than “display” or “print” in their function names.


There are a few differences between the different types of graphics files and these will be covered in the individual sub-sections below - and the first sub-section on Sprites will contain a detailed description which will generally apply to all the graphics types.



Sprites

Assuming that the sprite-file has already been correctly loaded into memory as in Section 2.12 - and that the main wish is to display a sprite in an application’s window - the wimp-function to use for displaying the sprite is:

PROCwimp_renderwindowsprite(window%,sname$,sarea%,bx,by%, minx%,miny%,maxx%,maxy%,xscale,yscale)

This looks more complicated than it is. window% is the handle of the window in which the sprite is to be displayed - and it is vital that this window was created with its ‘auto-redraw’ option unticked.

sname$ is the sprite name within the sprite-file - already loaded at sarea%.

bx% and by% are the work area coordinates (in OS units) of the bottom left-hand corner of the required sprite position in the window. i.e. the x/y values with reference to the top left corner of that window - so all visible y values will be negative.

minx%,miny%,maxx%,maxy% are the coordinates of the rectangle to be ‘redrawn’ (the ‘clipping rectangle’), Thses do not need to worry us here because they are merely copied through directly from the parameters passed in DEF PROCuser_redraw() where you will see the same set of four values.

xscale and yscale (note real rather than integer numbers) are your required x/y scaling factors for the sprite, with values <1 meaning a reduction in size and values >1 meaning enlargement, in their respective directions.

This one call can simply be placed inside DEF PROCuser_redraw() - with suitable ‘filtering’ to ensure that it is only relevant to the window intended. E.g. for a sprite called “mysprite” already loaded into block%, the coding might be:

DEF PROCuser_redraw(window%,minx%,miny%,maxx%,maxy%, printing%,page%)
CASE window% OF
WHEN main%
PROCwimp_renderwindowsprite(window%,”mysprite”,block%, 100,-300,minx%,miny%,maxx%,maxy%,1,1)
ENDCASE
ENDPROC

which will - if the window is fully visible and not scrolled - display the sprite at full size in the window with its bottom left corner at a position 100 OS units in from the left-hand edge of the window and 500 OS units down from the top edge of the window.

Note the important point that it doesn’t matter where the window is moved to on the screen: this call will ensure that the Wimp will automatically keep the sprite displayed in the correct relative location. By the same token, if you scroll the window the sprite will stay in the same position relative to the true window left/top edges - so the sprite will move to the left if you scroll the window horizontally and will start to disappear as the scroll exceeds 100 OS units.

If you were to set the value of the sprite area parameter to 0 (it is set to block% above) it would be telling the Wimp that your chosen sprite is already in the ‘Wimp sprite pool’ and you could then use any of the sprite pool sprite names for display e.g. all the sprites in Resources:$.Resources.Wimp.Sprites would be available to display.

In the Examples folder there is a full application demonstrating these rendering operations.

It is worth noting that we have ignored the passed parameters printing% and page% here. As you will have guessed they come into there own when printing and are not used when only displaying, but it reinforces the earlier point about the use of redraw for both printing and display..

There is a counterpart to PROCwimp_renderwindowsprite called PROCwimp_rendersprite i.e. without the “window” in its name. Accordingly, it does not have the window% parameter but is otherwise the same. Its purpose is predominantly for printing and, when used, the bx%/by% are put in screen/paper coordinates i.e. with reference to the bottom left corner of the display screen (see Section 2.22).

There is also a wimp-function for finding the width/height of a sprite. It is:

FNwimp_getspritesize(sname$,sarea%,side%)

where the first two parameters are as before and side% is set to 0 to get the width, or 1 to get the height - both in OS units.


Please note that sprites can also exist within a drawfile and they are then automatically rendered/printed using Dr Wimp’s drawfile facilities, as described below.


With regard to sprites in the ‘Wimp pool’, you will be aware that it is normal for all applications to add some items to this pool, via an *Iconsprites call in their !Run and/or !Boot file. For instance, the unique sprite(s) for an application’s filer icon and iconbar icon would normally be loaded into the Wimp sprite pool in this way and that is quite correct.
There is therefore a temptation to treat all of your sprites in this way, but it has the major disadvantage of taking up memory space even after the application has been quit. So you should use the ‘user sprite area’ approach for all other sprites.



Drawfiles
(Note: rendering drawfiles with Dr Wimp requires RISCOS Version 3.60 or higher.)

Unlike sprite-files, a drawfile contains only one draw document - but this can, of course, be made up of numerous ‘objects’ including text, sprites, transformed text, transformed sprites and JPEGs.

Before display, a drawfile needs to be loaded into memory as described in Section 2.12.

But there is also one further thing that needs to be done - a single call to PROCwimp_initdfile needs to be made.

It has no parameters and only needs to be made once, for any number of drawfiles. Its role is to set up some small special memory blocks ‘behind the scenes’ and the details do not need to concern us here.

As with sprites, the main call of interest for displaying a drawfile has “window” in its name. It is:

PROCwimp_renderwindow(window%,dfile%,bx%,by%, minx%,miny%,maxx%,maxy%,xscale,yscale,origin%)

The only differences from the sprite equivalent call are that, firstly, xscale and yscale can take negative numbers which will render the drawfile back-to-front and/or upside-down (but this will not work for JPEG objects in a drawfile).

Secondly, the handle of the stored drawfile, dfile%, is sufficient in the drawfile case and there is the added parameter called origin% which is a flag to activate an optional feature explained below.

The natural origin of all drawfiles is the bottom left corner of the !Draw page. However, very often, a drawfile is constructed of objects drawn higher up on the page - with, say, some empty space below and/or to the left of a rectangular ‘bounding box’ which would just surround all the objects, as below:



Picture Pics/pic009.png Such a drawfile can be rendered in one of two ways: if origin% is set to 0 then the whole drawfile page will be rendered ‘naturally’ i.e. the bottom left corner of the drawfile page (A) will be located at the specified x/y position. However, if origin% is set to 1 then the drawfile will be rendered with the bottom left corner of its overall ‘bounding box’ (B) located at the specified x/y position - i.e. exactly as if the overall bounding box of the objects was at the bottom left corner of the drawfile page.

This latter option makes it much easier to place drawfile objects exactly where you want them without needing to worry about any unwanted offsets which may occur when using ‘natural’ rendering. This option also correctly takes into account any scaling required by xscale and yscale.

As with the sprite case, there is a counterpart to PROCwimp_renderwindow for drawfiles called, simply, PROCwimp_render i.e. without the “window” in its name. And as before, its purpose is predominantly for printing.

Also similar to the sprite case, FNwimp_getdfilesize returns the width and height of a drawfile. In fact, it returns the sizes of the ‘bounding box’ containing all the drawfile objects.



(If you are using the utilities !FontFix or !SpecialFX at the same time as a Dr Wimp application which renders drawfiles a few users have reported a clash. The problem disappears if you disable those utilities temporarily - and their Help files say how.)


JPEG files

You will not be able to use Dr Wimp’s JPEG facilities if your RISCOS Version is less than 3.60 - but it might be possible if you load the SpriteExtend 0.99 Module available for download free at http://acorn.riscos.con/riscos/releases/spriteextend.arc

The JPEG format is a very popular method of storing digital images, particularly photographic images. Like sprites, it is a ‘bit-map’ process. A JPEG file has a filetype &C85 (”JPEG”).

As for sprites and drawfiles, a JPEG file needs to be loaded into memory first, using the sequence described in Section 2.12.

Then, for displaying a JPEG in a window, this is the call:

PROCwimp_renderwindowjpeg(window%,jpeghandle%,bx%,by%, minx%,miny%,maxx%,maxy%,xscalereal,yscalereal)

It is entirely similar to the sprite case above, but now with jpeghandle% being the handle of the memory block where the file has been loaded.


As with the sprite and drawfile cases, there is a counterpart to PROCwimp_renderwindowjpeg called PROCwimp_renderjpeg i.e. without the “window” in its name. And as before, its purpose is predominantly for printing.

Also similar to the sprite and drawfile cases, FNwimp_getjpegsize returns the width and height of a JPEG. (There is an option to return either its natural size or the size for the JPEG displayed at 90dpi.)


(Note that JPEG images can also exist within a drawfile and are then automatically rendered/printed using Dr Wimp’s drawfile facilities, as described above.)



However, for JPEGs only, there is an option to carry out display-only operations (i.e. not printing) without needing to load the file into memory first.

The corresponding wimp-function calls are then:

PROCwimp_renderwindowjpegfile(window%,jpegfilepath$,bx%,by%, minx%,miny%,maxx%,maxy%,xscalereal,yscalereal,warning%)

PROCwimp_renderjpegfile(jpegfilepath$,bx%,by%,minx%,miny%, maxx%,maxy%,xscalereal,yscalereal,warning%)

FNwimp_getjpegsizefile(jpegfilepath$,side%,dpi90%,warning%)

and the use of the filepath rather than the memory handle should be self-explanatory. The only addition is the final parameter warning% which - as in several other wimp-functions - allows the programmer to choose whether or not a warning will be given if the filepath cannot be found.



Possible practical problems
The most common practical problems with displaying graphics concern getting the coordinates right i.e. with reference to the top left corner of the unscrolled window. Remember that displaying in a window uses the calls with “window” in their name - made inside DEF PROCuser_redraw() - and that all visible y-values are negative.

By and large, if your rendering action appears to produce nothing visible yet no error messages appear, then it is very likely that the rendering is actually off-screen/off page or outside the window (and with a drawfile this could also simply be the result of having the flag origin% set wrongly). (The charity book “Dr Wimp’s Surgery” takes you through the rendering and coordinate conversion processes step by step.)


You may (rarely) run across a sprite which does not render in the correct colours. If this happens, try using the alternative sprite rendering method i.e. if a sprite in the Wimp sprite pool gives wrong colours, copy it to a user sprite area and try again (not forgetting to reset the spritearea% parameter!) - or drag the sprite to a drawfile and render the drawfile instead.

Finally, as we have seen, the wimp-functions provided for rendering allow scaling in the x and/or y direction. However, any other required translation e.g rotation/shearing/reversal etc. of objects needs to be done previously in the source sprite/drawfile.





Top of page        Back to Contents        Previous        Next