EngAlphaBlend

関数

サーフェスをアルファブレンドして合成する。

DLLGDI32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

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

BOOL EngAlphaBlend(
    SURFOBJ* psoDest,
    SURFOBJ* psoSrc,
    CLIPOBJ* pco,
    XLATEOBJ* pxlo,
    RECTL* prclDest,
    RECTL* prclSrc,
    BLENDOBJ* pBlendObj
);

パラメーター

名前	型	方向	説明
psoDest	SURFOBJ*	inout	描画先のサーフェスを識別する SURFOBJ 構造体へのポインターです。
psoSrc	SURFOBJ*	inout	ソースサーフェスを識別する SURFOBJ 構造体へのポインターです。
pco	CLIPOBJ*	inout	CLIPOBJ 構造体へのポインターです。*CLIPOBJ_Xxx* サービスルーチンは、クリップ領域を矩形の集合として列挙するために提供されます。この列挙により、変更される描画先の領域が制限されます。可能な限り、GDI は関係するクリッピングを簡略化します。ただし、EngBitBlt とは異なり、EngAlphaBlend** は出力のクリッピングにおける丸め誤差を防ぐために、単一の矩形で呼び出される場合があります。
pxlo	XLATEOBJ*	inout	ソースサーフェスと描画先サーフェスの間でカラーインデックスをどのように変換するかを指定する XLATEOBJ 構造体へのポインターです。ソースサーフェスがパレット管理されている場合、その色は RGB カラー値のルックアップテーブルへのインデックスで表現されます。この場合、GDI は XLATEOBJ 構造体に変換ベクトルを問い合わせることで、任意のソースインデックスを描画先のカラーインデックスへ素早く変換できます。状況がより複雑になるのは、たとえばソースが RGB であるのに対し、描画先がパレット管理されている場合です。この場合、各ソース RGB 値に最も近い色を描画先パレットの中から見つける必要があります。GDI はこのマッチング操作を実行するために XLATEOBJ_iXlate サービスルーチンを呼び出します。
prclDest	RECTL*	inout	変更対象となる矩形領域を定義する RECTL 構造体へのポインターです。この矩形は描画先サーフェスの座標系で指定され、左上と右下の 2 つの点によって定義されます。矩形を定義する 2 つの点は常に正しい順序になっています。この矩形は右下を含まない (lower-right exclusive) ものです。つまり、下端と右端はブレンドの一部には含まれません。指定された矩形は描画先サーフェスからはみ出すことがあります。その場合、GDI が適切なクリッピングを行います。 EngAlphaBlend は、空の描画先矩形で呼び出してはなりません。
prclSrc	RECTL*	inout	コピー対象となる領域を定義する RECTL 構造体へのポインターです。この矩形はソースサーフェスの座標系で指定され、左上と右下の 2 つの点によって定義されます。矩形を定義する 2 つの点は常に正しい順序になっています。この矩形は右下を含まない (lower-right exclusive) ものです。つまり、下端と右端はブレンドの一部には含まれません。ソース矩形はソースサーフェスの範囲を超えてはならず、したがってソースサーフェスからはみ出すこともありません。 EngAlphaBlend は、空のソース矩形で呼び出してはなりません。マッピングは prclSrc と prclDest によって定義されます。prclDest と prclSrc で指定される点は整数座標上にあり、これはピクセルの中心に対応します。このような 2 つの点で定義される矩形は、座標が与えられた点である 2 つの頂点を持つ幾何学的な矩形と見なされますが、各座標から 0.5 を引いたものになります。(POINTL 構造体は、これらの小数座標の頂点を指定するための簡略表記です。)
pBlendObj	BLENDOBJ*	inout	ソースサーフェスと描画先サーフェスの間で実行するブレンド操作を記述する BLENDOBJ 構造体へのポインターです。この構造体は BLENDFUNCTION 構造体のラッパーであり、XLATEOBJ 構造体では取得できない必要なソースおよび描画先のフォーマット情報を含みます。BLENDFUNCTION は Microsoft Windows SDK のドキュメントで宣言されています。そのメンバーは次のように定義されます。 BlendOp は実行するブレンド操作を定義します。現在、この値は AC_SRC_OVER でなければなりません。これは、ソースピクセルのアルファ値に基づいてソースビットマップが描画先ビットマップの上に重ねられることを意味します。このブレンド操作が処理すべきケースには 3 つの可能性があります。これらはこのリファレンスページの「解説」セクションで説明されています。 BlendFlags は予約済みであり、現在はゼロに設定されています。 SourceConstantAlpha は、ソースサーフェス全体に適用する定数ブレンド係数を定義します。この値は [0,255] の範囲であり、0 は完全に透明、255 は完全に不透明を表します。 AlphaFormat は、サーフェスがアルファチャンネルを持つと想定されるかどうかを定義します。このメンバーは、オプションで次の値に設定できます。 AC_SRC_ALPHA ソースサーフェスは、事前乗算済みアルファの 32bpp "BGRA" フォーマットであると想定できます。つまり、サーフェスの種類は BMF_32BPP、パレットの種類は BI_RGB です。アルファ成分は [0,255] の範囲の整数であり、0 は完全に透明、255 は完全に不透明を表します。

