Math Routines

The following routines are routines for handling arithmetic data, geometry, and modeling matrices.

absi

FUNCTION absi (i : integer) : integer;

absi returns the absolute value of an integer expression.

absr

FUNCTION absr (rl : real) : real;

absr returns the absolute value of a real expression.

acos

FUNCTION acos (rl : real) : real;

acos returns the inverse cosine of its argument rl (the angle whose cosine is rl).

asin

FUNCTION asin (rl : real) : real;

asin returns the angle whose sine is the

argument rl (the inverse sin of rl).

atan

FUNCTION atan (rl : real) : real;

atan returns the angle whose tangent is the

argument rl. Note that this angle is always in the first or fourth quadrant. A more useful function is atan2.

atan2

FUNCTION atan2 (dx, dy : real) : real;

atan2 returns the angle given by the delta

values dx and dy. This is similar to atan (dy / dx), but the angle is in the correct quadrant and you don't need a special test for dx = 0.

chr

FUNCTION chr (i : integer) : char;

chr is a type conversion procedure. It takes an integer and returns the corresponding character value. The high eight bits of the integer are ignored.

cos

FUNCTION cos (angle : real) : real;

cos returns the cosine of the angle that is its argument.

exp

FUNCTION exp (x : real) : real;

exp returns e raised to the x power (the inverse of natural logarithm).

expt

FUNCTION expt (a, x : real) : real;

expt returns a raised to the x power.

x can be fractional but not negative.

float

FUNCTION float (i : integer) : real;

float is a type conversion function. It returns a real value that is the same as its integer argument.

For example, float (-4) returns -4.0.

This function is needed because DCAL does not provide automatic type conversions.

intand

FUNCTION intand (int1, int2 : integer) : integer;

intand returns the bitwise AND of its two arguments.

For instance, intand (326, 211) returns 66.

intor

FUNCTION intor (int1, int2 : integer) : integer;

intor returns the bitwise OR of its two

arguments.

For example, intor (326, 211) returns 471.

intxor

FUNCTION intxor (int1, int2 : integer) : integer;

intxor returns the bitwise exclusive OR of its

two arguments.

For example, intxor (326, 211) returns 405.

log

FUNCTION log (x : real) : real;

log returns the natural logarithm (base e) of

its argument.

max

FUNCTION max (a, b : real) : real;

max returns the maximum of its two arguments.

min

FUNCTION min (a, b : real) : real;

min returns the minimum of its two arguments.

odd

FUNCTION odd (i : IN integer) : boolean;

odd returns true when the integer i is odd.

* When the integer i is even, odd returns false.

ord

FUNCTION ord (ch : char) : integer;

ord is a type conversion function. It takes a

character and returns the integer ASCII value.

order

PROCEDURE order (a, b : real; min, max : OUT real);

order returns in min the minimum of a and b, and returns in max the maximum of a and b.

round

FUNCTION round (rl : real) : integer;

round takes a real and returns the nearest integer to it.

round4

FUNCTION round4 (rl : IN real) : longint;

round4 takes a real number and rounds it to the nearest long integer.

sin

FUNCTION sin (ang : real) : real;

sin returns the sine of the angle that is passed to it.

sqr

FUNCTION sqr (rl : real) : real;

sqr returns the square of its argument. This routine is slightly faster than multiplying something by itself (especially when the argument is an expression).

sqrt

FUNCTION sqrt (rl : real) : real;

sqrt returns the square root of its argument.

A run-time error occurs when the argument is negative.

tan

FUNCTION tan (ang : IN real) : real;

The function tan returns the tangent of the angle ang.

* When ang is a multiple of +pi/2 or -pi/2, tan returns a value, but the value is undefined.

trunc

FUNCTION trunc (rl : real) : integer;

trunc is similar to round, except the returned value is truncated toward zero.

For example, trunc (3.8) returns 3.

trunc4

FUNCTION trunc4 (rl : IN real) : longint;

trunc4 takes a real number and truncates it to the nearest long integer.

Geometric Routines

The routines in this section let you manipulate geometric data, such as the geometry of lines and arcs. This refers to geometric concepts, not necessarily to DataCAD entities.

addpnt

PROCEDURE addpnt (pt1, pt2 : point; respnt : OUT point);

addpnt (pt1, pt2, respnt) is equivalent to:

respnt.x := pt1.x + pt2.x;

respnt.y := pt1.y + pt2.y;

respnt.z := pt1.z + pt2.z;

angle

FUNCTION angle (pt1, pt2 : point) : real;

angle returns the angle (in radians) between two lines. The first line is defined by the two IN parameter points. The second line goes through pt1 and is parallel to the x axis. The angle is measured from zero degrees in a counterclockwise direction. The return value is equivalent to that given by atan2 (pt2.x - pt1.x, pt2.y - pt1.y).

Although angle ignores the z coordinate, the z coordinate should be initialized to some valid value.

For example, when:

pt1.x := 0.0;

pt1.y := 0.0;

pt2.x := 2.6;

pt2.y := 5.7;

x := angle (pt1, pt2);

x is equal to 1.142848 radians, or about 65.5

degrees.

between

FUNCTION between (pt1, pt2, testpt : point) : integer;

between determines when a point testpt is on, between, or beyond the line segment defined by pt1 and pt2.

between has the following return values:

-2 beyond pt2 -1beyond pt1

0 between pt1 and pt2

1 on pt1

2 on pt2

The following conclusions can be drawn based on the return value:

< 0 The point is beyond either end point.

<> 0 The point is on or beyond either end point.

= 0 The point is between both end points.

>= 0 The point is between or on both end points.

> 0 The point is on either end point.

<= 0 The point is not on an end point.

betweenang

FUNCTION betweenang (tstang, ang1, ang2 : real);

betweenang returns true when tstang is between ang1 and ang2, otherwise, false returns. Between is defined in a counterclockwise direction.

For example:

betweenang (0.0, -pi, pi) returns true betweenang (0.0, 1.0, pi) returns false

cart_cylind

PROCEDURE cart_cylind (x, y, z : real; rad, planang, zdis : OUT real);

cart_cylind converts from cartesian to cylindrical coordinates.

For example, the point (x, y, z) converts to

(rad, planang, zdis).

cart_sphere

PROCEDURE cart_sphere (x, y, z : real; rad, planang, riseang : OUT real).

cart_sphere converts from cartesian to spherical coordinates.

For example, the point (x, y, z) converts to

(rad, planang, riseang).

circ3pt

FUNCTION circ3pt (pt1, pt2, pt3 : point; cent : OUT point; rad : OUT real) : boolean;

circ3pt calculates the circle that goes through any three points, pt1, pt2, and pt3.

* The center of the circle is returned in cent.

* The radius of the circle is returned in rad.

* When the three points do not define a circle (they are colinear), circ3pt returns false, otherwise true returns.

clip

FUNCTION clip (pt1, pt2 : IN OUT point; min, max : point; doz boolean) : boolean;

clip is used to clip a line segment to a box. clip works either in three dimensions (x, y, and z) or in two dimensions (x and y) based on the parameter doz.

