ImgMergeImage

int IMAPI ImgMergeImage( HANDLE hDst, HANDLE hSrc, int nOptions, int nTrans, long xOffset, long yOffset, DWORD RGBtran);

This function merges one image into another.

Parameter

Type

Description

hDst

HANDLE

Identifies the image that will be merged into and changed.

hSrc

HANDLE

Identifies the image data that will be used for making the new image.

nOptions

int

Flags for Combine, OR, XOR, AND etc. like ROP values the nOptions includes the color channels as well.

nOptions Flags include:

Option

Description

RGB_RED

Only merge the red channel

RGB_GREEN

Only merge the green channel

RGB_BLUE

Only merge the blue channel

RGB_ALPHA

Only merge the alpha channel

RGB_FULL

RGB_BLUE|RGB_GREEN|RGB_RED|RGB_ALPHA

IMG_TRANS

Use transparency value

IMG_TRANS2

Use transparency allowing for slight deviation w\ dithered images

IMG_TRANS_IDX

Used with palettized images, use index into color table instead of RGBtran value

IMG_TRANS_IDX_ARRAY

Use an array of transparent palette indexes

IMG_APPLY_ALPHA

Use alpha channel data to modify data being copied

IMG_COLOR2ALPHA

Takes specified color channels combines and copies to alpha

IMG_REPLACE

Replace Source Image channel or all where not masked

IMG_AND

Combine Src and Dest at given weight if specified

IMG_OR

Bitwise OR Src and Dest (DARK Src pixels will get color)

IMG_XOR

Bitwise XOR Src and Dest (Bright Src and Dst pixels will get dark)

Color channels can be merged separately or in any combination with the other color channels. To perform a bitwise NOT of an image invert either Source or Destination image prior to merge

nTrans

int

Is the transparency value. When Trans is set to to 255 the merged image is fully opaque and will replace the source image at the given x and y offset. When Trans = 0 nothing will get replaced in the source image since the merged in image is fully transparent.

xOffset

long

the x offset in the destination image where the 2nd image will be merged. These default to zero.

yOffset

long

the y offset in the destination image where the 2nd image will be merged. These default to zero.

RGBTran

DWORD

Optional, used to specify the transparent color. If IMG_TRANS or IMG_TRANS2 are set then this value needs to be set to a DWORD RGB color value in the format 0x00RRGGBB. If IMG_TRANS_IDX is specified and the image is a palettized image then this value will be an index into the array. If IMG_TRANS_IDX_ARRAY is set then this is an array of SHORTS each with their own transparency value of 255 opaque to 0, this array will start with the first palette entry and assign this transparency to to this palette entry for the length of the array. If the array is shorter than the number of palette entries than the rest will be set to full opacity.

Return Value

Returns IMG_OK on success

Comments

This function is optimized to allow for the creation of animated gif images that need to set a background color without the need to create a dc. This is done by writing to the bitmap data buffer directly.

Example

ImgMergeImage(m_hDisplayImg, m_hRestoreImg, IMG_REPLACE|RGB_BLUE|RGB_GREEN|RGB_RED, 0, 0,0, NULL);//m_cx, m_cy, rgb);

Parameter	Type	Description
hDst	HANDLE	Identifies the image that will be merged into and changed.
hSrc	HANDLE	Identifies the image data that will be used for making the new image.
nOptions	int	Flags for Combine, OR, XOR, AND etc. like ROP values the nOptions includes the color channels as well.

Option	Description
RGB_RED	Only merge the red channel
RGB_GREEN	Only merge the green channel
RGB_BLUE	Only merge the blue channel
RGB_ALPHA	Only merge the alpha channel
RGB_FULL	RGB_BLUE\|RGB_GREEN\|RGB_RED\|RGB_ALPHA
IMG_TRANS	Use transparency value
IMG_TRANS2	Use transparency allowing for slight deviation w\ dithered images
IMG_TRANS_IDX	Used with palettized images, use index into color table instead of RGBtran value
IMG_TRANS_IDX_ARRAY	Use an array of transparent palette indexes
IMG_APPLY_ALPHA	Use alpha channel data to modify data being copied
IMG_COLOR2ALPHA	Takes specified color channels combines and copies to alpha
IMG_REPLACE	Replace Source Image channel or all where not masked
IMG_AND	Combine Src and Dest at given weight if specified
IMG_OR	Bitwise OR Src and Dest (DARK Src pixels will get color)
IMG_XOR	Bitwise XOR Src and Dest (Bright Src and Dst pixels will get dark)

nTrans	int	Is the transparency value. When Trans is set to to 255 the merged image is fully opaque and will replace the source image at the given x and y offset. When Trans = 0 nothing will get replaced in the source image since the merged in image is fully transparent.
xOffset	long	the x offset in the destination image where the 2nd image will be merged. These default to zero.
yOffset	long	the y offset in the destination image where the 2nd image will be merged. These default to zero.
RGBTran	DWORD	Optional, used to specify the transparent color. If IMG_TRANS or IMG_TRANS2 are set then this value needs to be set to a DWORD RGB color value in the format 0x00RRGGBB. If IMG_TRANS_IDX is specified and the image is a palettized image then this value will be an index into the array. If IMG_TRANS_IDX_ARRAY is set then this is an array of SHORTS each with their own transparency value of 255 opaque to 0, this array will start with the first palette entry and assign this transparency to to this palette entry for the length of the array. If the array is shorter than the number of palette entries than the rest will be set to full opacity.