ImageGear for C and C++ on Windows v19.10 - Updated
Transparency and Background
User Guide > How to Work with... > Common Operations > Viewing > Display Options > Transparency and Background

The ImageGear display functionality supports transparency by color and by mask. The former means that it is possible to draw images with the specified color being transparent. The latter allows using a specified 1-bit per pixel image as the transparent mask. There are a few options related to transparency and background support:

TranspMode (AT_MODE)

Option that contains transparency flags. If its value is IG_DSPL_TRANSPARENCY_NONE then transparency is disabled. Each of the following flags enables some transparency-related features:

  • IG_DSPL_TRANSPARENCY_COLOR - If this flag is set, then the transparent color is enabled, and the color's value that is assigned to the TranspColor option is used as transparent while drawing the image.
  • IG_DSPL_TRANSPARENCY_MASK - If this flag is set, then the transparency mask is enabled, and the TranspMask option is used as the transparent bitmap.
  • IG_DSPL_TRANSPMASK_STRETCH_TO_IMAGE - This flag is used when the transparency mask is enabled. If this flag is set, then the TranspMask image is resized and oriented along with the image being displayed. In other words, if during the display operation the image is scaled by factors DX and DY in the horizontal and vertical directions respectively, then the TranspMask image is scaled by the same factors. If this flag is not set then the transparency mask is not scaled. This flag is ignored unless the IG_DSPL_TRANSPMASK_LOCATE_TO_IMAGE flag is set.

The next three flags are exclusive; only one of them can be set at a time:

  • IG_DSPL_TRANSPMASK_LOCATE_TO_IMAGE - This flag is applicable if the transparency mask is enabled. If this flag is set, then the mask is calculated in the image-dependent coordinate system. This means that the mask is oriented as the image is, and the MaskLocation option is calculated from the original image's ImageRect. If this flag is not set, then the IG_DSPL_TRANSPMASK_STRETCH_TO_IMAGE flag is ignored.
  • IG_DSPL_TRANSPMASK_LOCATE_TO_CLIPRECT - This flag locates the transparent mask relative to the ClipRect, so that the MaskLocation is calculated from this rectangle's left top point.
  • IG_DSPL_TRANSPMASK_LOCATE_ABSOLUTE - This flag locates the transparent mask on the output device so that the mask's left top point has the coordinates specified in the MaskLocation option.

The default value for TranspMode option is IG_DSPL_TRANSPARENCY_NONE, which means that transparency is disabled.

TranspColor (AT_RGB) This (RGB) triple specifies the transparent color, and it is used if the IG_DSPL_TRANSPARENCY_COLOR flag is set in TranspMode (see its description above). If the transparent color is enabled, then all the pixels in the image that have values equal to TranspColor are drawn as transparent.
TranspMask (HIGEAR) This option specifies the transparency mask, and it is used if the IG_DSPL_TRANSPARENCY_MASK flag is set (see the TranspMode's description above). This is a normal HIGEAR image, and its location on the screen depends on other flags described above and the MaskLocation option. The application code is responsible for creating and deleting this mask.
MaskRect (AT_RECTANGLE) This rectangle specifies which part of the TranspMask image should be used as the transparency mask. It is an analog of the original image's ImageRect, but it applies to the TranspMask image. By default, it is initialized with the empty rectangle, which means the complete TranspMask image will be used.
MaskLocation (AT_POINT) This option specifies how the transparency mask is located relative to either the image or the device, depending on the flags set in TranspMode.
BkMode (AT_MODE)

This option specifies how ImageGear should fill the area of ClientRect that is not covered by the image's pixels. If its value is IG_DSPL_BACKGROUND_NONE, then the background is disabled, and ImageGear does not fill this area. Other possible values are as follows:

  • IG_DSPL_BACKGROUND_UNDER_IMAGE - If this flag is set, then the image's transparent pixels are drawn with current BkColor and BkBrush (see their description below). The area outside of DisplayedImageRect is not affected.
  • IG_DSPL_BACKGROUND_BEYOND_IMAGE - If this flag is set, then the transparent pixels that are outside of DisplayedImageRect are drawn with current BkColor and BkBrush (see their description below).

The default value for this option is IG_DSPL_BACKGROUND_UNDER_IMAGE| IG_DSPL_BACKGROUND_BEYOND_IMAGE.

BkColor (AT_RGB) This option is a (RGB) triple that specifies the background color. This color is used to fill the area of ClipRect that is not covered by the image's pixels.
BkBrush (HBITMAP) This option is the handle of the bitmap that stores the brush to be used. The application code is responsible for creating and deleting this brush.