LMemoryFile::SetMemoryThresholds

#include "ltwrappr.h"

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

L_INT nTiledThreshold;

/* minimum free memory for allocating conventional memory bitmaps */

L_INT nMaxConvSize;

/* maximum size for conventional bitmaps */

L_INT nTileSize;

/* size of the tile for tiled bitmaps */

L_INT nConvTiles;

/* maximum number of tiles which will reside in memory at one time */

L_INT nConvBuffers;

/* number of buffers in conventional memory that will cache the disk tiles */

L_UINT uFlags;

/* flags indicating which parameters are valid */

Sets the memory restrictions for allocating bitmaps.

Parameter

Description

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.

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.

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.

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.

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.

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:

 

Value

Meaning

 

MEM_TILEDTHRESHOLD

[0x0001] The nTiledThreshold parameter is valid.

 

MEM_MAXCONVSIZE

[0x0002] The nMaxConvSize parameter is valid

 

MEM_TILESIZE

[0x0004] The nTileSize parameter is valid

 

MEM_CONVTILES

[0x0008] The nConvTiles parameter is valid

 

MEM_CONVBUFFERS

[0x0010] The nConvBuffers parameter is valid.

 

MEM_ALL

[0x001F] All parameters are valid. You do not need to bitwise OR ( | ) this with the other flags

Returns

SUCCESS

The function was successful.

< 1

An error occurred. Refer to Return Codes.

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.

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