BITMAPHANDLE (original) (raw)

Summary

The BITMAPHANDLE structure serves as a working area for image manipulation and conversion. LEADTOOLS functions use this structure as a bitmap handle for accessing the image in memory and for maintaining the characteristics of the image.

Note: Fields intended for internal use, such as the pointer to the bitmap, are omitted from the table. For instance, pLUT, pLUT16, PaintLowBit and PaintHighBit are all members that are useful when window-leveling. For more information about using these members when displaying images or performing image processing, refer to Lookup Table (LUT) in BITMAPHANDLE and its use for Displaying Images and Performing Image Processing. If necessary, you can refer to the LTKRN.H header file, which describes the entire structure.

Members

L_UINT uStructSize

Size of this structure in bytes, for versioning. Use the sizeof() operator to calculate this value.

L_INT Width

Image width in pixels.

L_INT Height

Image height in pixels.

L_INT BitsPerPixel

Number of bits per pixel.

L_UINT BytesPerLine

Bytes per line, rounded upward to the nearest multiple of four.

L_BITFIELD Flags.Allocated

TRUE if the bitmap is allocated.

L_BITFIELD Flags.ConventionalMemory

TRUE if the bitmap is allocated using conventional memory.

L_BITFIELD Flags.DiskMemory

TRUE if the bitmap is allocated using LEAD's own virtual memory.

L_BITFIELD Flags.ProgressiveAvailable

TRUE if an image is being loaded from a progressive file (i.e. Progressive JPEG).

L_BITFIELD Flags.LockedMemory

TRUE if the bitmap memory is locked down.

L_BITFIELD Flags.Interlaced

TRUE if an image is being loaded from an interlaced file (i.e. Interlaced GIF).

L_BITFIELD Flags.WaitUserInput

TRUE if the animation playback waits for user input.

L_BITFIELD Flags.Transparency

TRUE if the animation playback uses transparency.

L_BITFIELD Flags.Compressed

TRUE if the current bitmap is in 1-bit RLE-compressed format. For information about this format, refer to Speeding Up 1-Bit Documents.

L_BITFIELD Flags.Signed

TRUE if the pixel values in the bitmap are signed.

L_BITFIELD Flags.Mirror

TRUE if the bitmap is a mirror of another bitmap.

L_BITFIELD Flags.UseLUT

TRUE if the LUT is used in all image processing functions, including save. FALSE if the LUT is used only when painting. If this is FALSE, the LUT is ignored when an image processing function is applied or when a file is saved.

L_BITFIELD Flags.Global

Internal use only.

L_BITFIELD Flags.UsePaintLUT

TRUE to use PaintGamma, PaintContrast, PaintIntensity when painting.

L_BITFIELD Flags.Tiled

TRUE if the bitmap is a tiled bitmap.

L_BITFIELD Flags.SuperCompressed

TRUE if the bitmap is in super compressed format. The bitmap can be 24-bit or 1-bit. For more information, refer to Super Compressed Bitmaps.

L_BITFIELD Flags.NoClip

Internal use only.

L_BITFIELD Flags.PremultiplyAlpha

TRUE if the data is premultiplied with the alpha (for 32-bit bitmaps).

L_BITFIELD Flags.NonLinearLUT

TRUE if the LUT is non-linear (for 12/16-bit grayscale bitmaps).

L_BITFIELD Flags.AlphaBlend

TRUE if the bitmap is part of an animation that should be blended with the previous image using an AlphaBlend operation.

L_BITFIELD Flags.Float

TRUE if the bitmap samples use floating point values. (This is valid only if BitsPerPixel is 32. These bitmaps have limited functionality).

L_INT nColors

Number of colors (256 or less) that the bitmap has. If the image has more than 256 colors, this value is zero.

L_RGBQUAD * pPalette

Array of palette colors.

L_INT ViewPerspective

Where the beginning of the image is stored. Valid values are TOP_LEFT, BOTTOM_LEFT, TOP_RIGHT, BOTTOM_RIGHT, TOP_LEFT90, and TOP_LEFT270. For descriptions, refer to Accounting for View Perspective.

L_INT Order

Color order of the bitmap. Possible values are:

ORDER_RGB
ORDER_BGR
ORDER_GRAY
ORDER_ROMM
ORDER_RGB565

L_UINT32 Size

Deprecated, use the Size64 member.

L_UINT64 Size64

Size of the bitmap image data, in bytes.

L_UINT DitheringMethod

