LMemoryFile::SetMemoryThresholds

Summary

Sets the memory restrictions for allocating bitmaps.

Syntax

static L_INT LMemoryFile::SetMemoryThresholds(nTiledThreshold, nMaxConvSize, nTileSize, nConvTiles, nConvBuffers, uFlags)

Parameters

L_INT nTiledThreshold

Minimum amount of free memory required to allow the allocation of conventional bitmaps (default 0). If the amount of free memory falls below this threshold, all bitmaps will be allocated as tiled. The exception is when the bitmap size is smaller than the tile size in this case, the bitmap will be allocated in conventional memory.

Values less than 100 are not allowed.

If this parameter is > 0, it represents the required number of free bytes.

If the parameter is 0, then there is no minimum requirement for free memory, all bitmaps are allocated as conventional if there is enough memory.

Tiled bitmaps use a combination of memory tiles and disk tiles. When a bitmap is allocated, LEADTOOLS decides how many conventional memory tiles and how many disk tiles should be allocated. This parameter influences the number of conventional tiles allocated as follows: the toolkit will not allocate any more conventional tiles when the amount of memory falls below nTiledThreshold. When the amount of memory falls below nTiledThreshold, disk tiles will be allocated and several swap buffers might back these disk tiles. For each bitmap there will be at least one swap tile.

If this parameter is < 0, then it represents a percentage of free memory out of the total memory. For example, when you pass 20, tiled bitmaps will be used when the amount of free physical and swap memory will drop below 20% of the total memory.

This parameter is ignored if uFlags does not contain MEM_TILEDTHRESHOLD.

L_INT nMaxConvSize

Maximum size for a conventional bitmap (default is 0x7FFFFFFF). Any bitmaps with a size bigger than this will be allocated as tiled.

If this parameter is >0, then it represents the maximum size in bytes.

If the parameter is <0, then it represents the maximum size in percentage of the total memory (physical and swap).

Values less than 100 are not allowed.

This parameter is ignored if uFlags does not contain MEM_MAXCONVSIZE.

L_INT nTileSize

The size of the tile for tiled bitmaps (default 0). Pass a value smaller than nMaxConvSize.

All bitmaps with a size smaller than nTileSize will be allocated as conventional. (A tiled bitmap of a size smaller than nTileSize would consist of only small tile, which is the equivalent of the conventional bitmap).

If nTileSize is 0, then LEADTOOLS will pick a default size for the tile. (Currently it is 16MB)

The tiles will be smaller than this value and will be a complete number of rows. No rows will be split between tiles.

Values less than 0 are not allowed.

This parameter is ignored if uFlags does not contain MEM_TILESIZE.

L_INT nConvTiles

This is used when working with a tiled image. It represents the maximum number of tiles that will reside in conventional memory at any time. The tiles that do not reside in conventional memory will be on disk. (Default is 100 = all tiles are in memory)

If the value is >0, then this parameter represents the number of tiles.

If 0, then all the tiles in a tiled bitmap will be disk tiles.

If the value is < 0, then this parameter represents the percentage of tiles that will reside in memory.

Values less than -100 are not allowed.

This parameter is ignored if uFlags does not contain MEM_CONVTILES.

L_INT nConvBuffers

This is used when working with tiled images which have disk tiles. It represents the number of buffers in conventional memory that will cache the disk tiles. The swap buffers will greatly improve the access to these disk tiles. The default is 1 (one swap buffer will be used to cache the disk tiles).

This parameter specifies how many buffers should be used:

• >0, nConvBuffers indicates the number of swap buffers.
• <0, -nConvBuffers indicates the percentage of the total of disk tiles. For example, -50 means the number of buffers is half of the disk tiles will be used.
• 0, no swap buffers will be used. This uses the least amount of memory.

It is useful to have more than one swap buffer when you have an algorithm that constantly reads data going up and down. Usually, the data is read in one direction (from top to bottom or bottom to top) in this case, one swap buffer will be enough. Also, if you only view a certain portion of the image, you might benefit from having enough swap buffers to cache the visible portion of the image (or the bitmaps region).

The buffers are dynamic: when data is being read/written to a disk tile, a cache buffer is created (if permitted and there is enough memory). If the maximum number of cache buffers for that bitmap has been reached, the cache buffer for the last used tile will be deleted and used for the new tile.

L_UINT uFlags

A combination of flags that indicates which of the threshold parameters are valid. You can use a bitwise OR ( | ) to combine flags to change only some of the flags, or you can pass MEM_ALL to change all flags. Possible values are:

Returns

Comments

These are global settings and apply to the current thread. They will apply to bitmaps created in this thread after this function is called.

Required DLLs and Libraries

• LTFIL
• File format DLLs
• For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Win32, x64.

See Also

Functions

• LFileSettings::SetTempDirectory
• LFileSettings::GetTempDirectory
• Class Members

Topics

• Memory Storage Types for Bitmaps
• Raster Image Functions: Creating and Deleting Images

Example

Allocate tiled bitmaps when more than 75% of the computer memory is used, or for bitmaps larger than 100MB.

L_INT LMemoryFile__SetMemoryThresholdsExample() 
{ 
   return LMemoryFile::SetMemoryThresholds(-25, 100 *1024 * 1024, 0, 0, 0, MEM_TILEDTHRESHOLD | MEM_MAXCONVSIZE); 
}