00001 /** \file
00002 * \brief Windows DIB (Device Independent Bitmap)
00003 *
00004 * See Copyright Notice in im_lib.h
00005 */
00006
00007 #ifndef __IM_DIB_H
00008 #define __IM_DIB_H
00009
00010 #if defined(__cplusplus)
00011 extern "C" {
00012 #endif
00013
00014
00015 /** \defgroup dib Windows DIB
00016 *
00017 * \par
00018 * Windows DIBs in memory are handled just like a BMP file without the file header. \n
00019 * These functions will work only in Windows. They are usefull for interchanging data
00020 * with the clipboard, with capture drivers, with the AVI and WMF file formats and others.
00021 * \par
00022 * Supported DIB aspects:
00023 * \li bpp must be 1, 4, 8, 16, 24, or 32.
00024 * \li BITMAPV4HEADER or BITMAPV5HEADER are handled but ignored. \n
00025 * \li BITMAPCOREHEADER is not handled .
00026 * \li BI_JPEG and BI_PNG compressions are not handled.
00027 * \li biHeight can be negative, compression can be RLE only if created
00028 * from imDibCreateReference, imDibPasteClipboard, imDibLoadFile.
00029 * \li can not encode/decode Images to/from RLE compressed Dibs.
00030 * \li if working with RLE Dibs bits_size is greatter than used.
00031 * \li the resolution of a new Dib is taken from the screen.
00032 * \li SetDIBitsToDevice(start_scan is 0, scan_lines is dib->bmih->biHeight).
00033 * \li StretchDIBits(use always DIB_RGB_COLORS).
00034 * \li CreateDIBPatternBrushPt(packed_dib is dib->dib).
00035 * \par
00036 * Must include <windows.h> before using these functions. \n
00037 * Check <wingdi.h> for structures and definitions.
00038 * \par
00039 * See \ref im_dib.h
00040 * \ingroup util */
00041
00042
00043 /** \brief Windows DIB Structure
00044 *
00045 * \par
00046 * Handles a DIB in memory. \n
00047 * The DIB is stored in only one buffer.
00048 * The secondary members are pointers to the main buffer.
00049 * \ingroup dib */
00050 typedef struct _imDib
00051 {
00052 HGLOBAL handle; /**< The windows memory handle */
00053 BYTE* dib; /**< The DIB as it is defined in memory */
00054 int size; /**< Full size in memory */
00055
00056 BITMAPINFO* bmi; /**< Bitmap Info = Bitmap Info Header + Palette */
00057 BITMAPINFOHEADER* bmih; /**< Bitmap Info Header */
00058 RGBQUAD* bmic; /**< Bitmap Info Colors = Palette */
00059 BYTE* bits; /**< Bitmap Bits */
00060
00061 int palette_count; /**< number of colors in the palette */
00062 int bits_size; /**< size in bytes of the Bitmap Bits */
00063 int line_size; /**< size in bytes of one line, includes padding */
00064 int pad_size; /**< number of bytes remaining in the line, lines are in a word boundary */
00065
00066 int is_reference; /**< only a reference, do not free pointer */
00067 } imDib;
00068
00069 /** Creates a new DIB. \n
00070 * use bpp=-16/-32 to allocate space for BITFLIEDS.
00071 * \ingroup dib */
00072 imDib* imDibCreate(int width, int height, int bpp);
00073
00074 /** Duplicates the DIB contents in a new DIB.
00075 * \ingroup dib */
00076 imDib* imDibCreateCopy(const imDib* dib);
00077
00078 /** Creates a DIB using an already allocated memory. \n
00079 * "bmi" must be a pointer to BITMAPINFOHEADER. \n
00080 * "bits" can be NULL if it is inside "bmi" after the palette.
00081 * \ingroup dib */
00082 imDib* imDibCreateReference(BYTE* bmi, BYTE* bits);
00083
00084 /** Creates a DIB section for drawing porposes. \n
00085 * Returns the image handle also created.
00086 * \ingroup dib */
00087 imDib* imDibCreateSection(HDC hDC, HBITMAP *image, int width, int height, int bpp);
00088
00089 /** Destroy the DIB
00090 * \ingroup dib */
00091 void imDibDestroy(imDib* dib);
00092
00093 /** DIB GetPixel function definition. \n
00094 * the DWORD is a raw copy of the bits, use (unsigned char*)&pixel
00095 * \ingroup dib */
00096 typedef unsigned int (*imDibLineGetPixel)(unsigned char* line, int col);
00097
00098 /** Returns a function to read pixels from a DIB line.
00099 * \ingroup dib */
00100 imDibLineGetPixel imDibLineGetPixelFunc(int bpp);
00101
00102 /** DIB SetPixel function definition
00103 * \ingroup dib */
00104 typedef void (*imDibLineSetPixel)(unsigned char* line, int col, unsigned int pixel);
00105
00106 /** Returns a function to write pixels into a DIB line.
00107 * \ingroup dib */
00108 imDibLineSetPixel imDibLineSetPixelFunc(int bpp);
00109
00110 /** Creates a DIB from a image handle and a palette handle.
00111 * \ingroup dib */
00112 imDib* imDibFromHBitmap(const HBITMAP image, const HPALETTE hPalette);
00113
00114 /** Creates a image handle from a DIB.
00115 * \ingroup dib */
00116 HBITMAP imDibToHBitmap(const imDib* dib);
00117
00118 /** Returns a Logical palette from the DIB palette. \n
00119 * DIB bpp must be <=8.
00120 * \ingroup dib */
00121 HPALETTE imDibLogicalPalette(const imDib* dib);
00122
00123 /** Captures the screen into a DIB.
00124 * \ingroup dib */
00125 imDib* imDibCaptureScreen(int x, int y, int width, int height);
00126
00127 /** Transfer the DIB to the clipboard. \n
00128 * "dib" pointer can not be used after, or use imDibCopyClipboard(imDibCreateCopy(dib)).
00129 * Warning: Clipboard functions in C++ can fail with Visual C++ /EHsc (Enable C++ Exceptions)
00130 * \ingroup dib */
00131 void imDibCopyClipboard(imDib* dib);
00132
00133 /** Creates a reference for the DIB in the clipboard if any. Returns NULL otherwise.
00134 * Warning: Clipboard functions in C++ can fail with Visual C++ /EHsc (Enable C++ Exceptions)
00135 * \ingroup dib */
00136 imDib* imDibPasteClipboard(void);
00137
00138 /** Checks if there is a dib at the clipboard.
00139 * \ingroup dib */
00140 int imDibIsClipboardAvailable(void);
00141
00142 /** Saves the DIB into a file ".bmp".
00143 * \ingroup dib */
00144 int imDibSaveFile(const imDib* dib, const char* filename);
00145
00146 /** Creates a DIB from a file ".bmp".
00147 * \ingroup dib */
00148 imDib* imDibLoadFile(const char* filename);
00149
00150 /** Converts a DIB into an RGBA image. alpha is optional. bpp must be >8. \n
00151 * alpha is used only when bpp=32.
00152 * \ingroup dib */
00153 void imDibDecodeToRGBA(const imDib* dib, unsigned char* red, unsigned char* green, unsigned char* blue, unsigned char* alpha);
00154
00155 /** Converts a DIB into an indexed image. bpp must be <=8. colors must have room for at least 256 colors.
00156 * colors is rgb packed (RGBRGBRGB...)
00157 * \ingroup dib */
00158 void imDibDecodeToMap(const imDib* dib, unsigned char* map, long* palette);
00159
00160 /** Converts an RGBA image into a DIB. alpha is optional. bpp must be >8. \n
00161 * alpha is used only when bpp=32.
00162 * \ingroup dib */
00163 void imDibEncodeFromRGBA(imDib* dib, const unsigned char* red, const unsigned char* green, const unsigned char* blue, const unsigned char* alpha);
00164
00165 /** Converts an indexed image into a DIB. bpp must be <=8. \n
00166 * colors is rgb packed (RGBRGBRGB...)
00167 * \ingroup dib */
00168 void imDibEncodeFromMap(imDib* dib, const unsigned char* map, const long* palette, int palette_count);
00169
00170 /** Converts a IM_RGB packed image, with or without alpha, into a DIB.
00171 * \ingroup dib */
00172 void imDibEncodeFromBitmap(imDib* dib, const unsigned char* data);
00173
00174 /** Converts a DIB into IM_RGB packed image, with or without alpha.
00175 * \ingroup dib */
00176 void imDibDecodeToBitmap(const imDib* dib, unsigned char* data);
00177
00178 #ifdef __IM_IMAGE_H
00179 /* You must include "im_image.h" before this header to enable these declarations. */
00180
00181 /** Creates a imImage from the dib data.
00182 * \ingroup dib */
00183 imImage* imDibToImage(const imDib* dib);
00184
00185 /** Creates a Dib from the image. It must be a bitmap image.
00186 * \ingroup dib */
00187 imDib* imDibFromImage(const imImage* image);
00188
00189 #endif
00190
00191 #if defined(__cplusplus)
00192 }
00193 #endif
00194
00195 #endif