NAME

InstallClipRegion: Install clip region in layer

SYNOPSIS

oldclipregion = InstallClipRegion( l, region )
d0 a0 a1

struct Region *InstallClipRegion( struct Layer *, struct Region *);

FUNCTION

Installs a transparent Clip region in the layer. All subsequent graphics calls will be clipped to this region. You MUST remember to call InstallClipRegion(l,NULL) before calling DeleteLayer(l) or the Intuition function CloseWindow() if you have installed a non-NULL ClipRegion in l.

INPUTS

l: pointer to a layer
region: pointer to a region

RESULT

oldclipregion: The pointer to the previous ClipRegion that was installed. Returns NULL if no previous ClipRegion installed.

Returns "region" in case it could not install the user clip region, for example because it run out of memory.

NOTES

In V44 and before, if the system runs out of memory during this function, it would not install the user cliprect, but would also swep away the previously installed cliprect, hence would leave the layer completely unclipped. This has been fixed in V45. Note that you should therefore check the result code against your clip region. In case they are equal, the clip region could not be installed.

Removing a cliprect (i.e. installing NULL) will always work.

BUGS

If you try to remove a user clip rect while the layer is updating, i.e. BeginUpdate() has been called, then this function may erraneously insert cliprects that are not part of the damage list into the layer if layers runs low on memory. Note that calling InstallClipRegion() under this condition is discouraged.

If this function runs low on memory for removing a clip region otherwise, the resulting layer will be still in valid state, but the cliprect layout may be sub-optimal. This gets fixed on the next layer resize or depth-arrange operation.