[id] = CreateClipRegion(id, type, ...) [id] = CreateClipRegion(id, #BOX, x, y, width, height) [id] = CreateClipRegion(id, #SHAPE, id, x, y)
CreateClipRegion() creates a new clip
region and assigns the identifier id to it. If you pass Nil in id,
CreateClipRegion() will automatically choose an identifier and return it.
Note that CreateClipRegion() does not activate the clip region; this has
to be done using SetClipRegion().
Clip regions are useful to limit the area of your display, where graphics can be displayed, e.g. if you have a game screen with two parts: The level area and the status bar (lifes, ammo etc.) it can be useful to install a clip region which matches the bounds of the level area so that sprites will never be drawn outside of this area. All Hollywood graphics functions will respect the clip region you install using this function. No graphics will ever be drawn outside the bounds of your clip region.
There are two different clip region types: Rectangular (#BOX) and custom
shaped (#SHAPE) clip regions. Drawing to rectangular clip regions is
generally faster. If you want to install a rectangular clip region, you
have to specify its x and y position as well as its width and height.
A custom shaped clip region can be installed by specifying a brush, whose
mask is to be used as the clip region. Also, you need to specify x and y
offsets where the clip region shall be positioned on the display, e.g.
if you have a mask of size 320x240 but a display of size 640x480, you
might want to center the clip region on the display. If you install a
custom shaped clip region using a brush's mask, Hollywood will be able
to draw to all visible pixels of the mask and all invisible pixels of
the mask will be clipped.
See SetClipRegion for information on how to install a clip region created using CreateClipRegion().
To free a clip region created with CreateClipRegion(), use the FreeClipRegion()
function.
#BOX, #SHAPE or #NONE