GpiSetArcParams
This function sets the current arc parameters.
Syntax
GpiSetArcParams(hps, parcpArcParams)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- parcpArcParams (PARCPARAMS) - input
- Arc parameters.
- This structure has four elements p, q, r, and s.
Return Value
- rc (BOOL) - returns
- Success indicator.
- TRUE
- Successful completion
- FALSE
- Error occurred.
Remarks
The arc parameters p, q, r, and s, define the shape and orientation of a ellipse that is used for subsequent GpiPointArc, GpiFullArc, and GpiPartialArc functions. For GpiFullArc and GpiPartialArc, they also determine the direction of drawing, as follows:
- If p*q > r*s the direction is counterclockwise
- If p*q < r*s the direction is clockwise
- If p*q = r*s a straight line is drawn.
For GpiFullArc and GpiPartialArc, these parameters also define the nominal size of the ellipse; this may be changed by using the multiplier.
For GpiPointArc, the size of the ellipse is determined by the three points specified on GpiPointArc. The arc parameters define a transformation that maps the unit circle to the required ellipse, placed at the origin (0,0): x' = p*x + r*y y' = s*x + q*y With reference to the figure above, if p*r + s*q = 0, the transform is termed orthogonal, and the line from the origin (0,0) to the point (p,s) is either the radius of the circle, or half the major axis of the ellipse. The line from the origin to the point (r,q) is either the radius of the circle, or half of the minor axis of the ellipse. For maximum accuracy, orthogonal transforms must be used. The matrix must not be singular. The initial default values of arc parameters (unless changed with GpiSetDefArcParams) are:
p = 1 r = 0 s = 0 q = 1
producing a unit circle. (See the figure below.). Arc parameter transformation takes place in world coordinates. Any other non-square transformations in force change the shape of the figure accordingly. The attribute mode (see GpiSetAttrMode) determines whether the current value of the arc parameters is preserved.
Errors
Possible returns from WinGetLastError:
- PMERR_INV_HPS (0x207F)
- An invalid presentation-space handle was specified.
- PMERR_PS_BUSY (0x20F4)
- An attempt was made to access the presentation space from more than one thread simultaneously.
- PMERR_INV_COORDINATE (0x205B)
- An invalid coordinate value was specified.
Graphic Elements and Orders
Element Type: OCODE_GSAP This element type is generated if the attribute mode (see GpiSetAttrMode) is set to AM_NOPRESERVE. Order: Set Arc Parameters
Element Type: OCODE_GPSAP This element type is generated if the attribute mode is set to AM_PRESERVE. Order: Set Arc Parameters
Example Code
#define INCL_GPIPRIMITIVES /* Or use INCL_GPI, INCL_PM, */ #include <os2.h> HPS hps; /* Presentation-space handle. */ PARCPARAMS parcpArcParams; /* Arc parameters. */ BOOL rc; /* Success indicator. */ rc = GpiSetArcParams(hps, parcpArcParams);
This example uses the GpiSetArcParams function to draw an ellipse. The semimajor axis of the ellipse is 100, and the semiminor axis is 50. These values are in world coordinates, computed using the lP and lQ values of the arc parameters and the multiplier provided with the GpiFullArc function.
#define INCL_GPIPRIMITIVES
#include <OS2.H>
HPS hps; /* Presentation-space handle. */
ARCPARAMS arcp = { 4, 2, 0, 0 }; /* Arc parameters. */
/* This structure has four */
/* elements p, q, r, and s. */
POINTL ptl = {100, 100};
GpiSetArcParams(hps, &arcp);
GpiMove(hps, &ptl);
GpiFullArc(hps, DRO_OUTLINE, MAKEFIXED(25, 0));