* When doz is true, clip works in three dimensions, otherwise it works in two.

* min and max are the bounding corners of the box.

* pt1 and pt2 are the two points defining the ends of the line segment. When clip returns false, the line segment defined by pt1 and pt2 is not in the bounding box. When true returns, pt1 and pt2 change to the portion of the line segment inside the box.

crossprod

PROCEDURE crossprod (pt1, pt2, pt3 : point; result : IN OUT point);

crossprod calculates the vector cross product of two input vectors.

The notation used is somewhat non-standard and is defined to make classifying polygons simple.

* The first vector is defined as going from pt1 to pt2. The second vector goes from pt2 to pt3. The resulting vector is returned as result. Think of result as a 3D vector, with the x, y, and z values representing the x, y, and z components of the vector.

crossz

FUNCTION crossz (pt1, pt2, pt3 : point) : real;

crossz is similar to crossprod, except it returns the z value of the resulting cross product. crossz is useful to determine which side of a two-dimensional line an arbitrary point lies on

The first vector is defined as going from pt1 to pt2. The second vector goes from pt2 to pt3. When a line goes from pt1 to pt2, crossz returns a positive number if pt3 lies to the left of the line and a negative number if pt3 lies to the right of the line. If pt3 lies on the line, zero is returned.

cylind_cart

PROCEDURE cylind_cart (rad, planang, zdis : real; x, y, z : OUT real);

cylind_cart converts from cylindrical to cartesian coordinates.

For example, (rad, planang, zdis) is converted to (x, y, z).

degrees

FUNCTION degrees (angle : real) : real;

degrees converts its argument (which is given in radians) to degrees. All DCAL functions (except radians, see below) expect their arguments in radians.

dis_from_arc

FUNCTION dis_from_arc (center : IN point; radius, begang, endang : IN real; testpnt : IN point) : real;

dis_from_arc returns the square of the shortest distance from an arc specified by its center, radius, beginning angle, and ending angle to a point.

* center is the center point of the arc.

* radius is the radius of the arc.

* begang and endang are the beginning and ending angles of the arc respectively.

* testpnt is the point from which to calculate the distance to the arc.

* dis_from_arc returns the square of the distance between the point and the arc.

dis_from_line

FUNCTION dis_from_line (pt1, pt2, tstpt : point) : real;

dis_from_line returns the square of the shortest distance from the point tstpt to the infinite line defined by pt1 and pt2.

dis_from_seg

FUNCTION dis_from_seg (pt1, pt2, tstpt : point) : real;

dis_from_seg returns the square of the shortest distance from the point tstpt to the line segment defined by pt1 and pt2.

distance

FUNCTION distance (pt1, pt2 : point) : real;

distance returns the distance between the two points, pt1 and pt2.

Although distance ignores the z coordinates, the z coordinate should be initialized to a valid value.

For example, when:

pt1.x := 0.0;

pt1.y := 0.0;

pt2.x := 2.6;

pt2.y := 5.7;

x := distance (pt1, pt2);

x is equal to 6.265.

dotprod

FUNCTION dotprod (pt1, pt2, pt3 : point) : real;

dotprod computes the scalar dot product of two vectors.

See "crossprod" for the definition of the parameters pt1, pt2, and pt3.

gridcalc

PROCEDURE gridcalc (origin : IN point; ang : IN real; gridIn, gridout : OUT modmat);

gridcalc calculates two modeling matrices which are the transformations required for snapping a point to a grid which is defined by an origin and an angle of rotation. The procedure gridcalc is typically called once prior to using gridsnapto procedure for snapping a point to a grid. By using modeling matrices for the definition of the grid orientation, gridsnapto is efficient in its calculations, particularly when used inside repetitive loops.

Procedures gridcalc and gridsnapto are coordinate system independent when used together and may be used in any real number, cartesian coordinate system. ang is the angle of rotation of the grid coordinate system about its specified origin.

* origin is the origin of the grid in the grid coordinate system. The grid need not be defined in the global world coordinate system.

* gridIn is the modeling transformation from the base coordinate system to the translated and rotated grid coordinate system.

* gridout is the modeling transformation from the translated and rotated grid coordinate system to the base coordinate system.

gridsnapto

PROCEDURE gridsnapto (pnt : IN OUT point; gridsize : IN point; gridin, gridout : IN modmat);

gridsnapto snaps a point to a grid whose origin and angle of rotation are specified by two modeling matrices, and whose grid size is specified by an x and a y offset.

* pnt is the point that is snapped to the grid.

* gridsize is a point whose x and y-coordinates describe the size of the grid in the translated and rotated coordinate system described by the modeling matrices gridin and gridout.

* gridin and gridout are modeling matrices which are ordinarily computed using the procedure gridcalc. See "gridcalc" for a discussion of the definition of these two matrices.

intr_arcarc

FUNCTION intr_arcarc (cent1, cent2 : point; rad1, rad2, bang1, eang1, bang2, eang2 : real; int1, int2 : OUT point) : integer;

intr_arcarc computes the intersections of two arcs.

* The first arc is centered at cent1, its radius is rad1, and its beginning and ending angles are bang1 and eang1. The second arc is similarly defined.

intr_crcarc

FUNCTION intr_crcarc (cent1, cent2 : point; rad1, rad2, bang, eang : real; int1, int2 : OUT point) : integer;

intr_crcarc is similar to intr_crccrc except that cent2 is the center of an arc whose beginning and ending angles are bang and eang, respectively.

intr_crccrc

FUNCTION intr_crccrc (cent1, cent2 : point; rad1, rad2 : real; int1, int2 : OUT point) : integer;

intr_crccrc computes the intersections (if any) between two circles.

* int1, int2, and the return value have the same meaning as they do in intr_linarc.

* The first circle has its center at cent1 and its radius is rad1.

* The second circle has its center at cent2 and its radius is rad2.

intr_linarc

FUNCTION intr_linarc (center : point; radius, bang, eang : real; pt1, pt2 : point; int1, int2 : OUT point; segment : boolean) : integer;

intr_linarc computes the intersection of either a line or a line segment with an arc.

When intr_linarc returns 0, the line (or line segment) does not intersect the arc. When the return value is 1, int1 contains the only intersection. When the return value is 2, int1 and int2 contain both of the intersections.

* center is the center of the arc, radius is its radius, and bang and eang are its beginning and ending angles.

* When segment is true, pt1 and pt2 are considered the end points of a line segment, otherwise they are points defining an infinite line.

* intr_linarc returns the number of intersections found.

intr_lincrc

FUNCTION intr_lincrc (center : point; radius : real; pt1, pt2 : point; int1, int2 : OUT point; segment : boolean) : integer;

intr_lincrc is similar to intr_linarc, but computes the intersection of a line (or line segment) and a circle.

* center is the center of the arc and radius is its radius.

* When segment is true, pt1 and pt2 are considered the end points of a line segment, otherwise they are points defining an infinite line.

* The circle being tested for intersection has its center at center and its radius is radius.

intr_linlin

FUNCTION intr_linlin (pt1, pt2, pt3, pt4 : point; intr : OUT point; segments : boolean) : boolean;

