GpiSetBackMix

This function sets the current background mix attribute for each individual primitive type.

Syntax

GpiSetBackMix(hps, lMixMode)

Parameters

hps (HPS) - input

Presentation-space handle.

lMixMode (LONG) - input

Background-mix mode.

Background mixes marked with an asterisk (*) are mandatory for all devices.

The currently associated device supports any of the mixes specified as supported in DevQueryCaps (CAPS_BACKGROUND_MIX_SUPPORT) Any other valid mixes can be supported for some primitive types but otherwise result in BM_LEAVEALONE. An error is raised only if the value specified is not one of those listed.

For more information on mixing, see GpiSetMix.

BM_DEFAULT - The default value (BM_LEAVEALONE unless changed with GpiSetDefAttrs).

BM_OR - Logical-OR.

BM_OVERPAINT - The background of the primitive takes precedence over whatever is underneath. (*)

BM_XOR - Exclusive-OR.

BM_LEAVEALONE - The background of the primitive has no effect on what is underneath. (*)

Returns

rc (BOOL) - returns

Success indicator.

TRUE - Successful completion

FALSE - Error occurred.

Errors

Possible returns from WinGetLastError

PMERR_INV_HPS (0x207F): An invalid presentation-space handle was specified.
PMERR_PS_BUSY (0x20F4): An attempt was made to access the presentation space from more than one thread simultaneously.
PMERR_INV_BACKGROUND_COL_ATTR (0x2044): An invalid background color attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask.

Remarks

The background mix attribute controls the way that the background color of a primitive is combined with the color of any primitive that it overlaps.

These primitives are affected by the background mix attribute:

Areas: The background of an area is defined to be every pel within the area that is not set by the shading pattern.
Text: The background of a character is the complete character box.
Images: For an image, the background is every pel within the image that is not set.
Markers: The background of a marker is the complete marker box.

Note: When the background mix is BM_LEAVEALONE (initial default) the background color is not seen.

The attribute mode determines whether the current value of the background mix attribute is preserved. If it is, the values of the background mix attribute for each primitive type are preserved, and a single GpiPop function restores them.

This function should not be used within a path or area bracket.

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; see "MetaFile Resolutions" in the Presentation Manager Programming Reference for more information.

Example Code

#define INCL_GPIPRIMITIVES /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS     hps;       /*  Presentation-space handle. */
LONG    lMixMode;  /*  Background-mix mode. */
BOOL    rc;        /*  Success indicator. */

rc = GpiSetBackMix(hps, lMixMode);

This is an example of a function used to repaint the window when a WM_PAINT message is issued.

VOID cdecl ClientPaint( HWND hwnd )
{
  POINTL  pt;
  HPS     hps;                      /* Presentation space handle */
  RECTL   rcl;                      /* Window rectangle          */

  /* Obtain a cache PS and set color and background mix attributes */
  hps = WinBeginPaint( hwnd, (HPS)NULLHANDLE, (PRECTL)&rcl );
  GpiSetColor( hps, clrText );
  GpiSetBackColor( hps, CLR_BACKGROUND ); /* set background to white. */
  GpiSetBackMix( hps, BM_OVERPAINT );
                       /* the background of the primitive takes
                          over whatever is underneath.           */
}

Related Functions

GpiBox
GpiBeginArea
GpiCharString
GpiCharStringAt
GpiCharStringPos
GpiCharStringPosAt
GpiEndArea
GpiFullArc
GpiMarker
GpiPolyMarker
GpiQueryBackMix
GpiSetBackColor
GpiSetColor
GpiSetMix
GpiQueryCharStringPos
GpiQueryCharStringPosAt
GpiSetAttrMode
GpiSetAttrs
GpiSetDefAttrs

Graphic Elements and Orders

Element Type: OCODE_GSBMX

This element type is generated if the attribute mode (see GpiSetAttrMode) is set to AM_NOPRESERVE.

Order: Set Background Mix

Element Type: OCODE_GPSBMX

This element type is generated if the attribute mode is set to AM_PRESERVE.

Order: Set Background Mix