ホーム › UI.Controls › BeginBufferedAnimation

BeginBufferedAnimation

関数

状態間の遷移を補間するバッファアニメーション描画を開始する。

DLLUXTHEME.dll呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// UXTHEME.dll
#include <windows.h>

INT_PTR BeginBufferedAnimation(
    HWND hwnd,
    HDC hdcTarget,
    const RECT* prcTarget,
    BP_BUFFERFORMAT dwFormat,
    BP_PAINTPARAMS* pPaintParams,   // optional
    BP_ANIMATIONPARAMS* pAnimationParams,
    HDC* phdcFrom,
    HDC* phdcTo
);

パラメーター

名前	型	方向	説明
hwnd	HWND	in	アニメーションを再生するウィンドウのハンドルです。
hdcTarget	HDC	in	バッファーをアニメーション表示する対象 DC のハンドルです。
prcTarget	RECT*	in	描画を行う対象 DC の領域を指定する構造体へのポインターです。
dwFormat	BP_BUFFERFORMAT	in	バッファーの形式です。
pPaintParams	BP_PAINTPARAMS*	inoptional	描画操作のパラメーターを定義する構造体へのポインターです。この値は NULL にできます。
pAnimationParams	BP_ANIMATIONPARAMS*	in	アニメーション操作のパラメーターを定義する構造体へのポインターです。
phdcFrom	HDC*	out	この関数が返ると、NULL でない場合、この値はアプリケーションがアニメーションの開始状態を描画すべき DC のハンドルを指します。
phdcTo	HDC*	out	この関数が返ると、NULL でない場合、この値はアプリケーションがアニメーションの最終状態を描画すべき DC のハンドルを指します。

戻り値の型: INT_PTR

公式ドキュメント

バッファーアニメーション操作を開始します。このアニメーションは、指定した時間にわたって2つのバッファーの内容をクロスフェードさせるものです。

戻り値

Type: HANIMATIONBUFFER

バッファーペイントアニメーションのハンドルです。

解説(Remarks)

BeginBufferedAnimation は、複数の WM_PAINT メッセージを生成することで、これら2つの状態の間の中間フレームの描画を処理します。

BeginBufferedAnimation は、BufferedPaintRenderAnimation を呼び出すべき WM_PAINT メッセージを生成するタイマーを開始します。これらのメッセージの間、BufferedPaintRenderAnimation は中間フレームを描画したときに TRUE を返し、アプリケーションがそれ以上描画する必要がないことを示します。

アニメーションの継続時間が0の場合は、phdcTo のみが返され、phdcFrom は NULL に設定されます。この場合、アプリケーションは BeginBufferedPaint と同様の動作を得るために、phdcTo を使用して最終状態を描画する必要があります。

Examples

次のコード例は、この関数の使用方法を示しています。

#include <windows.h>
#include <tchar.h>
#include <uxtheme.h>

#pragma comment(lib, "uxtheme.lib")

#define WNDCLASSNAME L"BufferedPaintSample_WndClass"
#define ANIMATION_DURATION 500

bool g_fCurrentState = true;
bool g_fNewState = true;

void StartAnimation(HWND hWnd)
{
    g_fNewState = !g_fCurrentState;
    InvalidateRect(hWnd, NULL, TRUE);
}

void Paint(HWND hWnd, HDC hdc, bool state)
{
    RECT rc;
    GetClientRect(hWnd, &rc);
    FillRect(hdc, &rc, (HBRUSH)GetStockObject(WHITE_BRUSH));
    LPCTSTR pszIconId = state ? IDI_APPLICATION : IDI_ERROR;
    HICON hIcon = LoadIcon(NULL, pszIconId);
    if (hIcon)
    {
        DrawIcon(hdc, 10, 10, hIcon);
        DestroyIcon(hIcon);
    }
}

