CopyDIB Method

Description

Creates a copy of the current DIB.

Syntax

Visual Basic
Public Function CopyDIB() As Long

Return Type

This method returns the global handle to the copied DIB. If the method fails, the return value is zero.

Remarks

This method does not work with high-gray images as high-gray images cannot be DIBs by definition. Instead, use the CopyImage method to copy high-gray images.

If this method fails, in addition to the return value being zero, the ImagError property will have one of the following values: IX_Error_MemoryAlloc, IX_Error_NoImage, IX_Error_InvalidFormat, or IX_Error_NoCurrentBuffer.

Note that the receiver is responsible for freeing the DIB by issuing a GlobalFree on the DIB Handle. If the receiver is an ImagXpress control with the OwnDib property set to true, there is no need to issue the GlobalFree as ImagXpress does this for you.

Example

Use of CopyDIB showing necessary GlobalFree. This example shows what a typical C++ pattern would look like where the application is going to process the copy of the DIB on its own.

VC++ example of CopyDib (C++)

HANDLEhDib=NULL;
hDib=ImagXpress1.CopyDIB();
if(hDib!=NULL)
{
     //Do something on my own with the hDib
     PBYTE pDib=::GlobalLock(hDib);
     if(pDib!=NULL)
     {
          PBITMAPINFOHEADER pBmi=(PBITMAPINFOHEADER) pDib;
          //Locked Dib, process it...
          ::GlobalUnlock(hDib);
     }
     ::GlobalFree(hDib);
}

This example shows a typical use of CopyDIB to load another ImagXpress control with a copy of the current DIB. ImagXpress2 will own the DIB and make sure it is freed appropriately.

VB Example of CopyDib (Visual Basic)

'The CopyDIB method is typically used to create
'a copy of a DIB for another ImagXpress control.
'ImagXpress2 will own the copied DIB or other
'clean-up is necessary.
ImagXpress2.OwnDIB=True
ImagXpress2.hDIB=ImagXpress1.CopyDIB