Support for TCL Region Extensions

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.

  • shTclRegAddrGetFromName -- Get the address of a region implied by a region handle string
  • shTclRegNameGet -- Get a new name string for a handle to region
  • shTclRegNameSetWithAddr -- (Re)bind a region address to a name string
  • shTclRegNameDel -- Unbind a region address to a name string and release the name
  • shTclRegTypeCheck -- Check to see if a region has pixels of the specified types
  • shTclRegTypeGetAsEnum -- Given a string specifying a pixel type, return the corresponding enum
  • shTclRegTypeGetAsAscii -- Given an enum specifying a pixel type, return the corresponding string
  • shTclRowColStrGetAsFloat -- Given a number denoting a row of column number, produce a float
  • shTclRowColStrGetAsInt -- Given a number denoting a row of column number, produce an int
  • 
    
    
    

    shTclRegAddrGetFromName

    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.

    C SYNTAX: int shTclRegAddrGetFromName ( Tcl_Interp *interp, /* IN: Interpreter to set the result for */ charconst *regName, /* IN: ASCII Handle to region*/ REGION **region /* OUT: Address if region written here*/ ) RETURNS: TCL_OK TCL_ERROR
    
    
    
    
    
    
    

    shTclRegNameGet

    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.

    C SYNTAX: int shTclRegNameGet ( Tcl_Interp *interp, /* IN: Interpreter to set the result for */ char *regName, /* OUT: Pointer to string to be filled out with the name of the handle */ ) RETURNS: TCL_OK TCL_ERROR
    
    
    
    
    

    shTclRegNameSetWithAddr

    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.

    C SYNTAX: int shTclRegNameSetWithAddr ( Tcl_Interp *interp, /* IN: Interpreter to set the result for */ REGION *region /* IN: Address of region to be bound to */ /* the handle */ char *regName, /* IN: Pointer to string holding the ASCII */ /* name of the handle */ ) RETURNS: TCL_OK TCL_ERROR
    
    
    
    

    shTclRegNameDel

    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.

    C SYNTAX: int shTclRegNameSetWithAddr ( Tcl_Interp *interp, /* IN: Interpreter to set the result for */ char *regName, /* IN: Pointer to string holding the ASCII handle*/ ) RETURNS: TCL_OK TCL_ERROR
    
    
    
    

    shTclRegTypeCheck

    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.

    C SYNTAX: int shTclRegTypeCheck ( Tcl_Interp *interp, /* IN: Interpreter to set the result for */ REGION *region, /* IN: region Structure to test*/ int *typeMask /* IN: Or of allowable types*/ ) RETURNS: TCL_OK TCL_ERROR
    
    
    
    
    

    shTclRegTypeGetAsEnum

    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.

    C SYNTAX: int shTclRegTypeGetAsEnum ( Tcl_Interp *interp, /* IN: Interpreter to set the result for */ char const *typeName, /* IN: ASCII Name of type*/ int *typeOfPix /* IN: Or of allowable types*/ ) RETURNS: TCL_OK TCL_ERROR
    
    
    
    
    
    

    shTclRegTypeGetAsAscii

    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.

    C SYNTAX: int shTclRegTypeGetAsAscii ( Tcl_Interp *interp, /* IN: Interpreter to set the result for */ char const *typeName, /* IN: ASCII Name of type*/ int *typeOfPix /* IN: Or of allowable types*/ ) RETURNS: TCL_OK TCL_ERROR
    
    
    
    
    
    

    shTclRowColStrGetAsInt

    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.

    C SYNTAX: int shTclRowColStrGetAsInt ( Tcl_Interp *interp, /* IN: Interpreter to set the result for */ char const *RowOrCol, /* IN: String specifying row or column */ int *val /* IN: Address to write converted value */ ) RETURNS: TCL_OK TCL_ERROR
    
    
    
    
    
    

    shTclRowColStrGetAsFloat

    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.

    C SYNTAX: int shTclRowColStrGetAsFloat ( Tcl_Interp *interp, /* IN: Interpreter to set the result for */ char const *RowOrCol, /* IN: string specifying row or column*/ float *val /* IN: Adress to write converted value*/ ) RETURNS: TCL_OK TCL_ERROR