DelphiX 教學 (20)：TDirectDrawSurface 填充矩形系列函數詳解與色彩格式陷阱

TDirectDrawSurface 提供了多種矩形填充方法，功能從純色填充到 Alpha 混合、加法/減法混合應有盡有。但最大的挑戰在於**色彩格式不一致**：Fill/FillRect 使用 DirectDraw 原生格式，而 FillRectAlpha/Add/Sub 則支援 Delphi 標準 TColor。本文詳細解析各函數差異與正確用法。

填充函數完整比較

關鍵色彩格式差異示意

• DD 原生格式 (Fill/FillRect)：通常為 **0xBBGGRR** (藍綠紅) 或依表面格式而定。紅色 = $FF0000 (藍=0, 綠=0, 紅=255)。
• Delphi TColor (FillRectAlpha/Add/Sub)：標準 **0x00BBGGRR**。紅色 = $0000FF 或 clRed。

綜合示範範例

unit Unit1;

interface

uses
  Windows, Messages, SysUtils, Variants, Classes, Graphics, Controls, Forms,
  Dialogs, DXDraws, StdCtrls;

type
  TForm1 = class(TForm)
    DXDraw1: TDXDraw;
    Button1: TButton;
    Button2: TButton;
    Button3: TButton;
    Button4: TButton;
    Button5: TButton;
    procedure Button1Click(Sender: TObject);
    procedure Button2Click(Sender: TObject);
    procedure Button3Click(Sender: TObject);
    procedure Button4Click(Sender: TObject);
    procedure Button5Click(Sender: TObject);
    procedure FormCreate(Sender: TObject);
  end;

var
  Form1: TForm1;

implementation

{$R *.dfm}

const
  ImgPath1 = 'C:\Temp\Test.jpg';

procedure TForm1.Button1Click(Sender: TObject);
var
  MySurface: TDirectDrawSurface;
begin
  MySurface := TDirectDrawSurface.Create(DXDraw1.DDraw);
  try
    MySurface.LoadFromFile(ImgPath1);
    DXDraw1.Surface.Fill(0);  // DD 格式黑色
    DXDraw1.Surface.Draw(0, 0, MySurface);
    DXDraw1.Flip;
  finally
    FreeAndNil(MySurface);
  end;
end;

procedure TForm1.Button2Click(Sender: TObject);
var
  MySurface: TDirectDrawSurface;
  r: TRect;
begin
  MySurface := TDirectDrawSurface.Create(DXDraw1.DDraw);
  try
    MySurface.LoadFromFile(ImgPath1);
    DXDraw1.Surface.Fill(0);
    DXDraw1.Surface.Draw(0, 0, MySurface);
    r := Bounds(10, 10, DXDraw1.Width - 20, DXDraw1.Height - 20);
    { DD 格式紅色：$FF0000 }
    DXDraw1.Surface.FillRect(r, $FF0000);
    DXDraw1.Flip;
  finally
    FreeAndNil(MySurface);
  end;
end;

procedure TForm1.Button3Click(Sender: TObject);
var
  MySurface: TDirectDrawSurface;
  r: TRect;
begin
  MySurface := TDirectDrawSurface.Create(DXDraw1.DDraw);
  try
    MySurface.LoadFromFile(ImgPath1);
    DXDraw1.Surface.Fill(0);
    DXDraw1.Surface.Draw(0, 0, MySurface);
    r := Bounds(10, 10, DXDraw1.Width - 20, DXDraw1.Height - 20);
    { TColor 格式紅色：$0000FF 或 clRed，Alpha=128 (50%) }
    DXDraw1.Surface.FillRectAlpha(r, $0000FF, 128);
    DXDraw1.Flip;
  finally
    FreeAndNil(MySurface);
  end;
end;

procedure TForm1.Button4Click(Sender: TObject);
var
  MySurface: TDirectDrawSurface;
  r: TRect;
begin
  MySurface := TDirectDrawSurface.Create(DXDraw1.DDraw);
  try
    MySurface.LoadFromFile(ImgPath1);
    DXDraw1.Surface.Fill(0);
    DXDraw1.Surface.Draw(0, 0, MySurface);
    r := Bounds(10, 10, DXDraw1.Width - 20, DXDraw1.Height - 20);
    { 加法混合：發光效果，Weight=255 最強 }
    DXDraw1.Surface.FillRectAdd(r, $0000FF, 255);
    DXDraw1.Flip;
  finally
    FreeAndNil(MySurface);
  end;
end;

procedure TForm1.Button5Click(Sender: TObject);
var
  MySurface: TDirectDrawSurface;
  r: TRect;
begin
  MySurface := TDirectDrawSurface.Create(DXDraw1.DDraw);
  try
    MySurface.LoadFromFile(ImgPath1);
    DXDraw1.Surface.Fill(0);
    DXDraw1.Surface.Draw(0, 0, MySurface);
    r := Bounds(10, 10, DXDraw1.Width - 20, DXDraw1.Height - 20);
    { 減法混合：變暗效果 }
    DXDraw1.Surface.FillRectSub(r, $0000FF, 255);
    DXDraw1.Flip;
  finally
    FreeAndNil(MySurface);
  end;
end;

procedure TForm1.FormCreate(Sender: TObject);
begin
  Button1.Caption := '原始圖片';
  Button2.Caption := 'FillRect (DD格式)';
  Button3.Caption := 'FillRectAlpha (TColor+Alpha)';
  Button4.Caption := 'FillRectAdd (加法混合)';
  Button5.Caption := 'FillRectSub (減法混合)';
end;

end.

執行效果對比

實務開發核心提醒

1. 統一色彩處理：建議封裝輔助函數 function DDColor(c: TColor): Longint; 統一轉換，避免格式混淆。
2. 混合模式選擇：
   • 半透明 UI：FillRectAlpha
   • 魔法特效/發光：FillRectAdd
   • 陰影/夜晚效果：FillRectSub
3. 效能考量：Fill/FillRect 為硬體加速極快；Alpha/加減法混合可能回退軟體模擬，大面積使用需測試效能。
4. 表面格式相容：確保目標表面建立時支援所需混合模式 (如需 Alpha 混合請指定含 Alpha 通道的像素格式)。

掌握色彩格式差異是正確使用 DelphiX 填充函數的關鍵，建立統一的色彩轉換習慣將避免大量難以除錯的顯示錯誤。