Back to Contents        Previous        Next








20. Dynamic Areas

(You will need a RISCOS Version of 3.60 or higher to use Dr Wimp’s Dynamic Area facilities.)

Often it is necessary to be able to load data into memory which is set aside for that purpose.

Traditional method
Traditionally, a block of memory to be used for data storage is created with something like:

DIM block% 2048

which creates a block, called block%, 2048 bytes in size (2049 bytes actually - bytes 0-2048!).

The main problems with this are that the size of the block, and hence the maximum size of data that can be loaded, in is “hard-wired” into the program and, further, the block needs to be catered for in the size of the WimpSlot.

One partial solution to this is to put the size of the memory block into the !Run file by using a system variable. Thus:

Set MaxSize 2048

and then reading the value of the system variable MaxSize into the program with FNwimp_getsysvariable and creating the block accordingly. However, this requires that the application user edits the !Run file - and maybe the WimpSlot too - so this solution is not ideal.

A better solution is to use a ‘dynamic area’.

‘Dynamic areas’
A dynamic area is a block of memory - dedicated to your application - but it can shrink and expand in size, and it does not form part of the WimpSlot. The memory is taken from and returned to the free application memory pool as the block changes size, and thus the only limit on the size of a dynamic area is the amount of memory in the machine.

With Dr Wimp an application can create its own dynamic areas . These will be referred to as ADAs, for Application Dynamic Areas. Once created, these can then be expanded or shrunk as you wish - and they also appear in the Task Manager display.


The wimp-functions
DrWimp provides four wimp-functions for the creation, management and deletion of dynamic areas:

FNwimp_createdynamic()
FNwimp_changedynamic()
FNwimp_measuredynamic()
PROCwimp_deletedynamic()

Taking these in turn:

Creation

block%=FNwimp_createdynamic(size%,maxsize%,drag%,name$)

creates a dynamic area. The initial size, in bytes, is specified in size% and the maximum size to which this dynamic area can be expanded is put in maxsize%. It is important to try to set maxsize% to a realistic limit - and, often, size% and maxsize% can be made the same i.e. when you don’t need to adjust the dynamic area size at all. If you really do not want to limit the maximum size and you don’t know what value to use then you can set maxsize% to the special value of -1. This will then allow that dynamic area to expand up to the maximum your machine can cope with. But be warned! Using this value is not recommended as it can severely limit the use and management of dynamic areas and be the root of odd fatal errors.

name$ is the text that will be shown on the Task Display for this dynamic area - and setting drag% to 1 allows the size of the dynamic area to be changed by dragging the corresponding bar on the Task Display.

So, a typical call might be:

block%=FNwimp_createdynamic(1024,8192,0,"Test DA")

which will create a Dynamic area of 1024 bytes (but see later) with the capability of being expanded to 8192 bytes. The Task Display will show this area with the name “Test DA” but the area will not be able to be changed by dragging.


Note that RISC OS currently limits the minimum size of ADA dynamic areas to 4kbytes (4096 bytes) and also only allows ADA dynamic area sizes to be multiples of this same value i.e. ADA dynamic areas will only have values 4kbytes, 8kbytes, 12kbytes, ..... etc. There is no need for these exact values to be used in the calls: any specified value will be rounded up automatically. Provided that the actual size of an ADA is at least large enough for your needs it can be used without restriction. (Because of the 4k ‘lumps’, if the need is to load, say, more than one file into memory, then it would normally take less overall memory space to create one ADA to hold all the files - as described in Section 2.12.)


After creation of an ADA you can store data in it, such as drawfiles, sprite­files, or anything you like. The previous examples given for sizing and loading sprite-files, drawfiles and JPEG files need only substitute a dynamic area handle for the DIMmed handle. For example, if a sprite-file has the path path$ the measuring and loading sequence would be:

size%=FNwimp_measurefile(path$,0)
block%=FNwimp_createdynamic(size%,size%,0,”Sprite Files”)
d%=FNwimp_loadsprites(path$,block%,0)




Changing size
It is easy to change the size of an existing ADA with:

FNwimp_changedynamic(darea%,absolute%,size%)

darea% is the existing dynamic area’s handle. If absolute% is set to 0 then the value of size% is treated as incremental (+ or -). If absolute% is set to 1 then the value of size% is interpreted as the new required size.

The function returns the handle of the re-sized ADA and it should be noted that it will not necessarily be the same as before. It is therefore quite common to use the call in the following way, re-assigning the new handle to the old handle:

For example, to increase a dynamic area by 4096 bytes:

block%=FNwimp_changedynamic(block%,0,4096)

or to shrink it by 4096 bytes:

block%=FNwimp_changedynamic(block%,0,-4096)

Or, to make the new size 8192 bytes:

block%=FNwimp_changedynamic(block%,1,8192)


Note that the previously mentioned point about ADA dynamic areas being constrained to steps of 4kbytes often has much more practical effect when changing dynamic area sizes. For instance, reduction of less than 4kbytes will leave the actual size of an ADA dynamic area unchanged.


Finding the size of an existing dynamic area

The current size (in bytes) of an existing dynamic area can be obtained with:

size%=FNwimp_measuredynamic(darea%)

Deleting dynamic areas
When any dynamic area is finished with it is good housekeeping to delete it immediately - to avoid wasting memory. Simply use:

PROCwimp_deletedynamic(darea%)

(Note: Any dynamic areas created by your application with FNwimp_createdynamicarea() but not specifically deleted during the program run will be deleted automatically when you quit the application. This includes quitting due to most fatal errors.)

Note: To manage Dynamic Areas properly Dr Wimp needs to set the maximum number of dynamic areas that can be used by any one of its applications. This value is set by the global variable wMaxdynamicareas% in DEF FNwimp_initialise (near the start of the DrWimp library listing). As supplied, it is set to 16 which is likely to be more than adequate for most applications. However, the value can be changed for any specific application, if required.




Top of page        Back to Contents        Previous        Next