IntroImageHandle.htm

The ImageKit10 VCL keeps track of images and processes image data by using an image handle (also known as a memory handle). The image handle can be thought of as a unique address to the image data that is stored in the memory. The ImageKit10 VCL uses the image handle to locate and manipulate the image data that is stored in the memory. Below is a brief explanation of some of the ways image handles are used in the ImageKit Control (TVImageKit).

1. The base image and the layer images:

The image handle for the base image is represented by: ImageKit.ImageHandle
The image handles for the layer images are represented by ImageKit.Layer(LayerNo).ImageHandle (LayerNo: from 0 to 99)
The layer images can only be used if there is an image set in the base image.
To set an image as the base image, set the LayerNo property to -1. To set an image as a layer image, set the LayerNo property to values ranging from 0 to 99. The default value of the LayerNo property is -1.

To load an image as the base image:

     VImageKit1.LayerNo := -1;
     VImageKit1.FileIO.FileName := 'path to the image file';
     VImageKit1.FileIO.LoadFile(vikLoad);

To load an image as the 0 layer image:

     VImageKit1.LayerNo := 0;
     VImageKit1.FileIO.FileName := 'path to the image file';
     VImageKit1.FileIO.LoadFile(vikLoad);

The the value set in the LayerNo property determines the image to be processed. Because of this the results of the following methods will be different depending on the value set in the LayerNo property:

   (a) ImageKit methods:
      GetFromClipBrd()
      SetToClipBrd()
      DibFromBitmap()
      BitmapFromDib()

   (b) ImageKit.FileIO methods:
      LoadFile(), SaveFile()
      LoadFileMem(), SaveFileMem()
      RGBBmpPlaneFileLoad(), RGBBmpPlaneFileSave()
      CMYKBmpPlaneFileLoad(), CMYKBmpPlaneFileSave()
      YCCBmpPlaneFileLoad(), YCCBmpPlaneFileSave()

2. Image data is automatically freed from the memory:

Whenever an image file is loaded (i.e. the ImageKit1.FileIO.LoadFile method is executed), the previously loaded image data is automatically freed from the memory before the new image data is loaded into the memory. Please refer to the code below:

(An example of loading an image in Delphi)

   procedure TForm1.Button1Click(Sender: TObject);
   begin
      if VImageKit1.FileIO.OpenFileDialog = False then      //Select image file
         Exit;
      VImageKit1.DisplayMode := vikScale;
      VImageKit1.FileIO.LoadFile(vikLoad);      //Load image file
      VImageKit1.DisplayImage();      //Display image
   end;

Because the previously loaded image data is freed before the next image data is loaded, the memory consumption does not continue to increase even if this code is executed repeatedly.

In the code below:

VImageKit1.ImageHandle := VImageKit1.CopyImage(ImageHandle)

(1) The previous VImageKit1.ImageHandle is freed
(2) The image handle of the copied image data is set into the VImageKit1.ImageHandle

However, in the following code:

VImageKit1.ImageHandle := ImageHandle

(1) The previous VImageKit1.ImageHandle is freed
(2) The image data set in ImageHandle is set into the VImageKit1.ImageHandle

The following code is not ordinarily used but illustrates an important point about freeing memory:

VImageKit1.ImageHandle := VImageKit1.ImageHandle

(1) The previous VImageKit1.ImageHandle is freed
(2) An invalid image handle is set into the VImageKit1.ImageHandle because the image data it points to has already been freed.

3. Effect Processing:

When the ImageKit10 VCL is used to process an effect the VImageKit.ImageHandle is refreshed. This means that the original image handle (the image data prior to the effect) is freed from the memory and the new image handle (the image data after the effect) is set into VImageKit1.ImageHandle. If the original image data is still needed after the effect is processed, then something like the following is necessary:

      'first make a copy of the original image.
      Image=ImageKit1.CopyImage();
      'Note: When the CopyImage parameter is omitted, then the image data is referred to according to the value set in the LayerNo property.
      'If LayerNo = -1, the image handle is set in the VImageKit.ImageHandle property.

      'then execute the effect that you want
      VImageKit1.LayerNo := -1;
      VImageKit1.Effect.SelectMode := vikEffectAll;
      VImageKit1.DisplayMode := vikScale;
      ret := VImageKit1.Effect.Emboss(0, 3, 128);
      VImageKit1.DisplayImage();

Once the original image data that was duplicated by the CopyImage method is no longer needed it should be freed as quickly as possible by executing the ImageKit.FreeMemory method. Failing to free it from the memory when the image data is no longer needed could result in a memory leak and cause your program to crash.

4. Retrieving images from scan devices:

[When using ImageKit10 VCL control]
Execute scan --> AfterScan event is generated --> copy image data or save as a new image.

[Using DLL functions]
Execute scan --> user function is generated --> copy image data or save as a new image.

When scanning, the scanned image data is stored in the memory and the image handle for this memory block is returned as an argument of the AfterScan event (when using VCL controls) or the User Function (when using DLL). This image data is automatically freed after this event or function executes in preparation for the next scan. Therefore, it is necessary to copy or save this image data within the AfterScan event or User Function.

5. Referring to and coping image data:

The ImageKit10 VCL locates and processes the memory blocks where image data is stored by using an image handle. This image handle refers to the image data in the memory. When image data is deleted, the image handle still exists but it no longer refers to an existing block of image data in the memory. For example:

If image handle (A) = Image memory block
And we set image handle (B) = image handle (A)
Then both (A) and (B) refer to the same image data in the memory, i.e. (A) --> Image data <-- (B)

To free (delete) the image data, we can use the image handle (B) to refer to it and do the following:

[For VCL controls]
VImageKit1.ImageHandle := (B);
VImageKit1.FreeMemory; (When no parameter is used in this method, the LayerNo property sets the image handle that is freed)

(For DLL User Functions)
IKFreeMemory(B)

The image data which image handle (B) refers to has been deleted. Therefore, the image data cannot be referred to through either image handles (A) or (B).

When image data has been copied a new and distinct memory block has been created and a new image handle is used to refer to this new memory block. When the image data is no longer needed, it is important that both memory blocks be freed. For example:

A = The image handle for image data we want to copy
[For VCL controls]
B := VImageKit1.CopyImage(A);

(For DLL User Functions)
B := IKCopyImage (A);

Now image handle (A) refers to the original image memory block and image handle (B) refers to the newly created image memory block.

A --> Image memory block
B --> Newly created image memory block

Both image handles (A) and (B) represent separate and independent memory blocks and both must be freed when no longer needed.

[Image Data and the Memory Block]

The image handle that the ImageKit10 VCL uses to refer to a particular memory block (or raster image data) is the handle of the Device Independent Bitmap (DIB). The pointer to this (DIB) is obtained by using the GlobalLock function of Windows API.

The structure of the Device Independent bitmap (DIB) is shown below:

For more information about the device independent bitmap, please refer to WindowsAPI and appropriate manuals.

Images and Image Handles