Nano-X API Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# regions

## Name

regions —

## Synopsis

    GR_REGION_ID GrNewRegion                    (void);
    void        GrDestroyRegion                 (GR_REGION_ID region);
    void        GrUnionRectWithRegion           (GR_REGION_ID region,
                                                 GR_RECT *rect);
    void        GrUnionRegion                   (GR_REGION_ID dst_rgn,
                                                 GR_REGION_ID src_rgn1,
                                                 GR_REGION_ID src_rgn2);
    void        GrSubtractRegion                (GR_REGION_ID dst_rgn,
                                                 GR_REGION_ID src_rgn1,
                                                 GR_REGION_ID src_rgn2);
    void        GrXorRegion                     (GR_REGION_ID dst_rgn,
                                                 GR_REGION_ID src_rgn1,
                                                 GR_REGION_ID src_rgn2);
    void        GrIntersectRegion               (GR_REGION_ID dst_rgn,
                                                 GR_REGION_ID src_rgn1,
                                                 GR_REGION_ID src_rgn2);
    void        GrSetGCRegion                   (GR_GC_ID gc,
                                                 GR_REGION_ID region);
    GR_BOOL     GrPointInRegion                 (GR_REGION_ID region,
                                                 GR_COORD x,
                                                 GR_COORD y);
    int         GrRectInRegion                  (GR_REGION_ID region,
                                                 GR_COORD x,
                                                 GR_COORD y,
                                                 GR_COORD w,
                                                 GR_COORD h);
    GR_BOOL     GrEmptyRegion                   (GR_REGION_ID region);
    GR_BOOL     GrEqualRegion                   (GR_REGION_ID rgn1,
                                                 GR_REGION_ID rgn2);
    void        GrOffsetRegion                  (GR_REGION_ID region,
                                                 GR_SIZE dx,
                                                 GR_SIZE dy);
    int         GrGetRegionBox                  (GR_REGION_ID region,
                                                 GR_RECT *rect);
    GR_REGION_ID GrNewPolygonRegion             (int mode,
                                                 GR_COUNT count,
                                                 GR_POINT *points);

## Description

## Details

### GrNewRegion ()

    GR_REGION_ID GrNewRegion                    (void);

Creates a new region structure and returns the ID used to refer to it. The structure is initialised with a set of default parameters.

Returns : | the ID of the newly created region

### GrDestroyRegion ()

    void        GrDestroyRegion                 (GR_REGION_ID region);

Destroys the region structure with the specified ID.

`region` : | the ID of the region structure to destroy

### GrUnionRectWithRegion ()

    void        GrUnionRectWithRegion           (GR_REGION_ID region,
                                                 GR_RECT *rect);

Makes a union of the specified region and the specified rectangle and places the result back in the source region.

`region` : | the ID of the region to modify
`rect` : | a pointer to the rectangle to add to the region

### GrUnionRegion ()

    void        GrUnionRegion                   (GR_REGION_ID dst_rgn,
                                                 GR_REGION_ID src_rgn1,
                                                 GR_REGION_ID src_rgn2);

Makes a union of the specified source regions and places the result in the specified destination region.

`dst_rgn` : | the ID of the destination region
`src_rgn1` : | the ID of the first source region
`src_rgn2` : | the ID of the second source region

### GrSubtractRegion ()

    void        GrSubtractRegion                (GR_REGION_ID dst_rgn,
                                                 GR_REGION_ID src_rgn1,
                                                 GR_REGION_ID src_rgn2);

Subtracts the second source region from the first source region and places the result in the specified destination region.

`dst_rgn` : | the ID of the destination region
`src_rgn1` : | the ID of the first source region
`src_rgn2` : | the ID of the second source region

### GrXorRegion ()

    void        GrXorRegion                     (GR_REGION_ID dst_rgn,
                                                 GR_REGION_ID src_rgn1,
                                                 GR_REGION_ID src_rgn2);

Performs a logical exclusive OR operation on the specified source regions and places the result in the destination region. The destination region will contain only the parts of the source regions which do not overlap.

`dst_rgn` : | the ID of the destination region
`src_rgn1` : | the ID of the first source region
`src_rgn2` : | the ID of the second source region

