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.

Optional:

• Enable the progress bar: In the sample, go to Main > Settings > Progress Bar. Note that ImageGear display operations do not trigger the progress bar.
• Optimize image display time: If you are not particularly interested in fine display for large images, you can turn the display interpolation off (after the image has been loaded). This will result in much faster image display. In the sample, go to Main > View > Anti-aliasing, and uncheck the Color Antialiasing and Use Resampling check boxes.

Enabling Large Image Support

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

• DIB.FILE_MAPPING.THRESHOLD. Specifies minimum DIB size, in megabytes, for which the memory mapped file shall be used. DIBs that are smaller than this threshold are allocated in physical memory. By default, this parameter is set to 0, which means that the use of memory mapped files is disabled. 1-bit images are always allocated in the physical memory and are not affected by this parameter.
• DIB.FILE_MAPPING.PATH. Specifies the path to a folder where memory mapped files will be stored. Memory mapped files are temporary files that are created upon DIB creation and deleted upon its deletion. By default, this parameter is set to an empty string, which means that ImageGear will use the system temporary folder for memory mapped files. This parameter is only used when the DIB.FILE_MAPPING.THRESHOLD parameter value is greater than 0. Does not affect 1-bit images.

  For the best performance, use a separate SSD drive or hard drive for storing memory mapped files, and make sure that the operating system and other applications do not use this drive.

• DIB.FILE_MAPPING.FLUSH_SIZE. Specifies the maximum size of a memory block in a DIB that can be processed without flushing the memory mapped file. The default value is 200 Mb, which shall be efficient on typical systems that have 4 Gb of RAM. Greater values may improve performance on systems that have a larger amount of RAM. However, making this value too big (comparable to RAM size) will impact the system responsiveness and may lead to allocation failure for large DIBs. This parameter is only used when the DIB.FILE_MAPPING.THRESHOLD parameter is greater than 0. Does not affect 1-bit images.

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:

// 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:

// 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:

// 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:

// 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:

// 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:

// 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);