Chapter 19:
Translation Functions
 

/* Point arithmetic */

 

AbsPoint(); Absolute Point

 

AddPoints(); Add Points

 

ScalePoint(); Scale a Point

 

SubPoints(); Subtract Points

 

/* Device to Virtual translation */

 

dvCrust(); Device-to-Virtual Coordinates conversion of a CrustInfoRec

 

dvPoint(); Device-to-Virtual Coordinates conversion of a Point

 

dvPoint2D(); Device-to-Virtual Coordinates conversion of a Point2D

 

dvPoly(); Device-to-Virtual Coordinates conversion of a Poly

 

dvRect(); Device-to-Virtual Coordinates conversion of a Rect

 

dvScaleHeight(); Device-to-Virtual Coordinates conversion of Scale Height

 

dvScalePoint(); Device-to-Virtual Coordinates conversion of Scale Point

 

dvScalePoint2D(); Device-to-Virtual Coordinates conversion of Scale Point 2D

 

dvScaleWidth(); Device-to-Virtual Coordinates conversion of Scale Width

 

dvSlice(); Device-to-Virtual Coordinates conversion of a SliceInfoRec

 

dvWedge(); Device-to-Virtual Coordinates conversion of a WedgeInfoRec

 

/* Virtual to Device translation */

 

vdCrust(); Virtual-to-Device Coordinates conversion of a CrustInfoRec

 

vdPoint(); Virtual-to-Device Coordinates conversion of a Point

 

vdPoint2D(); Virtual-to-Device Coordinates conversion of a Point2D

 

vdPoly(); Virtual-to-Device Coordinates conversion of a Poly

 

vdRect(); Virtual-to-Device Coordinates conversion of a Rect

 

vdScaleHeight(); Virtual-to-Device Coordinates conversion of Scale Height

 

vdScalePoint(); Virtual-to-Device Coordinates conversion of Scale Point

 

vdScalePoint2D(); Virtual-to-Device Coordinates conversion of Scale Point2D

 

vdScaleWidth(); Virtual-to-Device Coordinates conversion of Scale Width

 

vdSlice(); Virtual-to-Device Coordinates conversion of a SliceInfoRec

 

vdWedge(); Virtual-to-Device Coordinates conversion of a WedgeInfoRec

 

/* Virtual / Physical translation */

 

pvScaleHeight(); Physical -to- Virtual Scale Height Conversion

 

pvScaleWidth(); Physical -to- Virtual Scale Width Conversion

 

vpScaleHeight; Virtual -to- Physical Scale Height Conversion

 

vpScaleWidth ; Virtual -to- Physical Scale Width Conversion

 

/* Device routines */

 

dCheckRect(); Verify the top, bottom, left and right parameters of a rectangle

 

dSetRect(); Define a Rectangle

 

/* Virtual routines */

 

vCheckRect(); Verify rectangle definition is consistent with coordinate system

 

vSetRect(); Set rectangle definition that is consistent with coordinate system

 

/* Utility routines */

 

xNormalizeDegrees(); Translate Normalize Degrees

 

xNormalizeRadians(); Translate Normalize Radians

 

xPt2Degrees(); Translate Point -to- Degrees

 

xPt2Radians(); Translate Point -to- Radians

 

/* Detection Routines */

 

xPtInEllipse(); Translate Point In Ellipse

 

xPtInPoly(); Translate Point In Polygon

 

xPtInRect(); Translate Point in Rectangle

 

xPtInSlice(); Determine if a point is in a slice

 

xPtInWedge(); Determine if a point is in a wedge

 

/* Rectangle Manipulation. */

 

xCompareRects(); Translate compare rectangles

 

xDefineRect(); Translate define rectangle

 

xHeightOfRect(); Translate Height of Rectangle

 

xInsetRect(); Translate Inset Rectangle

 

xIntersectRect(); Translate Intersect Rectangle

 

xOffsetRect(); Translate Offset Rectangle

 

xSumOfRects(); Translate Sum of Rectangles

 

xWidthOfRect(); Translate Width of Rectangle

 

/* Type conversion routines. */

 

xBoxToRect(); Translate BoxInstRec to Rect

 

xPoint2DToPoint(); Translate Point2D -to- Point

 

xPointToPoint2D(); Translate Point -to- Point2D

 

xRectToBox(); Translate Rectangle -to- BoxInstRec

AbsPoint()

 

This function gets the absolute value of a point and stores it in the location identified by p.

