Name
CreateClipRegion -- create a clip region (V2.0)
Synopsis
[id] = CreateClipRegion(id, type, ...)
[id] = CreateClipRegion(id, #BOX, x, y, width, height)
[id] = CreateClipRegion(id, #SHAPE, id, x, y)
Function
This function can be used to create a clip region which all Hollywood graphics functions will respect. CreateClipRegion() creates a new clip region and assigns the identifier id to it. If you pass Nil in id, CreateClipRegion() will automatically choose a vacant 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.

Inputs
id
identifier for the clip region or Nil for auto id selection
type
type of clip region to install; #BOX, #SHAPE or #NONE
...
the following arguments depend on the type; see above
Results
id
optional: identifier of the clip region; will only be returned when you pass Nil as argument 1 (see above)
Example
See SetClipRegion


Show TOC