ID2D1DeviceContext::CreateImageBrush(ID2D1Image*,constD2D1_IMAGE_BRUSH_PROPERTIES&,constD2D1_BRUSH_PROPERTIES&,ID2D1ImageBrush**) method (d2d1_1.h)

Article
02/22/2024

Creates an image brush. The input image can be any type of image, including a bitmap, effect, or a command list.

Syntax

HRESULT CreateImageBrush(
  [in]                ID2D1Image                          *image,
  [in, ref]           const D2D1_IMAGE_BRUSH_PROPERTIES & imageBrushProperties,
  [in, ref, optional] const D2D1_BRUSH_PROPERTIES &       brushProperties,
  [out]               ID2D1ImageBrush                     **imageBrush
);

Parameters

[in] image

Type: ID2D1Image*

The image to be used as a source for the image brush.

[in, ref] imageBrushProperties

Type: const D2D1_IMAGE_BRUSH_PROPERTIES

The properties specific to an image brush.

[in, ref, optional] brushProperties

Type: const D2D1_BRUSH_PROPERTIES

Properties common to all brushes.

[out] imageBrush

Type: ID2D1ImageBrush**

When this method returns, contains the address of a pointer to the input rectangles.

Return value

Type: HRESULT

The method returns an HRESULT. Possible values include, but are not limited to, those in the following table.

HRESULT	Description
S_OK	No error occurred.
E_OUTOFMEMORY	Direct2D could not allocate sufficient memory to complete the call.
E_INVALIDARG	An invalid value was passed to the method.

Remarks

The image brush can be used to fill an arbitrary geometry, an opacity mask or text.

This sample illustrates drawing a rectangle with an image brush.

HRESULT
CreatePatternBrush(
     __in ID2D1DeviceContext *pDeviceContext,
     __deref_out ID2D1ImageBrush **ppImageBrush
     )
{
    HRESULT hr = S_OK;
    ID2D1Image *pOldTarget = NULL;
    pDeviceContext->GetTarget(&pOldTarget);

    ID2D1CommandList *pCommandList = NULL;
    hr = pDeviceContext->CreateCommandList(&pCommandList);
     
    if (SUCCEEDED(hr))
    {   
        pDeviceContext->SetTarget(pCommandList);
        hr = RenderPatternToCommandList(pDeviceContext);
    }

    pDeviceContext->SetTarget(pOldTarget);

    ID2D1ImageBrush *pImageBrush = NULL;

    if (SUCCEEDED(hr))
    {        
         hr = pDeviceContext->CreateImageBrush(
            pCommandList,
            D2D1::ImageBrushProperties(
                D2D1::RectF(198, 298, 370, 470),
                D2D1_EXTEND_MODE_WRAP,
                D2D1_EXTEND_MODE_WRAP,
                D2D1_INTERPOLATION_MODE_LINEAR
                ),
            &pImageBrush
            );
    }
    
    // Fill a rectangle with the image brush.
    if (SUCCEEDED(hr))
    {
        pDeviceContext->FillRectangle(
            D2D1::RectF(0, 0, 100, 100), pImageBrush);
    }

    SafeRelease(&pImageBrush);
    SafeRelease(&pCommandList);
    SafeRelease(&pOldTarget);
    return hr;
}

Requirements

Requirement	Value
Minimum supported client	Windows 8 and Platform Update for Windows 7 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 and Platform Update for Windows Server 2008 R2 [desktop apps \| UWP apps]
Target Platform	Windows
Header	d2d1_1.h
DLL	D2d1.dll