Bitmap Functions (GDI+)
Windows GDI+ exposes a flat API that consists of about 600 functions, which are implemented in Gdiplus.dll and declared in Gdiplusflat.h. The functions in the GDI+ flat API are wrapped by a collection of about 40 C++ classes. It is recommended that you do not directly call the functions in the flat API. Whenever you make calls to GDI+, you should do so by calling the methods and functions provided by the C++ wrappers. Microsoft Product Support Services will not provide support for code that calls the flat API directly. For more information on using these wrapper methods, see GDI+ Flat API.
The following flat API functions are wrapped by the Bitmap C++ class.
Bitmap Functions and Corresponding Wrapper Methods
| Flat function | Wrapper method | Description |
|---|---|---|
| GpStatus WINGDIPAPI GdipCreateBitmapFromStream(IStream* stream, GpBitmap **bitmap) | Bitmap::Bitmap | Creates a Bitmap::Bitmap object based on a stream. This function does not use Image Color Management (ICM). It is called when the useEmbeddedColorManagement parameter of the Bitmap::Bitmap constructor is set to FALSE. |
| GpStatus WINGDIPAPI GdipCreateBitmapFromFile(GDIPCONST WCHAR* filename, GpBitmap **bitmap) | Bitmap::Bitmap | Creates a Bitmap::Bitmap object based on an image file. This function does not use ICM. It is called when the useEmbeddedColorManagement parameter of the Bitmap::Bitmap constructor is set to FALSE. |
| GpStatus WINGDIPAPI GdipCreateBitmapFromStreamICM(IStream* stream, GpBitmap **bitmap) | Bitmap::Bitmap | Creates a Bitmap::Bitmap object based on a stream. This function uses ICM. It is called when the useEmbeddedColorManagement parameter of the Bitmap::Bitmap constructor is set to TRUE. |
| GpStatus WINGDIPAPI GdipCreateBitmapFromFileICM(GDIPCONST WCHAR* filename, GpBitmap **bitmap) | Bitmap::Bitmap | Creates a Bitmap::Bitmap object based on an image file. This function uses ICM. It is called when the useEmbeddedColorManagement parameter of the Bitmap::Bitmap constructor is set to TRUE. |
| GpStatus WINGDIPAPI GdipCreateBitmapFromScan0(INT width, INT height, INT stride, PixelFormat format, BYTE* scan0, GpBitmap** bitmap) | Bitmap::Bitmap | Creates a Bitmap::Bitmap object based on an array of bytes along with size and format information. |
| GpStatus WINGDIPAPI GdipCreateBitmapFromGraphics(INT width, INT height, GpGraphics* target, GpBitmap** bitmap) | Bitmap::Bitmap | Creates a Bitmap::Bitmap object based on a Graphics object, a width, and a height. |
| GpStatus WINGDIPAPI GdipCreateBitmapFromDirectDrawSurface(IDirectDrawSurface7* surface, GpBitmap** bitmap) | Bitmap::Bitmap | Creates a Bitmap::Bitmap object based on a DirectDraw surface. The Bitmap::Bitmap object maintains a reference to the DirectDraw surface until the Bitmap::Bitmap object is deleted or goes out of scope. |
| GpStatus WINGDIPAPI GdipCreateBitmapFromGdiDib(GDIPCONST BITMAPINFO* gdiBitmapInfo, VOID* gdiBitmapData, GpBitmap** bitmap) | Bitmap::Bitmap | Creates a Bitmap::Bitmap object based on a BITMAPINFO structure and an array of pixel data. |
| GpStatus WINGDIPAPI GdipCreateBitmapFromHBITMAP(HBITMAP hbm, HPALETTE hpal, GpBitmap** bitmap) | Bitmap::Bitmap | Creates a Bitmap::Bitmap object based on a handle to a Windows Windows Graphics Device Interface (GDI) bitmap and a handle to a GDI palette. |
| GpStatus WINGDIPAPI GdipCreateHBITMAPFromBitmap(GpBitmap* bitmap, HBITMAP* hbmReturn, ARGB background) | Bitmap::GetHBITMAP | The Bitmap::GetHBITMAP method creates a GDI bitmap from this Bitmap object. |
| GpStatus WINGDIPAPI GdipCreateBitmapFromHICON(HICON hicon, GpBitmap** bitmap) | Bitmap::Bitmap | Creates a Bitmap object based on an icon. |
| GpStatus WINGDIPAPI GdipCreateHICONFromBitmap(GpBitmap* bitmap, HICON* hbmReturn) | Bitmap::GetHICON | The Bitmap::GetHICON method creates an icon from this Bitmap object. |
| GpStatus WINGDIPAPI GdipCreateBitmapFromResource(HINSTANCE hInstance, GDIPCONST WCHAR* lpBitmapName, GpBitmap** bitmap) | Bitmap::Bitmap | Creates a Bitmap::Bitmap object based on an application or DLL instance handle and the name of a bitmap resource. |
| GpStatus WINGDIPAPI GdipCloneBitmapArea(REAL x, REAL y, REAL width, REAL height, PixelFormat format, GpBitmap *srcBitmap, GpBitmap **dstBitmap) | Bitmap::Clone | The Bitmap::Clone method creates a new Bitmap object by copying a portion of this bitmap. |
| GpStatus WINGDIPAPI GdipCloneBitmapAreaI(INT x, INT y, INT width, INT height, PixelFormat format, GpBitmap *srcBitmap, GpBitmap **dstBitmap) | Bitmap::Clone | The Bitmap::Clone method creates a new Bitmap object by copying a portion of this bitmap. |
| GpStatus WINGDIPAPI GdipBitmapLockBits(GpBitmap* bitmap, GDIPCONST GpRect* rect, UINT flags, PixelFormat format, BitmapData* lockedBitmapData) | Bitmap::LockBits | The Bitmap::LockBits method locks a rectangular portion of this bitmap and provides a temporary buffer that you can use to read or write pixel data in a specified format. Any pixel data that you write to the buffer is copied to the Bitmap object when you call Bitmap::UnlockBits. |
| GpStatus WINGDIPAPI GdipBitmapUnlockBits(GpBitmap* bitmap, BitmapData* lockedBitmapData) | Bitmap::UnlockBits | The Bitmap::UnlockBits method unlocks a portion of this bitmap that was previously locked by a call to Bitmap::LockBits. |
| GpStatus WINGDIPAPI GdipBitmapGetPixel(GpBitmap* bitmap, INT x, INT y, ARGB *color) | Bitmap::GetPixel | The Bitmap::GetPixel method gets the color of a specified pixel in this bitmap. |
| GpStatus WINGDIPAPI GdipBitmapSetPixel(GpBitmap* bitmap, INT x, INT y, ARGB color) | Bitmap::SetPixel | The Bitmap::SetPixel method sets the color of a specified pixel in this bitmap. |
| GpStatus WINGDIPAPI GdipBitmapSetResolution(GpBitmap* bitmap, REAL xdpi, REAL ydpi) | Bitmap::SetResolution | The Bitmap::SetResolution method sets the resolution of this Bitmap object. |
| GpStatus WINGDIPAPI GdipBitmapConvertFormat(IN GpBitmap *pInputBitmap, PixelFormat format, DitherType dithertype, PaletteType palettetype, ColorPalette *palette, REAL alphaThresholdPercent) | Bitmap::ConvertFormat | The Bitmap::ConvertFormat method converts a bitmap to a specified pixel format. The original pixel data in the bitmap is replaced by the new pixel data. |
| GpStatus WINGDIPAPI GdipInitializePalette(OUT ColorPalette *palette, PaletteType palettetype, INT optimalColors, BOOL useTransparentColor, GpBitmap *bitmap) | Bitmap::InitializePalette | The Bitmap::InitializePalette method initializes a standard, optimal, or custom color palette. |
| GpStatus WINGDIPAPI GdipBitmapApplyEffect(GpBitmap* bitmap, CGpEffect *effect, RECT *roi, BOOL useAuxData, VOID **auxData, INT *auxDataSize) | Bitmap::ApplyEffect | The Bitmap::ApplyEffect method alters this Bitmap object by applying a specified effect. |
| GpStatus WINGDIPAPI GdipBitmapCreateApplyEffect(GpBitmap **inputBitmaps, INT numInputs, CGpEffect *effect, RECT *roi, RECT *outputRect, GpBitmap **outputBitmap, BOOL useAuxData, VOID **auxData, INT *auxDataSize) | Bitmap::ApplyEffect | The Bitmap::ApplyEffect method creates a new Bitmap object by applying a specified effect to an existing Bitmap object. |
| GpStatus WINGDIPAPI GdipBitmapGetHistogram(GpBitmap* bitmap, IN HistogramFormat format, IN UINT NumberOfEntries, OUT UINT *channel0, OUT UINT *channel1, OUT UINT *channel2, OUT UINT *channel3) | Bitmap::GetHistogram | The Bitmap::GetHistogram method returns one or more histograms for specified color channels of this Bitmap object. |
| GpStatus WINGDIPAPI GdipBitmapGetHistogramSize(IN HistogramFormat format, OUT UINT *NumberOfEntries) | Bitmap::GetHistogramSize | The Bitmap::GetHistogramSize returns the number of elements (in an array of UINTs) that you must allocate before you call the Bitmap::GetHistogram method of a Bitmap object. |
| Status __stdcall GdipCreateEffect(const GUID guid, CGpEffect **effect) | Effect | The constructors of all descendants of the Effect class call GdipCreateEffect. For example, the Blur constructor makes the following call: GdipCreateEffect(BlurEffectGuid, &nativeEffect); BlurEffectGuid is a constant defined in Gdipluseffects.h. |
| Status __stdcall GdipDeleteEffect(CGpEffect *effect) | virtual ~Effect() | Cleans up resources used by a Bitmap object. |
| Status __stdcall GdipGetEffectParameterSize(CGpEffect *effect, UINT *size) | Effect::GetParameterSize | The Effect::GetParameterSize method gets the total size, in bytes, of the parameters currently set for this Effect. The Effect::GetParameterSize method is usually called on an object that is an instance of a descendant of the Effect class. |
| Status __stdcall GdipSetEffectParameters(CGpEffect *effect, const VOID *params, const UINT size) | Effect | Each descendant of the Effect class has a SetParameters method that calls the protected method Effect::SetParameters, which in turn calls GdipSetEffectParameters. For example, the Blur::SetParameters method makes the following call: Effect::SetParameters(parameters, size). |
| Status __stdcall GdipGetEffectParameters(CGpEffect *effect, UINT *size, VOID *params) | Effect | Each descendant of the Effect class has a GetParameters method that calls the protected method Effect::GetParameters, which in turn calls GdipSetEffectParameters. For example, the Blur::GetParameters method makes the following call: Effect::GetParameters(parameters, size). |
| GpStatus WINGDIPAPI GdipTestControl(GpTestControlEnum control, void * param) | Not called by wrappers | Used for internal testing of GDI+. Specifies changes in image-processing behavior. The meaning of the param parameter varies depending on the value passed in the control parameter. If the control parameter is set to TestControlForceBilinear, param points to a value of type BOOL. If that value is TRUE and the current interpolation mode is anything other than InterpolationModeNearestNeighbor, then the InterpolationModeBilinear algorithm is used. If the value pointed to by param is FALSE or if the current interpolation mode is InterpolationModeNearestNeighbor, then the behavior of GDI+ is unchanged. If the control parameter is set to TestControlNoICM, param points to a value of type BOOL. If that value is TRUE, then ICM profiles are ignored when images are loaded into memory. If the value pointed to by param is FALSE, then the behavior of GDI+ is unchanged. If the control parameter is set to TestControlGetBuildNumber, param is an output parameter that points to a 32-bit integer variable. That variable receives the GDI+ build number. GdipTestControl is not thread-safe; it assumes that there is only one thread using GDI+. If you call GdipTestControl in a multithreaded environment, the results are unpredictable. The GpTestControlEnum enumeration has three elements: TestControlForceBilinear = 0, TestControlNoICM = 1, and TestControlGetBuildNumber = 2. |