These routines support code which adds extensions to TCL. An extension is a new word in the TCL language. These routines aid in the translation of handles to addresses, etc. Most of these routines are of interest to a person who wants to get at regions. Some of the routines here are of more general interest, and will be factored to a new module in a future release of DERVISH.
It is assumed that the reader has some familiarity with coding TCL extensions.
This procedure translates an ASCII handle, such as may be passed to a TCL extension from the command line to a region address. If an error occurs Interp->result is set to an appropriate string and TCL_ERROR is returned. If successful, it returns TCL_OK, and fills out the address of the region where REGION points.
This procedure creates a new handle for a region. It does NOT make a new region structure. Rather, the user is to bind a region address to the handle with shTclRegNameSetWithAddr. If an error occurs Interp->result is set to an appropriate string and TCL_ERROR is returned. If successful, it returns TCL_OK, and fills out the address of the region where REGIONNAME points. It is the user's responsibility to ensure that the regName array is large enought to contain the name of the handle.
This procedure binds an address of a region to a handle. If another region was previously bound to the handle, it is unbound. If an error occurs Interp->result is set to an appropriate string and TCL_ERROR is returned. If successful, the routine returns TCL_OK.
This procedure deletes a handle pointing to a region If a region was previously bound to the handle, it is unbound. If an error occurs Interp->result is set to an appropriate string and TCL_ERROR is returned. If successful, the routine returns TCL_OK.
This procedure checks to see if the pixels in a region are of a type mentioned in TYPEMASK. This allows protection for users implementing TCL extensions handling regions of many types. This routine provides protection against the addition of future types as well, so should be used if the the region structure is directly accessed by user code. (See regUtils for manipulating pixels as doubles.) TypeMask is produced by ORING values of PIXDATATYPE together.
This procedure takes a string which names a type of pixel in a region structure, and writes the appropriate value of the enum PIXDATATYPE to the location given by TYPEOFPIX. TCL_ERROR is returned and the Interp->Result is set if the string does not correspond to a valid type name.
This procedure takes an enum of type PIXDATATYPE and fills out a string which gives a name for that type. This string can be translated back to type PIXDATATYPE using the routine shTclRegGetAsEnum. TCL_ERROR is returned and the Interp->Result is set if the string does not correspond to a valid type name.
This procedure takes an a string specifying a row or column in a region and writes its integer value into the address specified by VAL. TCL_ERROR is returned and the Interp->Result is set if the string does not correspond to a valid type name.
Programmers are cautioned that it is allowable that rows and columns be specified using a floating point number from the TCL level. This routine rounds these numbers properly into the proper integer row and column numbers.
This procedure takes an a string specifying a row or column in a region and writes its floating point value into the address specified by VAL. TCL_ERROR is returned and the Interp->Result is set if the string does not correspond to a valid type name.