戻り値の型: BOOL

公式ドキュメント

EngAlphaBlend 関数は、アルファブレンディングを伴うビットブロック転送機能を提供します。

戻り値

EngAlphaBlend は、成功すると TRUE を返します。エラーが発生した場合は FALSE を返し、エラーコードを報告します。

解説(Remarks)

アルファブレンディングを伴うビットブロック転送は、次のサーフェス間でサポートされます。

あるデバイス管理サーフェスから別のデバイス管理サーフェスへ。
ある GDI 管理の標準フォーマットビットマップから別の GDI 管理の標準フォーマットビットマップへ。
デバイス管理サーフェスから GDI 管理サーフェスへ、およびその逆。

ドライバーは、同一サーフェス上で重なり合うソース矩形と描画先矩形を指定して EngAlphaBlend を呼び出してはなりません。

AC_SRC_OVER ブレンド関数について考えられる 3 つのケースは次のとおりです。

ソースビットマップがピクセルごとのアルファを持たない (AC_SRC_ALPHA が設定されていない) 場合、ブレンドは SourceConstantAlpha で指定された定数ソースアルファ値に基づいて、ピクセルのカラーチャンネルに次のように適用されます。

Dst.Red = Round(((Src.Red * SourceConstantAlpha) + 
    ((255 − SourceConstantAlpha) * Dst.Red)) / 255);
Dst.Green = Round(((Src.Green * SourceConstantAlpha) + 
    ((255 − SourceConstantAlpha) * Dst.Green)) / 255);
Dst.Blue = Round(((Src.Blue * SourceConstantAlpha) + 
    ((255 − SourceConstantAlpha) * Dst.Blue)) / 255);
/* Do the next computation only if the destination bitmap 
    has an alpha channel. */
Dst.Alpha = Round(((Src.Alpha * SourceConstantAlpha) + 
    ((255 − SourceConstantAlpha) * Dst.Alpha)) / 255);

ソースビットマップがピクセルごとのアルファ値を持ち (AC_SRC_ALPHA が設定されている)、SourceConstantAlpha は使用されません (255 に設定されています)。ブレンドは次のように計算されます。

Dst.Red = Src.Red + 
    Round(((255 − Src.Alpha) * Dst.Red) / 255);
Dst.Green = Src.Green + 
    Round(((255 − Src.Alpha) * Dst.Green) / 255);
Dst.Blue = Src.Blue + 
    Round(((255 − Src.Alpha) * Dst.Blue) / 255);
/* Do the next computation only if the destination bitmap 
    has an alpha channel. */
Dst.Alpha = Src.Alpha + 
    Round(((255 − Src.Alpha) * Dst.Alpha) / 255);

ソースビットマップがピクセルごとのアルファ値を持ち (AC_SRC_ALPHA が設定されている)、SourceConstantAlpha も使用されます (255 に設定されていません)。ブレンドは次のように計算されます。

