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