XSetClipRectangles − change clip_mask in a graphics context to a list of rectangles.
Synopsis
XSetClipRectangles(display, gc, clip_x_origin,
clip_y_origin, rectangles, n, ordering)
Display *display;
GC gc;
int clip_x_origin, clip_y_origin;
XRectangle rectangles[];
int n;
int ordering;
Arguments
displaySpecifies a connection to an X server; returned from XOpenDisplay().
gcSpecifies the graphics context.
clip_x_origin
clip_y_origin
Specify the x and y coordinates of the clip origin (interpreted later relative to the window drawn into with this GC).
rectanglesSpecifies an array of rectangles. These are the rectangles you want drawing clipped to.
nSpecifies the number of rectangles.
orderingSpecifies the ordering relations of the rectangles. Possible values are Unsorted, YSorted, YXSorted, or YXBanded.
Description
XSetClipRectangles() changes the clip_mask component in the specified GC to the specified list of rectangles and sets the clip origin to clip_x_origin and clip_y_origin. The rectangle coordinates are interpreted relative to the clip origin. The output from drawing requests using that GC are henceforth clipped to remain contained within the rectangles. The rectangles should be nonintersecting, or the graphics results will be undefined. If the list of rectangles is empty, output is effectively disabled as all space is clipped in that GC. This is the opposite of a clip_mask of None in XCreateGC(), XChangeGC(), or XSetClipMask(). If known by the client, ordering relations on the rectangles can be specified with the ordering argument. This may provide faster operation by the server. If an incorrect ordering is specified, the X server may generate a BadMatch error, but it is not required to do so. If no error is generated, the graphics results are undefined. Unsorted means the rectangles are in arbitrary order. YSorted means that the rectangles are nondecreasing in their y origin. YXSorted additionally constrains YSorted order in that all rectangles with an equal y origin are nondecreasing in their x origin. YXBanded additionally constrains YXSorted by requiring that, for every possible horizontal y scan line, all rectangles that include that scan line have identical y origins and y extents. To cancel the effect of this command, so that there is no clipping, pass None as the clip_mask in XChangeGC() or XSetClipMask(). For more information, see Volume One, Chapter 5, The Graphics Context.
Structures
typedef struct {
short x,y;
unsigned short width, height;
} XRectangle;
Errors
BadAlloc
BadGC
BadMatchIncorrect ordering (error message server-dependent).
BadValue
See Also
DefaultGC(), XChangeGC(), XCopyGC(), XCreateGC(), XFreeGC(), XGContextFromGC(), XSetArcMode(), XSetBackground(), XSetClipMask(), XSetClipOrigin(), XSetDashes(), XSetFillRule(), XSetFillStyle(), XSetForeground(), XSetFunction(), XSetGraphicsExposures(), XSetLineAttributes(), XSetPlaneMask(), XSetState(), XSetStipple(), XSetSubwindowMode(), XSetTSOrigin().
Copyright O’Reilly & Assoc. —