### GrIntersectRegion ()

    void        GrIntersectRegion               (GR_REGION_ID dst_rgn,
                                                 GR_REGION_ID src_rgn1,
                                                 GR_REGION_ID src_rgn2);

Calculates the intersection of the two specified source regions and places the result in the specified destination region. The destination region will contain only the parts of the source regions which overlap each other.

`dst_rgn` : | the ID of the destination region
`src_rgn1` : | the ID of the first source region
`src_rgn2` : | the ID of the second source region

### GrSetGCRegion ()

    void        GrSetGCRegion                   (GR_GC_ID gc,
                                                 GR_REGION_ID region);

Sets the clip mask of the specified graphics context to the specified region. Subsequent drawing operations using this graphics context will not draw outside the specified region. The region ID can be set to 0 to remove the clipping region from the specified graphics context.

`gc` : | the ID of the graphics context to set the clip mask of
`region` : | the ID of the region to use as the clip mask

### GrPointInRegion ()

    GR_BOOL     GrPointInRegion                 (GR_REGION_ID region,
                                                 GR_COORD x,
                                                 GR_COORD y);

Tests whether the specified point is within the specified region, and then returns either True or False depending on the result.

`region` : | the ID of the region to examine
`x` : | the X coordinate of the point to test for
`y` : | the Y coordinate of the point to test for
Returns : | True if the point is within the region, or False otherwise

### GrRectInRegion ()

    int         GrRectInRegion                  (GR_REGION_ID region,
                                                 GR_COORD x,
                                                 GR_COORD y,
                                                 GR_COORD w,
                                                 GR_COORD h);

Tests whether the specified rectangle is contained within the specified region. Returns GR_RECT_OUT if it is not inside it at all, GR_RECT_ALLIN if it is completely contained within the region, or GR_RECT_PARTIN if it is partially contained within the region.

`region` : | the ID of the region to examine
`x` : | the X coordinates of the rectangle to test
`y` : | the Y coordinates of the rectangle to test
`w` : | the width of the rectangle to test
`h` : | the height of the rectangle to test
Returns : | GR_RECT_PARTIN, GR_RECT_ALLIN, or GR_RECT_OUT

### GrEmptyRegion ()

    GR_BOOL     GrEmptyRegion                   (GR_REGION_ID region);

Determines whether the specified region is empty, and returns GR_TRUE if it is, or GR_FALSE otherwise.

`region` : | the ID of the region to examine
Returns : | GR_TRUE if the region is empty, or GR_FALSE if it is not

### GrEqualRegion ()

    GR_BOOL     GrEqualRegion                   (GR_REGION_ID rgn1,
                                                 GR_REGION_ID rgn2);

Determines whether the specified regions are identical, and returns GR_TRUE if it is, or GR_FALSE otherwise.

`rgn1` : | the ID of the first region to examine
`rgn2` : | the ID of the second region to examine
Returns : | GR_TRUE if the regions are equal, or GR_FALSE otherwise

### GrOffsetRegion ()

    void        GrOffsetRegion                  (GR_REGION_ID region,
                                                 GR_SIZE dx,
                                                 GR_SIZE dy);

Offsets the specified region by the specified distance.

`region` : | the ID of the region to offset
`dx` : | the distance to offset the region by in the X axis
`dy` : | the distance to offset the region by in the Y axis

### GrGetRegionBox ()

    int         GrGetRegionBox                  (GR_REGION_ID region,
                                                 GR_RECT *rect);

Fills in the specified rectangle structure with a bounding box that would completely enclose the specified region, and also returns the type of the specified region.

`region` : | the ID of the region to get the bounding box of
`rect` : | pointer to a rectangle structure
Returns : | the region type

### GrNewPolygonRegion ()

    GR_REGION_ID GrNewPolygonRegion             (int mode,
                                                 GR_COUNT count,
                                                 GR_POINT *points);

Creates a new region structure, fills it with the region described by the specified polygon, and returns the ID used to refer to it.

`mode` : | the polygon mode to use (GR_POLY_EVENODD or GR_POLY_WINDING)
`count` : | the number of points in the polygon
`points` : | pointer to an array of point structures describing the polygon
Returns : | the ID of the newly allocated region structure, or 0 on error

<<< Previous Page | Home | Up | Next Page >>>
colours | selections