void OnPaint(HWND hWnd)
{
    PAINTSTRUCT ps;
    HDC hdc = BeginPaint(hWnd, &ps);
    if (hdc)
    {
        // See if this paint was generated by a soft-fade animation
        if (!BufferedPaintRenderAnimation(hWnd, hdc))
        {
            BP_ANIMATIONPARAMS animParams;
            ZeroMemory(&animParams, sizeof(animParams));
            animParams.cbSize = sizeof(BP_ANIMATIONPARAMS);
            animParams.style = BPAS_LINEAR;
            
            // Check if animation is needed. If not set dwDuration to 0
            animParams.dwDuration = (g_fCurrentState != g_fNewState ? ANIMATION_DURATION : 0);

            RECT rc;
            GetClientRect(hWnd, &rc);

            HDC hdcFrom, hdcTo;
            HANIMATIONBUFFER hbpAnimation = BeginBufferedAnimation(hWnd, hdc, &rc,
                BPBF_COMPATIBLEBITMAP, NULL, &animParams, &hdcFrom, &hdcTo);
            if (hbpAnimation)
            {
                if (hdcFrom)
                {
                    Paint(hWnd, hdcFrom, g_fCurrentState);
                }
                if (hdcTo)
                {
                    Paint(hWnd, hdcTo, g_fNewState);
                }

                g_fCurrentState = g_fNewState;
                EndBufferedAnimation(hbpAnimation, TRUE);
            }
            else
            {
                Paint(hWnd, hdc, g_fCurrentState);
            }
        }
        
        EndPaint(hWnd, &ps);
    }
}

LRESULT CALLBACK WndProc(HWND hWnd, UINT message, WPARAM wParam, LPARAM lParam)
{
    switch (message)
    {
    case WM_LBUTTONDOWN:
        StartAnimation(hWnd);
        break;
    case WM_PAINT:
        OnPaint(hWnd);
        break;
    case WM_SIZE:
        BufferedPaintStopAllAnimations(hWnd);
        break;
    case WM_DESTROY:
        PostQuitMessage(0);
        break;
    default:
        return DefWindowProc(hWnd, message, wParam, lParam);
    }
    return 0;
}

int WINAPI _tWinMain(HINSTANCE hInstance,
     HINSTANCE hPrevInstance,
     LPSTR     lpCmdLine,
     int       nCmdShow)
{
    UNREFERENCED_PARAMETER(hPrevInstance);
    UNREFERENCED_PARAMETER(lpCmdLine);

    if (SUCCEEDED(BufferedPaintInit()))
    {
        WNDCLASSEX wcex;
        ZeroMemory(&wcex, sizeof(wcex));
        wcex.cbSize = sizeof(WNDCLASSEX);
        wcex.style = CS_HREDRAW|CS_VREDRAW;
        wcex.lpfnWndProc = WndProc;
        wcex.hInstance = hInstance;
        wcex.hCursor = LoadCursor(NULL, IDC_ARROW);
        wcex.hIcon = LoadIcon(NULL, IDI_APPLICATION);
        wcex.lpszClassName = WNDCLASSNAME;
        RegisterClassEx(&wcex);

        HWND hWnd = CreateWindow(WNDCLASSNAME, L"Buffered Paint Sample", 
            WS_OVERLAPPEDWINDOW, CW_USEDEFAULT, 0, 
            CW_USEDEFAULT, 0, NULL, NULL, hInstance, NULL);

        if (hWnd)
        {
            ShowWindow(hWnd, nCmdShow);
            UpdateWindow(hWnd);

            MSG msg;
            while (GetMessage(&msg, NULL, 0, 0))
            {
                TranslateMessage(&msg);
                DispatchMessage(&msg);
            }
        }

        BufferedPaintUnInit();
    }

    return 0;
}

void BufferedPaint(HDC hdc, const RECT *prcPaint)
{
    BP_PAINTPARAMS paintParams = {0};
    paintParams.cbSize = sizeof(paintParams);

    HDC hdcBuffer;
    HPAINTBUFFER hBufferedPaint = BeginBufferedPaint(hdc, prcPaint, 
        BPBF_COMPATIBLEBITMAP, &paintParams, &hdcBuffer);

    if (hBufferedPaint)
    {
        // Application specific painting code
        AppPaint(hdcBuffer, prcPaint);
        EndBufferedPaint(hBufferedPaint, TRUE);
    }
    else
    {
        // Error occurred, default to unbuffered painting
        AppPaint(hdc, prcPaint);
    }
}

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// UXTHEME.dll
#include <windows.h>

