DelphiX 教學 (17)：TPictureCollectionItem PatternWidth/PatternHeight 圖片平鋪與縮放控制

TPictureCollectionItem 的 PatternWidth 與 PatternHeight 屬性控制圖片在繪製時的**重複平鋪**或**縮放**行為。這對於製作背景圖平鋪、UI 九宮格縮放、動畫精靈表切片等非常實用。本文透過互動式範例詳細演示各種設定效果。

屬性運作原理

• PatternWidth：指定繪製時單一圖片塊的寬度。若大於原圖寬度則拉伸，小於則裁剪/平鋪。
• PatternHeight：指定繪製時單一圖片塊的高度，運作邏輯同寬度。
• 預設值：均為 0，表示使用原圖實際尺寸 (Width/Height)。
• Draw 方法行為：呼叫 Draw(Surface, X, Y, PatternIndex) 時，會以 PatternWidth × PatternHeight 為單位重複填滿目標區域 (或配合目標矩形)。

互動測試範例

unit Unit1;

interface

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

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

var
  Form1: TForm1;

implementation

{$R *.dfm}

var
  PicItem: TPictureCollectionItem;
  w, h: Integer;

procedure TForm1.FormCreate(Sender: TObject);
const
  ImgPath1 = 'C:\Temp\DelphiX.bmp';
begin
  DXImageList1.DXDraw := DXDraw1;
  PicItem := TPictureCollectionItem(DXImageList1.Items.Add);
  PicItem.Picture.LoadFromFile(ImgPath1);
  w := PicItem.Width;   // 記錄原始寬度
  h := PicItem.Height;  // 記錄原始高度
end;

procedure TForm1.Button1Click(Sender: TObject);
begin
  { 1. 原始尺寸 (預設行為) }
  PicItem.PatternWidth := w;
  PicItem.PatternHeight := h;
  DXDraw1.Surface.Fill(0);
  PicItem.Draw(DXDraw1.Surface, 0, 0, 0);
  DXDraw1.Flip;
end;

procedure TForm1.Button2Click(Sender: TObject);
begin
  { 2. 寬度拉伸 2 倍，高度不變 }
  PicItem.PatternWidth := w * 2;
  PicItem.PatternHeight := h;
  DXDraw1.Surface.Fill(0);
  PicItem.Draw(DXDraw1.Surface, 0, 0, 0);
  DXDraw1.Flip;
end;

procedure TForm1.Button3Click(Sender: TObject);
begin
  { 3. 寬度壓縮一半，高度不變 }
  PicItem.PatternWidth := w div 2;
  PicItem.PatternHeight := h;
  DXDraw1.Surface.Fill(0);
  PicItem.Draw(DXDraw1.Surface, 0, 0, 0);
  DXDraw1.Flip;
end;

procedure TForm1.Button4Click(Sender: TObject);
begin
  { 4. 寬度不變，高度拉伸 2 倍 }
  PicItem.PatternWidth := w;
  PicItem.PatternHeight := h * 2;
  DXDraw1.Surface.Fill(0);
  PicItem.Draw(DXDraw1.Surface, 0, 0, 0);
  DXDraw1.Flip;
end;

procedure TForm1.Button5Click(Sender: TObject);
begin
  { 5. 寬度不變，高度壓縮一半 }
  PicItem.PatternWidth := w;
  PicItem.PatternHeight := h div 2;
  DXDraw1.Surface.Fill(0);
  PicItem.Draw(DXDraw1.Surface, 0, 0, 0);
  DXDraw1.Flip;
end;

procedure TForm1.Button6Click(Sender: TObject);
begin
  { 6. 寬高皆拉伸 2 倍 }
  PicItem.PatternWidth := w * 2;
  PicItem.PatternHeight := h * 2;
  DXDraw1.Surface.Fill(0);
  PicItem.Draw(DXDraw1.Surface, 0, 0, 0);
  DXDraw1.Flip;
end;

end.

執行效果對比

實務應用場景

1. 無縫背景平鋪：設定 PatternWidth := ImageWidth，呼叫 Draw 覆蓋整個螢幕區域，自動重複平鋪。
2. UI 九宮格縮放：將單一圖片切割為 9 區，邊角固定，邊緣單向拉伸，中心雙向拉伸，透過調整 PatternWidth/Height 實現任意尺寸按鈕/面板。
3. 精靈表動畫：將多幀動畫排列在單一圖片中，設定 PatternWidth := FrameWidth，配合 Draw 的 PatternIndex 參數切換幀。
4. 程序化地形：小型材質圖片設定較小 PatternWidth/Height，大面積繪製自動形成重複紋理。

進階技巧與注意事項

• 配合目標矩形：Draw(Surface, DestRect, PatternIndex) 多載版本可限制繪製區域，Pattern 會在該矩形內重複。
• 色鍵透明：平鋪時透明色正常運作，可製作鏤空花紋背景。
• 效能考量：大面積平鋪屬硬體加速繪製，極快；但極小 Pattern (如 1x1 像素) 可能因驅動程式優化不佳反而變慢。
• 恢復預設：設定為 0 即可恢復原圖尺寸行為。

常見誤區

• 以為 PatternWidth 是目標繪製寬度，**實際上它是來源圖片的邏輯寬度**，決定如何從來源採樣。
• 忽略 PicItem.Restore：若先前修改過 Pattern 屬性，後續直接繪製可能產生非預期結果，建議繪製前呼叫 Restore 重置。

靈活運用 PatternWidth/Height 可大幅減少美術素材數量，實現動態 UI 縮放與無縫背景，是 2D 遊戲資源優化的關鍵技巧之一。