วาดเกรเดียนต์และใช้ความโปร่งใสร่วมกับโหมดผสานสี

ภาพรวมโดยสังเขป

เติมพื้นที่ด้วยเกรเดียนต์สองจุดสีแบบแกน (เชิงเส้น) หรือแบบรัศมี แล้วผสานรูปทรงที่ซ้อนทับกันด้วยค่าอัลฟาคงที่และโหมดผสานสีที่เลือกได้ โค้ดนี้อ้างอิง 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 และทำงานตามเมทริกซ์ backport 8.1–8.4

ภาพรวมเชิงแนวคิด

linearGradient(x, y, w, h, start, end) วาดการไล่ระดับสีระหว่างจุดสี Color สองจุดไปตามแกนของกล่อง ISO 32000-2 นิยาม Coords ของเชดดิงแบบแกนเป็น [x0 y0 x1 y1] หากจุดปลายทั้งสองทับกัน จะไม่มีการวาดสิ่งใด radialGradient(...) วาดการไล่ระดับสีระหว่างวงกลมสองวง Coords ของแบบรัศมีคือ [x0 y0 r0 x1 y1 r1] และรัศมีทั้งสองต้องมีค่า ≥ 0

setAlpha($alpha, $mode) กำหนดความทึบแสงคงที่สำหรับการวาดต่อจากนั้น อาร์กิวเมนต์แรกคือค่าคงที่อัลฟา (ca/CA) อาร์กิวเมนต์ที่สองใช้เลือกโหมดผสานสี (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');

ตัวอย่างโค้ด — สำหรับใช้งานจริง

นี่คือตัวอย่างฉบับสมบูรณ์ที่พร้อมใช้กับ harness โดยใช้ค่า 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() ถือว่าไม่ถูกต้อง รัศมีที่เป็นศูนย์ทั้งสองค่าจะไม่วาดสิ่งใด
ค่าอัลฟาคงอยู่ข้ามคำสั่งวาด setAlpha(0.7, …) ยังคงมีผลกับการวาดทุกครั้งที่ตามมาจนกว่าจะรีเซ็ต ให้คืนค่า setAlpha(1.0, BlendMode::Normal) หลังบล็อกที่โปร่งใส มิฉะนั้นเนื้อหาที่ตามมาจะดูจางลง
โหมดผสานสีต้องมีฉากหลัง โหมดผสานสีเช่น Multiply หรือ Screen จะผสานกับสิ่งที่วาดไว้แล้ว ในหน้าว่างเปล่าจะมองไม่เห็นผลลัพธ์ ดังนั้นให้วาดฉากหลังก่อน
อาร์เรย์โหมดผสานสีของ PDF 2.0 ถูกเลิกใช้แล้ว NextPDF สร้างชื่อโหมดผสานสีเพียงชื่อเดียว ซึ่งเป็นรูปแบบของ PDF 2.0 ข้อกำหนดดังกล่าวเลิกใช้รูปแบบอาร์เรย์แบบเดิม

ประสิทธิภาพ

เกรเดียนต์ประกอบด้วยอ็อบเจกต์เชดดิงหนึ่งรายการพร้อมการระบายพื้น ค่าอัลฟาและโหมดผสานสีเป็นพารามิเตอร์ของสถานะกราฟิก แต่ละรายการมีต้นทุนคงที่ต่อการใช้งานหนึ่งครั้ง และทั้งสองอยู่ภายในงบ 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 ใน trailer และอะตอมวันที่จะแตกต่างกันในการบันทึกแต่ละครั้ง harness จะตัดอะตอมเหล่านั้นออก แล้วเปรียบเทียบโครงสร้างที่ผ่านการทำให้เป็นมาตรฐานด้วย qpdf สูตรนี้อธิบายวิธีที่ NextPDF สร้างโครงสร้างดังกล่าว สูตรนี้ไม่ได้อ้างว่าครอบคลุมความสอดคล้องตาม ISO 32000-2 ทั้งหมด

บริบทเชิงพาณิชย์

ไม่เกี่ยวข้อง เกรเดียนต์ อัลฟา และโหมดผสานสีเป็นความสามารถของ Core โดยไม่มีเงื่อนไขจำกัดเฉพาะ Premium