**CIGAL Reference Manual, Chapter 3 (Functions): pointer** ===== Pointer -- Create a pointer to a variable ===== **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:**\\ [[jvs:cigal:manual:chapter2:declare|DECLARE(2)]], [[jvs:cigal:manual:chapter3:file|FILE(3)]], [[jvs:cigal:manual:chapter1:files|FILES(1)]], [[jvs:cigal:manual:chapter2:offset|OFFSET(2)]], [[jvs:cigal:manual:chapter2:pin|PIN(2)]], [[jvs:cigal:manual:chapter3:projection|PROJECTION(3)]], [[jvs:cigal:manual:chapter2:rotate|ROTATE(2)]], [[jvs:cigal:manual:chapter2:scale|SCALE(2)]], [[jvs:cigal:manual:chapter4:simage|SIMAGE(4)]], [[jvs:cigal:manual:chapter1:tiff|TIFF(1)]], [[jvs:cigal:manual:chapter3:transform|TRANSFORM(3)]], [[jvs:cigal:manual:chapter1:variables|VARIABLES(1)]], [[jvs:cigal:manual:chapter4:vimage|VIMAGE(4)]], [[jvs:cigal:manual:chapter4:yzimage|YZIMAGE(4)]], [[jvs:cigal:manual:chapter4:zimage|ZIMAGE(4)]] [[jvs:cigal|CIGAL Home]], [[jvs:cigal:manual|CIGAL Manual]], [[jvs:cigal:manual:chapter3|Functions List]], [[jvs:cigal:manual:help|Manual Help]]