CAD/CAM Developer's Kit/3D

Reference Guide

1. Introduction

2. 2D Geometry

3. 3D Geometry

4. DXF

5. Display

6. Lists

7. Home

Copyright (c) 1988-2009 Building Block Software, Inc. All rights reserved.

CAD/CAM Developer's Kit/3D

Overview

========

The Building Block Software CAD/CAM Developer's Kits (CCDK) are a collection

of C function libraries for writing CAD/CAM applications. The CCDK

libraries provide functions for operations such as reading and writing of

DXF files, display of geometry, and 2D and 3D geometric computations.

The set of types, macros and functions that support operations with 2D points,

vectors and curves are called "2D GEOMETRY". The operations supported include:

* construction of lines, arcs, circles, ellipses, polycurves and NURB splines

* coordinate, tangent vector and curvature evaluation

* computation of curve intersection points

* curve offset construction

This reference provides:

* fundamental concepts behind the objects and functions in 2D GEOMETRY

* type definitions for 2D objects

* public functions and macros (organized by category)

* public functions and macros (organized alphabetically)

Fundamental Concepts

====================

Introduction

------------

This section presents the concepts behind the 2D GEOMETRY objects and operations.

2D Objects

----------

The object types supported in 2D GEOMETRY are:

* points/vectors

* curves

* bounding boxes

* transform

A point is a set of cartesian coordinates representing a location in space.

The term vector denotes a direction and a magnitude.

A curve is an object that can represent curve geometry. Curve types

supported in CCDK/2D are:

* line

* arc

* ellipse

* polycurve

* Non-Uniform Rational B-spline (NURB-spline)

A line is a linear segment.

An arc is a circular segment or a full circle.

An ellipse is an elliptical segment, either partial or closed.

A polycurve is an end-to-end chain of line and arc segments.

A Non-Uniform Rational B-spline (NURB-spline) is a general type of B-spline.

It can represent a range of spline types, including uniform, non-rational and

Bezier splines as well as conic curves.

A bounding box is a rectangle, often used to record the extents of a 2D

object. This box is aligned with the coordinate axes.

Bounding boxes are useful for determining the approximate locations and

sizes of curves. This information can be applied to "cull" curves from a

set of curves to increase display performance in "zoom" operations. They

can also be used to determine quickly if two curves have no intersection

points (if the bounding boxes of two curves do not intersect, then the

curves do not intersect).

A transform is a matrix used to transform objects in one coordinate system

into another.

Curve Properties

----------------

All curve types have a common set of properties. These properties are defined by the

following statements:

* Every curve has a start point, an end point and an "orientation"; if a curve is

closed, the start point and the end point are the same; the orientation is

the direction one follows along the curve to travel from the start point

to the end point.

* For each point on a curve, there is a corresponding real number called a

parameter value; in mathematical terms, there is a "one-to-one mapping"

between points on a curve and a continuous range of real numbers.

* At each point on a curve, one may evaluate a tangent vector, a curvature,

and other mathematical properties.

* curves may be rotated, scaled, translated, mirrored, intersected, trimmed

and filleted.

* a curve may be offset to produce a parallel curve which runs along the

original curve a constant distance away.

Treating all curve types as one type with these properties eliminates the

need to have a separate function for each curve type for each operation.

Instead, there is only one function for each operation.

Curve Parameters

----------------

A curve parameter is simply a real number (often represented by the symbol

t) that corresponds to a point on a curve. Each point is associated with

only one parameter value, and any one parameter value is associated with

only one point. This number has a particular value at the start point of a

curve, and it increases continuously as one moves along the curve towards

the end point.

The concept of a curve parameter is a key notion in the object- oriented

scheme that enables one general curve type to represent all curve types.

Curve parameters have two very useful features:

* they unambigously specify positions on curves

* they imply relative positions of points on curves

The first feature is a convenient method for identifying the location on a

curve where, for example, an intersection or a local extremum occurs. Also,

this feature can be used to specify where an operation, such as the

evaluation of a tangent vector, should be performed.

The second feature is useful for determining the order of points along a

curve. For example, if point A has a parameter value less than point B, then

point A is encountered first as one travels along the curve from its start

point to its end point.

Parameter values corresponding to points on a curve can be obtained from a

number of sources:

* CCDK/2D macros and routines which provide parameter values of start and end

points of curves

* curve intersection records, which report locations of intersections in terms

of curve parameter values as well as cartesian coordinates

* curve extremum records, which report locations of local extreme points in

terms of curve parameters

* c2c_project, the function that projects a point orthogonally onto a curve;

it reports the location of the projection in terms of a curve parameter;

this function converts cartesian coordinates of a location on a curve into

its corresponding curve parameter

A curve intersection is a point where two curves cross. CCDK/2D

intersection functions report the curve parameters of intersection points as

well as their coordinates and tangency conditions.

A curve extremum is a point on a curve where the curve changes direction

along either the x or y axes. For example, a circle has four extrema: two

