For those writing applications using physical regions, only the following routine is currently available in Dervish (several routines must also be provided by the user - see below). All manipulations of physical regions are deferred to the TCL level where many virtual region verbs apply to physical regions as well (except those that modify the image or header). See the region features description for more information.
Initialize physical configuration structures so that images located in physical memory may be manipulated (at TCL level) similar to virtual regions. This routine must be called by the user's main program in order to utilize the TCL commands available for physical regions.
A successful completion of this routine will result in configuration of the specified number of physical structures. These structures will be identified by a physical ID number in the range 0 to n-1, where n is the specfied number of regions. The physical ID will also be passed to the user supplied routines (described below) when invoked and will serve as a means for the user to identify the appropriate physical region. It is up to the user to make the associations between this ID and the region in physical memory.
A requisite for the user calling shPhysRegConfig is to provide five specific "access" routines, whose pointers are passed as parameters. This mechanism eliminates the circular dependency that would arise if Dervish instead depended on the user routines directly.
Two of the routines simply return (physical memory) pointers to the pixel image data and the image header, while two other routines "free" the image and header data. In most cases the "free" routines do not need to do any actual freeing, they are merely invoked for the user's benefit to indicate when dervish is done with a particular physical region (i.e., it's up to the user to decide whether or not to do anything).
The last routine that must be provided is one which will fill the physical memory with the appropriate image and header data.
This user written routine is required to return the pointer to the pixel image in physical memory if it is large enough to contain the number of bytes specified. It should return a NULL pointer otherwise.
This user written routine has no requirements. It is called only for the user's benefit, should he need to know when Dervish is finished with a pixel image in physical memory.
This user written routine is required to return the pointer to the image header in physical memory if it is large enough to contain the number of bytes specified. It should return a NULL pointer otherwise.
This user written routine has no requirements. It is called only for the user's benefit, should he need to know when Dervish is finished with an image header in physical memory.
This user written routine is required to fill the appropriate region in physical memory with the the specified frame. If errors are encountered, it should return a 0 and describe the error in the ASCII string parameter. For successful completion, a non-zero value should be returned. The 'a_fillErr' character array is allocated by the calling routine.