Syntax:

void PUBLIC
AbsPoint (
     Point FAR *p
);

Input:

p: Pointer to a place to store the absolute value

Return:

None

Example:

{
     //Size of virtual coordinate system
     Point vRectSize;
     //Size of device coordinate system
     Point dRectSize;
     SubPoints(&vRectSize,
          &botRight(pDE->virtRect),
          &topLeft(pDE->virtRect));
     SubPoints(&dRectSize,
          &botRight(pDE->destRect),
          &topLeft(pDE->destRect));
     AbsPoint(&vRectSize);
     AbsPoint(&dRectSize);
     ScalePoint(p, &vRectSize, &dRectSize);
}

Also See:

AddPoints(), SubPoints(), dvPoint(), ScalePoint(), vdPoint()

   

AddPoints()

 

This function sets sum to the sum of the two points specified by the input parameters p1 and p2. The input parameter sum is a pointer to the location to store the sum of p1 and p2.

Syntax:

void PUBLIC
AddPoints (
     Point FAR *sum,
     Point FAR *p1,
     Point FAR *p2
);

Input:

sum: Place to store the sum of p1 and p2.

 

p1 and p2: Two points to be summed

Return:

None

Also See:

SubPoints()

dCheckRect()

 

This function verifies that the top, bottom, left and right parameters of the rectangle (r) are defined to be consistent with the coordinate system's axes' directions. If they are not consistent, the offending sides of the rectangle, top/bottom or left/right, are exchanged.

Syntax:

