ImageGear for C and C++ on Windows v19.1 - Updated
Configuring Memory Mapping
User Guide > How to Work with... > Common Operations > Loading and Saving > Load an Image or Document > Working with Large Images > Configuring Memory Mapping

ImageGear handles all of the memory mapped file operations internally, except for when accessing individual pixels (see Accessing Pixels of Large Images for details). The application only needs to set a few parameters to enable the usage of memory mapped files and adjust it to its needs.

This topic provides information about:

Trying Large Image Support

By default, parameters that improve processing of large images are disabled in ImageGear. Follow these steps to try ImageGear’s enhanced support for large images in a sample:

  1. Run the Image Processing sample.
  2. Go to Main > Settings > Parameters…
  3. Select DIB.FILE_MAPPING.THRESHOLD in the list of parameters and set its value to 500. This enables memory mapping file storage for DIBs that have uncompressed size of 500 Mb and more.
  4. Click Apply and close the dialog.

The sample is now ready to work with large images.

If you try loading a gigabyte-sized image into ImageGear without file mapping enabled, the system may become unresponsive because of excessive RAM usage by ImageGear.

Optional:

Enabling Large Image Support

The usage of memory mapped files is controlled by three global control parameters:

All three parameters DIB.FILE_MAPPING.THRESHOLD, DIB.FILE_MAPPING.PATH, and DIB.FILE_MAPPING.FLUSH_SIZE are taken into account at the time of the DIB creation. After the DIB has been created, changing these parameters will not have an effect on the storage of this DIB, or flush frequency during its processing. However, if some operation replaces the DIB in a HIGEAR (e.g., Resize, Rotate), a new DIB will be created according to the current DIB.FILE_MAPPING.THRESHOLD and DIB.FILE_MAPPING.PATH values, and will then be processed according to the DIB.FILE_MAPPING.FLUSH_SIZE value at the time of the DIB replacement.

The following example tells ImageGear to use memory mapped files for images whose pixel data size is greater than or equal to 500 MB:

 
Copy Code
// Memory mapping will be used for DIBs with sizes greater than or equal to 500 Mb.
AT_INT fileMappingThreshold = 500;
IG_gctrl_item_set("DIB.FILE_MAPPING.THRESHOLD", AM_TID_INT, &fileMappingThreshold, sizeof(fileMappingThreshold), "");

The following example obtains the current value of the DIB.FILE_MAPPING.THRESHOLD parameter:

 
Copy Code
// Get memory mapping threshold
AT_INT fileMappingThreshold;
IG_gctrl_item_get("DIB.FILE_MAPPING.THRESHOLD", NULL, (LPVOID)&fileMappingThreshold, sizeof(fileMappingThreshold), NULL, NULL, 0, NULL);

The following example tells ImageGear to create temporary memory-mapped files in the current directory:

 
Copy Code
// Use current directory for the memory mapped files
char* szMemoryMappingPath = ".";
IG_gctrl_item_set("DIB.FILE_MAPPING.PATH", AM_TID_MAKELP(AM_TID_CHAR), szMemoryMappingPath, (DWORD)strlen(szMemoryMappingPath) + 1, "");

The following example obtains the directory used for storing memory mapped files:

 
Copy Code
// Get path for memory mapped files
char szMemoryMappingPath[_MAX_PATH];
IG_gctrl_item_get("DIB.FILE_MAPPING.PATH", NULL, (LPVOID)&szMemoryMappingPath, sizeof(szMemoryMappingPath) - 1, NULL, NULL, 0, NULL);

The following example tells ImageGear to set the flush size to 100 Mb:

 
Copy Code
// Memory mapping flush size will be equal to 200 Mb.
AT_INT fileMappingFlushSize = 200;
IG_gctrl_item_set("DIB.FILE_MAPPING.FLUSH_SIZE", AM_TID_INT, &fileMappingFlushSize, sizeof(fileMappingFlushSize), "");

The following example obtains the current flush size:

 
Copy Code
// Get memory mapping flush size
AT_INT fileMappingFlushSize;
IG_gctrl_item_get("DIB.FILE_MAPPING.FLUSH_SIZE", NULL, (LPVOID)&fileMappingFlushSize, sizeof(fileMappingFlushSize), NULL, NULL, 0, NULL);