In This Topic ▼

L_AllocateBitmap

Summary

Allocates storage to hold an image that is referenced by a bitmap handle.

Syntax

#include "l_bitmap.h"

L_LTKRN_API L_INT L_AllocateBitmap(pBitmap, uMemory)

Parameters

pBITMAPHANDLE pBitmap

Pointer to the bitmap handle that describes the bitmap for which to allocate storage.

L_UINT uMemory

Flag to request the type of memory to allocate. Possible Values are:

Value	Meaning
TYPE_CONV	[0x0001] Use conventional memory if the image will fit, otherwise swap to disk.
TYPE_USER	[0x0002] Create a bitmap where the user maintains the data pointer.
TYPE_TILED	[0x0004] Create tiled bitmaps.
TYPE_NOTILED	[0x0008] Do not create tiled bitmaps, even if the conventional memory has failed.
TYPE_DISK	[0x0080] Do not use conventional memory. Swap to disk only.
	Note: If the image is allocated as TYPE_DISK, then the image should not be used in multiple threads.
TYPE_NODISK	[0x0100] Do not swap to disk using LEAD's virtual memory. Windows virtual memory is not affected.
TYPE_COMPRESSED	[0x0200] (Document and Medical Imaging toolkits) Allocate an RLE-compressed bitmap. You can use this flag with TYPE_CONV or TYPE_NODISK. For more information, refer to Speeding Up 1-Bit Documents.
TYPE_SUPERCOMPRESSED	[0x0400] (Document and Medical Imaging toolkits) Keep images compressed in memory. This option causes slow access, but very low memory usage. This option is available for 1-bit, 8-bit grayscale, and 24-bit images only.

Returns

Value	Meaning
SUCCESS	The function was successful.
< 1	An error occurred. Refer to Return Codes.

Comments

The amount allocated depends on the size of the image indicated in the bitmap handle (Width, Height, and BitsPerPixel). L_InitBitmap must be called prior to calling this function.

This is a low-level function that is used only when you create a bitmap from scratch using L_InitBitmap. Normally, the functions that load or create a bitmap allocate the required memory for you. (In that case, calling L_AllocateBitmap causes your application to lose memory.)

The default memory type can only be Conventional or Disk.

If TYPE_USER is set in nMemory, the bitmap is marked as having the data pointer set using L_SetBitmapDataPointer. Freeing this type of bitmap will not free the data pointer set by L_SetBitmapDataPointer.

There is some speed penalty (loss) for accessing tiled bitmaps. Therefore, it is not recommended for use with all bitmaps.

The tiled bitmaps are not used by default. LEADTOOLS will create them only if it failed to create conventional bitmaps and TYPE_NOTILED was not specified.

There are now three distinct types of bitmaps:

a. Conventional (uncompressed and contiguous) This is the most common type.

b. Compressed (1-bit only).

c. Tiled (uncompressed, stored internally as up to 64MB tiles).

Note: If the image is allocated as TYPE_DISK, then the image should not be used in multiple threads.