void PUBLIC
dCheckRect (
     DrawEnvPtr pDE,
     Rect FAR *r
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

r: Rectangle to check

Return:

None

Also See:

dSetRect()

   

dSetRect()

 

This function defines a rectangle. It insures that the top (top) and bottom (bottom) values are consistent with the coordinate system.

Syntax:

void PUBLIC
dSetRect (
     DrawEnvPtr pDE,
     Rect FAR *pRect,
     INT16 left,
     INT16 top,
     INT16 right,
     INT16 bottom
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pRect: Pointer to a rectangle data structure. See the Rect structure in Appendix A.

 

left: X-coordinate of rectangle's left side

 

top: Y-coordinate of rectangle's top

 

right: X-coordinate of rectangle's right side

 

bottom: Y-coordinate of rectangle's bottom

Return:

None

Also See:

dCheckRect()

dvCrust()

 

This function scales a graphics primitive of type CrustInfoRec from device to virtual coodrindate. Use vdCrust() to scale a CrustInfoRec from virtual to device coordinates.

Syntax:

void PUBLIC
dvCrust (
     DrawEnvPtr pDE,
     CrustInfoPtr pCrust
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pCrust: Pointer to a CrustInfoRec data structure

Return:

None

Also See:

vdCrust()

   

dvPoint()

 

This function scales a graphics primitive of type Point from device to virtual coordinates. Use vdPoint() to scale a point from virtual to device coordinates.

Syntax:

void PUBLIC
dvPoint (
     DrawEnvPtr pDE,
     Point FAR *p
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

p: Pointer to a point data structure

Return:

None

Notes:

This function is typically used to convert a mouse pointer location (in device coordinates) to virtual coordinates as shown in the following example.

Example:

POINT pt;
//Get mouse pointer
pt = MAKEPOINT (lParam);
//Convert to virtual coordinates
dvPoint(gpDrawEnv,&pt);

Also See:

vdPoint()

 

dvPoint2D()

 

This function maps a point2D from device to virtual coordinates. Use vdPoint2D() to map a point from virtual to device coordinates.

Syntax:

void PUBLIC
dvPoint2D (
     DrawEnvPtr pDE,
     Point2D FAR *p
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

p: Pointer to a Point2D data structure

Return:

None

Also See:

vdPoint2D()

   

dvPoly()

 

This function scales a graphics primitive of type Poly from device to virtual coordinates. Use vdPoly() to scale this type of graphics primitive from virtual to device coordinates.

Syntax:

void PUBLIC
dvPoly (
     DrawEnvPtr pDE,
     _PolyHandle hPoly
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

hPoly: A polygon handle

Return:

None

Also See:

vdPoly()

   

dvRect()

 

This function scales a graphics primitive of type Rect from device to virtual coordinates. Use vdRect() to scale a graphics primitive of this type from virtual to device coordinates.

Syntax:

void PUBLIC
dvRect (
     DrawEnvPtr pDE,
     Rect FAR *pRect
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pRect: Pointer to a rectangle data structure. See the Rect data structure in Appendix A.

Return:

None

Example:

// Make sure top is less than bottom
Rect FAR * r2if (r2.top > r2.bottom)
{
     i = r2.top;
     r2.top = r2.bottom
     r2.bottom = i;
}
aRect = r2
// Convert to virtual coordinates
dvRect(gpDrawEnv, &aRect);

Also See:

vdRect()

   

dvScaleHeight()

 

This function maps height (i.e. Y-component) from destination to virtual coordinates. Use vdScaleHeight() to map a height from virtual to destination coordinates.

Syntax:

INT16 PUBLIC
dvScaleHeight (
     DrawEnvPtr pDE,
     INT16 height
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

height: INT16 value identifying the height to be mapped

Return:

INT16 value of virtual coordinates

Also See:

vdScaleWidth()

dvScalePoint()

 

This function scales a graphics primitive of type Point from device to virtual coordinates. Use vdScalePoint() to scale a point from virtual to device coordinates.

Syntax:

void PUBLIC
dvScalePoint (
     DrawEnvPtr pDE,
     Point FAR *p
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

p: Pointer to a Point data structure

Return:

None

Example:

PointX(&vActualSize) = dActualSize[0]+2;
PointY(&vActualSize) = dActualSize[1]+1;
dvScalePoint (pDE, &vActualSize);

Notes:

This routine ignores the absolute values of the coordinate system's origins.

Also See:

vdScaleWidth, vdScalePoint()

   

dvScalePoint2D()

 

This function scales a point2D from device to virtual coordinate sizes. Use vdScalePoint2D() to scale a point2D from virtual to device coordinates.

Syntax:

void PUBLIC
dvScalePoint2D (
     DrawEnvPtr pDE,
     Point2D FAR *p
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

p: Pointer to a Point2D data structure

Return:

None

Notes:

This routine ignores the absolute values of the coordinate system's origins

Also See:

dvScalePoint, vdScalePoint2D

   

dvScaleWidth()

 

This function scales an integer value from destination to virtual width. Use vdScaleWidth() to scale a value from virtual to destination width.

Syntax:

INT16 PUBLIC
dvScaleWidth (
     DrawEnvPtr pDE,
     INT16 width
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

width: INT16 value identifying the width to be scaled

Return:

INT16 value of scaled width

Example:

// Calculate virtual height
// and width of picture
width=dvScaleWidth ( pDE,
     abs ( rPic.right - rPic.left ) );
height=dvScaleHeight (pDE,
     abs ( rPic.bottom - rPic.top ) );

Also See:

dvScaleHeight(), vdScaleWidth()

   

dvSlice()

 

This function scales a graphics primitive of type SliceInfoRec from device to virtual coodrindate. Use vdSlice() to scale a SliceInfoRec from virtual to device coordinates.

Syntax:

void PUBLIC
dvSlice (
     DrawEnvPtr pDE,
     SliceInfoPtr pSlice
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pSlice: Pointer to a SliceInfoRec data structure

Return:

None

Also See:

vdSlice()

   

dvWedge()

 

This function scales a graphics primitive of type WedgeInfoRec from device to virtual coodrindate. Use vdWedge() to scale a WedgeInfoRec from virtual to device coordinates.

Syntax:

void PUBLIC
dvWedge (
     DrawEnvPtr pDE,
     WedgeInfoPtr pWedge
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pWedge: Pointer to a WedgeInfoRec data structure

Return:

None

Also See:

vdWedge()

   

pvScaleHeight()

 

This function maps height (i.e. Y-component) from physical to virtual coordinates. Physical coordinates are in 1/1000-inch increments. The returned virtual coordinates will be pinned to the MAX and MIN values for virtual coordinates. Use vpScaleHeight() to map a height value from virtual to physical coordinates.

Syntax:

INT16 PUBLIC
pvScaleHeight (
     DrawEnvPtr pDE,
     INT16 height
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

height: Height value in physical coordinates

Return:

INT16: Height in virtual coordinates

Also See:

pvScaleWidth(), vpScaleHeight()

pvScaleWidth()

 

This function maps width (i.e. X-component) from physical to virtual coordinates. Physical coordinates are in 1/1000-inch increments. The returned virtual coordinates will be pinned to the MAX and MIN values for virtual coordinates. Use vpScaleWidth() to map a width value from virtual to physical coordinates.

Syntax:

INT16 PUBLIC
pvScaleWidth (
     DrawEnvPtr pDE,
     INT16 width
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

width: Width value in physical coordinates

Return:

INT16: Width in virtual coordinates

Also See:

pvScaleHeight(), vpScaleWidth()

   

ScalePoint()

 

This function scales a point by a fraction expressed as two integers. When the charting engine maps a point from one coordinate system to another, it must multiply it by a fraction, the multiplier of which is the mul parameter, the divisor the div parameter.

Syntax:

void PUBLIC
ScalePoint (
     Point FAR *p,
     Point FAR *mul,
     Point FAR *div
);

Input:

p: Place to store the scaled point

 

mul: Multiplier

 

div: Divisor

Return:

None

Also See:

dvScalePoint(), vdScalePoint()

   

SubPoints()

 

This function returns the difference between the two points specified by the input parameters p1 and p2. The input parameter dif is a pointer to the location to store the difference between p1 and p2.

Syntax:

void PUBLIC
SubPoints (
     Point FAR *dif,
     Point FAR *p1,
     Point FAR *p2
);

Input:

dif: Place to store the difference of p1 and p2.

 

p1 and p2: Two points to be compared

Return:

None

Also See:

AddPoints()

   

vCheckRect()

 

This function verifies that the top, bottom, left and right parameters of the rectangle are defined to be consistent with the coordinate system's axes directions. If not, the offending sides of the rectangle, top/bottom or left/right, are exchanged.

Syntax:

void PUBLIC
vCheckRect (
     DrawEnvPtr pDE,
     Rect FAR *r     
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

r: Pointer to a rectangle (Rect) data structure

Return:

None

Example:

/* Pointer to rectangle */
Rect FAR * pRect,
pRect->left = left;
pRect->right = right;
pRect->top = top;
pRect->bottom = bottom;
vCheckRect(pDE, pRect);

Also See:

dCheckRect()

   

vdCrust()

 

This function scales a graphics primitive of type CrustInfoRec from virtual to device coodrindate. Use dvCrust() to scale a CrustInfoRec from device to virtual coordinates.

Syntax:

void PUBLIC
vdCrust (
     DrawEnvPtr pDE,
     CrustInfoPtr pCrust
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pCrust: Pointer to a CrustInfoRec data structure

Return:

None

Also See:

dvCrust()

   

vdPoint()

 

This function scales a graphics primitive of type Point from device to virtual coordinates. It will function properly regardless of negative or positive offsets of either coordinate system and regardless of the directions of the axes. Use dvPoint() to scale a Point from virtual to device coordinates().

Syntax:

void PUBLIC
vdPoint (
     DrawEnvPtr pDE,
     Point FAR *p
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

p: A pointer to a point in virtual coordinates

Return:

None

Example:

/* Pointer to draw environment */
DrawEnvPtr pDE,
/* Ptr to wedge. */
WedgeInfoPtr pWedge
vdRect(pDE, &pWedge->bounds);
vdPoint(pDE, &pWedge->ptStart);
vdPoint(pDE, &pWedge->ptEnd);

Also See:

dvPoint()

vdPoint2D()

 

This function maps a point2D from virtual to device coordinates. Use dvPoint2D() to map a point2D from device to virtual coordinates.

Syntax:

void PUBLIC
vdPoint2D (
     DrawEnvPtr pDE,
     Point2D FAR *p
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

p: Pointer to a Point2D data structure

Return:

None

Example:

for (i=0; i<nPoints; i++)
{
     ip[i][xx] = (INT16) p[i][xx];
     ip[i][yy] = (INT16) p[i][yy];
     iq[i][xx] = (INT16) q[i][xx];
     iq[i][yy] = (INT16) q[i][yy];
     ir[i][xx] = (INT16) r[i][xx];
     ir[i][yy] = (INT16) r[i][yy];
     is[i][xx] = (INT16) s[i][xx];
     is[i][yy] = (INT16) s[i][yy];
     vdPoint2D(pDE, (Point2D FAR *) &ip[i][xx]);
     vdPoint2D(pDE, (Point2D FAR *) &iq[i][xx]);
     vdPoint2D(pDE, (Point2D FAR *) &ir[i][xx]);
     vdPoint2D(pDE, (Point2D FAR *) &is[i][xx]);
}

Also See:

dvPoint2D()

vdPoly()

 

This function scales a graphics primitive of type Poly from virtual to device coordinates. Use dvPoly() to scale a graphics primitive of this type from device to virtual coordinates.

Syntax:

void PUBLIC
vdPoly (
     DrawEnvPtr pDE,
     _PolyHandle hPoly
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

hPoly: A polygon handle

Return:

None

Also See:

dvPoly()

vdRect()

 

This function scales a graphics primitive of type Rect from virtual to device coordinates. Use dvRect() to scale a rectangle from device to virtual coordinates.

Syntax:

void PUBLIC
vdRect (
     DrawEnvPtr pDE,
     Rect FAR *r
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

r: Pointer to a rectangle (Rect) data structure

Return:

None

Example:

Rect r3;
vdRect(gpDrawEnv, &r3);

Also See:

dvRect()

   

vdScaleHeight()

 

This function maps height (Y-component) from virtual to destination coordinates. Use dvScaleHeight() to map a height value from destination to virtual coordinates.

Syntax:

INT16 PUBLIC
vdScaleHeight (
     DrawEnvPtr pDE,
     INT16 height
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

height: INT16 value specifying the height to be converted

Return:

INT16 value of destination coordinates

Example:

INT16 vFontSize;
dFontSize = vdScaleHeight (gpDrawEnv, vFontSize);

Also See:

dvScaleHeight()

vdScalePoint()

 

This function scales a graphics primitive of type Point from virtual to device coordinates. Use dvScalePoint () to scale a point from device to virtual coordinates.

Syntax:

void PUBLIC
vdScalePoint (
     DrawEnvPtr pDE,
     Point FAR *p
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

p: Pointer to a Point data structure

Return:

None

Example:

/* Translate size into device coordinates since the */
/* available space is expressed in screen */
/* coordinates. */
PointX(&aPoint) = SpaceAvail[0];
PointY(&aPoint) = SpaceAvail[1];
vdScalePoint (pDE, &aPoint);

Notes:

This routine ignores the absolute values of the coordinate system's origins.

Also See:

dvScalePoint()

   

vdScalePoint2D()

 

This function scales a point2D from virtual to device coordinate sizes. Use dvScalePoint2D() to map a point2D from device to virtual coordinates.

Syntax:

void PUBLIC
vdScalePoint2D (
     DrawEnvPtr pDE,
     Point2D FAR *p
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

p: Pointer to a Point2D data structure

Return:

None

Notes:

This function ignores the absolute values of the coordinate system's origins.

Also See:

dvScalePoint2D()

vdScaleWidth()

 

This function scales the integer width based on ratio of virtual to destination width. Use dvScaleWidth() to map a width value from destination to virtual coordinates.

Syntax:

INT16 PUBLIC
vdScaleWidth (
     DrawEnvPtr pDE,
     INT16 width
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

width: INT16 value to be scaled

Return:

INT16 value of scaled width

Example:

nWidth=Max(vdScaleWidth(pDE,pLine->nThick),1);

Also See:

dvScaleWidth()

   

vdSlice()

 

This function scales a graphics primitive of type SliceInfoRec from virtual to device coodrindate. Use dvSlice() to scale a SliceInfoRec from device to virtual coordinates.

Syntax:

void PUBLIC
vdSlice (
     DrawEnvPtr pDE,
     SliceInfoPtr pSlice
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pSlice: Pointer to a SliceInfoRec data structure

Return:

None

Also See:

dvSlice()

   

vdWedge()

 

This function scales a graphics primitive of type WedgeInfoRec from virtual to device coodrindate. Use dvWedge() to scale a WedgeInfoRec from device to virtual coordinates.

Syntax:

void PUBLIC
vdWedge (
     DrawEnvPtr pDE,
     WedgeInfoPtr pWedge
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pWedge: Pointer to a WedgeInfoRec data structure

Return:

None

Also See:

dvWedge()

   

vpScaleHeight()

 

This function maps height (i.e. Y-component) from virtual to physical coordinates. Physical coordinates are in 1/1000 inch. Use pvScaleHeight() to map a height value from physical to virtual coordinates.

Syntax:

INT16 PUBLIC
vpScaleHeight (
     DrawEnvPtr pDE,
     INT16 height
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

height: Height value in virtual coordinates

Return:

INT16: Height in physical coordinates

Also See:

pvScaleHeight()

vpScaleWidth()

 

This function map width from virtual to physical coordinates. Physical coordinates are in 1/1000 inch. Use pvScaleWidth() to map a width value from physical to virtual coordinates.

Syntax:

INT16 PUBLIC
vpScaleWidth (
     DrawEnvPtr pDE,
     INT16 width
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

height: Height value in virtual coordinates

Return:

INT16: Height in physical coordinates

Also See:

pvScaleWidth()

   

vSetRect()

 

This function defines a rectangle making sure that the top and bottom values are consistent with the coordinate systems.

Syntax:

void PUBLIC
vSetRect (
     DrawEnvPtr pDE,
     Rect FAR *pRect,
     INT16 left,
     INT16 top,
     INT16 right,
     INT16 bottom
);

Input:

pDE: Pointer to a draw environment created by AllocDrawEnvPtr()

 

pRect: Pointer to rectangle to be defined. See the Rect data structure in Appendix A.

 

left: x-coordinate of rectangle's left side

 

top: y-coordinate of rectangle's top

 

right:: x-coordinate of rectangle's right side

 

bottom: y-coordinate of rectangle's bottom

Return:

None

Also See:

dSetRect()

xBoxToRect()

 

This function translates the box identified by pBox to rectangle type.

Syntax:

void PUBLIC
xBoxToRect (
     Rect *pRect,
     BoxInstPtr pBox
);

Input:

pRect: Pointer to a rectangle data structure. See the Rect structure in Appendix A.

 

pBox: Pointer to a box data structure. See the BoxInstRec in Appendix A.

Return:

None

Example:

xBoxToRect(&ThisRect,pBox);
InsetRect = ThisRect;

Also See:

xCompareRects(), xDefineRect()

   

xCompareRects()

 

The function compares two rectangles (r1 and r2) and returns a BOOLEAN16 indicating whether or not the two rectangle data structures are the same.

Syntax:

BOOLEAN16 PUBLIC
xCompareRects (
     Rect FAR *r1,
     Rect FAR *r2
);

Input:

r1: Rectangle to be intersected. See the Rect structure in Appendix A.

 

r2: Rectangle to intersect against. See the Rect structure in Appendix A.

Return:

BOOLEAN16: TRUE/FALSE

 

TRUE=

r1 and r2 are the same

 

FALSE=

r1 and r2 are different

Also See:

xDefineRect()

xDefineRect()

 

The function defines a rectangle using the four points specified by left, top, right, and bottom.

Syntax:

void
xDefineRect (
     Rect FAR *r,
     INT16 left,
     INT16 top,
     INT16 right,
     INT16 bottom
);

Input:

r: Pointer to rectangle to be defined. See the Rect structure in Appendix A.

 

left: Left edge of rectangle

 

top: Top edge of rectangle

 

right: Right edge of rectangle

 

bottom: Bottom edge of rectangle

Return:

None

Also See:

xCompareRects()

   

xHeightOfRect()

 

This function calculates the height of a rectangle.

Syntax:

INT16 PUBLIC
xHeightOfRect (
     Rect FAR *r
);

Input:

r: Rectangle. See the Rect structure in Appendix A.

Return:

INT16: Height of rectangle

Example:

PointX(&RAY->SourceSize) =
     xWidthOfRect (&RAY->SourceRect);
PointY(&RAY->SourceSize) =
     xHeightOfRect(&RAY->SourceRect);

Also See:

xWidthOfRect()

xInsetRect()

 

This function shrinks the rectangle (r) horizontally by x and vertically by y.

Syntax:

void PUBLIC
xInsetRect (
     Rect FAR *r
     INT16 x,
     INT16 y
);

Input:

r: Rectangle to be clipped. See the Rect structure in Appendix A.

 

x: Horizontal inset

 

y: Vertical inset

Return:

None

Example:

xBoxToRect(&ThisRect,pBox);
InsetRect = ThisRect;
xInsetRect(&InsetRect,
     dvScaleWidth(pDE, FRAME_INSET),
     dvScaleHeight(pDE, FRAME_INSET));

Also See:

xBoxToRect(), xCompareRects(), xDefineRect(), xIntersectRect()

   

xIntersectRect()

 

The function calculates the intersection of two rectangles (r and cr).

Syntax:

void PUBLIC
xIntersectRect (
     Rect FAR *r,
     Rect FAR *cr
);

Input:

r: Rectangle to be intersected. See the Rect structure in Appendix A.

 

cr: Rectangle to intersect against. See the Rect structure in Appendix A.

Return:

None

Example:

xBoxToRect(&LastRect,pLastLabelBox);
xBoxToRect(&ThisRect,&LBox);
xIntersectRect(&ThisRect,&LastRect);

Also See:

xBoxToRect()

   

xNormalizeDegrees()

 

The function ensures that a given angle resides between zero and 360.

Syntax:

REAL PUBLIC
xNormalizeDegrees (
     REAL rAngle
);

Input:

rAngle: Angle to normalize

Return:

REAL: Normalized angle

Also See:

xNormalizeRadians()

   

xNormalizeRadians()

 

The function ensures that a given angle resides between 0 and 2 * PI.

Syntax:

REAL PUBLIC
xNormalizeRadians (
     REAL rAngle
);

Input:

rAngle: Angle to normalize

Return:

REAL: Normalized angle

Also See:

xNormalizeDegrees()

   

xOffsetRect()

 

This function shifts a rectangle (r) horizontally by x and vertically by y.

Syntax:

void PUBLIC
xOffsetRect (
     Rect FAR *r
     INT16 x,
     INT16 y
);

Input:

r: Rectangle to be offset. See the Rect structure in Appendix A.

 

x: Horizontal offset

 

y: Vertical offset

Return:

None

   

xPoint2DToPoint()

 

This function translates the point (np2D) from Three |D| Graphics' generic Point2D type to platform-dependent Point type.

Syntax:

void PUBLIC
xPoint2DToPoint (
     Point *p
     Point2D *np2D
);

Input:

p: Place to store translated point

 

np2D: Point to be translated. See the Point2D structure in Appendix A.

Return:

None

Example:

{
     Point aPoint;
     xPoint2DToPoint (&aPoint, p);
     dvScalePoint (pDE, &aPoint);
     xPointToPoint2D (p, &aPoint);
}

Also See:

xPointToPoint2D()

   

xPointToPoint2D()

 

This function translates the platform-dependent Point (p) type to Three |D| Graphic's generic Point2D type.

Syntax:

void PUBLIC
xPointToPoint2D (
     Point2D *np2D
     Point *p
);

Input:

np2D: Place to store translated point. See the Point2D structure in Appendix A.

 

p: Point to be translated

Return:

None

Example:

{
     Point aPoint;
     xPoint2DToPoint (&aPoint, p);
     dvScalePoint (pDE, &aPoint);
     xPointToPoint2D (p, &aPoint);
}

Also See:

xPoint2DToPoint()

xPt2Degrees()

 

This function calculates an integer angle between a line from the center of the rectangle (pRect) to the given point (p) and a line from the center of the rectangle pointing to 3 o'clock (0 degrees). The angle is in degrees from 0 to 359, measured counter-clockwise from 3 o'clock, with 90 degrees at 12 o'clock, 180 degrees at 9 o'clock, and 270 degrees at 6 o'clock. Other angles are measured relative to the rectangle: if the line to the given point goes through the top right corner of the rectangle, the angle returned is 45 degrees, even if the rectangle isn't square; if it goes through the top left corner the angle is 135 degrees, and so on.

Syntax:

REAL PUBLIC
xPt2Degrees (
     Point FAR *p
     Rect FAR *pRect
);

Input:

p: Point in the rectangle

 

pRect: Rectangle. See the Rect structure in Appendix A.

Return:

REAL: The calculated angle (0 >= angle < 360).

Also See:

xPt2Radians()

   

xPt2Radians()

 

This function calculates an integer angle between a line from the center of the rectangle (pRect) to the given point (p).

Syntax:

REAL PUBLIC
xPt2Radians (
     Point FAR *p
     Rect FAR *pRect
);

Input:

p: Point in the rectangle

 

pRect: Rectangle. See the Rect structure in Appendix A.

Return:

REAL: The calculated angle in radians (0 >= angle < 2 * pi)

Example:

/*calc angle relative to center of target rect.*/
fTargetAngle = xPt2Radians(pMouse, pEllipseRect);
/*ensure all angles are normalized between (0...720)*/
if (fTargetAngle < fStartAngle)fTargetAngle += TWOPI;

Also See:

xPt2Degrees()

xPtInEllipse()

 

This function returns true if the point, p, is inside the ellipse bounded by *pRect.

Syntax:

BOOLEAN16 PUBLIC
xPtInEllipse (
     Point FAR *p
     Rect FAR *pRect
);

Input:

p: Point to be tested

 

pRect: Pointer to ellipse's bounding rectangle. See the Rect structure in Appendix A.

Return:

BOOLEAN16; TRUE / FALSE

 

TRUE=

Point is within pRect

 

FALSE=

Point is not in pRect

Example:

foundIt = xPtInEllipse(
     pMouser, &pCrust->bounds);

Also See:

xPtInPoly(), xPtInRect()

   

xPtInPoly()

 

This function returns true if the point, p, is inside the polygon (hPoly).

Syntax:

BOOLEAN16 PUBLIC
xPtInPoly (
     Point FAR *p
     _PolyHandle hPoly
);

Input:

p: Point to be tested

 

hPoly: Pointer to Mac-style poly

Return:

BOOLEAN16; TRUE / FALSE

 

TRUE=

Point is within hPoly

 

FALSE=

Point is not in hPoly

Example:

foundIt = xPtInPoly(pMouser,
     pNode->info.line.hPoly);

Also See:

xPtInEllipse(), xPtInRect()

   

xPtInRect()

 

This function returns true if the point, p, is inside the rectangle *pRect. This routine works even if the top of the rectangle is numerically higher than the bottom (which is not true for the Mac's coordinate system, for example).

Syntax:

BOOLEAN16 PUBLIC
xPtInRect (
     Point FAR *p
     Rect FAR *pRect
);

Input:

p: Point to be tested

 

pRect: Pointer to rectangle for containment test. See the Rect structure in Appendix A.

Return:

BOOLEAN16; TRUE / FALSE

 

TRUE=

Point is within pRect

 

FALSE=

Point is not in pRect

Example:

foundIt = xPtInRect(
     pMouser, &pNode->detBounds);

Also See:

xPtInEllipse(), xPtInPoly()

   

xPtInSlice()

 

This function returns TRUE/FALSE identifying whether or not the point (p) is in the slice identified by (pSlice).

Syntax:

BOOLEAN16 PUBLIC
xPtInSlice (
     Point FAR *p,
     SliceInfoPtr pSlice
);

Input:

p: Point to be tested

 

pSlice: Pointer to SliceInfoRect data structure.

Return:

BOOLEAN16; TRUE / FALSE

 

TRUE=

Point is in pSlice

 

FALSE=

Point is not in pSlice

Also See:

xPtInWedge()

   

xPtInWedge()

 

This function returns TRUE/FALSE identifying whether or not the point (p) is in the area identified by (pWedge).

Syntax:

BOOLEAN16 PUBLIC
xPtInWedge (
     Point FAR *p,
     WedgeInfoPtr pWedge
);

Input:

p: Point to be tested

 

pWedge: Pointer to SliceInfoRect data structure.

Return:

BOOLEAN16; TRUE / FALSE

 

TRUE=

Point is in pWedge

 

FALSE=

Point is not in pWedge

Also See:

xPtInSlice()

   

xRectToBox()

 

This function translates the rectangle at pRect to a box and stores the information in the BoxInstRec identified by pBox.

Syntax:

void PUBLIC
xRectToBox (
     BoxInstPtr pBox
     Rect *pRect
);

Input:

pBox: Place to stored translated rectangle. See the BoxInstRec in Appendix A.

 

pRect: Rectangle to be translated. See the Rect structure in Appendix A.

Return:

None

Example:

xRectToBox (&TempBox, &InsetRect);
nError = DrawRect(pDE,
          pArea,
          pLine,
          TempBox.xULC, TempBox.yULC,
          TempBox.xLRC, TempBox.yLRC,
          IGNORE_ME,
          -3, -3,
          NULL, 0);

Also See:

xBoxToRect()

   

xSumOfRects()

 

This function calculates the bounds that contains two rectangles.

Syntax:

Rect PUBLIC
xSumOfRects (
     Rect FAR *r1
     Rect FAR *r2
);

Input:

r1: Rectangle one. See the Rect structure in Appendix A.

 

r2: Rectangle two. See the Rect structure in Appendix A.

Return:

Rect: Sum of r1 and r2. See the Rect structure in Appendix A.

Also See:

xWidthOfRect(), xHeightOfRect()

xWidthOfRect()

 

This function calculates the width of a rectangle.

Syntax:

INT16 PUBLIC
xWidthOfRect (
     Rect FAR *r
);

Input:

r: Rectangle. See the Rect structure in Appendix A.

Return:

INT16: Width of rectangle

Example:

PointX(&RAY->SourceSize) =
     xWidthOfRect (&RAY->SourceRect);
PointY(&RAY->SourceSize) =
     xHeightOfRect(&RAY->SourceRect);

Also See:

xHeightOfRect()