L_SetMemoryThresholds

#include "l_bitmap.h"

L_LTKRN_API L_INT L_SetMemoryThresholds(nTiledThreshold, nMaxConvSize, nTileSize, nConvTiles, nConvBuffers, uFlags);

L_INT nTiledThreshold;

minimum free memory for allocating conventional memory bitmaps

L_SSIZE_T nMaxConvSize;

maximum size for conventional bitmaps

L_SSIZE_T 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. The flags can be or-ed together 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] nTiledThreshold is valid.
  MEM_MAXCONVSIZE [0x0002] nMaxConvSize is valid
  MEM_TILESIZE [0x0004] nTileSize is valid
  MEM_CONVTILES [0x0008] - nConvTiles is valid
  MEM_CONVBUFFERS [0x0010] nConvBuffers is valid.
  MEM_ALL [0x001F] all parameters are valid. You do not need to 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

LTKRN

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, Linux.

See Also

Functions:

L_GetMemoryThresholds, L_GetBitmapMemoryInfo, L_SetBitmapMemoryInfo, L_SetTempDirectory, L_GetTempDirectory

Topics:

Memory Storage Types for Bitmaps

 

Raster Image Functions: Creating and Deleting Images

Example

L_INT SetMemoryThresholdsExample(L_VOID) 
{ 
   L_INT nRet; 
   /* Allocate tiled bitmaps when more than 75% of the computer memory is used, or for bitmaps larger than 100MB. */ 
   nRet = L_SetMemoryThresholds(-25, 100 *1024 * 1024, 0, 0, 0, MEM_TILEDTHRESHOLD | MEM_MAXCONVSIZE); 
   if(nRet != SUCCESS) 
      return nRet; 
   return SUCCESS; 
} 
Help Version 20.0.2018.7.30
Products | Support | Contact Us | Copyright Notices
© 1991-2018 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Raster Imaging C API Help