IKPasteImage

This function pastes a raster image into another raster image.

[C++Builder/Visual C++] HANDLE IKPasteImage(HANDLE Handle, PTR_IKSELECT_IMAGE SrcHandle, int Angle, BOOL TurnX, BOOL TurnY, BYTE Trans, BOOL TransColor, BYTE TRed, BYTE TGreen, BYTE TBlue, BYTE BRed, BYTE BGreen, BYTE BBlue, int x, int y, BOOL Clip, IKPROCESSPROC UserProc, LPCTSTR Caption, LPCTSTR Message, LPCTSTR Button);

[Delphi] function IKPasteImage(Handle: THandle; var SrcHandle: IKSELECT_IMAGE; Angle: Integer; TurnX, TurnY: LongBool; Trans: Byte; TransColor: LongBool; TRed, TGreen, TBlue, BRed, BGreen, BBlue: Byte; x, y: Integer; Clip: LongBool; UserProc: LONG_PTR; Caption, Message, Button: PChar): THandle;

[Visual Basic] Function IKPasteImage(ByVal Handle As Long, SrcHandle As IKSELECT_IMAGE, ByVal Angle As Long, ByVal TurnX As Long, ByVal TurnY As Long, ByVal Trans As Byte, ByVal TransColor As Long, ByVal TRed As Byte, ByVal TGreen As Byte, ByVal TBlue As Byte, ByVal BRed As Byte, ByVal BGreen As Byte, ByVal BBlue As Byte, ByVal x As Long, ByVal y As Long, ByVal Clip As Long, ByVal UserProc As Long, ByVal Caption As String, ByVal Message As String, ByVal Button As String) As Long

Parameters

Name	Explanation
Handle	The handle of the base image. This is the image onto which another image is pasted (supports 1, 4, 8, 16, 24, 32 bit images)
SrcHandle	A structure containing the image handle and the mask image handle member variables hImgBmh can be 1, 4, 8, 16, 24, or 32 bit images
Angle	Angle of rotation (-35999 to 35999, in 1/100 degree units)
TurnX	Reversal of the x axis (False(0): no reversal, True (nonzero): reversal)
TurnY	Reversal of the y axis (False(0): no reversal, True (nonzero): reversal)
Trans	The level of transparency (from 0 to 255, as this value increases, the image in SrcHandle becomes visible)
TransColor	Sets whether or not there is a transparent color in SrcHandle(hImgBmh) (False(0)No transparent color, True(nonzero):transparent color)
TRed	Sets the red component of the transparent color in SrcHandle(hImgBmh) (from 0 to 255)
TGreen	Sets the green component of the transparent color in SrcHandle(hImgBmh) (from 0 to 255)
TBlue	Sets the blue component of the transparent color in SrcHandle(hImgBmh) (from 0 to 255)
BRed	Sets the red component of the background color. This color is drawn in the area not in either SrcHandle( hImgBmh) or Handle images) (from 0 to 255)
BGreen	Sets the green component of the background color. This color is drawn in the area not in either SrcHandle( hImgBmh) or Handle images) (from 0 to 255)
BBlue	Sets the blue component of the background color. This color is drawn in the area not in either SrcHandle(hImgBmh) or Handle image) (from 0 to 255)
x,y	The attachment coordinates (in pixels)
Clip	Sets whether or not the image is clipped (False(0): No clipping, True(nonzero) clipping)
UserProc	The address of the user function (If not using the user function then set to 0)
Caption	Sets the text displayed in the title bar of the progress dialog box
Message	Sets the message displayed in the progress dialog box
Button	Sets the name of the button displayed in the progress dialog box

Return Value

Returns the raster image handle if successful. Returns 0 if unsuccessful.
In general the resulting image will be 24 bit color. However, if the Handle and SrcHandle stucture images are the same bitcount and both images have the same palette then the resultant image will have the same bitcount as the those images. (This is for images with a bit count of 8 or less.)

Explanation

The IKPasteImage function pastes a raster image into another raster image. The base image, the image that another image is pasted into) is set into the Handle parameter. The image you want to paste into the base image is set in the SrcHandle stucture. If using a mask image (to determine an area on the image to be processed), then set the image handle of the mask image in the SrcHandle stucture. The IKPasteImage function supports 1, 4, 8, 16, 24, 32 bit images.

The Angle, TurnX, and TurnY parameters apply to the images in the SrcHandle stucture. The x,y parameters determine the coordinates on the base image (the image in the Handle parameter) where the CENTER of the SrcHandle stucture images are pasted. When the Clip parameter is True, the result is the same size as the base image (the image in the Handle parameter) and any excess is clipped. When the TransColor parameter is True, the color specified in the TRed, TGreen and TBlue parameters is transparent.

Note: The image handles passed to this function are not freed after execution.

An explanation of the output bitcounts:

When the Trans parameter is NOT 0 or 255, then the output will be 24 bit color.
When Handle and SrcHandle are both 8 bits or less and their bitcounts are the same and their palettes are IDENTICAL (same colors in the same order), then the output will be the same bitcount as the input images.
If Handle and SrcHandle are less than 8 bits and their bitcounts are different, or their bitcounts are the same (less than 8 bits) but their palettes are not IDENTICAL (same colors in the same order), then the output will be a 24 bit image.

If the user function is set or if the Caption, Message, and Button parameters are blank then the Progress dialog box is not displayed. If the Progress dialog box is displayed, it indicates the percentage of the current process completed. For more information about the user function please refer to the Definition of User Function in the Ik9Effect.dll, Ik9EffectA.dll, Ik9Effect64.dll, Ik9Effect64A.dlll section.

[Differences from the ImageKit5]

Function NameParameters




IK5PasteImage	Handle, SrcHandle, Angle, TurnX, TurnY, Trans, Red, Green, Blue, x, y, Clip, EffectUserProc, Caption, Message, Button
IKPasteImage	Handle, SrcHandle, Angle, TurnX, TurnY, Trans, TransColor, TRed, TGreen, TBlue, BRed, BGreen, BBlue, x, y, Clip, UserProc, Caption, Message, Button

The TransColor, TRed, TGreen and TBlue parameters have been added. In the ImageKit5 the Red, Green and Blue parameters are now called BRed, BGreen and BBlue. When the TransColor parameter is false, this function is the same as in the ImageKit5. EffectUserProc refers to the same user function as UserProc.