Temp.Red = Round((Src.Red * SourceConstantAlpha) / 255);
Temp.Green = Round((Src.Green * SourceConstantAlpha) / 255);
Temp.Blue = Round((Src.Blue * SourceConstantAlpha) / 255);
/* The next computation must be done even if the 
    destination bitmap does not have an alpha channel. */
Temp.Alpha = Round((Src.Alpha * SourceConstantAlpha) / 255);
 
/* Note that the following equations use the just-computed 
   Temp.Alpha value: */
Dst.Red = Temp.Red + 
    Round(((255 − Temp.Alpha) * Dst.Red) / 255);
Dst.Green = Temp.Green + 
    Round(((255 − Temp.Alpha) * Dst.Green) / 255);
Dst.Blue = Temp.Blue + 
    Round(((255 − Temp.Alpha) * Dst.Blue) / 255);
/* Do the next computation only if the destination bitmap 
    has an alpha channel. */
Dst.Alpha = Temp.Alpha + 
    Round(((255 − Temp.Alpha) * Dst.Alpha) / 255);

ドライバーが DrvAlphaBlend をフックしており、サポートしていない処理を行うよう呼び出された場合、ドライバーは EngAlphaBlend を呼び出す必要があります。

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

各言語での呼び出し定義

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

BOOL EngAlphaBlend(
    SURFOBJ* psoDest,
    SURFOBJ* psoSrc,
    CLIPOBJ* pco,
    XLATEOBJ* pxlo,
    RECTL* prclDest,
    RECTL* prclSrc,
    BLENDOBJ* pBlendObj
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("GDI32.dll", ExactSpelling = true)]
static extern bool EngAlphaBlend(
    IntPtr psoDest,   // SURFOBJ* in/out
    IntPtr psoSrc,   // SURFOBJ* in/out
    IntPtr pco,   // CLIPOBJ* in/out
    IntPtr pxlo,   // XLATEOBJ* in/out
    IntPtr prclDest,   // RECTL* in/out
    IntPtr prclSrc,   // RECTL* in/out
    IntPtr pBlendObj   // BLENDOBJ* in/out
);