INT_PTR BeginBufferedAnimation(
    HWND hwnd,
    HDC hdcTarget,
    const RECT* prcTarget,
    BP_BUFFERFORMAT dwFormat,
    BP_PAINTPARAMS* pPaintParams,   // optional
    BP_ANIMATIONPARAMS* pAnimationParams,
    HDC* phdcFrom,
    HDC* phdcTo
);

[DllImport("UXTHEME.dll", ExactSpelling = true)]
static extern IntPtr BeginBufferedAnimation(
    IntPtr hwnd,   // HWND
    IntPtr hdcTarget,   // HDC
    IntPtr prcTarget,   // RECT*
    int dwFormat,   // BP_BUFFERFORMAT
    IntPtr pPaintParams,   // BP_PAINTPARAMS* optional
    IntPtr pAnimationParams,   // BP_ANIMATIONPARAMS*
    IntPtr phdcFrom,   // HDC* out
    IntPtr phdcTo   // HDC* out
);

<DllImport("UXTHEME.dll", ExactSpelling:=True)>
Public Shared Function BeginBufferedAnimation(
    hwnd As IntPtr,   ' HWND
    hdcTarget As IntPtr,   ' HDC
    prcTarget As IntPtr,   ' RECT*
    dwFormat As Integer,   ' BP_BUFFERFORMAT
    pPaintParams As IntPtr,   ' BP_PAINTPARAMS* optional
    pAnimationParams As IntPtr,   ' BP_ANIMATIONPARAMS*
    phdcFrom As IntPtr,   ' HDC* out
    phdcTo As IntPtr   ' HDC* out
) As IntPtr
End Function

' hwnd : HWND
' hdcTarget : HDC
' prcTarget : RECT*
' dwFormat : BP_BUFFERFORMAT
' pPaintParams : BP_PAINTPARAMS* optional
' pAnimationParams : BP_ANIMATIONPARAMS*
' phdcFrom : HDC* out
' phdcTo : HDC* out
Declare PtrSafe Function BeginBufferedAnimation Lib "uxtheme" ( _
    ByVal hwnd As LongPtr, _
    ByVal hdcTarget As LongPtr, _
    ByVal prcTarget As LongPtr, _
    ByVal dwFormat As Long, _
    ByVal pPaintParams As LongPtr, _
    ByVal pAnimationParams As LongPtr, _
    ByVal phdcFrom As LongPtr, _
    ByVal phdcTo As LongPtr) As LongPtr
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