'x' extrema (3 o'clock and 9 o'clock) and two 'y' extrema (12 o'clock and 6

o'clock).

Unlike other curve properties of 2D curves, the extrema depend on the

coordinate system. Rotations change the locations of extrema.

Extrema have many uses, such as identifying points at which curves must be

"broken". An example of an application that requires curves to be broken at

extrema is motion control; an extremum point denotes a change in direction,

which, in motion control programs, must be accompanied with "backlash

compensation". By breaking curves at extrema, motion control programs can

insert the necessary backlash compensation at these points.

2D Geometric Operations

-----------------------

This section presents the 2D geometric operations supported by CCDK/2D

functions. These operations fall into three main categories:

* point and vector

* curve

* bounding box

* transform

Point and vector operations consist of:

* construction

* evaluation

* addition and multiplication

Construction operations create point and vector objects.

Evaluation operations compute properties of points and vectors, such as

linear distances, lengths and angles.

Addition and multiplication operations consist of standard vector

computations.

Curve operations consist of:

* construction

* copying

* modification

* evaluation

Construction operations create geometry from input information. Creating an

arc passing through three points is one example of a construction operation.

Copying operations create copies of curves. Many of the functions also

alter copies by trimming or transforming them.

Modification operations, which change existing geometry,

include:

* trimming

* breaking

* rotation

* scaling

* mirroring

* translation

* offsetting

Evaluation operations compute information about geometry such as: tangent

vectors, curvature, midpoints, endpoints and lengths. In addition,

evaluation operations locate intersection and extremum points.

Bounding box operations consist of:

* construction

* evaluation

Construction operations create and modify bounding boxes.

Evaluation determines if bounding boxes overlap.

Transform operations are divided into:

* construction

* evaluation

Construction operations create and combine transforms. Transforms are

constructed from the axes of coordinate systems.

Evaluation consists of applying transforms to points and vectors in one

coordinate system to obtain their coordinates in another coordinate system.

Computational Accuracy

----------------------

The accuracy of the computations performed by routines in the CCDK is

governed by three quantities: absolute tolerance, relative tolerance and

world size.

The relationship between the two tolerances and the world size is specified

by the following equation:

absolute_tolerance = relative_tolerance * world_size ;

Absolute tolerance is used to determine when lengths and distances are small

enough to be treated as negligible; it is dependent on the quantity, world

size, since "negligible" is relative to how big your world is.

Relative tolerance is used to determine when quantities such as angles are

small enough to be considered zero. Another definition for this quantity is

that it is equal to the absolute tolerance when the world size is 1.0.

Unlike the absolute tolerance, the relative tolerance is not dependent on

world size.

World size is simply a number that indicates the typical size of the

geometry being processed. Geometry is not necessarily limited to this size,

but computational accuracy may decrease if geometry much larger than the

world size is used without adjusting the internal world size parameter. The

initial value of world size is 10 units; this value may be changed by

calling the qgl_put_world_size function.

The relative tolerance has an initial value of 1.0E-12, and may be changed

with the qgl_put_tol function.

The absolute tolerance, which has an initial value of 1.0E-11, may not be

set directly; instead it must be changed by resetting the world size and/or

the relative tolerance.

The function qgl_is_small can be used to determine if the absolute value of

a REAL is less than the absolute tolerance. The function qgl_is_zero can be

used to determine if the absolute value of a REAL is less than the relative

tolerance.

Object Types

============

Introduction

------------

This section presents programming information about the objects defined in

CCDK/2D. Use this section of the manual to locate the names of object

types, and the macros that access the attributes of these types.

Types Overview

--------------

CCDK/2D defines types, constants and macros for the following categories:

* general types and constants

* point and vector

* bounding box

* parameter record

* curve

* intersection record

* extremum record

* transform

The general types and constants category consists of basic types used

throughout CCDK.

The point and vector, bounding box, parameter record, curve, intersection

record, extremum record, and transform categories provide types for each of

these objects, and macros which access attributes of these types.

General Types and Constants

---------------------------

The object types in this category are the "atoms" of CCDK objects:

______________________________________________________________________________

| Type | Meaning |

|----------------------------------------------------------------------------|

| INT | integer |

| REAL | real number |

| BOOLEAN | Boolean value; TRUE or FALSE |

| STRING | string; pointer to a character |

------------------------------------------------------------------------------

These types are defined in the header file qgldefs.h.

CCDK/2D also provides the following constants:

______________________________________________________________________________

| Constant | Meaning |

|----------------------------------------------------------------------------|

| TRUE | true |

| FALSE | false |

| SQRT_2 | square root of two |

| SQRT_3 | square root of three |

| TWO_PI | two pi |

| PI | pi |

| HALF_PI | one-half pi |

| PI_OVER_180 | pi divided by 180; useful for |

| | converting between degrees and |

| | radians |

------------------------------------------------------------------------------

Points and Vectors

------------------

Points and vectors are represented by the following types:

______________________________________________________________________________

| Type | Meaning |

|----------------------------------------------------------------------------|

| PT2 | a two-dimensional point or vector |

| PT2 | a pointer to two-dimensional point |

| | or vector |

------------------------------------------------------------------------------

Declaring a variable of type PT2 allocates uninitialized space for two

coordinate values. The coordinates of a PT2 object are set with the

function c2v_set.

These types are defined in the header file c2defs.h.

The following macros access the coordinates of points and components of

vectors:

______________________________________________________________________________

| Type | Meaning |

|----------------------------------------------------------------------------|

| PT2_X(P) | the abscissa (x-coordinate) of |

| | point P, or the x component of |

| | vector P |

| PT2_Y(P) | the ordinate (y-coordinate) of |

| | point P, or the y component of |

| | vector P |

------------------------------------------------------------------------------

These macros are defined in the header file c2defs.h.

Bounding Box

------------

A bounding box is a rectangle that encloses a curve. For lines, arcs, and

circles, this rectangle is the smallest possible one; for ellipses and

splines, it is not necessarily the smallest one, but it is nearly so.

Bounding boxes are represented by these types:

______________________________________________________________________________

| Type | Meaning |

|----------------------------------------------------------------------------|

| C2_BOX_S | a bounding box structure |

| C2_BOX | a pointer to a bounding box |

------------------------------------------------------------------------------

These types are defined in the header file c2defs.h.

The term "bounding box" refers to an object of type C2_BOX. This object is a

pointer to a bounding box structure.

When a bounding box is used as working space or for output, it must refer to

a bounding box structure that has been declared as an automatic variable, or

has been allocated.

When declaring automatic storage, it is often convenient to declare both a

structure and a pointer to the structure to avoid repetitive evaluation of

the structure address:

C2_BOX_S box_s;

C2_BOX box = &box_s;

Alternatively, memory for a bounding box may be allocated with c2a_box:

C2_BOX box = c2a_box ( NULL, NULL );

When an allocated bounding box is no longer needed, it must be freed with

c2a_free_box.

The following macros access information in bounding boxes:

______________________________________________________________________________

| Type | Meaning |

|----------------------------------------------------------------------------|

| C2_MIN_PT(B) | a PT2 that represents the lower |

| | left corner of bounding box B |

| C2_MAX_PT(B) | a PT2 that represents the upper |

| | right corner of bounding box B |

| C2_MIN_X(B) | a REAL that specifies the x |

| | coordinate of the left edge of |

| | bounding box B |

| C2_MIN_Y(B) | a REAL that specifies the y |

| | coordinate of the bottom edge of |

| | bounding box B |

| C2_MAX_X(B) | a REAL that specifies the x |

| | coordinate of the right edge of |

| | bounding box B |

| C2_MAX_Y(B) | a REAL that specifies the y |

| | coordinate of the top edge of |

| | bounding box B |

------------------------------------------------------------------------------

These macros are defined in the header file c2defs.h.

Parameter Record

-----------------

A parameter record is a structure composed of a parameter value and an

index. Only the parameter value is a "public" quantity. The index is used

internally, and should never be set by a CCDK user. To set a parameter

value, use the macro PARM_SET.

______________________________________________________________________________

| Type | Meaning |

|----------------------------------------------------------------------------|

| PARM_S | a parameter record structure |

| PARM | a pointer to a parameter record |

------------------------------------------------------------------------------

These types are defined in the header file qgldefs.h.

The term "parameter record" refers to an object of type PARM. This object is

a pointer to a parameter record structure.

The term "parameter value" means the REAL value stored in a parameter

record. This value is usually represented with the symbol t.

The prefix "C2_" is omitted from the curve parameter record type name

because curve parameters apply to three-dimensional curves as well as

two-dimensional curves.

When calling a routine such as c2c_project which uses a parameter record for

output, the parameter record supplied must refer to a parameter record

structure that has been declared as an automatic variable, or has been

allocated.

When declaring automatic storage, it is often convenient to declare both a

structure and a pointer to the structure to avoid repetitive evaluation of

the structure address:

PARM_S parm_s;

PARM parm = &parm_s;

Alternatively, memory for a parameter record may be allocated with ald_parm

or ald_parm_t:

PARM parm = ald_parm();

When an allocated parameter record is no longer needed, it must be freed

with ald_parm_free.

The following macros read and set the parameter value of parameter records:

______________________________________________________________________________

| Macro | Meaning |

|----------------------------------------------------------------------------|

| PARM_T(P) | a REAL which is the parameter |

| | value in parameter record P |

| PARM_SET(T,P) | a macro that sets the parameter |

| | value of parameter record P to |

| | REAL value T |

------------------------------------------------------------------------------

These macros are defined in the header file qgldefs.h.

Curves

------

The following object type defines a curve:

______________________________________________________________________________

| Type | Meaning |

|----------------------------------------------------------------------------|

| C2_CURVE | a curve |

------------------------------------------------------------------------------

An object of type C2_CURVE can represent a line, an arc, a circle, an

ellipse, a polycurve, or a B-spline. "Create" functions are provided to

create each of these geometry types.

C2_CURVE is defined in the header file c2defs.h.

The following macros access start and end parameters of a curve:

______________________________________________________________________________

| Macro | Meaning |

|----------------------------------------------------------------------------|

| C2_CURVE_PARM0(C) | a PARM which is the curve |

| | parameter record corresponding to |

| | the start point of curve C; the |

| | return value type of this macro is |

| | PARM |

| C2_CURVE_PARM1(C) | a PARM which is the curve |

| | parameter record corresponding to |

| | the end point of curve C; the |

| | return value type of this macro is |

| | PARM |

| C2_CURVE_T0(C) | a REAL which is the curve |

| | parameter t corresponding to the |

| | start point of curve C; the return |

| | value type of this macro is REAL |

| C2_CURVE_T1(C) | a REAL which is the curve |

| | parameter t corresponding to the |

| | end point of curve C; the return |

| | value type of this macro is REAL |

------------------------------------------------------------------------------

The following macros determine curve type:

______________________________________________________________________________

| Macro | Meaning |

|----------------------------------------------------------------------------|

| C2_CURVE_IS_LINE(C) | a BOOLEAN which is TRUE if curve C |

| | is a line; FALSE otherwise |

| C2_CURVE_IS_ARC(C) | a BOOLEAN which is TRUE if curve C |

| | is an arc or a circle; FALSE |

| | otherwise |

| C2_CURVE_IS_PCURVE(C) | a BOOLEAN which is TRUE if curve C |

| | is a polycurve; FALSE otherwise |

------------------------------------------------------------------------------

The following functions access curve bounding boxes:

______________________________________________________________________________

| Macro | Meaning |

|----------------------------------------------------------------------------|

| C2_CURVE_BOX(C) | a C2_BOX which is the bounding box |

| | of curve C |

| C2_CURVE_X_MIN(C) | a REAL which is the x coordinate |

| | of the left edge of the bounding |

| | box of curve C |

| C2_CURVE_X_MAX(C) | a REAL which is the x coordinate |

| | of the right edge of the bounding |

| | box of curve C |

| C2_CURVE_Y_MIN(C) | a REAL which is the y coordinate |

| | of the bottom edge of the |

| | bounding box of curve C |

| C2_CURVE_Y_MAX(C) | a REAL which is the y coordinate |

| | of the top edge of the bounding |

| | box of curve C |

------------------------------------------------------------------------------

Use these macros, defined in the header file c2defs.h, to obtain curve

parameter, type and bounding box information. Use routines c2c_ept0 and

c2c_ept1 to compute start and end points of curves.

The following macros are defined when the symbol SPLINE is defined to enable

spline code.

______________________________________________________________________________

| Type | Meaning |

|----------------------------------------------------------------------------|

| C2_CURVE_IS_ELLIPSE(C) | TRUE if curve C is an ellipse; |

| | FALSE otherwise |

| C2_CURVE_IS_SPLINE(C) | TRUE if curve C is a spline; FALSE |

| | otherwise |

------------------------------------------------------------------------------

These macros are defined in the header file c2defs.h.

Intersection Record

-------------------

The point where two curves cross, termed a curve intersection, is reported

by an object called an intersection record.

This type of object is composed of:

* the coordinates of an intersection point

* two parameter records corresponding to the locations where the intersection

occurs

* a flag indicating whether the curves cross, touch tangentially, or are

collinear

Intersection records are usually returned on an intersection result list.

The following type is used to represent an intersection record:

______________________________________________________________________________

| Type | Meaning |

|----------------------------------------------------------------------------|

| C2_INT_REC | an intersection record; this |

| | object consists of information |

| | about a point where two curves |

| | intersect |

------------------------------------------------------------------------------

Intersection records always reference two curves. The terminology "first

curve" and "second curve", used to distinguish between the two curves,

denotes the first and the second of the two curve arguments, respectively,

in the intersection function argument list.

Intersection records are created internally by intersection routines, and

therefore CCDK/2D does not provide a "create" routine. A free routine,

c2d_free_int_rec, is provided for disposing of intersection records when

they are no longer needed.

C2_INT_REC is defined in the header file c2defs.h.

The following macros access information in an intersection record:

______________________________________________________________________________

| Type | Meaning |

|----------------------------------------------------------------------------|

| C2_INT_REC_PARM1(R) | the curve parameter record in |

| | intersection record R |

| | corresponding to the location |

| | where an intersection occurs on |

| | the first of two curves |

| | intersected |

| C2_INT_REC_T1(R) | the curve parameter value in |

| | intersection record R |

| | corresponding to the location |

| | where an intersection occurs on |

| | the first of two curves |

| | intersected |

| C2_INT_REC_PARM2(R) | the curve parameter record in |

| | intersection record R |

| | corresponding to the location |

| | where an intersection occurs on |

| | the second of two curves |

| | intersected |

| C2_INT_REC_T2(R) | the curve parameter value in |

| | intersection record R |

| | corresponding to the location |

| | where an intersection occurs on |

| | the second of two curves |

| | intersected |

| C2_INT_REC_PARM(R,I) | the curve parameter record in |

| | intersection record R |

| | corresponding to the location |

| | where an intersection occurs on |

| | the "I"th of two curves |

| | intersected; I may be either 1 or |

| | 2 |

| C2_INT_REC_T(R,I) | the curve parameter value in |

| | intersection record R |

| | corresponding to the location |

| | where an intersection occurs on |

| | the "I"th of two curves |

| | intersected; I may be either 1 or |

| | 2 |

| C2_INT_REC_PT(R) | a record of type PT2 in |

| | intersection record R which |

| | contains the coordinates of a |

| | point of intersection |

| C2_INT_REC_TYPE(R) | a flag that specifies whether the |

| | intersection reported by |

| | intersection R is transverse, |

| | tangent or collinear |

| C2_INT_REC_TRANS(R) | if the intersection reported in |

| | intersection record R is |

| | transverse, this macro returns |

| | TRUE; it returns FALSE otherwise |

| C2_INT_REC_TANGENT(R) | if the intersection reported in |

| | intersection record R is tangent, |

| | this macro returns TRUE; it |

| | returns FALSE otherwise |

------------------------------------------------------------------------------

These macros are defined in the header file c2defs.h.

Extremum Record

---------------

The point where a curve reverses direction, along either the x or y axes, is

termed a curve extremum. This point is reported by an object called an

extremum record. The CCDK/2D function c2c_coord_extrs locates the extrema

of a curve and returns a list of extremum records, one for each extremum.

Curve endpoints are never considered curve extrema.

An extremum record is composed of:

* a parameter record representing the location of an curve extremum

* the coordinate value of a curve extremum on the axis of the extremum

* a flag indicating whether an extremum is a minimum or a maximum.

The following type is used to represent an extremum record:

______________________________________________________________________________

| Type | Meaning |

|----------------------------------------------------------------------------|

| C2_EXTR_REC | an extremum record; this record |

| | consists of information about a |

| | local x or y extremum point on a |

| | curve |

------------------------------------------------------------------------------

This type is defined in the header file c2defs.h.

The following macros access information in extremum records:

______________________________________________________________________________

| Type | Meaning |

|----------------------------------------------------------------------------|

| C2_EXTR_REC_PARM(R) | the curve parameter record |

| | corresponding to the extremum |

| | point on a curve reported by |

| | extremum record R |

| C2_EXTR_REC_T(R) | the curve parameter value |

| | corresponding to the extremum |

| | point on a curve reported by |

| | extremum record R |

| C2_EXTR_REC_F(R) | the extremum coordinate value of |

| | the extremum point reported by |

| | extremum record R |

| C2_EXTR_REC_TYPE(R) | a flag which indicates whether the |

| | extremum point reported by |

| | extremum record R is a maximum or |

| | a minimum; the value 1 denotes a |

| | maximum; -1 denotes a minimum |

------------------------------------------------------------------------------

These macros are defined in the header file c2defs.h.

Transform

---------

2D transforms are represented by the type:

______________________________________________________________________________

| Type | Meaning |

|----------------------------------------------------------------------------|

| C2_TRANSFORM | a 2D transform |

------------------------------------------------------------------------------

This type is defined in the header file c2defs.h.

When a transform is used as working space or for output, it must be declared

as an automatic variable, or it must be allocated dynamically.

Declaring an automatic variable of type C2_TRANSFORM allocates space for the

transform matrix.

To allocate dynamic memory for a transform, use c2t_create:

C2_TRANSFORM *t = c2t_create();

When an allocated transform is no longer needed, it must be freed with

c2t_free.

Functions and Macros By Category

================================

Introduction

------------

This section presents CCDK/2D functions organized by the type of operation

they perform.

Category Overview

-----------------

The functions in the CCDK/2D are organized into four areas:

* general

* point/vector

* curve

* bounding box

* transform

General functions deal mostly with computational tolerance and world size.

Point/vector functions perform computations with points and vectors.

Curve functions create curves and perform computations with them.

Bounding box functions build bounding boxes and determine if bounding boxes

overlap.

Transform functions build transforms and apply them to points and vectors.

Functions that perform point and vector operations are divided into the

following groups:

* construction

* evaluation

* addition and multiplication

Construction functions create and initialize points and vectors. They also

construct points and vectors from other points and vectors, and they rotate,

scale and mirror points and vectors.

Evaluation functions compute properties of points and vectors.

Addition and multiplication functions perform vector computations.

Functions that perform curve operations are divided into the following

groups:

* construction

* copying

* modification

* evaluation

Construction create curves from input parameters. They also create curve

parameter objects.

Copying functions copy existing curves, in most cases also altering the copy

by transforming, trimming or offsetting it.

Modification functions alter existing curves. These functions are similar

to copy functions, except that the curve that is altered is the input curve,

not a copy.

Evaluation functions compute properties of curves, such as end point

coordinates, tangent vectors and extremum points. These functions also

compute intersection points.

Functions that perform bounding box operations are divided into the

following groups:

* construction

* evaluation

Construction functions create and modify bounding boxes.

Evaluation consists of one function, c2a_box_overlap, that determines if two

bounding boxes interfere.

Function Prefixes

-----------------

CCDK functions are labelled with prefixes to indicate the general type of

operation they perform. Prefixes used in CCDK/2D are:

______________________________________________________________________________

| Prefix | Meaning |

|----------------------------------------------------------------------------|

| qgl | general |

| c2v | point/vector |

| ald | curve parameter |

| c2d | curve construction and copying |

| c2c | curve modification and evaluation |

| c2a | bounding box |

| c2t | transform |

------------------------------------------------------------------------------

General Functions

-----------------

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| qgl_get_tol | to obtain the absolute tolerance |

| qgl_put_tol | to set the absolute tolerance |

| qgl_is_small | to test if a REAL number is less |

| | than the absolute tolerance |

| qgl_is_zero | to test if a REAL number is less |

| | than the relative tolerance |

| qgl_get_world_size | to obtain the world size parameter |

| qgl_put_world_size | to set the world size parameter |

------------------------------------------------------------------------------

When using functions from this group, include the header file qgldefs.h.

Point and Vector Construction

-----------------------------

The following functions create and initialize points and vectors:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2d_point | to create a point |

| c2d_free_point | to free a point |

| c2v_set_zero | to set a vector to zero |

| c2v_set | to set the coordinates of a vector |

| | |

------------------------------------------------------------------------------

A point or vector may be created by declaring an automatic variable of type

PT2 or by calling c2d_point. If a point or vector created by c2d_point is

no longer needed, it must be freed with c2d_free_point.

When using functions from this group, include the header file c2ddefs.h or

c2vdefs.h, depending on the prefix.

The following functions construct points and vectors from other points and

vectors:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2v_copy | to copy a point or a vector |

| c2v_negate | to construct a vector which has |

| | the reverse direction of a vector |

| | |

| c2v_mid_pt | to construct the midpoint between |

| | two points |

| c2v_normal | to compute the 90 degree |

| | counter-clockwise rotation of a |

| | vector |

| c2v_project_line | to project a point onto a line |

| | defined by two points |

| c2v_offset | to construct the point at a given |

| | distance from a point in a |

| | direction 90 degrees |

| | counter-clockwise to a given |

| | direction |

------------------------------------------------------------------------------

The following functions normalize vectors:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2v_normalize | to normalize a vector |

| c2v_normalize_l1 | to divide the components of a |

| | vector by its "Manhattan length"; |

| | produces a vector that |

| | approximately has unit length |

------------------------------------------------------------------------------

The following functions transform points and vectors:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2v_mirror | to mirror a point about a line |

| | defined by two points |

| c2v_scale | to multiply a vector by a scalar |

| c2v_rotate_vec | to rotate a vector about the |

| | origin |

| c2v_rotate_vec_cs | to rotate a vector about the |

| | origin given the cosine and sine |

| | of the rotation angle |

| c2v_rotate_pt | to rotate a vector about a point |

| c2v_rotate_pt_cs | to rotate a vector about a point |

| | given the cosine and the sine of |

| | the rotation angle |

------------------------------------------------------------------------------

When using point and vector construction routines, include the header file

c2vdefs.h.

Point and Vector Evaluation

---------------------------

The following functions compute distances between points and lengths of

vectors:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2v_is_small | to determine if a vector has |

| | length less than absolute |

| | tolerance |

| c2v_ident_pts | to determine if two points are |

| | identical |

| c2v_norm | to determine the length of a |

| | vector |

| c2v_norm_squared | to determine the square of the |

| | length of a vector |

| c2v_norml1 | to estimate the length of a |

| | vector; this length is often |

| | termed the "Manhattan length" |

| c2v_dist | to determine the distance between |

| | two points |

| c2v_distl1 | to determine the "Manhattan |

| | distance" between two points |

| c2v_dist_squared | to determine the square of the |

| | distance between two points |

------------------------------------------------------------------------------

When using functions from this group, include the header file c2vdefs.h.

The following functions compute angles related to vectors:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2v_vecs_angle | to determine the angle between two |

| | vectors |

| c2v_vecs_cos | to determine the cosine of the |

| | angle between two vectors |

| c2v_vecs_sin | to determine the sine of the angle |

| | between two vectors |

| c2v_vecs_parallel | to determine if two vectors are |

| | parallel |

------------------------------------------------------------------------------

When using functions from this group, include c2vdefs.h.

Vector Addition and Multiplication

----------------------------------

The following functions perform vector addition:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2v_add | to add two vectors |

| c2v_addt | to compute the sum of a vector and |

| | a multiple of another vector |

| c2v_addw | to compute the weighted sum of two |

| | vectors |

| c2v_addu | to compute the convex combination |

| | of two vectors |

| c2v_sub | to subtract two vectors |

------------------------------------------------------------------------------

The following functions perform vector multiplication:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2v_dot | to compute the dot product of two |

| | vectors |

| c2v_cross | to compute the cross product of |

| | two vectors |

------------------------------------------------------------------------------

When using functions from these groups, include the header file c2vdefs.h.

Curve Construction

------------------

The following functions create single-segment curves:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2d_line | to construct a line defined by two |

| | points |

| c2d_line_dir | to construct a line defined by a |

| | point and a direction vector |

| c2d_ray | to construct a line defined by a |

| | point and an angle |

| c2d_arc | to construct an arc defined by a |

| | center, radius, start angle, |

| | sweep angle and direction |

| c2d_arc_3pts | to construct an arc passing |

| | through three points |

| c2d_arc_ctr_2pts | to construct an arc with a given |

| | center, starting at one point, |

| | and ending at another |

| c2d_circle | to construct a circle defined by a |

| | center point and a radius |

| c2d_circle_ctr_pt | to construct a circle defined by a |

| | center point and a point on the |

| | circle |

------------------------------------------------------------------------------

The following functions create polycurves:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2d_pcurve_init | to create an empty polycurve |

| c2d_pcurve_through | to create a polycurve through a |

| | set of points |

| c2d_pcurve_add_arc_2pts | to add an arc to the end of a |

| | polycurve starting at the end |

| | point, and passing through two |

| | given points |

| c2d_pcurve_add_arc_tan | to add an arc to the end of a |

| | polycurve tangent to the endpoint |

| | and ending at a specified point |

| c2d_pcurve_add_line | to add a line segment to the end |

| | of a polyline |

| c2d_pcurve_add_line_tan | to add a line to the end of a |

| | polycurve tangent to the end |

| | point, and ending at a specified |

| | point |

| c2d_pcurve_remove_last | to remove the last segment from a |

| | polycurve |

| c2d_pcurve_close | to add a segment to close a |

| | polycurve |

------------------------------------------------------------------------------

The function c2d_pcurve_segment creates a C2_CURVE object from a specified

segment of a 2D polycurve.

The following functions, which create ellipses and splines, are available

only when the symbol SPLINE is defined:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2d_ellipse | to construct an ellipse |

| c2d_spline | to construct a spline |

| c2d_spline_knots | to construct a spline with a |

| | specific parameterization |

| c2d_spline_tan | to construct a spline with |

| | specific start and end tangent |

| | conditions |

| c2d_spline_clsd | to construct a closed spline |

------------------------------------------------------------------------------

When curves are created, memory is allocated dynamically. Accordingly, the

memory they occupy must be freed whey they are no longer needed. The routine

c2d_free_curve is provided for this purpose. Do not use the routine free to

free curves.

When using functions from this group, include the header file c2ddefs.h.

The following functions create and initialize curve parameter objects.

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| ald_parm | to create a parameter record |

| ald_parm_t | to create a parameter record |

| | initialized to parameter value t |

| ald_parm_copy | to copy a parameter record |

| ald_parm_free | to free a parameter record |

------------------------------------------------------------------------------

When using curve parameter functions, include the header file alddefs.h.

Curve Copying

-------------

The following functions copy curves. Most of the functions also alter the

copy:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2d_copy | to create a copy of a curve |

| c2d_translate | to create a translated copy a |

| | curve |

| c2d_rotate | to create a rotated copy of a |

| | curve |

| c2d_rotate_cs | to create a rotated copy of a |

| | curve; the rotation angle is |

| | specified by the cosine and the |

| | sine of the rotation angle; use |

| | this routine when rotating a |

| | number of curves by the same angle |

| | to avoid unnecessary calls to the |

| | sin and cos functions |

| c2d_scale | to create a scaled copy of a curve |

| c2d_mirror_line | to create a curve which is the |

| | mirror image of a curve about a |

| | line |

| c2d_mirror_dir | to create a curve which is the |

| | mirror image of a curve about an |

| | axis defined by a point and a |

| | direction |

| c2d_transform | to create a transformed copy of a |

| | curve |

------------------------------------------------------------------------------

The following functions create offset curves:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2d_offset | to create a curve offset from a |

| | curve by a given distance |

| c2d_offset_curve | to create a curve offset from a |

| | curve by a given distance; |

| | accepts only line and arc curves |

| c2d_offset_through | to create a curve offset from a |

| | curve, passing through a given |

| | point |

| c2d_offset_curve_through | to create a curve offset from a |

| | curve, passing through a given |

| | point ; accepts only line and arc |

| | curves |

------------------------------------------------------------------------------

The following functions create trimmed copies of curves:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2d_trim0 | to create a curve by copying a |

| | curve and trimming away the |

| | "start portion" of the copy; the |

| | portion of the copy from the |

| | trimming point to the end point |

| | is retained; the trimming point is |

| | specified with a parameter record |

| c2d_trim1 | to create a curve by copying a |

| | curve and trimming away the "end |

| | portion" of the copy; the portion |

| | of the copy from the start point |

| | to the trimming point is retained; |

| | the trimming point is specified |

| | with a parameter record |

| c2d_trim | to create a curve by copying a |

| | curve and trimming away both ends |

| | of the copy; the portion of the |

| | copy between the trimming points |

| | is retained; the trimming points |

| | are specified with parameter |

| | records |

| c2d_trim_t0 | to create a curve by copying a |

| | curve and trimming away the |

| | "start portion" of the copy; the |

| | portion of the copy from the |

| | trimming point to the end point |

| | is retained; the trimming point is |

| | specified with a parameter value |

| c2d_trim_t1 | to create a curve by copying a |

| | curve and trimming away the "end |

| | portion" of the copy; the portion |

| | of the copy from the start point |

| | to the trimming point is retained; |

| | the trimming point is specified |

| | with a parameter value |

| c2d_trim_t | to create a curve by copying a |

| | curve and trimming away both ends |

| | of the copy; the portion of the |

| | copy between the trimming points |

| | is retained; the trimming points |

| | are specified with parameter |

| | values |

------------------------------------------------------------------------------

When using functions from these groups, include the header file c2ddefs.h.

Curve Modification

------------------

Curve modification consists of transformation and trimming.

The following functions transform curves:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2c_translate | to translate a curve |

| c2c_rotate | to rotate a curve |

| c2c_rotate_cs | to rotate a curve; a special |

| | version intended to make multiple |

| | rotations of a curve more |

| | efficient |

| c2c_scale | to scale a curve |

| c2c_mirror_line | to mirror a curve about a line |

| c2c_mirror_dir | to mirror a curve about an axis |

| | defined by a point and a |

| | direction |

| c2c_transform | to transform a curve |

------------------------------------------------------------------------------

The following functions trim a curve:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2c_trim0 | to trim away the "start portion" |

| | of a curve; the portion of the |

| | curve from the trimming point to |

| | the end point is retained; the |

| | trimming point is specified with a |

| | parameter record |

| c2c_trim1 | to trim away the "end portion" of |

| | a curve; the portion of the curve |

| | from the start point to the |

| | trimming point is retained; the |

| | trimming point is specified with a |

| | parameter record |

| c2c_trim | to trim away both ends of a curve; |

| | the portion of the curve between |

| | the trimming points is retained; |

| | the trimming points are specified |

| | with parameter records |

| c2c_trim_t0 | to trim away the "start portion" |

| | of a curve; the portion of the |

| | curve from the trimming point to |

| | the end point is retained; the |

| | trimming point is specified with a |

| | parameter value |

| c2c_trim_t1 | to trim away the "end portion" of |

| | a curve; the portion of the curve |

| | from the start point to the |

| | trimming point is retained; the |

| | trimming point is specified with a |

| | parameter value |

| c2c_trim_t | to trim away both ends of a curve; |

| | the portion of the curve between |

| | the trimming points is retained; |

| | the trimming points are specified |

| | with parameter values |

------------------------------------------------------------------------------

When using curve modification functions, include the header file c2cdefs.h.

Curve Evaluation

----------------

The following functions compute points, tangent vectors, and other

information about curves:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2c_eval | to compute the coordinates and a |

| | number of derivatives at a point |

| c2c_eval_pt | to compute or to evaluate the |

| | coordinates of a point on a curve |

| | specified by a curve parameter |

| | record |

| c2c_eval_tan | to evaluate a tangent vector of a |

| | curve at a location specified by |

| | a curve parameter record |

| c2c_eval_pt_tan | to evaluate the coordinates and |

| | the tangent vector of a curve at |

| | a location specified by a curve |

| | parameter record |

| c2c_ept0 | to compute the coordinates of the |

| | start point of a curve |

| c2c_etan0 | to evaluate the tangent vector at |

| | the start point of a curve |

| c2c_ept_tan0 | to evaluate the coordinates and |

| | the tangent vector at the start |

| | point of a curve |

| c2c_ept1 | to evaluate the coordinates of the |

| | end point of a curve |

| c2c_etan1 | to evaluate the tangent vector at |

| | the end point of a curve |

| c2c_ept_tan1 | to evaluate the coordinates and |

| | the tangent vector at the end |

| | point of a curve |

| c2c_closed | to determine if a curve is closed |

| c2c_coord_extrs | to locate the coordinates of curve |

| | extrema |

| c2c_length | to compute the length of a curve |

| c2c_curvature | to evaluate the curvature of a |

| | curve at a location specified by |

| | a curve parameter record |

| c2c_project | to project a point onto a curve; |

| | this routine should be used to |

| | generate the curve parameter |

| | record corresponding to a given |

| | point on a curve |

| c2c_select | to check if a point lies within a |

| | given distance from a curve |

| c2c_info_curve | to print information about a curve |

------------------------------------------------------------------------------

When using curve evaluation functions, include the header file c2cdefs.h.

The following functions compute the center and contact points of fillet

arcs:

arc and the curve paramters of the contact points on the filleted curves

arc and the curve paramters of the contact points on the filleted curves;

curves must form a sharp corner

The following functions compute information about curves which are arcs,

circles and ellipses.

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2c_get_arc_data | to obtain the center, radius, |

| | start angle, sweep and direction |

| | of an arc |

| c2c_get_arc_radius | to obtain the radius of an arc |

| c2c_get_arc_center | to obtain the center point of an |

| | arc |

| c2c_get_arc_start_angle | to obtain the start angle of an |

| | arc; the result is in radians |

| c2c_get_arc_sweep | to obtain the sweep of an arc; the |

| | result is in radians |

| c2c_get_arc_dir | to obtain the direction of an arc; |

| | +1 is counter-clockwise; -1 is |

| | clockwise |

| c2c_arc_angle | to obtain the angle on an arc |

| | corresponding to a parameter |

| c2c_arc_parm | to obtain the parameter on an arc |

| | corresponding to an angle |

| c2c_get_ellipse_data | to obtain the center, major and |

| | minor axes, start angle, sweep |

| | and direction of an ellipse; |

| | available only if SPLINE is |

| | defined |

| c2c_get_pcurve_data | to obtain information about a |

| | specified segment of a polycurve |

------------------------------------------------------------------------------

Include c2cdefs.h when using arc, ellipse and polycurve information

routines.

The following functions create linear interpolations, or "polygonal

approximations", of 2D curves. The precision of interpolation is controlled

by a specified maximum chordal deviation from the exact mathematical

representation of the curve being approximated:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2c_approx | to compute a linear approximation |

| | of a curve |

| c2c_approx_init | to initialize a linear |

| | approximation of a curve |

------------------------------------------------------------------------------

The following function locate points where curves intersect:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2c_intersect | to intersect two curves |

| c2c_intersect_ext | to intersect two curves, treating |

| | lines as infinite lines and arcs |

| | as full circles |

| c2c_self_intersect | to find self intersections; |

| | applies only to splines and |

| | polycurves |

| c2c_intersect_line_or_arc | to intersect lines and arcs |

| c2c_intersect_line_or_arc_ext | to intersect infinite lines and |

| | full circles |

| c2d_free_int_rec | to free an intersection record |

| c2c_info_int_rec | to print information about an |

| | intersection record. |

------------------------------------------------------------------------------

Include c2ddefs.h when using c2d_free_int_rec. Include c2cdefs.h when using

the other functions.

The routines c2c_intersect and c2c_intersect_ext intersect curves of any

type. The results of intersections are returned in intersection records that

are on an "intersection result list". Intersection records contain:

* the coordinates of the intersection point

* the parameters on each of the intersecting curves where the intersection

occurred

* whether the intersection is transverse, tangent or collinear

The information in these records may be accessed by "walking" the

intersection result list and applying access macros to the intersection

records. The function c2c_info_int_rec prints information about an

intersection on the screen.

Routines c2c_intersect_line_or_arc and c2c_intersect_line_or_arc_ext are a

departure from the CCDK/2D object-oriented approach for the convenience of

programmers who are using lines and arcs only. These routines return

intersection information directly as arguments rather than on an

intersection result list, simplifying the process of obtaining information

about intersections.

Bounding Box Operations

-----------------------

These functions perform curve bounding box operations.

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2a_box | to create a bounding box |

| c2a_free_box | to free a bounding box |

| c2a_box_append | to expand a bounding box to |

| | include another bounding box |

| c2a_box_append_pt | to expand a bounding box to |

| | include a point |

| c2a_box_copy | to copy a bounding box |

| c2a_box_init_pt | to initialize a bounding box to a |

| | point |

| c2a_box_poly | to build a bounding box that |

| | contains an array of points |

| c2a_box_union | to create a bounding box that |

| | contains two bounding boxes |

| c2a_box_overlap | to test if two bounding boxes |

| | overlap |

------------------------------------------------------------------------------

When using functions from this group, include the header file c2adefs.h.

Transform Construction and Evaluation

-------------------------------------

The following functions create and modify 2D transforms:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2t_create | to create a identity transform |

| c2t_lcs | to compute a transform for |

| | transforming objects from the |

| | global coordinate system to a |

| | local coordinate system |

| c2t_mirror_line | to construct a 2D transform for |

| | mirroring |

| c2t_rotate | to construct a 2D transform for |

| | rotating |

| c2t_rotate_cs | to construct a 2D transform for |

| | rotating; the rotation angle is |

| | specified with it cosine and sine |

| c2t_scale | to construct a 2D transform for |

| | scaling |

| c2t_translate | to construct a 2D transform for |

| | translation |

| c2t_inverse | to compute the inverse of a |

| | transform |

| c2t_mult | to multiply two transforms |

| c2t_orthogonal | to determine if a transform is |

| | orthogonal |

| c2t_free | to free a transform |

------------------------------------------------------------------------------

The following functions transform points and vectors:

______________________________________________________________________________

| Function | Use |

|----------------------------------------------------------------------------|

| c2t_eval_pt | to transform a point |

| c2t_eval_vec | to transform a vector |

------------------------------------------------------------------------------

When using transform functions, include the header file c2tdefs.h.

Alphabetized Reference

======================

***>> ald_parm <<***

****** Summary ******

#include <alddefs.h>

PARM ald_parm();

****** Description ******

This function creates an unitialized parameter record.

****** Return Value ******

The return value is a pointer to a parameter record. If memory could not be

allocated, NULL is returned.

****** Example ******

#include <alddefs.h>

void main()

{

PARM parm = ald_parm();

SET_PARM ( 0.5, parm );

ald_parm_free ( parm );

}

This program creates and frees a parameter record.

***>> ald_parm_copy <<***

****** Summary ******

#include <alddefs.h>

PARM ald_parm_copy ( p1, p2 );

****** Description ******

This function copies the contents of one parameter record to another.

****** Input ******

------------------------------------------------------------------------------

| PARM | p1 | parameter record to copy; |

| | | source |

------------------------------------------------------------------------------

| PARM | p2 | parameter record to copy |

| | | into; target; must be |

| | | allocated or declared as an |

| | | automatic variable structure |

------------------------------------------------------------------------------

****** Example ******

#include <alddefs.h>

void main()

{

PARM_S p1, p2;

PARM_SET ( 0.1, &p1 );

ald_parm_copy ( &p1, &p2 );

printf ( "%lf\n", PARM_T(&p2) );

}

This program initializes a parameter record, and then copies it to another

parameter record.

***>> ald_parm_free <<***

****** Summary ******

#include <alddefs.h>

void ald_parm_free ( parm );

****** Description ******

This function frees a parameter record. Use this function to free only

parameter record created with ald_parm or ald_parm_t.

****** Input ******

------------------------------------------------------------------------------

| PARM | parm | a parameter record |

------------------------------------------------------------------------------

****** Example ******

#include <alddefs.h>

void main()

{

PARM parm = ald_parm_t ( 0.5 );

ald_parm_free ( parm );

}

This program creates and frees a parameter record.

***>> ald_parm_t <<***

****** Summary ******

#include <alddefs.h>

PARM ald_parm_t ( t );

****** Description ******

This function creates a parameter record initialized to a given parameter

value.

****** Input ******

------------------------------------------------------------------------------

| REAL | t | a parameter value |

------------------------------------------------------------------------------

****** Return Value ******

The return value is a pointer to a parameter record initialized to the given

parameter value.

****** Example ******

#include <alddefs.h>

void main()

{

PARM parm = ald_parm_t ( 0.5 );

ald_parm_free ( parm );

}

This program creates a parameter record initialized to 0.5, and then frees

it.

***>> ATAN2 <<***

****** Summary ******

#include <qgldefs.h>

ATAN2 ( y, x );

****** Description ******

This macro computes the angle defined by the specified "rise" and "run".

The returned value is between 0 and two pi. The standard C routine atan2

returns an angle between -pi and pi.

****** Input ******

------------------------------------------------------------------------------

| REAL | y, x | the "rise" and "run" of the |

| | | angle |

------------------------------------------------------------------------------

****** Return Value ******

The return value is the angle in radians defined by the specified "rise" and

"run".

****** Example ******

#include <qgldefs.h>

void main()

{

REAL rise = 4.0, run = 7.0;

printf ( "%lf\n", ATAN2(rise,run) );

}

This program computes the angle defined by a specified rise and run.

***>> c2a_box <<***

****** Summary ******

#include <c2adefs.h>

C2_BOX c2a_box ( min_pt, max_pt );

****** Description ******

This function creates a bounding box initialized to the rectangle

represented by two given points.

****** Input ******

------------------------------------------------------------------------------

| PT2 | min_pt, max_pt | the lower left and upper |

| | | right corner points of the |

| | | bounding box; if either is |

| | | NULL, the bounding box is |

| | | created, but not |

| | | initialized |

------------------------------------------------------------------------------

****** Return Value ******

The return value is a pointer to a bounding box. If memory could not be

allocated, NULL is returned.

****** Example ******

#include <c2vdefs.h>

#include <c2adefs.h>

void main()

{

PT2 p0, p1;

C2_BOX box;

c2v_set ( 2.0, 3.0, p0 );

c2v_set ( 5.0, 6.0, p1 );

box = c2a_box ( p0, p1 );

c2a_free_box ( box );

}

This program creates a bounding box with corners (2,3) and (5,6).

***>> c2a_box_append <<***

****** Summary ******

#include <c2adefs.h>

C2_BOX c2a_box_append ( box, append_box );

****** Description ******

This routine expands a bounding box to include another bounding box.

****** Input ******

------------------------------------------------------------------------------

| C2_BOX | box | the box to expand |

------------------------------------------------------------------------------

| C2_BOX | append_box | the box fitted into the |

| | | expanded box |

------------------------------------------------------------------------------

****** Example ******

#include <c2vdefs.h>

#include <c2adefs.h>

void main()

{

PT2 p0, p1;

C2_BOX box0, box1;

c2v_set ( 2.0, 3.0, p0 );

c2v_set ( 5.0, 6.0, p1 );

box0 = c2a_box ( p0, p1 );

c2v_set ( 3.0, 4.0, p0 );

c2v_set ( 7.0, 8.0, p1 );

box1 = c2a_box ( p0, p1 );

c2a_box_append ( box0, box1 );

}

This program creates two bounding boxes and then expands the first to

include the second.

***>> c2a_box_append_pt <<***

****** Summary ******

#include <c2adefs.h>

C2_BOX c2a_box_append_pt ( box, pt );

****** Description ******

This function expands a bounding box to include a point.

****** Input ******

------------------------------------------------------------------------------

| C2_BOX | box | the box to expand |

------------------------------------------------------------------------------

| PT2 | pt | a point |

------------------------------------------------------------------------------

****** Example ******

#include <c2vdefs.h>

#include <c2adefs.h>

void main()

{

PT2 p0, p1, p;

C2_BOX box0;

c2v_set ( 2.0, 3.0, p0 );

c2v_set ( 5.0, 6.0, p1 );

box0 = c2a_box ( p0, p1 );

c2v_set ( 7.0, 8.0, p );

c2a_box_append_pt ( box0, p );

}

This program expands a bounding box to include a point.

***>> c2a_box_copy <<***

****** Summary ******

#include <c2adefs.h>

C2_BOX c2a_box_copy ( box0, box1 );

****** Description ******

This function copies a bounding box.

****** Input ******

------------------------------------------------------------------------------

| C2_BOX | box0 | the box to copy |

------------------------------------------------------------------------------

****** Output ******

------------------------------------------------------------------------------

| C2_BOX | box1 | the copy; this box must be |

| | | created by the caller |

------------------------------------------------------------------------------

****** Example ******

#include <c2vdefs.h>

#include <c2adefs.h>

void main()

{

PT2 p0, p1, origin;

C2_BOX box0, box1 ;

c2v_set ( 0.0, 0.0, origin );

box1 = c2a_box ( origin, origin );

c2v_set ( 2.0, 3.0, p0 );

c2v_set ( 5.0, 6.0, p1 );

box0 = c2a_box ( p0, p1 );

c2a_box_copy ( box0, box1 );

}

This program makes box1 a copy of box0.

***>> c2a_box_init_pt <<***

****** Summary ******

#include <c2adefs.h>

C2_BOX c2a_box_init_pt ( box, pt );

****** Description ******

This function initializes the lower left and upper right corners of a

bounding box to the same point. The result is a rectangle with zero area.

****** Input ******

------------------------------------------------------------------------------

| C2_BOX | box | the box to initialize |

------------------------------------------------------------------------------

| PT2 | pt | the point to initialize the |

| | | box to |

------------------------------------------------------------------------------

****** Example ******

#include <c2adefs.h>

#include <c2vdefs.h>

void main()

{

PT2 p;

C2_BOX box = c2a_box ( NULL, NULL );

c2v_set ( 2.0, 3.0, p );

c2a_box_init_pt ( box, p );

c2a_free_box ( box );

}

This program creates a bounding box with both corners (2.0,3.0).

***>> c2a_box_overlap <<***

****** Summary ******

#include <c2adefs.h>

BOOLEAN c2a_box_overlap ( box1, box2 );

****** Description ******

This routine determines if two bounding boxes overlap.

****** Input ******

------------------------------------------------------------------------------

| C2_BOX | box1, box2 | the bounding boxes to test |

| | | for overlap |

------------------------------------------------------------------------------

****** Return Value ******

The return value is TRUE if the boxes overlap; it is FALSE otherwise.

****** Example ******

#include <c2vdefs.h>

#include <c2adefs.h>

void main()

{

PT2 p0, p1;

C2_BOX box0, box1;

c2v_set ( 2.0, 3.0, p0 );

c2v_set ( 5.0, 6.0, p1 );

box0 = c2a_box ( p0, p1 );

c2v_set ( 3.0, 4.0, p0 );

c2v_set ( 7.0, 8.0, p1 );

box1 = c2a_box ( p0, p1 );

if ( c2a_box_overlap ( box0, box1 ) )

printf ( "boxes overlap\n" );

c2a_free_box ( box0 );

c2a_free_box ( box1 );

}

This program tests two bounding boxes to determine if they overlap, and

returns TRUE in this particular example.

***>> c2a_box_poly <<***

****** Summary ******

#include <c2adefs.h>

C2_BOX c2a_box_poly ( a, d, box );

****** Description ******

This function computes the bounding box that encloses an array of points.

****** Input ******

------------------------------------------------------------------------------

| PT2 * | a | the array of points |

------------------------------------------------------------------------------

| INT | d | the number of points in the |

| | | array |

------------------------------------------------------------------------------

****** Output ******

------------------------------------------------------------------------------

| C2_BOX | box | the bounding box that |

| | | contains all of the points |

------------------------------------------------------------------------------

****** Example ******

#include <c2adefs.h>

#include <c2vdefs.h>

void main()

{

PT2 p[4];

C2_BOX box = c2a_box ( NULL, NULL );

c2v_set ( 2.0, 3.0, p[0] );

c2v_set ( 5.0, 6.0, p[1] );

c2v_set ( 3.0, 4.0, p[2] );

c2v_set ( 7.0, 8.0, p[3] );

c2a_box_poly ( p, 4, box );

c2a_free_box ( box );

}

This program creates a bounding box that encloses four points.

***>> c2a_box_union <<***

****** Summary ******

#include <c2adefs.h>

C2_BOX c2a_box_union ( box1, box2, box );

****** Description ******

This function computes the smallest bounding box that encloses two bounding

boxes.

****** Input ******

------------------------------------------------------------------------------

| C2_BOX | box1, box2 | the boxes to enclose |

------------------------------------------------------------------------------

****** Output ******

------------------------------------------------------------------------------

| C2_BOX | box | the box that contains both |

| | | input boxes |

------------------------------------------------------------------------------

****** Example ******

#include <c2vdefs.h>

#include <c2adefs.h>

void main()

{

PT2 p0, p1;

C2_BOX box0, box1, box;

c2v_set ( 2.0, 3.0, p0 );

c2v_set ( 5.0, 6.0, p1 );

box0 = c2a_box ( p0, p1 );

c2v_set ( 3.0, 4.0, p0 );

c2v_set ( 7.0, 8.0, p1 );

box1 = c2a_box ( p0, p1 );

box = c2a_box ( NULL, NULL );

c2a_box_union ( box0, box1, box );

c2a_free_box ( box );

c2a_free_box ( box0 );

c2a_free_box ( box1 );

}

This program computes the bounding box that encloses two boxes.

***>> c2a_box_w_overlap <<***

****** Summary ******

#include <c2adefs.h>

BOOLEAN c2a_box_w_overlap ( box1, box2, w );

****** Description ******

This function determines if two boxes are less than a given distance apart.

****** Input ******

------------------------------------------------------------------------------

| C2_BOX | box1, box2 | the boxes to test |

------------------------------------------------------------------------------

| REAL | w | the separation distance |

------------------------------------------------------------------------------

****** Return Value ******

If the boxes overlap or are separated by a distance less than the given

distance, the return value is TRUE; otherwise it is FALSE.

****** Example ******

#include <c2vdefs.h>

#include <c2adefs.h>

void main()

{

PT2 p0, p1;

C2_BOX box0, box1;

REAL w = 1.0;

c2v_set ( 2.0, 3.0, p0 );

c2v_set ( 5.0, 6.0, p1 );

box0 = c2a_box ( p0, p1 );

c2v_set ( 5.5, 6.5, p0 );

c2v_set ( 7.0, 8.0, p1 );

box1 = c2a_box ( p0, p1 );

if ( c2a_box_w_overlap ( box0, box1, w ) )

printf ( "boxes overlap or are less than 1 unit apart\n" );

c2a_free_box ( box0 );

c2a_free_box ( box1 );

}

This program determines if two bounding boxes overlap or are less than 1

unit apart.

***>> c2a_free_box <<***

****** Summary ******

#include <c2adefs.h>

void c2a_free_box ( box );

****** Description ******

This function frees a bounding box.

****** Input ******

------------------------------------------------------------------------------

| C2_BOX | box | the box to free |

------------------------------------------------------------------------------

****** Example ******

#include <c2vdefs.h>

#include <c2adefs.h>

void main()

{

PT2 p0, p1;

C2_BOX box0;

c2v_set ( 2.0, 3.0, p0 );

c2v_set ( 5.0, 6.0, p1 );

box0 = c2a_box ( p0, p1 );

c2a_free_box ( box0 );

}

This program creates and frees a bounding box.

***>> c2c_approx <<***

****** Summary ******

#include <c2cdefs.h>

BOOLEAN c2c_approx ( curve, parm1, marker_parm, gran, dir, pt_buffer,

parm_buffer, buf_size, index );

****** Description ******

This function computes the vertices of a polygon that approximates a curve.

The polygon does not deviate from the curve by more than a specified

distance.

If dir is TRUE, the polygon follows the curve away from its start point and

toward its end point; otherwise the polygon follows the curve in the

opposite direction.

The vertices of the polygon are stored in a caller-supplied array of points.

If the number of points required for an approximating polygon is greater

than the number that will fit into the array, this function fills the array,

marks the location of the last point with marker_parm, and returns FALSE to

indicate that the entire polygon was not computed. The next call to this

function begins the approximating polygon at the location specified by

marker_parm. Thus, if a polygon cannot be generated with one call, it can

be generated with a number of successive calls.

When a curve is approximated with a series of calls to this function, the

first point in a set of points is the last point of the previous set.

Prior to generating a polygon with this function, the argument marker_parm

should be initialized with the c2c_approx_init function.

This function optionally computes the curve parameters that correspond to

the vertices of the polygon.

This routines is very useful for applications such as graphics and motion

control, where curved shapes must be approximated with short lines.

****** Input ******

------------------------------------------------------------------------------

| C2_CURVE | curve | a curve |

------------------------------------------------------------------------------

| PARM | parm1 | ending parameter record; |

| | | points will not be computed |

| | | past this curve parameter; |

| | | if NULL is supplied, the |

| | | polygon will end at the |

| | | curve end point |

------------------------------------------------------------------------------

| PARM | marker_parm | the curve parameter at which |

| | | to begin the polygonal |

| | | approximation; when the |

| | | point and parameter arrays |

| | | are full, this parameter |

| | | record marks where the next |

| | | call to this function should |

| | | begin |

------------------------------------------------------------------------------

| REAL | gran | the maximum distance allowed |

| | | between the curve and any |

| | | chord of the polygonal |

| | | approximation |

------------------------------------------------------------------------------

| INT | buf_size | the size of the point and |

| | | parameter record arrays; |

| | | both arrays must be the |

| | | same size |

------------------------------------------------------------------------------

| BOOLEAN | dir | the direction that the |

| | | polygonal approximation |

| | | follows along the curve; |

| | | TRUE denotes along its |

| | | natural direction; FALSE |

| | | denotes against its natural |

| | | direction |

------------------------------------------------------------------------------

****** Output ******

------------------------------------------------------------------------------

| PT2 | *pt_buffer | an array of points supplied |

| | | by the caller; if NULL, no |

| | | points are computed |

------------------------------------------------------------------------------

| PARM | parm_buffer | an array of parameter |

| | | records supplied by the |

| | | caller; if NULL, no |

| | | parameters are computed |

------------------------------------------------------------------------------

| INT * | index | the number of points |

| | | actually computed; this |

| | | number is less than size if |

| | | the curve can be |

| | | approximated adequately with |

| | | fewer than size points |

------------------------------------------------------------------------------

****** Return Value ******

The return value is FALSE if there are more points to compute on the curve.

A return value of TRUE indicates that the polygonal approximation has

covered the entire curve, or it has reached the ending parameter, if

specified.

****** Example ******

#include <c2cdefs.h>

void polygonalize ( curve, acc, direction )

C2_CURVE curve ;

REAL acc ;

BOOLEAN direction ;

{

PT2 pt[10] ;

PARM_S parm ;

BOOLEAN end_flag ;

INT i0, i, index ;

c2c_approx_init ( curve, NULL, &parm, direction ) ;

i0 = 0 ;

do {

end_flag = c2c_approx ( curve, NULL, &parm,

acc, direction, pt, NULL, 10, &index ) ;

for ( i=i0 ; i<index ; i++ )

printf ( "%lf\t%lf\n", PT2_X(pt[i]),PT2_Y(pt[i]));

i0 = 1 ;

} while ( !end_flag ) ;

}

This routine generates the vertices of a polygon approximating a given curve

within a specified accuracy and in the specified direction. The vertices

are generated in groups of ten.

***>> c2c_approx_init <<***

****** Summary ******

#include <c2cdefs.h>

void c2c_approx_init ( curve, parm0, marker_parm, dir );

****** Description ******

This function initializes the process which creates a polygonal

approximation of a curve.

Use this function with c2c_approx.

****** Input ******

------------------------------------------------------------------------------

| C2_CURVE | curve | a curve |

------------------------------------------------------------------------------

| PARM | parm0 | the curve parameter at which |

| | | to begin the polygonal |

| | | approximation; if NULL, the |

| | | approximation begins at the |

| | | start or end point of the |

| | | curve, depending on dir |

------------------------------------------------------------------------------

| BOOLEAN | dir | the direction that the |

| | | polygonal approximation |

| | | should follow along the |

| | | curve; TRUE denotes with the |

| | | natural direction, and FALSE |

| | | denotes against |

------------------------------------------------------------------------------

****** Output ******

------------------------------------------------------------------------------

| PARM | marker_parm | the marker parameter |

| | | initialized to the curve |

| | | location where the |

| | | polygonal approximation |

| | | should begin |

------------------------------------------------------------------------------

****** Example ******

See c2c_approx

***>> c2c_arc_angle <<***

****** Summary ******

#include <c2cdefs.h>

BOOLEAN c2c_arc_angle ( curve, parm, angle ) ;

****** Description ******

This function computes the arc angle that corresponds to a specified curve

parameter. The angle is expressed relative to the start of the arc, and in

radians.

****** Input ******

------------------------------------------------------------------------------

| C2_CURVE | curve | an arc |

------------------------------------------------------------------------------

| PARM | parm | a curve parameter |

------------------------------------------------------------------------------

****** Output ******

------------------------------------------------------------------------------

| REAL * | angle | the angle in radians that |

| | | corresponds to the curve |

| | | parameter |

------------------------------------------------------------------------------

****** Return Value ******

The return value is TRUE if the input curve is an arc; it is FALSE

otherwise.

****** Example ******

#include <c2cdefs.h>

void pr_arc_angle ( arc, parm )

C2_CURVE arc ;

PARM parm ;

{

REAL angle;

if ( c2c_arc_angle ( arc, parm, &angle ) )

printf ( "angle: %lf\n", angle );

else printf ( "Curve is not an arc\n" ) ;

}

This subroutine prints the arc angle corresponding to a curve parameter.

***>> c2c_arc_parm <<***

****** Summary ******

#include <c2cdefs.h>

BOOLEAN c2c_arc_parm ( curve, angle, parm ) ;

****** Description ******

This function computes the curve parameter that corresponds to an arc angle.

The arc angle is measured relative to the start of the arc.

****** Input ******

------------------------------------------------------------------------------

| C2_CURVE | curve | an arc |

------------------------------------------------------------------------------

| REAL | angle | an arc angle expressed in |

| | | radians |

------------------------------------------------------------------------------

****** Output ******

------------------------------------------------------------------------------

| PARM | parm | the curve parameter that |

| | | corresponds to the angle |

------------------------------------------------------------------------------

****** Return Value ******

The return value is TRUE if the input curve is an arc; it is FALSE

otherwise.

****** Example ******

#include <c2cdefs.h>

void pr_arc_parm ( arc, angle )

C2_CURVE arc ;

REAL angle ;

{

PARM_S parm_s;

PARM parm = &parm_s;

if ( c2c_arc_parm ( arc, angle, parm ) )

printf ( "parameter: %lf\n", PARM_T(parm) );

else printf ( "Curve is not an arc\n" ) ;

}

This subroutine prints the curve parameter corresponding to an arc angle.

***>> c2c_closed <<***

****** Summary ******

#include <c2cdefs.h>