intr_linlin computes the intersection point of two lines or two line segments.

* The two lines (or segments) are defined from pt1 to pt2 and from pt3 to pt4.

* When the parameter segments is true, the intersection must be on or between the end points. When segments is false, the intersection can be anywhere on the two lines. If the lines do intersect and the intersection is between the two end points if segments is true, then the function returns true, otherwise false returns.

* When true is returned, intr is the intersection point.

linelen3

FUNCTION linelen3 (pt1, pt2 : point) : real;

linelen3 returns the square of the distance from pt1 to pt2. Note that this is the three- dimensional distance in space, not the two dimensional distance returned by distance.

mulpnt

PROCEDURE mulpnt (pt : point; scale : real; respnt : OUT point);

mulpnt (pt, scale, respnt) is equivalent to:

respnt.x := pt.x * scale;

respnt.y := pt.y * scale;

respnt.z := pt.z * scale;

pnt_in_poly

FUNCTION pnt_in_poly (testpnt : IN point; pnt : IN pntarr; npnt : IN integer; min, max : IN point) : integer;

pnt_in_poly determines if a point lies within, on, or outside of the boundaries of a polygon. The polygon is described as an array of up to 36 points. The polygon may be arbitrarily concave or convex, but may not be degenerate.

Only the x and y-coordinates of the test point

and the polygon vertices are considered, but the z-coordinates of the test point and the polygon vertices must be initialized to valid real numbers. pnt_in_poly returns the value 1 when testpnt lies within the boundary of the polygon, 0 when testpnt lies on the boundary of polygon, and -1 when testpnt lies outside the boundaries of the polygon.

* testpnt is the point to test.

* pnt is the array of vertices of the polygon, up to a maximum of 36.

* npnt is an integer indicating the number of vertices in the polygon. npnt must be at least 3, but no more than 36.

* min and max contain the extents of the polygon. min and max are used for trivial rejection to increase performance when pnt_in_poly is used in a repetitive manner.

polar

PROCEDURE polar (pt1 : point; ang, dist : real; pt2 : OUT point);

polar takes a point pt1 and returns in pt2 the

point that is at a distance dist and angle ang from that point.

poly_fix

PROCEDURE poly_fix (pnt : IN OUT pntarr; npnts : IN integer; min, max : IN OUT point);

poly_fix performs three operations upon a

polygon to normalize the polygon for use in some algorithms. poly_fix tests to insure that the points of the polygon are specified in a counterclockwise order. When they are not, the order of points is reversed. Secondly, poly_fix insures that pnt [1] of the polygon is the point which has the minimum x-coordinate among the points which have the minimum y-coordinate. This normalization allows some algorithms which test for inclusion in a polygon to be used when they would not otherwise operate properly. Third, poly_fix computes the extents of the polygon.

* pnt is the array of points which are the vertices of the polygon, up to a maximum of 36.

* npnts is an integer indicating the number of vertices in the polygon. npnts should be a number between 3 and 36 inclusive.

* min is the minimum extents of the polygon and max is the maximum extents of the polygon.

project

PROCEDURE project (pt1, pt2 : point; tstpt : IN OUT point);

project projects tstpt onto the line formed by

pt1 and pt2.

On entry, tstpt is any point. On exit, tstpt is

on the line (not line segment) formed by pt1 and pt2 perpendicular to the original value of tstpt.

radians

FUNCTION radians (ang : real) : real;

radians takes an angle ang in degrees and converts it to radians.

radians (180.0) returns a number that is equal

to pi.

setpoint

PROCEDURE setpoint (pt : OUT point; rl : real);

setpoint sets the three coordinates of pt to be equal to rl. This is identical to:

pt.x := rl;

pt.y := rl;

pt.z := rl;

but executes faster, generating less code.

sphere_cart

PROCEDURE sphere_cart (rad, planang, riseang : real; x, y, z : OUT real);

sphere_cart converts the point (rad, planang, riseang) from spherical coordinates to its cartesian equivalent (x, y, z).

subpnt

PROCEDURE subpnt (pt1, pt2 : point; respnt : OUT point);

subpnt (pt1, pt2, respnt) is equivalent to:

respnt.x := pt1.x - pt2.x;

respnt.y := pt1.y - pt2.y;

respnt.z := pt1.z - pt2.z;

Modeling Matrix Routines

The routines in this section manipulate modeling matrices. A modeling matrix is a four- by-four matrix of real numbers. With it, any series of arbitrary three-dimensional scalings, rotations, and translations can be applied to any entity that has a modeling matrix in its definition, such as a symbol or a dome. In addition, using the procedure xformpt, you can apply these same transformations to any point. These scalings, rotations, and enlargements can be applied one after the other, or concatenated.

For examples of the usage of modeling matrices,

see the "Sample Macros" chapter.

catenlrel

PROCEDURE catenlrel (mat : IN OUT modmat; xsc, ysc, zsc : real; pt : point);

catenlrel is very similar to setenlrel, but

concatenates the relative enlargement instead of setting it.

catmat

PROCEDURE catmat (mat1 : IN OUT modmat; mat2 : modmat);

catmat concatenates two modeling matrices, mat1

and mat2.

catrotate

PROCEDURE catrotate (mat : IN OUT modmat; ang : real; axis : integer);

catrotate adds a rotation of ang around axis to

the current transformation of mat.

See the description of setrotate for the usage

of ang and axis.

catrotrel

PROCEDURE catrotrel (mat : IN OUT modmat; ang : real; axis : integer; pt : point);

catrotrel is similar to setrotrel, but the

rotation is concatenated onto the existing transformation of mat.

catscale

PROCEDURE catscale (mat : IN OUT modmat; xsc, ysc, zsc : real);

catscale concatenates a scaling onto the

current transformation assigned to mat.

See "setscale".

cattran

PROCEDURE cattran (mat : IN OUT modmat; dx, dy, dz : real);

cattran concatenates, or adds, a translation of

(dx, dy, dz) to the current transformation assigned to mat.

invert

FUNCTION invert (matin : modmat; matout : OUT modmat; det : OUT real) : boolean;

invert calculates the inverse transformation for matin, if one exist

* false returns when no inverse exists, otherwise true returns. When the inverse does exist, the determinate of the matrix returns in det and the inverse matrix returns in matout.

matmmat

