グラデーションの描画と透過・ブレンドモードの使用

概要

領域を 2 つのストップを持つ軸方向（線形）または放射状のグラデーションで塗りつぶし、一定のアルファ値と任意のブレンドモードで、重なり合うシェイプを合成します。このコードは examples/25-gradients.php と examples/20-transparency.php に沿っています。

グラデーションは ISO 32000-2 のシェーディングです。linearGradient() は Type 2（軸方向）のシェーディングを出力し、radialGradient() は Type 3（放射状）のシェーディングを出力します。透過はグラフィックスステートのアルファ定数で表します。setAlpha() は、非ストローク用の ca 値と、ストローク用の CA 値を設定します。

インストール

composer require nextpdf/core:^3

オプションの拡張機能は必要ありません。グラデーション、アルファ、ブレンドモードの API は 1.0.0 以降で安定しており、8.1〜8.4 のバックポートマトリックスで動作します。

概念の概要

linearGradient(x, y, w, h, start, end) は、2 つの Color ストップ間で、ボックスの軸に沿った色のブレンドを描画します。ISO 32000-2 は、軸方向シェーディングの Coords を [x0 y0 x1 y1] として定義します。端点が一致する場合、何も描画されません。radialGradient(...) は、2 つの円の間をブレンドします。放射状の Coords は [x0 y0 r0 x1 y1 r1] であり、両方の半径は 0 以上である必要があります。

setAlpha($alpha, $mode) は、以降の描画に適用される一定の不透明度を設定します。第 1 引数はアルファ定数（ca/CA）です。第 2 引数はブレンドモード（透過イメージングモデルにおける BM）を選択します。関連のないコンテンツを描画する前に、アルファを 1.0 に、ブレンドモードを Normal にリセットしてください。

API サーフェス

API サーフェスは PHPDoc から自動生成されます。このレシピは次のメソッドに依存します。

linearGradient(float $x, float $y, float $w, float $h, Color $start, Color $end): static
radialGradient(float $x, float $y, float $w, float $h, Color $start, Color $end): static
setAlpha(float $alpha, BlendMode $mode = BlendMode::Normal): static
Color::rgb(int $r, int $g, int $b)、Color::white()、Color::black() はグラデーションストップを提供します。
setFillColor(...) は、アルファとブレンドモードによって合成される色を設定します。

コードサンプル — クイックスタート

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;
use NextPDF\Graphics\BlendMode;
use NextPDF\Graphics\Color;

$doc = Document::createStandalone();
$doc->addPage();

// Axial gradient: blue -> white across a 190 x 40 box.
$doc->linearGradient(10, 30, 190, 40, Color::rgb(30, 58, 138), Color::white());

// Two overlapping rectangles at 70% opacity with Multiply blend.
$doc->setAlpha(0.7, BlendMode::Multiply);
$doc->setFillColor(220, 38, 38);
$doc->rect(20, 90, 60, 40, 'F');
$doc->setFillColor(37, 99, 235);
$doc->rect(50, 90, 60, 40, 'F');
$doc->setAlpha(1.0, BlendMode::Normal); // reset

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/gradients.pdf');

コードサンプル — 本番

これは、完全でハーネスに対応した例です。NEXTPDF_COOKBOOK_OUTPUT を尊重し、独自のエントロピーは固定しません。

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;
use NextPDF\Graphics\BlendMode;
use NextPDF\Graphics\Color;

$doc = Document::createStandalone();
$doc->setTitle('Gradients and Transparency');
$doc->addPage();

$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Gradients and Transparency', newLine: true);
$doc->ln(4);

// 1. Axial gradient — blue to white.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '1. Axial gradient', newLine: true);
$doc->ln(2);
$doc->linearGradient(
    x: 10, y: $doc->getY(), w: 190, h: 40,
    start: Color::rgb(30, 58, 138), end: Color::white(),
);
$doc->ln(44);

