CachedBitmap Functions (GDI+)

A CachedBitmap object stores a bitmap in a format that is optimized for display on a particular device. To display a cached bitmap, call the GdipDrawCachedBitmap function.
 

Return Values

If the function succeeds, it returns Ok, which is an element of the Status enumeration.

 

If the function fails, it returns one of the other elements of the Status enumeration.

GdipCreateCachedBitmap

Description

Creates a CachedBitmap object based on a Bitmap object and a Graphics object. The cached bitmap takes the pixel data from the Bitmap object and stores it in a format that is optimized for the display device associated with the Graphics object.

Syntax

GpStatus WINGDIPAPI GdipCreateCachedBitmap(

    GpBitmap *bitmap,

    GpGraphics *graphics,

    GpCachedBitmap **cachedBitmap

);

PowerBASIC Syntax

DECLARE FUNCTION GdipCreateCachedBitmap ( _

    BYVAL pbitmap AS DWORD, _

    BYVAL graphics AS DWORD, _

    BYREF cachedBitmap AS DWORD _

) AS LONG

Parameters

bitmap

[in] Pointer to a Bitmap object that contains the pixel data to be optimized.

graphics

[in] Pointer to a Graphics object that is associated with a display device for which the image will be optimized.

cachedBitmap

[out] Pointer to a DWORD variable that receives a pointer to the new created CachedBitmap object.

Remarks

You can display a cached bitmap by passing the address of a CachedBitmap object to the GdipDrawCachedBitmap function.

GdipDeleteCachedBitmap

Description

Deletes a CachedBitmap object.

Syntax

GpStatus WINGDIPAPI GdipDeleteCachedBitmap(

   GpCachedBitmap *cachedBitmap

);

PowerBASIC Syntax

DECLARE FUNCTION GdipDeleteCachedBitmap ( _

    BYVAL cachedBitmap AS DWORD _

) AS LONG

Parameters

cachedBitmap

[in] Pointer to a CachedBitmap object.

GdipDrawCachedBitmap

Description

Draws the image stored in a CachedBitmap object.

Syntax

GpStatus WINGDIPAPI GdipDrawCachedBitmap(

    GpGraphics *graphics,

    GpCachedBitmap *cachedBitmap,

    INT x,

    INT y

);

PowerBASIC Syntax

DECLARE FUNCTION GdipDrawCachedBitmap ( _

    BYVAL graphics AS DWORD, _

    BYVAL cachedBitmap AS DWORD, _

    BYVAL x AS LONG, _

    BYVAL y AS LONG _

) AS LONG

Parameters

graphics

[in] Pointer to a Graphics object.

cachedBitmap

[in] Pointer to a CachedBitmap object that contains the image to be drawn.

x

[in] Long integer value that specifies the x-coordinate of the upper-left corner of the image.

y

[in] Long integer value that specifies the y-coordinate of the upper-left corner of the image.

Remarks

A CachedBitmap object stores an image in a format that is optimized for a particular display screen. You cannot draw a cached bitmap to a printer or to a metafile.

Cached bitmaps will not work with any transformations other than translation.

When you construct a CachedBitmap object, you must pass the address of a Graphics object to the GdipCreateCachedBitmap function. If the screen associated with that Graphics object has its bit depth changed after the cached bitmap is constructed, then the GdipDrawCachedBitmap function will fail, and you should reconstruct the cached bitmap. Alternatively, you can hook the display change notification message and reconstruct the cached bitmap at that time.

GdipEmfToWmfBits

Description

Converts an enhanced-format metafile to a Microsoft® Windows® Metafile Format (WMF) metafile and stores the converted records in a specified buffer.

Syntax

UINT WINGDIPAPI GdipEmfToWmfBits(

    HENHMETAFILE hemf,

    UINT cbData16,

    LPBYTE pData16,

    INT iMapMode,

    INT eFlags

);

PowerBASIC Syntax

DECLARE FUNCTION GdipEmfToWmfBits ( _

    BYVAL hemf AS DWORD, _

    BYVAL cbData16 AS DWORD, _

    BYREF pData16 AS ANY, _

    BYVAL iMapMode AS LONG, _

    BYVAL eFlags AS LONG _

) AS DWORD

Parameters

hemf

[in] Handle to the enhanced-format metafile that is to be converted.

cbData16

[in] Unsigned integer that specifies the number of bytes in the buffer pointed to by the pData16 parameter.

pData16

[out] Pointer to a buffer that receives the converted records. If pData16 is NULL, GdipEmfToWmfBits returns the number of bytes required to store the converted metafile records.

iMapMode

[in] Specifies the mapping mode to use in the converted metafile. For a list of possible mapping modes, see SetMapMode. The default value is MM_ANISOTROPIC.

eFlags

[in] Element of the EmfToWmfBitsFlags enumeration that specifies options for the conversion. The default value is EmfToWmfBitsFlagsDefault.

Return Value

If the function succeeds and the buffer pointer is NULL, the return value is the number of bytes required to store the converted records. If the function succeeds and the buffer pointer is a valid pointer, the return value is the size of the metafile data in bytes. If the function fails, the return value is zero.

Remarks

When you call GdipEmfToWmfBits to determine the size of the required buffer, you must pass the same value for eFlags that you pass later when you call GdipEmfToWmfBits to perform the conversion. Otherwise, the size returned by the first call to GdipEmfToWmfBits will be incorrect.

This function cannot convert metafiles of type EmfTypeEmfPlusOnly. If you use this function to convert a metafile of type EmfTypeEmfPlusDual, the Enhanced Metafile (EMF) records in that metafile are converted, but the EMF+ records are not converted.

This function converts an enhanced metafile into a WMF metafile so that its picture can be displayed in an application that recognizes the older format.

The GdipEmfToWmfBits function does not invalidate the enhanced metafile handle. Call the DeleteEnhMetaFile function to release the handle when it is no longer needed.

To create a scalable WMF metafile, specify MM_ANISOTROPIC as the iMapMode parameter.