<DllImport("GDI32.dll", ExactSpelling:=True)>
Public Shared Function EngAlphaBlend(
    psoDest As IntPtr,   ' SURFOBJ* in/out
    psoSrc As IntPtr,   ' SURFOBJ* in/out
    pco As IntPtr,   ' CLIPOBJ* in/out
    pxlo As IntPtr,   ' XLATEOBJ* in/out
    prclDest As IntPtr,   ' RECTL* in/out
    prclSrc As IntPtr,   ' RECTL* in/out
    pBlendObj As IntPtr   ' BLENDOBJ* in/out
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' psoDest : SURFOBJ* in/out
' psoSrc : SURFOBJ* in/out
' pco : CLIPOBJ* in/out
' pxlo : XLATEOBJ* in/out
' prclDest : RECTL* in/out
' prclSrc : RECTL* in/out
' pBlendObj : BLENDOBJ* in/out
Declare PtrSafe Function EngAlphaBlend Lib "gdi32" ( _
    ByVal psoDest As LongPtr, _
    ByVal psoSrc As LongPtr, _
    ByVal pco As LongPtr, _
    ByVal pxlo As LongPtr, _
    ByVal prclDest As LongPtr, _
    ByVal prclSrc As LongPtr, _
    ByVal pBlendObj As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

EngAlphaBlend = ctypes.windll.gdi32.EngAlphaBlend
EngAlphaBlend.restype = wintypes.BOOL
EngAlphaBlend.argtypes = [
    ctypes.c_void_p,  # psoDest : SURFOBJ* in/out
    ctypes.c_void_p,  # psoSrc : SURFOBJ* in/out
    ctypes.c_void_p,  # pco : CLIPOBJ* in/out
    ctypes.c_void_p,  # pxlo : XLATEOBJ* in/out
    ctypes.c_void_p,  # prclDest : RECTL* in/out
    ctypes.c_void_p,  # prclSrc : RECTL* in/out
    ctypes.c_void_p,  # pBlendObj : BLENDOBJ* in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('GDI32.dll')
EngAlphaBlend = Fiddle::Function.new(
  lib['EngAlphaBlend'],
  [
    Fiddle::TYPE_VOIDP,  # psoDest : SURFOBJ* in/out
    Fiddle::TYPE_VOIDP,  # psoSrc : SURFOBJ* in/out
    Fiddle::TYPE_VOIDP,  # pco : CLIPOBJ* in/out
    Fiddle::TYPE_VOIDP,  # pxlo : XLATEOBJ* in/out
    Fiddle::TYPE_VOIDP,  # prclDest : RECTL* in/out
    Fiddle::TYPE_VOIDP,  # prclSrc : RECTL* in/out
    Fiddle::TYPE_VOIDP,  # pBlendObj : BLENDOBJ* in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "gdi32")]
extern "system" {
    fn EngAlphaBlend(
        psoDest: *mut SURFOBJ,  // SURFOBJ* in/out
        psoSrc: *mut SURFOBJ,  // SURFOBJ* in/out
        pco: *mut CLIPOBJ,  // CLIPOBJ* in/out
        pxlo: *mut XLATEOBJ,  // XLATEOBJ* in/out
        prclDest: *mut RECTL,  // RECTL* in/out
        prclSrc: *mut RECTL,  // RECTL* in/out
        pBlendObj: *mut BLENDOBJ  // BLENDOBJ* in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("GDI32.dll")]
public static extern bool EngAlphaBlend(IntPtr psoDest, IntPtr psoSrc, IntPtr pco, IntPtr pxlo, IntPtr prclDest, IntPtr prclSrc, IntPtr pBlendObj);
"@
$api = Add-Type -MemberDefinition $sig -Name 'GDI32_EngAlphaBlend' -Namespace Win32 -PassThru
# $api::EngAlphaBlend(psoDest, psoSrc, pco, pxlo, prclDest, prclSrc, pBlendObj)

#uselib "GDI32.dll"
#func global EngAlphaBlend "EngAlphaBlend" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; EngAlphaBlend varptr(psoDest), varptr(psoSrc), varptr(pco), varptr(pxlo), varptr(prclDest), varptr(prclSrc), varptr(pBlendObj)   ; 戻り値は stat
; psoDest : SURFOBJ* in/out -> "sptr"
; psoSrc : SURFOBJ* in/out -> "sptr"
; pco : CLIPOBJ* in/out -> "sptr"
; pxlo : XLATEOBJ* in/out -> "sptr"
; prclDest : RECTL* in/out -> "sptr"
; prclSrc : RECTL* in/out -> "sptr"
; pBlendObj : BLENDOBJ* in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "GDI32.dll"
#cfunc global EngAlphaBlend "EngAlphaBlend" var, var, var, var, var, var, var
; res = EngAlphaBlend(psoDest, psoSrc, pco, pxlo, prclDest, prclSrc, pBlendObj)
; psoDest : SURFOBJ* in/out -> "var"
; psoSrc : SURFOBJ* in/out -> "var"
; pco : CLIPOBJ* in/out -> "var"
; pxlo : XLATEOBJ* in/out -> "var"
; prclDest : RECTL* in/out -> "var"
; prclSrc : RECTL* in/out -> "var"
; pBlendObj : BLENDOBJ* in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "GDI32.dll"
#cfunc global EngAlphaBlend "EngAlphaBlend" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; res = EngAlphaBlend(varptr(psoDest), varptr(psoSrc), varptr(pco), varptr(pxlo), varptr(prclDest), varptr(prclSrc), varptr(pBlendObj))
; psoDest : SURFOBJ* in/out -> "sptr"
; psoSrc : SURFOBJ* in/out -> "sptr"
; pco : CLIPOBJ* in/out -> "sptr"
; pxlo : XLATEOBJ* in/out -> "sptr"
; prclDest : RECTL* in/out -> "sptr"
; prclSrc : RECTL* in/out -> "sptr"
; pBlendObj : BLENDOBJ* in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。