// 2. Radial gradient — red centre fading to white.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '2. Radial gradient', newLine: true);
$doc->ln(2);
$doc->radialGradient(
    x: 50, y: $doc->getY(), w: 110, h: 55,
    start: Color::rgb(220, 38, 38), end: Color::white(),
);
$doc->ln(59);

// 3. Constant alpha + blend mode over a light backdrop.
$doc->setFont('helvetica', 'B', 12);
$doc->cell(0, 8, '3. Alpha 0.7 with Multiply blend', newLine: true);
$doc->ln(2);
$baseY = $doc->getY();
$doc->setAlpha(1.0, BlendMode::Normal);
$doc->setFillColor(245, 245, 245);
$doc->rect(15, $baseY, 90, 40, 'F');
$doc->setAlpha(0.7, BlendMode::Multiply);
$doc->setFillColor(220, 38, 38);
$doc->rect(20, $baseY + 5, 40, 30, 'F');
$doc->setFillColor(37, 99, 235);
$doc->rect(40, $baseY + 5, 40, 30, 'F');

// Always reset compositing state before continuing.
$doc->setAlpha(1.0, BlendMode::Normal);
$doc->setFillColor(255);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/gradients.pdf';
$doc->save($out);

echo "Created gradients.pdf\n";

エッジケースと注意点

一致するグラデーション端点では何も描画されません。 w または h が軸をつぶすサイズゼロのボックスでは、ISO 32000-2 に従って空の軸方向シェーディングが生成されます。ボックスに広がりがあることを確認してください。
半径は非負である必要があります。 radialGradient() に負の半径を渡すことは無効です。2 つの半径がともにゼロの場合、何も描画されません。
アルファは描画をまたいで保持されます。 setAlpha(0.7, …) は、リセットするまで以降のすべての描画に対して有効なままです。透過ブロックの後に setAlpha(1.0, BlendMode::Normal) を復元してください。そうしないと、以降のコンテンツが薄く表示されてしまいます。
ブレンドモードには背景が必要です。 Multiply や Screen などのブレンドモードは、すでに描画されている内容に対して合成を行います。空のページ上では効果が見えないため、先に背景を描画してください。
PDF 2.0 のブレンドモード配列は非推奨です。 NextPDF は単一のブレンドモード名を出力します。これは PDF 2.0 の形式です。従来の配列形式は仕様で非推奨とされています。

パフォーマンス

グラデーションは、1 つのシェーディングオブジェクトと塗りつぶしで構成されます。アルファとブレンドモードはグラフィックスステートのパラメーターです。使用 1 回あたりのコストは一定であり、どちらも 2000 ms / 64 MB の予算内に収まります。ラスタライズは行われないため、グラデーションは解像度に依存しないシェーディングのままです。

セキュリティに関する注意

このレシピは、コードで指定されたジオメトリと色のみを描画します。入力のパースやネットワークアクセスは発生しません。信頼できないデータに由来する色や座標の値は、使用する前に検証してください。

適合性

記述	仕様	条項
`ShadingType` 2 は軸方向、3 は放射状。	ISO 32000-2	§8.7.4.3
軸方向の `Coords` は `[x0 y0 x1 y1]`。端点が一致する場合は描画なし。	ISO 32000-2	§8.7.4.5.3
放射状の `Coords` は `[x0 y0 r0 x1 y1 r1]`。半径は 0 以上。	ISO 32000-2	§8.7.4.5.4
`CA`/`ca` は stroking/non-stroking のアルファ定数。	ISO 32000-2	§8.4.5
`BM` は現在のブレンドモード。	ISO 32000-2	§11.3.5

再現性プロファイル — 構造的。 トレーラーの /ID と日付アトムは、保存のたびに変化します。ハーネスはこれらのアトムを除去したうえで、qpdf で正規化された構造を比較します。このレシピは、NextPDF がどのように構造を生成するかを説明しています。これは ISO 32000-2 適合性を包括的に主張するものではありません。

商用上の位置付け

該当しません。グラデーション、アルファ、ブレンドモードは Core の機能です。これらは Premium によるゲート対象ではありません。