Dithering method (referenced by some functions). For possible values, refer to the L_DefaultDithering function.

L_INT XResolution

Horizontal resolution, in dots per inch. Some file formats save this value in the file header.

L_INT YResolution

Vertical resolution, in dots per inch. Some file formats save this value in the file header.

L_INT Left

Left offset for animation playback.

L_INT Top

Top offset for animation playback, based on a TOP_LEFT view perspective.

L_UINT32 Delay

Animation playback delay in milliseconds (ms).

COLORREF Background

Background color for animation playback. You can specify a COLORREF value, such as the return value of the Windows RGB macro, or you can use the PALETTEINDEX macro to specify a palette color.

COLORREF Transparency

Transparent color for animation playback. You can specify a COLORREF value, such as the return value of the Windows RGB macro, or you can use the PALETTEINDEX macro to specify a palette color.

L_UINT DisposalMethod

Animation playback disposal method. For possible values, refer to Animation Disposal Methods.

L_INT LowBit

Value indicating the low bit used for window leveling. 0 <= nLowBit <= nHighBit <= (11 for 12-bit grayscale or 15 for 16-bit grayscale). A value of -1 will be treated as 0.

L_INT HighBit

Value indicating the high bit used for window leveling. 0 <= nLowBit <= nHighBit <= (11 for 12-bit grayscale or 15 for 16-bit grayscale). A value of -1 will be treated as BitsPerPixel -1.

L_INT32 MinVal

Minimum grayscale value. For every value between 0 and MinVal, Black (RGB(0,0,0)) will be used. For values between MinVal and MaxVal, the gray value to be displayed is calculated by : gray = (index - MinVal) * 255 / (MaxVal - MinVal).(See * below)

L_UINT MaxVal

Maximum grayscale value. For every value larger than MaxVal, White (RGB(255,255,255)) will be used. For values between MinVal and MaxVal, the gray value to be displayed is calculated by : gray = (index - MinVal) * 255 / (MaxVal - MinVal). (See * below)

* index is the intensity value of the pixel. If the intensity value is > MaxVal, the color will be White. If the intensity value is < MinVal, the color will be Black. For those intensity values between MinVal and MaxVal, the above equation is used to determine the color, with index equal to the intensity value.

Comments

pBITMAPHANDLE is a pointer to a BITMAPHANDLE structure. Generally, where a function parameter type is pBITMAPHANDLE, you can declare a BITMAPHANDLE variable, update the structure's fields, and pass the variable's address in the parameter. Declaring a pBITMAPHANDLE variable is necessary only if your program requires a pointer.

Some functions which take this structure as a parameter require that the structure be initialized prior to the function call. You must set the uStructSize member to the total size, in bytes, of the structure. Use the sizeof() operator to calculate this value. Functions that do not require the structure be initialized will take the total size of the structure, in bytes, as an additional function parameter.

In most cases, the values of fields in the BITMAPHANDLE structure are maintained by LEADTOOLS functions.

Notes:

A 16-bpp image may be color or grayscale. If you are working with a 16-bit grayscale image, explicitly set BITMAPHANDLE.Order to ORDER_GRAY. By default, the Order for a 16-bit image will be set to ORDER_BGR.
Tiled bitmaps will have Flags.ConventionalMemory set, since the bitmap is allocated in conventional memory. To determine whether a bitmap is "regular memory", do the following:
if (!pBitmap->Flags.Compressed && !pBitmap->Flags.Tiled)
{
// regular bitmap. It is not compressed and it is not tiled.
}

Support for super compressing bitmaps is available in the Document and Medical Imaging toolkits.

When Flags.NonLinearLUT is set to TRUE, the LEADTOOLS resample functions will resample the LUT index. This is the preferred mechanism for DICOM images. However, if the LUT is not linear (for example if some LUT portions contain some colors while others have grayscale values), painting artifacts might be produced when operating on the index. If the LUT is not linear, LEADTOOLS converts the image data to color 24-bit when painting by using the LUT and then performs the resample/bicubic resize on the 24-bit data. LEADTOOLS sets this value to TRUE automatically when loading DICOM files that contain a 16-bit palette. You should set this to TRUE if you change the LUT manually, or if you change the LUT to be non-linear. Warning: Failure to set this value properly can cause problems with displaying zoomed bitmaps when paint mode is set to resample/bicubic.

When Flags.Float is set to 1, the bitmap uses floating point values. In this situation, the bitmap handle can be used for very few operations. See Working with floating point bitmaps for more details.