PROCEDURE matmmat (mat1, mat2 : modmat; result : OUT modmat;

matmmat multiplies two modeling matrices, mat1

and mat2, and places the result in result. Multiplying two matrices concatenates the transformations of mat2 onto mat1.

setenlrel

PROCEDURE setenlrel (mat : IN OUT modmat; xsc, ysc, zsc : real; pt : point);

setenlrel sets mat to produce an enlargement

relative to pt. This procedure is similar to setscale but the enlargement is not relative to the origin.

setident

PROCEDURE setident (mat : OUT modmat);

setident sets mat to have the identity

transformation, that is, no affect at all. A point transformed by the identity matrix yields the original point.

setrotate

PROCEDURE setrotate (mat : OUT modmat; ang : real; axis : integer);

setrotate sets mat to have a rotation of ang

about the axis axis.

The axis should be one of the built-in

constants x, y, or z. Notice that the center of this rotation is around the origin.

setrotrel

PROCEDURE setrotrel (mat : IN OUT modmat; ang : real; axis : integer; pt : point);

setrotrel is similar to setrotate but the

rotation is relative to the point pt.

setscale

PROCEDURE setscale (mat : OUT modmat; xsc, ysc, zsc : real);

setscale sets mat to apply a scaling of xsc,

ysc, and zsc along the x, y, and z axes, respectively. The scaling is relative to the origin.

settran

PROCEDURE settran (mat : OUT modmat; dx, dy, dz : real);

settran sets mat to have a translation of (dx,

dy, dz). This is used to move a point or entity.

transpose

PROCEDURE transpose (mat : IN OUT modmat);

transpose swaps the rows and columns of the

matrix mat. Row one becomes column one, row two becomes column two, etc.

xformpt

PROCEDURE xformpt (ptin : point; mat : modmat; ptout : OUT point);

xformpt transforms the point ptin according to

the transformations that have been assigned to mat, and places the result in ptout. This is most often used to set up a transformation and then transform a series of points to determine their new values.

Viewing Routines

The declarations for the routines in this section are not built into the DCAL compiler, but require the inclusion of the file _views.inc.

Use the routines in this section to manage and

manipulate saved and displayed views in DataCAD. The basic unit of information used by DataCAD's viewing system is the view. A view, represented in DCAL as a variable of type view_type, represents two kinds of information:

* A view can represent the information necessary to completely specify or calculate a viewing projection. In this case, a view is any one particular orientation of a drawing or model relative to the screen in a particular projection. For example, with a perspective projection, a view contains the location of the viewer, the direction in which the viewer is looking, clipping information, and window to viewport mapping information, as well as a variety of supporting information.

* A view can represent the basic unit of information for the storage and retrieval of viewing parameters in a drawing database. In this case, a variable of type view_type is the data object used for maintaining a linked data structure consisting of sets of viewing parameters. DataCAD supports four types of projections: orthographic, parallel, perspective, and oblique.

Refer to the DataCAD Reference Manual for a

discussion of the differences between views and projections, as well as the differences between each of the four types of projections. The DataCAD Reference Manual also includes instructions on how to define and create different views in each of the projection types. Many of the DCAL view calculation routines are used by DataCAD's viewing system, therefore the explanations in the DataCAD Reference Manual also apply to these routines.

Viewing Database Management

Routines

The following routines manage views in the drawing database.

view_add

PROCEDURE view_add (view : IN OUT view_type);

view_add adds a view to the list of saved views

in a drawing database.

* The variable view must be initialized using view_init, or previously read from the database using view_get. view must contain a valid set of viewing parameters. The view is added to the chain of saved views at the end of the list. Adding a view to the list of saved views does not make a view the current view, nor does it set the current viewing parameters to those of the view variable, nor does it refresh the screen. view_add is strictly a database function which adds the contents of the view variable to the list of saved views. view_add automatically stores a list of those layers which are on at the time with the view. In this way, a view is sensitive to the *LayrSet toggle in the DataCAD 3D GotoView menu.

view_del

PROCEDURE view_del (view : IN OUT view_type);

view_del deletes a view from the list of saved

views in a drawing database.

The view must be previously extracted from the

database by a call to view_get. Do not attempt to delete a view which has not been previously read from the database using view_get.

view_first

FUNCTION view_first : viewaddr;

view_first returns the address of the first view in the list of saved views in a drawing database.

When the list of saved views is empty, view_first returns the value nil. view_first is used with view_get so you can linearly scan the list of saved views in a drawing database.

See "view_get".

view_get

FUNCTION view_get (view : IN OUT view_type; addr : IN viewaddr) : boolean;

view_get reads a view from the drawing database located at address addr.

l When addr is nil the list is either empty or the end of the list has been reached and view_get returns false. In this case, the view returned is undefined.

* When view_get is successful, true is returned and the variable view contains the view located at address addr. view_get is most often used with view_first to linearly scan the list of saved views.

For example, to scan the list of saved views

and test for those which are orthographic projections, use the following code:

VAR

view: view_type

addr: viewaddr

...

addr := view_first

WHILE view_get (view, addr) DO

addr := view.next

IF view.projtype = vmode_orth THEN

{ Process orthographic projections here.}

END;

END;

view_init

PROCEDURE view_init (view : IN OUT view_type);

view_init initializes the fields of a variable of type view_type.

Call view_init before using a view_type variable, particularly when adding or deleting views from the database.

view_last

FUNCTION view_last : viewaddr;

view_last returns the address of the last view in the list of saved views in a drawing database.

When the list of saved views is empty,

view_last returns a value of nil. Use view_last to scan the list of views in reverse order or to test against the address of the last view.

view_update

PROCEDURE view_update (view : IN OUT view_type);

view_update updates a view in the list of saved

views in a drawing database.

The view must be previously extracted from the

database with a call to view_get. The view must also contain a valid set of viewing parameters. view_update is strictly a database function. To make the view the current view, use view_setcurr. view_update does not alter the current viewing parameters, nor will it refresh the screen.

Viewer Control and Interrogation

Routines

The routines described in this section control the current viewing projection in various ways, or interrogate the current viewing parameters. The routines are most-frequently used during three-dimensional editing operations or during the specification of views.

inmat_curr

PROCEDURE inmat_curr (inmag : OUT modmat);

inmat_curr returns the value of the current input matrix. This matrix is applicable only in parallel projections, and contains the inverse of the complete viewing transformation.

inmat_curr is typically used with the function getpointp when entering or editing data in parallel projections as is done in the DC- Modeler. The matrix returned by inmat_curr represents the transformation required to change from world coordinates to the screen coordinate system used by getpointp.

scale_curr

FUNCTION scale_curr : integer;

scale_curr returns the number of the current two-dimensional window-to-viewport display scale.

The value that returns is an integer in the range of 1 to 18.

To determine the window-to-viewport scale

factor corresponding to this integer number, use the following code:

VAR

scale : real;

name: string (8);

...

scale_get (scale_curr, scale, name);

scale_get

PROCEDURE scale_get (num : IN integer; scale : OUT real; name : OUT string);

scale_get returns the display scale and name for a given scale number.

* scale is the ratio of the world coordinate system to the display coordinate system. DataCAD maintains up to 18 discrete drawing display scale factors. The user can edit these scale factors via the Settings/EditDefs/ Scales function. The DataCAD support file dcad.scl may also be edited directly so that any new drawing reflects these new scales. Therefore, the 18 numbered scales are not necessarily unique for any particular drawing nor from drawing to drawing.

* name is a string, up to eight characters in length, which is the name of the scale used in DataCAD's ToScale menu.

view_checkmode

PROCEDURE view_checkmode (projtype : IN integer);

view_checkmode checks the current viewing

projection to determine if it is the same as projtype.

view_checkmode takes an integer parameter which

must be equal to one of the constants vmode_orth, vmode_para, vmode_pers, vmode_oblq, or vmode_edit. The first four constants check for the projection which they represent as described above. vmode_edit indicates to view_checkmode that either an orthographic or a parallel projection is acceptable.

With vmode_edit, when the current projection is

either orthographic or parallel no action is taken. vmode_edit is typically used for three- dimensional editing operations similar to the 3D Move function or the entering of slabs and polygons. These functions are valid in either an orthographic or parallel projection, but not in a perspective or oblique projection.

* When the current viewing projection is equal to projtype, no action is taken. When the current viewing projection is not equal to projtype, the most recent view of that projection type is made current and the screen is refreshed.

view_currmode

FUNCTION view_currmode : integer;

view_currmode returns an integer value indicating the current viewing projection type.

view_currmode is typically used for determining

the current viewing projection without having to call view_getcurr and examine the individual fields of a view_type variable. For this purpose, view_currmode is faster and easier to use.

l The return value is equal to one of the

constants vmode_orth, vmode_para, vmode_pers, or vmode_oblq. These values represent orthographic, parallel, perspective, or oblique projections.

The following example prints a message

indicating the current viewing projection:

VAR

vmode : integer;

...

vmode := view_currmode;

IF vmode = vmode_orth THEN

wrterr (Orthographic.);

ELSIF vmode = vmode_para THEN

wrterr (Parallel.);

ELSIF vmode = vmode_pers THEN

wrterr (Perspective.);

ELSIF vmode = vmode_oblq THEN

wrterr (Oblique.);

END;

view_getcurr

PROCEDURE view_getcurr (view : IN OUT view_type);

view_getcurr sets the view_type variable view to the current viewing parameters. view_getcurr does not read from or affect the list of saved views.

view_getcurr does not alter or initialize any of the following fields in a view_type variable: addr, next, prev, name, currlyr, frstlyr, lastlyr, or togglelyr.

Use the following code to load the current

viewing parameters into a view variable, and then add this view to the list of saved views in a drawing database:

VAR

view : view_type;

...

view_init (view);

view_getcurr (view);

view_add (view)

To read, update, add to, or delete from the list of saved views, refer to "Viewing Database Management Routines" in this chapter.

view_setcurr

PROCEDURE view_setcurr (view : IN OUT view_type; redraw : IN boolean);

view_setcurr sets the current view to reflect

the parameters and projection contained in the variable view.

The view need not be read out of the database,

but must contain a valid set of viewing parameters. When the view is not read from the database, it should be initialized using view_init prior to modifying the fields of the view.

* When redraw is true, the screen is refreshed after setting the current viewing parameters. When redraw is false, the current viewing parameters are altered, but the screen is not refreshed. In this case, if the user presses (Esc), or any subsequent operation is performed which implicitly forces a refresh of the screen, the screen is refreshed using the new viewing parameters. Typically, the view variable is initialized using view_init, then one of the view calculation routines is called, followed by a call to view_setcurr with refresh set to true. During a call to view_setcurr, some of the fields of the view may be changed depending upon the projection specified and the status of certain system variables. This is because some of the view parameters may be derived from these system parameters depending upon the type of projection. In any case, the fields addr, next, prev, name, lyrcurr, lyrfrst, lyrlast, flag1 and flag2 are not altered by view_setcurr.

view_setmode

PROCEDURE view_setmode (projtype : IN integer; refresh : IN boolean);

view_setmode explicitly sets the current

viewing projection to the type passed by projtype.

* When the parameter refresh is true, the screen is refreshed (even if the current viewing projection is the same as projtype). When refresh is false, the screen is not refreshed, but the current viewing projection is still updated. In this case, if the user presses (Esc), or performs any other operation which automatically forces a refresh, the viewing projection contained in projtype is used. view_setmode explicitly changes among the four current viewing projections. Unlike view_checkmode, view_setmode takes an action even when the current viewing projection is equal to projtype.

Viewing Calculation Routines

The routines described in this section calculate a view of a specific projection based upon a given set of input parameters. These routines operate only upon the view_type variable passed to them. These routines do not affect the current viewing parameters (use view_setcurr) nor do these routines affect any view which was saved in the drawing database (use view_add or view_update).

view_calcoblq

PROCEDURE view_calcoblq (view : IN OUT view_type; center : IN point; planang, shearang, shearfact : IN real; oblqtype, scalenum : IN integer);

view_calcoblq calculates an oblique viewing

projection. Calculate oblique viewing projections using one of two conventions: plan oblique or elevation oblique.

* When the calculation is made using the plan oblique convention, oblqtype is set to the constant oblqplan. When the calculation is made using the elevation oblique convention, oblqtype is set to the constant oblqelev.

* For plan oblique calculations, the parameters to view_calcoblq have the following meanings:

center becomes the center point of the display and is the point relative to which the viewing shear is calculated.

shearang is ignored.

planang is the angle by which the drawing is rotated about the z-axis before applying the oblique shear.

shearfact is the factor by which lines parallel to the z-axis are enlarged (nominal value is 1.0).

scalenum is an integer, from 1 to 18 inclusively, that indicates which of the currently-loaded display scales is used to calculate the window to viewport mapping for the view.

* For elevation calculations, the parameters to view_calcoblq have the following meanings:

center is the center point of the display and is the point relative to which the viewing shear is calculated.

planang is the angle about the z-axis by which the drawing is rotated to orient a particular vertical plane towards the viewer.

shearang is the angle up from the positive x- axis by which lines extending out of the screen are rotated as the shear is applied.

shearfact is the factor by which lines parallel to the axis of shear are enlarged (nominal value is 1.0).

scalenum is an integer, from 1 to 18 inclusively, that indicates which of the currently-loaded display scales is used to calculate the window to viewport mapping for the view.

view_calcorth

PROCEDURE view_calcorth (view : IN OUT view_type; center : IN point; scalenum : IN integer);

view_calcorth calculates an orthographic projection.

* center is the point in world coordinates which lies at the center of the screen in the resulting view.

* scalenum is an integer, from 1 to 18 inclusively, that indicates which of the currently-loaded display scales is used to calculate the window-to-viewport mapping for the view. The absolute position of the drawing in the viewport is dependent upon the user's display device. Some display devices have a much larger resolution than others and as a consequence may display more or less of a drawing accordingly.

view_calcpara

PROCEDURE view_calcpara (view : IN OUT view_type; center : IN point; planang, riseang : IN real; scalenum : IN integer);

view_calcpara calculates a parallel viewing projection.

* center is the center point of rotation for the view and indicates where the center of the screen should be located. planang is the angle by which the drawing is rotated about the z-axis to orient the view.

* riseang is the angle up from the xy-plane (horizon) by which the drawing is rotated to orient the view.

* scalenum is an integer, from 1 to 18 inclusively, that indicates which currently- loaded display scale to use to calculate the window-to-viewport mapping for the view.

view_calcpers

PROCEDURE view_calcpers (view : IN OUT view_type; eyepnt, centpnt : IN point; coneang : IN real);

view_calcpers calculates a perspective viewing projection.

* eyepnt is the location of the viewer's eye.

* eyepnt is in absolute world coordinates and the z-coordinate of eyepnt determines the height from the xy-plane (at z = zero) of the viewer's eye. l centpnt is the point in the drawing or model at which the user is looking. centpnt defines the location of the picture plane relative to eyepnt. The picture plane is perpendicular to a line passing from eyepnt to centpnt, and passes through centpnt. centpnt as passed to view_calcpers is not necessarily equal to the field view.centpnt since the cone-of-vision angle may alter this parameter.

* coneang is the angle of the cone of vision and is the subtended angle between the right and left sides of the frustum of vision. coneang must be within the range 0.0 to 180.0 degrees, but may not be equal to 0.0, or 180.0. coneang determines the values of the window to viewport mapping parameters for the view. The cone of vision in the y-direction is typically less than in the x-direction since nearly all display devices have an aspect ratio which is less than 1.0. Unlike the other view calculation routines, the window-to-viewport mapping parameters for the view are derived from the cone of vision, instead of being explicitly stated.

Hidden Line Removal Routines

The following routine allows a DCAL application to call DataCAD's hidden line removal routine directly.

hide

FUNCTION hide (mode : IN mode_type; lyr : IN OUT layer; view : IN view_type; addimag, drawhidden : boolean) : boolean;

hide performs hidden line removal on the entities described by the mode_type variable mode.

* The mode variable must be properly initialized, and may contain any valid combination of mode parameters.

* view is a view_type variable which must contain a valid set of viewing parameters. view does not necessarily need to exist in the drawing database, but must be valid.

* When drawhidden is true, hidden lines are drawn. When drawhidden is false, hidden lines are not drawn.

* When addimag is true, the result of the Hidden Line Removal process is retained and stored on the layer passed to hide. When addimag is false, the result of the hidden line removal process is not retained, but is displayed on the screen only.

* The layer represented by lyr must be previously created and exist in the database prior to calling hide with addimag set to true; otherwise an error occurs. If you create a temporary layer in the database using lyr_init, make sure you subsequently remove this layer using lyr_term. Note that lyr_init and lyr_term are used only for free layers (layers not part of the main layer/entity structure), and are distinctly different from layers created by the routines lyr_create and lyr_del which add and delete layers from the main layer/entity structure. The following example performs hidden line removal on all layers which are currently on, using the current view and projection, and stores the result on the active layer:

VAR

lyr : layer:

mode : mode_type;

view : view_type;

...

lyr := getlyrcurr;

view_get_curr (view);

mode_init (mode);

mode_lyr (mode, lyr_on);

IF hide (mode, lyr, view,

true, false) THEN

{ Successful run. Resulting image resides on active layer. }

ELSE

{ Process broken via DEL or END keys, or out of memory. }

END;

Hatching Routines

The declarations for the routines in this section are not built into the DCAL compiler, but require the inclusion of the file _hatch.inc.

The following routines invoke DataCAD's

hatching system from a DCAL macro. The hatching interface to DCAL is extremely flexible without compromising the performance of the system. Hatch patterns are defined as a series of passes consisting of parallel scan lines. The scan lines can either be solid (continuous) or dashed.

hatch_mode may be called many times to create

complex hatching patterns. For instance, the DataCAD hatch pattern brick consists of two calls to hatch_mode, one with a horizontal solid pattern and the second with a 90 degree rotated, dashed line pattern.

hatch_mode

PROCEDURE hatch_mode

(mode : IN OUT mode_type;

sl : IN OUT scanLineType;

zbase : IN real;

zhite : IN real;

origin : IN point;

ang : IN real;

scale : IN real;

htype : IN integer;

lyr : IN layer;

min : IN point;

max : IN point;

dobrk : IN boolean;

brk : IN OUT integer);

draw : IN boolean;

hatch_mode hatches a collection of entities.

hatch_mode takes a large number of parameters so you can have as much control as possible over the hatching process. This also provides you with the flexibility to create virtually any hatching pattern.

hatch_mode calls the same set of procedures that are used by the standard Hatch menu, and therefore executes at virtually the same speed.

* mode is a mode_type variable that indicates which entities to hatch. mode must be initialized using procedure mode_init and refers to a valid collection of entities in the drawing database.

* sl is a variable of type scanlinetype and describes the dash/space pattern for each scan line. Refer to "scanlinetype" for the definition of each field of this record.

* zbase is the z-base coordinate of any lines added to the database by hatch_mode.

* zhite is the z-height coordinate of any lines added to the database by hatch_mode.

* origin is the origin of the overall hatch pattern. Be careful not to confuse the parameter origin with the .origin field of a scanlinetype. In this case, origin is the overall origin of the hatch pattern whereas the .origin field of a scanLineType is the local origin for each scan line. ang is the angle of the hatch pattern and is measured using the standard DataCAD angle conventions.

* When ang is non-zero, rotation of the hatch pattern is performed about the point origin (in any event, ang should be initialized). l scale is the overall scaling factor for the hatch pattern. A value for scale of 1.0 indicates that the values contained in the .dash field of sl are in world coordinates and are used directly.

* htype is a flag which may take on one of the three values htype_normal, htype_outer, or htype_ignore and indicates the manner in which hatch_mode handles interior objects in the hatching boundary. See the hatching constants in the "Constants" chapter.

* lyr is a variable of type layer and is the layer to which entities of type line (entlin) are added during the hatching process. lyr must be a valid layer which exists in the drawing database or an error occurs.

* min and max are the extents of the collection of entities to hatch as indicated by mode. The hatching entities' extents must be calculated before calling hatch_mode or hatching does not proceed correctly. The procedure ent_extents may be used in a loop for calculating the extents of a collection of entities described by a mode variable.

* draw is a Boolean flag which is true when the resulting lines of the hatching process are to be drawn as they are added to the drawing database. When draw is false, lines are not drawn as they are added to the drawing database.

* dobrk is a flag which indicates when the user can interrupt the hatching process by pressing (Del) or (End). When dobrk is true, interruption of the hatching process is allowed, otherwise it is not.

* brk is an integer containing the current status of the brkpress state as would be returned by the function brkpress. brk should be initialized to zero. brk is passed to hatch_mode as a formal parameter so that hatch_mode can be placed in a loop when more than one set of scan lines are required for a given hatch pattern. In this case, the calling macro knows if the process has been broken and by which key, through the function brkpress. When (Del) is pressed brk returns a value of -1; when (End) is pressed brk returns a value of 1.

Menu Routines

The routines in this section call the appropriate DataCAD menu. The user is taken to the menu and stays there until exiting the menu, at which time the macro continues. These are convenient for digitizer menus as well as for incorporating the default menus into your own macros. All menu procedures are defined in the include file _menu.inc which must be included in any source file that calls any of these routines.

menu1lntrim

menu2lntrim

menu2lntrim

menu3dline

menuarc2pt

menuarc3pt

menuarccentang

menuarccentarc

menuarccentchrd

menuarctan

menuarraycirc

menuarrayrect

menuchamfer

menuchange

menucleanup

menuclipcube

menucontrols

menucopy

menucrc3pt

menucrcdia

menucrcrad

menucurves

menucutwall

menuDataCAD3

menudirectry

menudisplay

menudivide

menudmension

menudoorswng

menueditplane

menuelevation

menuellipse

menuenlarge

menuerase

menufileio

menufillets

menufreehand

menugoodies

menugotoview

menugotoview3d

menugrids

menuhatch

menuhide

menuidentify

menuintrsect

menulayers

menulinetype

menulinkline

menulintsct

menumeasures

menumirror

menumove

menumovedrag

menuobjsnap

menuobjsnap

menuplanesnap

menuplotter

menupolygons

menurotate

menusaveimage

menusetobliq

menusetpersp

menusettings

menusettings3d

menuss

menustretch

menutangents

menutemplate

menutext

menutintsct

menutoscale

menuviewer

menuwalkthru

menuweldline

menuwindowin

menuwindows

The following menu calls all require the DC-Modeler package, otherwise, no action is taken and control returns immediately to the macro.

menublocks

menuchange3d

menucone

menucopy3d

menucylnhori

menucylnvert

menudome

menuedit3d

menuenlarge3d

menuentity3d

menuerase3d

menuexplode3d

menumarker

menumeshsurf

menumove3d

menupartial

menupolygon

menupolyhori

menupolyincl

menupolyrect

menupolyvert

menurevsurf

menurotate3d

menuslab

menuslabhori

menuslabincl

menuslabrect

menuslabvert

menustretch3d

menutorus

menutrunccone

menuvoids

Miscellaneous Routines

The routines in this section do not fall into any other category presented in this manual.

addr2ints

PROCEDURE addr2ints (addr : entaddr; int1, int2 : OUT integer);

addr2ints converts an address to two integers.

Use this when you write the address out to a file and must write out type integer. While the address of an entity does not change, you have no way of knowing when an entity was deleted and its location used for another entity.

assignProc

PROCEDURE assignProc (proc : procedure; x, y : integer);

assignProc assigns a procedure given by proc to

a given box on the digitizer menu. The procedure must have no parameters. It must be declared at the outermost lexical level -- it cannot be a nested procedure.

l x and y are the location of the box to which the procedure is assigned. When the user picks the box (x, y), procedure proc executes. For example, look at the following code fragment.

PROCEDURE callMove;

BEGIN

menumove;

END callMove;

BEGIN { main program }

configTab (11.0 * 32.0, 11.0 * 32.0, 22, 22, 9, 10, 17, 16);

assignProc (callMove, 0, 0);

END main.

The procedure proc given as a parameter cannot be one of the built-in procedures, so a small wrapper is needed, such as callMove.

beep

PROCEDURE beep;

This procedure causes a beep or warning tone.

bitclear

FUNCTION bitclear (int, bitnum : integer) : integer;

bitclear clears bit number bitnum in int.

* bitnum is is a value from 0 to 15.

* The return value is int with the specified bit cleared.

num := bitclear (num, 5);

clears the fifth bit of num.

bitclear (100, 6) returns 68

bitclear (100, 5) returns 100

bitset

FUNCTION bitset (int, bitnum : integer) : integer;

bitset is identical in usage to bitclear, but the corresponding bit number is set, not cleared.

bittest

FUNCTION bittest (int, bitnum : integer) : boolean;

bittest is similar to bitclear and bitset, but it tests to see if a particular bit is set.

* When the number bitnum bit is set in int, bittest returns true; otherwise, bittest returns false.

bittest (100, 6)returns true

bittest (100, 5)returns false

brkpress

FUNCTION brkpress : integer;

DataCAD defines two break keys, (End) and (Del).

brkpress returns one of three possible values. It returns 0 when neither break key is pressed, 1 when (End) is pressed, and -1 when (Del) is pressed. Unfortunately, the keyboard buffer is cleared whenever brkpress is called, regardless of what the return value is.

clrGetName

PROCEDURE clrGetName (clr : IN integer; clrname : OUT string);

clrGetName reads the name of one of the 15 built-in colors.

In the standard (English) version of DataCAD, color 1 returns White, color 2 returns Red, etc. This procedure is useful to build menus that use the color names.

clrGetPen

FUNCTION clrGetPen (clr : IN integer) : integer;

clrGetPen returns the pen to use with a certain color when the drawing is plotted.

clrSetName

PROCEDURE clrSetName (clr : IN integer; clrname : IN string);

clrSetName sets the name of one of the 15 built-in colors.

clrSetPen

PROCEDURE clrSetPen (clr, pennum : IN integer;

clrSetPen sets the pen pennum that color clr is plotted in.

configTab

PROCEDURE configTab (xsize, ysize : real; xmax, ymax, xlft, ybot, xrht, ytop : integer);

This procedure, along with assignProc, sets up digitizer menus within DataCAD.

* The physical dimensions of the overall tablet are given by xsize and ysize, in 32nds of an inch. l xmax is the total number of boxes in the x dimension, and ymax is the total number of boxes in the y dimension.

* The lower left corner of the area reserved for the screen is xlft, ybot; the upper right corner of the screen area is xrht, ytop. For example, to divide an 11 x 11 inch digitizer into half inch squares, you could use:

configTab (11.0 * 32.0, 11.0 * 32.0, 22, 22, 9, 10, 17, 16);

cutout

FUNCTION cutout (pt1, pt2 : IN OUT point; pt3, pt4 : OUT point;

addr1, addr2, addr3, addr4, addr5, addr6 : OUT entaddr;

doCut : boolean) : boolean;

cutout cuts an opening in a wall.

* The three input parameters are pt1, pt2, and doCut. pt1 and pt2 are the two points that define the edges of the cut in the wall. As in DataCAD, these points do not have to be on the wall.

* When doCut is true, the two lines that form the wall are broken into two pieces with an opening between them. This is useful for inserting a window or door into an existing wall. When doCut is false, the wall lines are not cut, but cutout finds the walls lines anyway. When cutout finds a wall to put an opening in, it returns true.

* On exit, pt1, pt2, pt3, and pt4 define the four corners of the opening in the wall. These points are on the wall that was found. pt3 is opposite pt1, and pt4 is opposite pt2. The meanings of the addresses depend on whether the wall was cut, that is, if doCut was true or false.

* When the wall is cut, addr1 is the address of the line that ends at pt1. addr2 is the address of the line that ends at pt2.

* addr3 and addr4 are the addresses of the lines ending at pt3 and pt4, respectively.

* addr5 is the address of the line that was added between pt1 and pt3.

* addr6 is the address of the line that was added between pt2 and pt4. As an example, this piece of code deletes the two small lines added at the jamb:

IF cutout (pt1, pt2, pt3, pt4, addr1,

addr2, addr3, addr4, addr5, addr6, true) THEN

IF ent_get (ent, addr5) THEN

{ this is always true }

ent_draw (ent, drmode_black);

ent_del (ent);

END;

IF ent_get (ent, addr6) THEN

{ this is always true }

ent_draw (ent, drmode_black);

ent_del (ent);

END;

END;

If the wall was not cut, addr1 is the address of the line that pt1 and pt2 are on, and addr2 is the address of the line that pt3 and pt4 are on. In this case, addr3, addr4, addr5, and addr6 are undefined.

dwgname

PROCEDURE dwgname (str : OUT string);

dwgname sets its parameter to the current drawing name without the path or extension.

For example, if you are in a drawing named c:\dcad\dwg\spiral.dwg, dwgname sets str to spiral.

ent_explode

FUNCTION ent_explode (ent : IN OUT entity; lyr : layer; expMode : integer); boolean;

ent_explode explodes an entity into lines or polygons.

* The resulting lines or polygons are created on layer lyr, which can be a regular or temporary layer as described under lyr_init. Any existing entities on lyr are deleted first.

* When expMode is 0, the entity is exploded into lines; when expMode is 1, the entity is exploded into polygons. ent_explode works for any type of entity, including an instance of a symbol. When this operation is completed successfully, it returns true.

envget

PROCEDURE envget (find : string; val : OUT string);

envget reads the DOS environment.

* This procedure looks for an environment variable with a name like find. l When find is found, the parameter val is set to its value. When find is not found, val is set to an empty string (length zero).

getcurrfont

PROCEDURE getcurrfont (font : IN OUT string);

getcurrfont reads the current font that DataCAD is using. This is a string of up to eight characters that represents the font file without path or extension. The string may be null.

See the DataCAD Reference Manual for further information on fonts.

getCurrInMat

PROCEDURE getCurrInMat (mat : OUT modmat);

getCurrInMat gets a modeling matrix which is the mathematical inverse of the current viewing matrix. getCurrInMat returns a valid matrix only when the current projection is either orthographic or parallel.

* mat is the inverse of the viewing matrix in these cases. getCurrInMat is typically used when entering and editing entities in a parallel projection and is faster and simpler than using the procedure view_getcurr and extracting the field inptmat from the view_type variable.

getpath

PROCEDURE getpath (str : OUT string; num : integer);

getpath reads one of DataCAD's internal pathnames.

DataCAD maintains several pathnames internally and uses them when it opens or creates several types of files. Examples are the pathnames for symbol files and the path where layer files are kept. Notice that the user can change most of these at the get filename prompts. The constants used for the various paths (used for the parameter num) are given in the "Constants" chapter.

getrefpnt

PROCEDURE getrefpnt (pt : OUT point);

getrefpnt reads the point from which DataCAD is displaying distances. This point is used in relative distance output mode.

getrubpnt

PROCEDURE getrubpnt (pt : OUT point);

getrubpnt reads the point from which DataCAD is rubberbanding. This is typically the last point entered. This point is valid whether or not rubln or rubbx is true.

high

FUNCTION high (param : ARRAY) : integer;

high, and the corresponding procedure low, handle arrays of indeterminate bounds (conformant arrays).

For example:

FUNCTION sum (a : ARRAY OF integer) : integer;

VAR

i : integer;

sum1 : integer;

BEGIN

sum1 := 0;

FOR i := low (a) TO high (a) DO

sum1 := sum1 + a [i];

END;

RETURN sum1;

END sum;

This function can be called with any array of integers. At run-time, low and high, return the bounds of the actual parameter. Many of the string routines do essentially this, taking an array of characters.

ints2addr

FUNCTION ints2addr (int1, int2 : integer) : entaddr;

ints2addr converts two integers into an address. This procedure is the reverse of addr2ints.

The two integer parameters must be in the same order as in addr2ints.

isnil

FUNCTION isnil (adr : entaddr) : boolean;

isnil tests for the address of adr. It returns true when adr points to nothing, that is, it is nil. isnil returns false when adr points to something.

NOTE: Even when adr is pointing to invalid data isnil returns true.

keypress

FUNCTION keypress : boolean;

keypress returns true when a key is waiting in the keyboard buffer, and false when one is not.

light

PROCEDURE light (onoff : boolean);

light toggles the asterisk in the lower left corner of the screen.

DataCAD typically uses this to let the user know some time-consuming task is underway.

* When onoff is true, the asterisk is visible, otherwise it is off.

low

FUNCTION low (param : ARRAY) : integer;

low, and the corresponding procedure high, handle arrays of indeterminate bounds (conformant arrays).

lyr_init

PROCEDURE lyr_init (lyr : OUT layer);

lyr_init is similar to lyr_create, creating a layer in the database.

The layer, however, is not one of the standard DataCAD layers that the user has access to. The layer is considered a temporary layer. The layer can be used for a short period of time, but should never exist while the user has control, that is, during any of the get or dget procedures because the user can terminate the macro with (Ctrl)-(C) leaving the temporary layer in the database. It must never be the current layer when the user has control.

* The macro can set lyr as the current layer to add entities to it, as long as the user is not given control to make changes to lyr. Set some other layer as the current layer before returning control to the user.

lyr_term

PROCEDURE lyr_term (lyr : layer);

lyr_term destroys a layer that was created using lyr_init.

This procedure should never be called with a layer that DataCAD created or one the macro created with lyr_create. All entities must be deleted from the layer with lyr_clear before lyr_term is called.

pause

PROCEDURE pause (secs : real);

pause stops the system for the specified number of seconds.

sercheck

FUNCTION serCheck (str : IN string) : boolean;

serCheck returns true when str is the serial number of the copy of DataCAD the macro is running under.

setcurrfont

PROCEDURE setcurrfont (font : string);

setcurrfont sets the current font to font.

* font is the filename, without path or extension, for a font file. The font file specified should exist in the path specified by the system constant pathchr.

See the DataCAD Reference Manual for further information on fonts.

setnil

PROCEDURE setnil (addr : IN OUT entaddr);

setnil sets addr to the special value nil, therefore, the pointer points to nothing.

See isnil and ent_get.

setpath

PROCEDURE setpath (str : string; num : integer);

setpath is related to getpath. It is used to set DataCAD's internal paths.

EXERCISE GREAT CARE IN CHANGING THESE PATHS. Some paths, such as the pathnames for drawing files, should not be changed.

setrefpnt

PROCEDURE setrefpnt (pt : point);

setrefpnt sets the point from which DataCAD displays distances.

setrefpnt is useful when the point being rubberbanded from (see setrubpnt) is not the same as the point you want distance information from, as displayed across the bottom of the window.

setrubpnt

PROCEDURE setrubpnt (pt : point);

setrubpnt sets the point from which DataCAD is rubberbanding when either rubbx or rubln is true.

sizeof

FUNCTION sizeof (variable) : integer;

sizeof returns the size, in bytes, of its parameter.

* The parameter can be any variable or constant, but not a type.

For example:

VAR

rl : real;

addr: entaddr;

str : str80;

sizeof (1) returns 2

sizeof (rl) returns 4

sizeof (addr) returns 4

sizeof (str) returns 81

NOTE: A string has an extra byte which contains the dynamic length of the string.

txtbox

PROCEDURE txtbox (ent : IN OUT entity; pt1, pt2, pt3, pt4 : IN OUT point);

txtbox finds the four corners of an entity of type enttxt.

Use this procedure to justify text.

* The entity ent must be of type enttxt.

* On exit, pt1 is the lower left corner of the text, that is, it is the same as ent.txtpnt.

* pt2 is the lower right corner of the text.

* pt3 is the upper left corner of the text.

* pt4 is the upper right corner of the text.