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], VARIABLES[1], FILES[1], TIFF[1], ROTATE[2],
SCALE[2], OFFSET[2], PIN[2], TRANSFORM[3], PROJECTION[3], VIMAGE[4],
ZIMAGE[4], YZIMAGE[4], SIMAGE[4].