Enables the blur effect on the provided window handle.

Syntax

HRESULT DwmEnableBlurBehindWindow(      
    HWND hWnd,
    const DWM_BLURBEHIND *pBlurBehind
);

Parameters

hWnd

The handle to the window for which the blur behind data is applied.

pBlurBehind

[in] The pointer to a DWM_BLURBEHIND structure that provides blur behind data.

Return Value

Returns S_OK if successful, or an error value otherwise.

Remarks

Enabling blur by setting pBlurBehind's fEnable to TRUE results in subsequent compositions of the HWND having the content underneath it blurred. This function should be called immediately prior to a BeginPaint call to ensure prompt application of the effect.

The alpha values in the window are honored and the rendering atop the blur will use these alpha values. It is the applications responsiblity for ensuring that the alpha values of all pixels in the window are correct. Some GDI operations do not perserve alpha values so care must be taken when presenting child windows as the alpha values they contribute are unpredicitable.

The region specified within the DWM_BLURBEHIND is owned by the caller. It is the caller's responsibility to free the region and can do so as soon as the function call is completed.

This function can only be called on top-level windows. An error will result when called on other window types.

If Desktop Window Manager (DWM) composition is toggled, this function must be called again. Handle the WM_DWMCOMPOSITIONCHANGED message for composition change notification.

Example

The following example demonstrates how to apply the blur behind the entire window.

HRESULT EnableBlurBehind(HWND hwnd)
{
   HRESULT hr = S_OK;

   //Create and populate the BlurBehind structre
   DWM_BLURBEHIND bb = {0};
   //Disable Blur Behind and Blur Region;
   bb.dwFlags = DWM_BB_ENABLE;
   bb.fEnable = true;
   bb.hRgnBlur = NULL;

   //Disable Blur Behind
   hr = DwmEnableBlurBehindWindow(hwnd, &bb);
   if (SUCCEEDED(hr))
   {
      //do more things
   }
   return hr;
}

Function Information

Minimum DLL Version	dwmapi.dll
Header	dwmapi.h
Import library	dwmapi.lib
Minimum operating systems	Windows Vista

See Also

DWM Blur Behind Overview