Functions | |
void | DSet_Complex_Clip_Region (int loops, const int *lengths, const HC_DPOINT *points, const char *options) |
Similar to Set_Complex_Clip_Region(), but takes double-precision precision points. More... | |
void | Set_Complex_Clip_Region (int loops, const int *lengths, const HC_POINT *points, const char *options) |
Defines a complex clip region in the segment tree. More... | |
Detailed Description
Function Documentation
◆ DSet_Complex_Clip_Region()
void DSet_Complex_Clip_Region | ( | int | loops, |
const int * | lengths, | ||
const HC_DPOINT * | points, | ||
const char * | options | ||
) |
Similar to Set_Complex_Clip_Region(), but takes double-precision precision points.
- Parameters
-
loops - Number of loops defined in the points array. This will be the size of the array lengths. lengths - An array of integers defining the number of points in each loop. The sum of the absolute values of these integers will be the size of the points array. points - The array of points used to define the clip region. options - A comma separated list of the desired settings.
◆ Set_Complex_Clip_Region()
void Set_Complex_Clip_Region | ( | int | loops, |
const int * | lengths, | ||
const HC_POINT * | points, | ||
const char * | options | ||
) |
Defines a complex clip region in the segment tree.
- Parameters
-
loops - Number of loops defined in the points array. This will be the size of the array lengths. lengths - An array of integers defining the number of points in each loop. The sum of the absolute values of these integers will be the size of the points array. points - The array of points used to define the clip region. options - A comma separated list of the desired settings.
DETAILS
This function allows you to define a complex clip region consisting of multiple loops on a segment.
A negative integer in the lengths array indicates that the array element is part of the clip region with the array element that precedes it. For example, in an array with the values [4, -5, 7, -6], the loop represented by the second element (-5) is part of the clip region that also includes the first element (4). When sequential values in the array change from negative to positive, the positive integer represents a new clip region, so in this case, the third element (7) represents a new clip region. Because the value of the fourth element is negative (-6), then that loop is part of the same clip region as the third element (7).
For multiple loops, an "even-odd" rule is applied. The interior region of a loop is filled if there are an odd number of edges between the interior of the loop and a point beyond the farthest edge in the plane. Otherwise, the number of edges is even, and the region is considered exterior and isn't drawn. The edges of the loop will receive the usual edge attributes. For face-numbering purposes, the loop is not counted separately – it's a part of the face it's in.
The options string allows you to specify whether the region is a clip region (in which case all the geometry "outside" the polygon will not be drawn) or a mask region (in which case all the geometry "inside" the polygon will not be drawn). Available choices for the options string are:
window | world | object
Specify the coordinate space. Valid options are either 'window', 'world', or 'object'. 'window' means that the coordinates specified in the points array are in window space; 'world' indicate the values specifed in the points array are in world space. If 'object' is specified, then the clip region will be transformed by the object modelling matrix.
type [= clip|mask]
If "type=clip", then everything in and below the currently opened segment which lies outside the defined polygon will not be drawn. If the "type=mask", then everything in and below the currently opened segment which lies inside the defined polygon will not be drawn.
If nothing is specified in the options string, then the region will be a clip region and the points will be assumed to be in window space.
NOTES
Where possible, display drivers make use of any hardware stencil buffers to accelerate this feature. Performance when using this feature is therefore greatly enhanced if the 'stencil' driver option is not turned off prior to the first update (it is on by default). Where not possible, some geometry may overstep the boundaries slightly. For example, text can often only be clipped away whole characters at a time.
Both concave and convex regions are supported.
RESTRICTIONS
- Clip regions inherit down the segment tree like other attributes. However, when you set a clip region on a segment which also inherits a different clip region from a parent, the clip space is limited to the overlap of the clip regions.