Graphics API¶

namespace NextPDF\Core\Graphics;

final class DrawingEngine

/**
 * 繪製直線。
 *
 * @param float  $x1    起點 X（mm）
 * @param float  $y1    起點 Y（mm，從頁面頂部計算）
 * @param float  $x2    終點 X（mm）
 * @param float  $y2    終點 Y（mm）
 * @param Color  $color 線條顏色
 * @param float  $width 線寬（pt）
 * @param 'solid'|'dashed'|'dotted' $style 線條樣式
 */
public function line(
    float  $x1,
    float  $y1,
    float  $x2,
    float  $y2,
    Color  $color = Color::BLACK,
    float  $width = 0.5,
    string $style = 'solid',
): void

/**
 * 繪製矩形。
 *
 * @param Color|null $fill         填充色（null = 無填充）
 * @param Color|null $stroke       框線色（null = 無框線）
 * @param float      $strokeWidth  框線寬（pt）
 * @param float      $cornerRadius 圓角半徑（mm）
 */
public function rectangle(
    float   $x,
    float   $y,
    float   $width,
    float   $height,
    ?Color  $fill         = null,
    ?Color  $stroke       = null,
    float   $strokeWidth  = 0.5,
    float   $cornerRadius = 0.0,
): void

/**
 * 繪製圓形 / 橢圓形。
 *
 * @param float $cx 圓心 X
 * @param float $cy 圓心 Y
 * @param float $rx 水平半徑
 * @param float $ry 垂直半徑（預設等於 $rx，為正圓）
 */
public function ellipse(
    float  $cx,
    float  $cy,
    float  $rx,
    float  $ry           = 0.0,
    ?Color $fill         = null,
    ?Color $stroke       = null,
    float  $strokeWidth  = 0.5,
): void

/**
 * 繪製多邊形（路徑）。
 *
 * @param list<array{x: float, y: float}> $points 頂點座標列表
 */
public function polygon(
    array  $points,
    ?Color $fill        = null,
    ?Color $stroke      = null,
    float  $strokeWidth = 0.5,
    bool   $closed      = true,
): void

/**
 * 繪製三次貝茲曲線。
 *
 * @param float $x1 起點 X   @param float $y1 起點 Y
 * @param float $cx1 控制點1 X  @param float $cy1 控制點1 Y
 * @param float $cx2 控制點2 X  @param float $cy2 控制點2 Y
 * @param float $x2 終點 X   @param float $y2 終點 Y
 */
public function bezierCurve(
    float $x1, float $y1,
    float $cx1, float $cy1,
    float $cx2, float $cy2,
    float $x2, float $y2,
    Color $color = Color::BLACK,
    float $width = 0.5,
): void

/**
 * 在指定位置繪製嵌入的圖像。
 *
 * @param EmbeddedImage $image    已嵌入的圖像（從 ImageRegistry 取得）
 * @param float         $x        左上角 X（mm）
 * @param float         $y        左上角 Y（mm）
 * @param float         $width    顯示寬度（mm），高度按比例計算
 * @param float|null    $height   顯示高度（mm），指定後不保持比例
 * @param float         $opacity  透明度（0.0–1.0）
 * @param float         $rotation 旋轉角度（degree，以中心為軸）
 */
public function image(
    EmbeddedImage $image,
    float         $x,
    float         $y,
    float         $width,
    ?float        $height      = null,
    float         $opacity     = 1.0,
    float         $rotation    = 0.0,
    ?StructureElement $structureElement = null,
): void

/** 設定後續圖形操作的填充色 */
public function setFillColor(Color $color): void

/** 設定後續圖形操作的框線色 */
public function setStrokeColor(Color $color): void

/** 推入圖形狀態堆疊（儲存當前色彩、變換矩陣等）*/
public function pushGraphicsState(): void

/** 彈出圖形狀態堆疊（恢復之前的狀態）*/
public function popGraphicsState(): void

namespace NextPDF\Core\Support;

final class ImageRegistry

/**
 * 從檔案路徑嵌入圖像。
 * 支援格式：JPEG、PNG（含透明通道）、WebP、GIF（靜態）、BMP
 *
 * @param non-empty-string $path 圖像檔案的絕對路徑
 * @return EmbeddedImage
 * @throws ImageLoadException
 */
public function embed(string $path): EmbeddedImage

/**
 * 從二進位字串嵌入圖像。
 *
 * @param non-empty-string $data MIME 類型
 */
public function embedFromString(string $data, string $mimeType): EmbeddedImage

/** 清除圖像快取（在記憶體受限環境中使用）*/
public function clearCache(): void

/** 已快取的圖像數量 */
public function cacheCount(): int

final readonly class EmbeddedImage
{
    public string $hash;          // 內容雜湊（用於去重）
    public int    $widthPx;       // 原始像素寬度
    public int    $heightPx;      // 原始像素高度
    public float  $naturalWidth;  // 自然寬度（mm，依 DPI 計算）
    public float  $naturalHeight; // 自然高度（mm）
    public string $format;        // 'jpeg' | 'png' | 'webp'
    public bool   $hasAlpha;      // 是否含透明通道
}

namespace NextPDF\Core\Graphics;

final class SvgParser

/**
 * 解析 SVG 並轉換為 PDF 向量圖形指令。
 *
 * @param non-empty-string $svg SVG 字串（非檔案路徑）
 * @return ParsedSvg
 * @throws SvgParseException
 */
public function parse(string $svg): ParsedSvg

/** 從 DrawingEngine 渲染已解析的 SVG */
public function render(
    ParsedSvg $svg,
    float     $x,
    float     $y,
    float     $width,
    ?float    $height = null,
): void