[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

Regions allow the application to install clipping rectangles into layers.
A clipping rectangle is a rectangular area into which the graphics
routines will draw.  All drawing that would fall outside of that
rectangular area is clipped (not rendered).

User clipping regions are linked lists of clipping rectangles created by
an application program through the graphics library routines described
below.  By combining together various clipping rectangles, any arbitrary
clipping shape can be created.  Once the region is set up, you use the
layers library call InstallClipRegion() to make the clipping region active
in a layer.

Regions are safe to use with layers created by Intuition (i.e., windows).
The following table describes the routines available for the creation,
manipulation and use of regions.


                Table 30-4: Functions Used with Regions
  ____________________________________________________________________
 |                                                                    |
 |          Routine      Library         Description                  |
 |====================================================================|
 |  InstallClipRegion()  Layers    Add a clipping region to a layer.  |
 |--------------------------------------------------------------------|
 |          NewRegion()  Graphics  Create a new, empty region.        |
 |      DisposeRegion()  Graphics  Dispose of an existing region and  |
 |                                 its rectangles.                    |
 |--------------------------------------------------------------------|
 |      AndRectRegion()  Graphics  And a rectangle into a region.     |
 |       OrRectRegion()  Graphics  Or a rectangle into a region.      |
 |      XorRectRegion()  Graphics  Exclusive-or a rectangle into a    |
 |                                 region.                            |
 |    ClearRectRegion()  Graphics  Clear a rectangular portion of a   |
 |                                 region.                            |
 |    AndRegionRegion()  Graphics  And two regions together.          |
 |     OrRegionRegion()  Graphics  Or two regions together.           |
 |    XorRegionRegion()  Graphics  Exclusive-or two regions together. |
 |--------------------------------------------------------------------|
 |        ClearRegion()  Graphics  Clear a region.                    |
 |____________________________________________________________________|


With these functions, the application can selectively update a
custom-shaped part of a layer without disturbing any of the other layers
that might be present.

    Never Modify the DamageList of a Layer Directly.
    ------------------------------------------------
    Use the routine InstallClipRegion() to add clipping to the layer.
    The regions installed by InstallClipRegion() are independent of
    the layer's DamageList and use of user clipping regions will not
    interfere with optimized window refreshing.

    Do Not Modify A Region After It Has Been Added.
    -----------------------------------------------
    After a region has been added with InstallClipRegion(), the
    program may not modify it until the region has been removed with
    another call to InstallClipRegion().

 Creating and Deleting Regions    Changing a Region 
 Installing Regions               Regions Example