D2Bitmap function

Requires: Direct2D.lg32

Purpose

Creates and returns a Direct2D bitmap for the current render target.

Syntax

Set brObj = D2Bitmap(arg [,AlphaChannel%])

Description

Before using D2Bitmap() make sure the proper render target is activated using D2SetRT.

A Direct2D bitmap can be created form different sources and depends on the type of the argument arg:

• When arg specifies an integer the argument arg is interpreted as a GDI bitmap handle and the GDI bitmap is converted to a Direct2D image.
• When arg is a string it is interpreted as a filename or :Files resource name. The function loads the image file and creates a Direct2D bitmap. Supported image files include PNG, JPEG (XR), BMP, ICO, GIF, TIFF, DDS, DNG, and HD Photo formats.

The returned D2Bitmap object must be assigned to an Object variable, which can then be used with the drawing command D2Put.

D2Bitmap returns the first frame from an image with multiple frames.

A D2Bitmap is usually kept in memory for the duration of the program, but if necessary it can be released by setting the object-variable - holding a COM reference to the bitmap - to Nothing. Normally, the bitmaps are stored in global Object variables that are (automatically) released from memory when the program ends.

The Optional AlphaCannel argument determines the desired alpha channel usage. By default D2Bitmap ignores the alpha channel of the loaded bitmap; the AlphaChannel% = WICBitmapIgnoreAlpha (2). The AlphaChannel% can be set to one of three enumerations :

• WICBitmapUseAlpha (0x00000000)
• WICBitmapUsePremultipliedAlpha (0x00000001)
• WICBitmapIgnoreAlpha (0x00000002)

Example

'

' D2BitmapSize sample (dpi-unaware)

'

$Library "direct2d"

Global Object Win1RT

OpenW 1, 0, 0, 320, 260, ~15

' DC Rendertarget same size as clientarea

Set Win1RT = D2GetRT()

' Here: Create Win_1 render target resources

Global Object BmpFish

Set BmpFish = D2Bitmap(":goldfish")

Global BmpFishW!, BmpFishH!

D2BitmapSize BmpFish, BmpFishW!, BmpFishH!

Do

Sleep

Until Me Is Nothing

Sub Win_1_Paint

D2BeginDraw Win1RT, D2C_White

D2Put 10, 10, BmpFish, BmpFishW!, BmpFishH!

D2Clip

D2EndDraw

EndSub

NOTE: The above example will not run correctly as it relies on an embedded file which is not present in the syntax. The programme with full resources can be found in GFABASIC/Samples/Direct2D/D2BitmapSize.g32.

Remarks

Direct2D uses the Windows Imaging Component (WIC) to load bitmaps. To load a bitmap from a file, first WIC objects are used to load the image and to convert it to a Direct2D-compatible format. Then ID2D1RenderTarget::CreateBitmapFromWicBitmap method is used to create an ID2D1Bitmap.

See Also

D2BitmapSize, D2SetRT, D2Put.

{Created by Sjouke Hamstra; Last updated: 04/07/2021 by James Gaite}