CD - Canvas Draw


The clipping area is an area that limits the available drawing area inside the canvas. Any primitive is drawn only inside the clipping area. It affects all primitives.

You can set the clipping area by using the function cdClipArea, and retrieve it using cdGetClipArea. The clipping area is a rectangle by default, but it can has other shapes. In some drivers a polygon area can be defined, and in display based drivers a complex region can be defined. The complex region can be a combination of boxes, polygons, sectors, chords and texts.

The cdClip function activates and deactivaes the clipping.

int cdClip(int mode); [in C]
cd.Clip(mode: number) -> (old_mode: number) [in Lua]

Activates or deactivates clipping. Returns the previous status. Values: CD_CLIPAREA, CD_CLIPPOLYGON or CD_CLIPOFF. The value CD_QUERY simply returns the current status. Default value: CD_CLIPOFF.

The value CD_CLIPAREA activates a rectangular area as the clipping region.

The value CD_CLIPPOLYGON activates a polygon as a clipping region, but works only in some drivers (please refer to the notes of each driver). The clipping polygon must be defined before activating the polygon clipping; if it is not defined, the current clipping state remains unchanged. See the documentation of cdBegin/cdVertex/cdEnd to create a polygon.

The value CD_CLIPREGION activates a complex clipping region. See the documentation of Regions.

void cdClipArea(int xmin, int xmax, int ymin, int ymax); [in C]
void wdClipArea(double xmin, double xmax, double ymin, double ymax); (WC) [in C]
cd.ClipArea(xmin, xmax, ymin, ymax: number) [in Lua]
cd.wClipArea(xmin, xmax, ymin, ymax: number) (WC) [in Lua]

Defines a rectangle for clipping. Only the points in the interval: x_min<= x <= x_max, y_min <= y <= y_max will be printed. Default region: (0, w-1, 0, h-1).

int cdGetClipArea(int *xmin, int *xmax, int *ymin, int *ymax); [in C]
int wdGetClipArea(double *xmin, double *xmax, double *ymin, double *ymax); (WC) [in C]
cd.GetClipArea() -> (xmin, xmax, ymin, ymax, status: number) [in Lua]
d.wGetClipArea() -> (xmin, xmax, ymin, ymax, status: number) (WC) [in Lua]

Returns the rectangle and the clipping status. It is not necessary to provide all return pointers, you can provide only the desired values and NULL for the others.


A polygon for clipping can be created using cdBegin(CD_CLIP)/cdVertex(x,y)/.../cdEnd().

See the documentation of cdBegin/cdVertex/cdEnd.

int* cdGetClipPoly(int *n); [in C]
double * wdGetClipPoly(int *n); (WC) [in C]
cd.GetClipPoly() -> (n: number, points: table) [in Lua]
cd.wGetClipPoly() -> (n: number, points: table) (WC) [in Lua]

Returns the number of points in the clipping polygon and the polygon itself as a sequence of points, each with its respective x and y coordinates (E.g.: x1,y1,x2,y2,x3,y3,...).