Class Documentation

Name:Mask
Version:1.0
ID:ID_MASK
Status:Beta
Category:Graphics
Include:graphics/bitmap.h
Date:October 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2001. All rights reserved.
Short:  Manages graphical masks for Bitmap objects.



Description

The Mask class provides masking capabilities for the Bitmap object. It is typically used in conjunction with the Bitmap class' BlitArea() method, at times when masking is required.

To create a Mask, you need to base it on the graphics of an existing Bitmap object. This means that you need to draw an image or shape to a Bitmap, then create a new Mask and initialise it from the Bitmap object. You are required to elect a transparent background colour so that the generation routine can determine the shape of the mask.

A Mask may have a variable Width and Height, which you can set on initialisation to define the dimensions of the Mask. The dimensions may not exceed the size of the source Bitmap, otherwise they will be automatically restricted. The XOrigin and YOrigin fields can also be set to define the starting position from which the mask graphic will be generated from the source Bitmap.

Masks are not dependent on the Bitmaps that they are generated from. This means that you can use a Mask generated from one Bitmap in conjunction with other Bitmap sources.

Actions

The Mask class supports the following actions:

Refresh  Regenerates the graphics of a Mask from its source Bitmap.
Resize  Alters the dimensions of a Mask.

Structure

The Mask object consists of the following public fields:

Bitmap  Points to the Bitmap that a Mask should be generated from.
ColourRGB  The transparent colour to use when generating a Mask from a Bitmap.
Height  The height of a Mask's graphical area.
Width  The width of a Mask's graphical area.
XOrigin  The horizontal origin of a Mask within a source Bitmap.
YOrigin  The vertical origin of a Mask within a source Bitmap.
Action:Refresh
Short:Regenerates the graphics of a Mask from its source Bitmap.

Refreshing a Mask object will cause it to rebuild its mask image from the object referenced in the Bitmap field. This action is typically used in situations where you have changed the source graphic and need to update the Mask so that it reflects any changes in the graphic's shape.

The Refresh action should also be used if you alter the ColourRGB field in order to change the transparency value. If the dimensions of the source Bitmap have changed, the Width and Height of the Mask will not be updated to reflect the new dimensions. Use the Resize action if you want to update the dimensions of a Mask before a refresh.

 

Field:Bitmap
Short:Points to the Bitmap that a Mask should be generated from.
Type:Bitmap
Status:Read/Set

Before initialising a Mask you should set the Bitmap field so that it refers to the source Bitmap. The Bitmap that you refer to must be initialised and should contain some graphical information that will define the Mask's shape. You will also need to set the ColourRGB field so that the generation routine knows what the transparent colour is.

If you set this field after initialisation, the Mask object will automatically rebuild its image to match the contents of the referenced Bitmap. If the dimensions of the Bitmap do not match the Width and Height of the Mask, the dimensions will not be altered. For this reason, you may want to call the Resize action on the Mask before redefining the Bitmap field.

 

Field:ColourRGB
Short:The transparent colour to use when generating a Mask from a Bitmap.
Type:RGB
Status:Read/Write

This field defines the colour that will be used for transparency when generating a new mask graphic from a Bitmap. If this field is not set, then the transparency colour will be extracted from the source Bitmap's MaskRGB field.

 

Field:Height
Short:The height of a Mask's graphical area.
Type:LONG
Status:Read/Write

The height of a Mask can be declared in this field. If you do not specify a Height for a Mask prior to its initialisation, the Height value will be inherited from the Height of the source Bitmap.

 

Field:Width
Short:The width of a Mask's graphical area.
Type:LONG
Status:Read/Write

The width of a Mask can be declared in this field. If you do not specify a Width for a Mask prior to its initialisation, the Width value will be inherited from the Width of the source Bitmap.

 

Field:XOrigin
Short:The horizontal origin of a Mask within a source Bitmap.
Type:LONG
Status:Read/Write

If you would like to generate a new Mask from a source Bitmap at a specific horizontal starting position, set the XOrigin field. This will cause the generation routine to pick up the mask graphic from a position other than (0,0).

 

Field:YOrigin
Short:The vertical origin of a Mask within a source Bitmap.
Type:LONG
Status:Read/Write

If you would like to generate a new Mask from a source Bitmap at a specific vertical starting position, set the YOrigin field. This will cause the generation routine to pick up the mask graphic from a position other than (0,0).