L_CreateBitmap

#include "l_bitmap.h"

L_LTKRN_API L_INT L_CreateBitmap(pBitmap, uStructSize, uMemory, uWidth, uHeight, uBitsPerPixel, uOrder, pPalette, uViewPerspective, pData, dwSize)

pBITMAPHANDLE pBitmap;

pointer to the bitmap handle

L_UINT uStructSize;

size of the BITMAPHANDLE structure

L_UINT uMemory;

flag to request the type of memory to allocate

L_UINT uWidth;

width of the bitmap in pixels

L_UINT uHeight;

height of the bitmap in pixels

L_UINT uBitsPerPixel;

number of bits per pixel

L_UINT uOrder;

color order for 16-, 24-, 32, 48, and 64-bit bitmaps

L_RGBQUAD pPalette;

pointer to the palette that the bitmap will use

L_UINT uViewPerspective;

where the beginning of the image is stored

L_UCHAR pData;

data pointer

L_SIZE_T dwSize;

size of the data buffer pointed to by pData

Initializes and allocates a bitmap, without loading any data.

Parameter Description
pBitmap Pointer to the bitmap handle referencing the bitmap to be created.
uStructSize Size in bytes, of the structure pointed to by pBitmap, for versioning. Use sizeof(BITMAPHANDLE).
uMemory Flags that indicate the type of memory to allocate. The following are valid values:
  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_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.
uWidth Width of the bitmap in pixels.
uHeight Height of the bitmap in pixels.
uBitsPerPixel The number of bits per pixel. Valid values are 0, 1, 2, 3, 4, 5, 6, 7, 8, 12, 16, 24, 32, 48, and 64.
  Use 0 to create an 8-bit grayscale bitmap. In that case, the function ignores the uOrder and pPalette parameters.
uOrder Color order for 16-, 24-, 32-, 48- and 64-bit bitmaps. If the resultant bitmap is less than 16 bits per pixel, this will have no effect since palletized images have no order.
  The following are valid values:
  Value Meaning
  ORDER_RGB [0] Red, green, and blue color order in memory
  ORDER_BGR [1] Blue, green, and red color order in memory
  ORDER_GRAY [2] 12 or 16-bit grayscale image. 12 and 16-bit grayscale images are only supported in Document and Medical Imaging toolkits.
  ORDER_ROMM [5] ROMM order in memory. ROMM only supports 24 and 48-bit images.
pPalette Pointer to the palette that the bitmap will use. You can specify your own palette, or use NULL for LEAD's fixed palette.
uViewPerspective Where the beginning of the image is stored. Most file formats start in the lower left corner while some formats start in the upper left corner. For valid values, refer to Accounting for View Perspective.
pData Data pointer that will contain the bitmap data when uMemory is TYPE_USER. This data must be aligned on a four byte boundary. If pData is NULL, the data pointer must be passed later, by calling L_SetBitmapDataPointer, before the bitmap can be used.
dwSize Size of the data buffer pointed to by pData. This should be at least pBitmap->Size. This parameter is only valid when uMemory is set to TYPE_USER.

Returns

SUCCESS

The function was successful.

< 1

An error occurred. Refer to Return Codes.

Comments

Support for 12 and 16-bit grayscale images is only available in the Document and Medical Imaging toolkits.

You can specify 0 bits per pixel to create an 8-bit grayscale bitmap. In that case, the function ignores the uOrder and pPalette parameters.

Creating a bitmap of type TYPE_USER does not allocate memory for the bitmap. Instead, the data pointer pData is used.

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)

If you pass TYPE_USER, you are responsible for freeing the bitmap data. L_FreeBitmap will not do this for you.

Some image processing functions, such as L_RotateBitmap and L_ColorResBitmap, need to re-allocate the image data. If you create a bitmap with TYPE_USER, and pass it to these functions, they will change the bitmap to TYPE_CONV and re-allocate the memory. Your original pData will no longer be used.

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

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_InitBitmap, L_AllocateBitmap, L_FreeBitmapL_GetBitmapYUVDataL_SetBitmapYUVData

Topics:

Raster Image Functions: Creating and Deleting Images

Example

This example loads a temporary bitmap, creates a new bitmap, and copies the temporary bitmap’s image data to the new bitmap.

L_INT CreateBitmapExample(L_VOID) 
{ 
   L_INT nRet; 
   BITMAPHANDLE LeadBitmap;   /* Bitmap handle for the final image */ 
   BITMAPHANDLE TmpBitmap;    /* Bitmap handle for the initial image */ 
   RGBQUAD      Palette[256]; /* Palette for the final image */ 
 
   /* Load a bitmap at 8 bits per pixel so that we can demonstrate palette handling */ 
   nRet = L_LoadBitmap (MAKE_IMAGE_PATH(TEXT("ImageProcessingDemo\\Image3.cmp")), &TmpBitmap, sizeof(BITMAPHANDLE), 8, ORDER_BGR, NULL, NULL); 
   if(nRet !=SUCCESS) 
      return nRet; 
   /* Load the new palette */ 
   nRet = L_GetBitmapColors(&TmpBitmap, 0, 256, Palette); 
   if(nRet !=SUCCESS) 
   { 
      L_FreeBitmap(&TmpBitmap); 
      return nRet; 
   } 
   /* Create the new bitmap */ 
   nRet = L_CreateBitmap(&LeadBitmap, sizeof(BITMAPHANDLE),TYPE_CONV, 
                        TmpBitmap.Width, 
                        TmpBitmap.Height, 
                        TmpBitmap.BitsPerPixel, 
                        TmpBitmap.Order, 
                        Palette, 
                        TmpBitmap.ViewPerspective, NULL, 0); 
   if(nRet !=SUCCESS) 
   { 
      L_FreeBitmap(&TmpBitmap); 
      return nRet; 
   } 
   /* Copy image data to the new bitmap */ 
   nRet = L_CopyBitmapData(&LeadBitmap, &TmpBitmap); 
   if(nRet !=SUCCESS) 
   { 
      L_FreeBitmap(&LeadBitmap); 
      L_FreeBitmap(&TmpBitmap); 
      return nRet; 
   } 
   /* Clean up */ 
   L_FreeBitmap(&TmpBitmap); 
   L_FreeBitmap(&LeadBitmap); 
   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