L_AllocateBitmap

#include "l_bitmap.h"

L_LTKRN_API L_INT L_AllocateBitmap(pBitmap, uMemory)

pBITMAPHANDLE pBitmap;

/* pointer to the bitmap */

L_UINT uMemory;

/* flag for the type of memory to allocate */

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

Parameter

Description

pBitmap

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

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.

 

TYPE_NODISK

[0x0100] Do not swap to disk using LEAD's virtual memory. Windows virtual memory is not affected.

 

TYPE_COMPRESSED

[0x0200] (Document/Medical only) 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/Medical only) 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

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.)

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)

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

Windows 2000 / XP/Vista, Windows CE.

See Also

Functions:

L_CreateBitmap, L_InitBitmap, L_FreeBitmap

Topics:

Raster Image Functions: Creating and Deleting Images

Example

For a short example, refer to L_ResizeBitmap. For complete sample code, refer to the FEATURE1 example.