Brain Imaging & Analysis Center

usage: ptr = pointer(varb [,bsize,xdim,ydim,zdim,ovalue,wdsiz])

The POINTER command assigns a descriptor of a data variable to a “pointer” variable. The pointer variable (PTR in the example above) must have been declared as a POINTER by the DECLARE command; for example as:

             declare pointer ptr

The data variable to which you want to assign a pointer (VARB in the example above) can be any data variable, or any subset of a data variable. Once you have assigned a variable to a pointer you can use the pointer anywhere you would have used the variable.

The arguments to the pointer function are:

        VARB            - any CIGAL variable or subset of a variable,
                            excluding NUMBER variables and CONSTANTS (i.e.,
                            explicit numbers or quoted character strings)
          
        BSIZE           - if BSIZE > 0, it is the buffer size (in bytes)
                            assigned to this pointer
                          if BSIZ < 0 and VARB is the screen variable @0,
                            then this flag lets you select a sub-region of
                            the screen interactively by clicking the cursor
                            on the upper and lower corners of a box
         
         XDIM,YDIM,ZDIM   - set the dimensions of the pointer's variable to
                            XDIM,YDIM,ZDIM.  This is used when assigning a
                            pointer to a nonstandard variable such as a
                            binary data file (see example below).
        
         OVALUE           - offset value: ignore this many bytes at beginning
                            of variable
         
         WDSIZ            - size of individual data words, as follows:
                              1 - bit                 16 - integer (16 bits)
                              2 - crumb (2 bits)      32 - long (32 bits)
                              4 - nibble (4 bits)     96 - real (32 bits)
                              8 - byte (8 bits)      136 - vector (64 bits)
                           (normally only used with file variables).

There are several advantages to using a pointer to a variable:

   1) The type and size of the variable are checked when the pointer is
      assigned, and therefore don't need to be checked again when the pointer
      is used, thus saving some execution time.

   2) You can define "windows" into subsets of your data variables, which can
      then be used as independent variables themselves without having to
      specify the offset values each time.  Offsets within a pointer variable
      are taken relative to the origin of the "window". (See examples below.)

   3) The transformation operations: ROTATE, PIN, SCALE, OFFSET, and TRANSFORM
      only work when using pointers to variables, because the transformation
      parameters are stored in the pointer, not in the variable.  Note: you
      can have any number of pointers to a single variable, all with different
      transformation settings.

   4) Some internal CIGAL variables are pointer variables, which you can set
      using the pointer command.  For example, the variable ZIMAGE is a
      pointer that can be set to point to an image, and is used for doing
      hidden surface removal when drawing 3-dimensional graphics.

   5) You can explicitly specify the size of the data buffer used for a
      pointer variable using the BSIZE argument, or the physical dimensions
      of the variable using the XDIM, YDIM, and ZDIM arguments.  This is
      probably most useful if you want to setup a pointer to a non-standard
      data file variable (see [FILE][3]).

   6) For data file variables, the OVALUE argument can be used to specify the
      number of bytes to ignore at the beginning of the file.  Again, this is
      particularly useful when reading non-standard binary data files.
      WARNING: Setting the OVALUE argument for a variable that is not a data
      file can produce disastrous results!

   7) Data file variables are opened by the POINTER command and remain open
      until the pointer is assigned to something else.  This can save a lot
      of time if a data file is used for more than a single operation.  NOTE:
      the data file cannot be accessed EXCEPT through the pointer variable as
      long as it remains open.

Examples:

1) If MAT is a 200 x 200 matrix, you could assign it as:
             ptr1 = pointer(mat)
    or assign a pointer to part of it as:
             ptr2 = pointer(mat(50:150,100:150))

2) You can use subscripts with the pointer to select a further subset of
   the "windowed" data.  For the two examples above, the expressions:
             ptr1(100:120,120:140) = 99
             ptr2(50:70,20:40) = 99
   give identical results since the origin of PTR2 is at PTR1(50,100).

3) Opening a non-standard data file, 'picture.dat' as:
             ptr = pointer(@'picture.dat'(0:511,0:511),768,768,640,1,200,8)
   would produce a 512 x 512 pixel window into an image ('@') that is
   itself stored as 768 x 640 bytes.  Data transfer will be via 768 byte
   records, and the first 200 bytes of the file will be ignored.

See Also:
DECLARE(2), FILE(3), FILES(1), OFFSET(2), PIN(2), PROJECTION(3), ROTATE(2), SCALE(2), SIMAGE(4), TIFF(1), TRANSFORM(3), VARIABLES(1), VIMAGE(4), YZIMAGE(4), ZIMAGE(4)

CIGAL Home, CIGAL Manual, Functions List, Manual Help