BeginBufferedAnimation = ctypes.windll.uxtheme.BeginBufferedAnimation
BeginBufferedAnimation.restype = ctypes.c_ssize_t
BeginBufferedAnimation.argtypes = [
    wintypes.HANDLE,  # hwnd : HWND
    wintypes.HANDLE,  # hdcTarget : HDC
    ctypes.c_void_p,  # prcTarget : RECT*
    ctypes.c_int,  # dwFormat : BP_BUFFERFORMAT
    ctypes.c_void_p,  # pPaintParams : BP_PAINTPARAMS* optional
    ctypes.c_void_p,  # pAnimationParams : BP_ANIMATIONPARAMS*
    ctypes.c_void_p,  # phdcFrom : HDC* out
    ctypes.c_void_p,  # phdcTo : HDC* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('UXTHEME.dll')
BeginBufferedAnimation = Fiddle::Function.new(
  lib['BeginBufferedAnimation'],
  [
    Fiddle::TYPE_VOIDP,  # hwnd : HWND
    Fiddle::TYPE_VOIDP,  # hdcTarget : HDC
    Fiddle::TYPE_VOIDP,  # prcTarget : RECT*
    Fiddle::TYPE_INT,  # dwFormat : BP_BUFFERFORMAT
    Fiddle::TYPE_VOIDP,  # pPaintParams : BP_PAINTPARAMS* optional
    Fiddle::TYPE_VOIDP,  # pAnimationParams : BP_ANIMATIONPARAMS*
    Fiddle::TYPE_VOIDP,  # phdcFrom : HDC* out
    Fiddle::TYPE_VOIDP,  # phdcTo : HDC* out
  ],
  Fiddle::TYPE_INTPTR_T)

#[link(name = "uxtheme")]
extern "system" {
    fn BeginBufferedAnimation(
        hwnd: *mut core::ffi::c_void,  // HWND
        hdcTarget: *mut core::ffi::c_void,  // HDC
        prcTarget: *const RECT,  // RECT*
        dwFormat: i32,  // BP_BUFFERFORMAT
        pPaintParams: *mut BP_PAINTPARAMS,  // BP_PAINTPARAMS* optional
        pAnimationParams: *mut BP_ANIMATIONPARAMS,  // BP_ANIMATIONPARAMS*
        phdcFrom: *mut *mut core::ffi::c_void,  // HDC* out
        phdcTo: *mut *mut core::ffi::c_void  // HDC* out
    ) -> isize;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("UXTHEME.dll")]
public static extern IntPtr BeginBufferedAnimation(IntPtr hwnd, IntPtr hdcTarget, IntPtr prcTarget, int dwFormat, IntPtr pPaintParams, IntPtr pAnimationParams, IntPtr phdcFrom, IntPtr phdcTo);
"@
$api = Add-Type -MemberDefinition $sig -Name 'UXTHEME_BeginBufferedAnimation' -Namespace Win32 -PassThru
# $api::BeginBufferedAnimation(hwnd, hdcTarget, prcTarget, dwFormat, pPaintParams, pAnimationParams, phdcFrom, phdcTo)

#uselib "UXTHEME.dll"
#func global BeginBufferedAnimation "BeginBufferedAnimation" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; BeginBufferedAnimation hwnd, hdcTarget, varptr(prcTarget), dwFormat, varptr(pPaintParams), varptr(pAnimationParams), phdcFrom, phdcTo   ; 戻り値は stat
; hwnd : HWND -> "sptr"
; hdcTarget : HDC -> "sptr"
; prcTarget : RECT* -> "sptr"
; dwFormat : BP_BUFFERFORMAT -> "sptr"
; pPaintParams : BP_PAINTPARAMS* optional -> "sptr"
; pAnimationParams : BP_ANIMATIONPARAMS* -> "sptr"
; phdcFrom : HDC* out -> "sptr"
; phdcTo : HDC* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "UXTHEME.dll"
#cfunc global BeginBufferedAnimation "BeginBufferedAnimation" sptr, sptr, var, int, var, var, sptr, sptr
; res = BeginBufferedAnimation(hwnd, hdcTarget, prcTarget, dwFormat, pPaintParams, pAnimationParams, phdcFrom, phdcTo)
; hwnd : HWND -> "sptr"
; hdcTarget : HDC -> "sptr"
; prcTarget : RECT* -> "var"
; dwFormat : BP_BUFFERFORMAT -> "int"
; pPaintParams : BP_PAINTPARAMS* optional -> "var"
; pAnimationParams : BP_ANIMATIONPARAMS* -> "var"
; phdcFrom : HDC* out -> "sptr"
; phdcTo : HDC* out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "UXTHEME.dll"
#cfunc global BeginBufferedAnimation "BeginBufferedAnimation" sptr, sptr, sptr, int, sptr, sptr, sptr, sptr
; res = BeginBufferedAnimation(hwnd, hdcTarget, varptr(prcTarget), dwFormat, varptr(pPaintParams), varptr(pAnimationParams), phdcFrom, phdcTo)
; hwnd : HWND -> "sptr"
; hdcTarget : HDC -> "sptr"
; prcTarget : RECT* -> "sptr"
; dwFormat : BP_BUFFERFORMAT -> "int"
; pPaintParams : BP_PAINTPARAMS* optional -> "sptr"
; pAnimationParams : BP_ANIMATIONPARAMS* -> "sptr"
; phdcFrom : HDC* out -> "sptr"
; phdcTo : HDC* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。