CopyImage API Function discussion

[Chris Boss]

I was posting in another thread and something came up about the use of the CopyImage API function. Its been a long time since I wrote my original code which uses this function, so I don't remember why I chose to use the code I did, but in reexamining my code and the API docs I have some confusion of one of the flags used, LR_COPYRETURNORG

My code assumes I will get a totally new bitmap handle every time.
Rereading the API docs appears to indicate this flag will possibly return the original bitmaps handle when the size and resolution are the same (I assume resolution must be the current video resolution).

I wrote some test code to see if CopyImage indeed returns the original handle in this instance. To do this requires creating a DDB (device dependent bitmap) via the API, rather than loading an image.

Here is my test code:

#COMPILE EXE
#INCLUDE "win32api.inc"

'TYPE BITMAP
'  bmType AS LONG
'  bmWidth AS LONG
'  bmHeight AS LONG
'  bmWidthBytes AS LONG
'  bmPlanes AS WORD
'  bmBitsPixel AS WORD
'  bmBits AS BYTE PTR
'END TYPE
FUNCTION PBMAIN
     LOCAL BM1 AS BITMAP, BM2 AS BITMAP
     LOCAL hDC AS LONG, hBmp1&, hBmp2&, T$
     hDC = GetDC(%HWND_DESKTOP)
     hBmp1&=CreateCompatibleBitmap(hDC, 128,128)
     ReleaseDC %HWND_DESKTOP, hDC
     hBmp2&=CopyImage(hBmp1&, %IMAGE_BITMAP, 0,0,%LR_COPYRETURNORG)
     MSGBOX "Compare Handles: "+STR$(hBmp1&)+" "+STR$(hBmp2&)
     GetObject hBmp1&, SIZEOF(BM1), BM1
     GetObject hBmp2&, SIZEOF(BM2), BM2
     IF BM1<>BM2 THEN
          MSGBOX "format not the same"
     ELSE
          T$="Compare BITMAP structure values:"+CHR$(13)+CHR$(10)
          T$=T$+STR$(BM1.bmType)+" "+STR$(BM1.bmWidth)+" "+STR$(BM1.bmHeight)+" "+STR$(BM1.bmWidthBytes)+" "+STR$(BM1.bmPlanes)+" "+STR$(BM1.bmBitsPixel)+" "+STR$(BM1.bmBits)+CHR$(13)+CHR$(10)
          T$=T$+STR$(BM2.bmType)+" "+STR$(BM2.bmWidth)+" "+STR$(BM2.bmHeight)+" "+STR$(BM2.bmWidthBytes)+" "+STR$(BM2.bmPlanes)+" "+STR$(BM2.bmBitsPixel)+" "+STR$(BM2.bmBits)
          MSGBOX T$
     END IF
END FUNCTION

Running the test on my system (WinXP Home, 32 bit color), CopyImage always appears to return a new bitmap handle and never the original one.

If the call were to return the original handle, it would break some of my code, so I need to know if (and if so, when) the CopyImage function will return the same handle as the original.

Are the API docs simply not clear on this (they are a bit cryptic) ?
Am I reading the API docs incorrectly ?

If some could test the test app on different systems (ie. Win 95,98,ME,2000, XP, Vista) and different video resolutions, it would be helpful.

I need to know whether CopyImage ever returns the same handle as the original bitmap, when using this flag (LR_COPYRETURNORG).

[Chris Boss]

Note: The testcopy.zip file has both the basic code and a compiled EXE in it (compiled with PB 6.1).

[Kev Peel]

XP Pro, 32bpp: Never
Vista, 32bpp: Never

[Chris Holbrook]

under XP version 2002 SP2.

Compare Handles numbers are different, Compare Bitmap Structure Values numbers are the same.

[Chris Boss]

How about different resolutions, like 24 bit, 16 bit, 8 bit ?

[Chris Holbrook]

How about different resolutions, like 24 bit, 16 bit, 8 bit ?

Eh? You're not playing to one of my strengths here - do ye mean different video modes?

[Chris Boss]

Yes, I mean different video modes.

I used the term resolution I guess because the API docs refer to resolution when calling CopyImage. It says when the bitmap to be created is the same size and resolution, it returns the original.

What is not clear is whether returning the original means the same handle or a new bitmap exactly like the original (new handle).

[Jules Marchildon]

This is what the on-line MSDN says:

LR_COPYRETURNORG
Returns the original hImage if it satisfies the criteria for the copy—that is, correct dimensions and color depth—in which case the LR_COPYDELETEORG flag is ignored. If this flag is not specified, a new object is always created.

[Chris Holbrook]

Chris,

I tested on XP SP2 at 1024x768, 1280x1024, 640x480, both True and High Color, also on W98 2nd Ed 4.10 at 640x480 and 1024x768, using 256-bit color, 24-bit true color and 32-bit true color in each case.

Different handles every time.

[Chris Boss]

Jules,

The API docs give the impression that it may not return a different handle in some instances, but in practical experience it appears that it always does return a new handle.

The docs also say the one or more flags can be used. This implies that at least one flag must be used and LR_COPYRETURNORG is the only one that makes sense for what I want (other than returning the same handle though).

[Jules Marchildon]

I have a few old notes, not sure of my sources, they may be only rumours.

(1.) LR_COPYRETURNORG only works on NT 4.0
(2.) Unfortunately, on devices that use a palette, the CopyImage function mangles
the colors of the DDB. In this case you need to perform the Copying manually.

In my two graphic API books, both the examples listed use;
CopyImage(hBMp,IMAGE_BITMAP,0,0,0)
Says use IMAGE_BITMAP (0) to make an exact copy, set all other parmaters to zero.