Rysowanie gradientów oraz używanie przezroczystości i trybów mieszania

W skrócie

Wypełnij obszar dwupunktowym gradientem osiowym (liniowym) lub promienistym. Następnie złóż nakładające się kształty przy stałej wartości kanału alfa i opcjonalnym trybie mieszania. Kod odpowiada przykładom w plikach examples/25-gradients.php i examples/20-transparency.php.

Gradient to cieniowanie w rozumieniu ISO 32000-2. linearGradient() generuje cieniowanie typu 2 (osiowe), a radialGradient() generuje cieniowanie typu 3 (promieniste). Przezroczystość opiera się na stałej alfa w stanie graficznym. setAlpha() ustawia wartość ca dla wypełniania oraz wartość CA dla obrysu.

Instalacja

composer require nextpdf/core:^3

Opcjonalne rozszerzenie nie jest potrzebne. API gradientów, kanału alfa i trybów mieszania jest stabilne od wersji 1.0.0 i działa w ramach macierzy backportów 8.1–8.4.

Omówienie koncepcyjne

linearGradient(x, y, w, h, start, end) rysuje przejście kolorów wzdłuż osi prostokąta między dwoma punktami Color. ISO 32000-2 definiuje pole Coords cieniowania osiowego jako [x0 y0 x1 y1]. Jeśli punkty końcowe się pokrywają, nic nie zostaje narysowane. radialGradient(...) tworzy przejście między dwoma okręgami. Dla cieniowania promienistego pole Coords ma postać [x0 y0 r0 x1 y1 r1], a oba promienie muszą być ≥ 0.

setAlpha($alpha, $mode) ustawia stałą krycia dla kolejnych operacji rysowania. Pierwszy argument to stała alfa (ca/CA). Drugi argument wybiera tryb mieszania (BM w modelu obrazowania z przezroczystością). Przed rysowaniem niezależnej treści przywróć alfę do wartości 1.0, a tryb mieszania do Normal.

Powierzchnia API

Opis API jest generowany z PHPDoc. Ten przepis korzysta z następujących metod:

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() dostarczają kolory punktów gradientu.
setFillColor(...) ustawia kolor składany następnie według kanału alfa i trybu mieszania.

Przykładowy kod — szybki start

<?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');

Przykładowy kod — wersja produkcyjna

To kompletny przykład, gotowy do uruchomienia w środowisku testowym. Uwzględnia zmienną NEXTPDF_COOKBOOK_OUTPUT i nie wprowadza żadnej własnej entropii.

<?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";

Przypadki brzegowe i pułapki

Pokrywające się punkty końcowe gradientu nic nie rysują. Prostokąt o zerowym rozmiarze, w którym w lub h sprowadza oś do punktu, daje puste cieniowanie osiowe zgodnie z ISO 32000-2. Upewnij się, że prostokąt ma niezerowe wymiary.
Promienie muszą być nieujemne. Ujemny promień przekazany do radialGradient() jest nieprawidłowy. Dwa zerowe promienie nic nie rysują.
Kanał alfa utrzymuje się między kolejnymi operacjami rysowania. setAlpha(0.7, …) pozostaje w mocy dla każdej kolejnej operacji rysowania, dopóki nie zostanie zresetowane. Po bloku z przezroczystością przywróć setAlpha(1.0, BlendMode::Normal), w przeciwnym razie późniejsza treść będzie wyglądać na wyblakłą.
Tryb mieszania wymaga tła. Tryb mieszania, taki jak Multiply lub Screen, składa obraz z tym, co już zostało narysowane. Na pustej stronie efekt jest niewidoczny, dlatego najpierw narysuj tło.
Forma tablicowa trybów mieszania z PDF 2.0 jest wycofana. NextPDF zapisuje pojedynczą nazwę trybu mieszania, czyli formę zgodną z PDF 2.0. Specyfikacja wycofuje starszą formę tablicową.

Wydajność

Gradient to jeden obiekt cieniowania wraz z wypełnieniem. Kanał alfa i tryb mieszania są parametrami stanu graficznego. Każdy z nich ma stały koszt jednorazowego użycia, a oba mieszczą się w budżecie 2000 ms / 64 MB. Nie zachodzi rasteryzacja, dlatego gradienty pozostają cieniowaniami niezależnymi od rozdzielczości.

Uwagi dotyczące bezpieczeństwa

Ten przepis rysuje wyłącznie geometrię i kolory dostarczane przez kod. Nie parsuje danych wejściowych ani nie korzysta z sieci. Zanim użyjesz wartości kolorów i współrzędnych pochodzących z niezaufanych danych, sprawdź ich poprawność.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula
`ShadingType` 2 to cieniowanie osiowe, 3 to promieniste.	ISO 32000-2	§8.7.4.3
Osiowe `Coords` ma postać `[x0 y0 x1 y1]`; pokrywające się punkty końcowe nic nie rysują.	ISO 32000-2	§8.7.4.5.3
Dla cieniowania promienistego `Coords` ma postać `[x0 y0 r0 x1 y1 r1]`; promienie ≥ 0.	ISO 32000-2	§8.7.4.5.4
`CA`/`ca` to stałe alfa dla stroking/non-stroking.	ISO 32000-2	§8.4.5
`BM` to bieżący tryb mieszania.	ISO 32000-2	§11.3.5

Profil powtarzalności — strukturalny. Element /ID w trailerze oraz atomy daty zmieniają się przy każdym zapisie. Środowisko testowe usuwa te atomy, a następnie porównuje strukturę znormalizowaną przez qpdf. Ten przepis opisuje, w jaki sposób NextPDF tworzy tę strukturę. Nie formułuje ogólnego twierdzenia o zgodności z ISO 32000-2.

Kontekst komercyjny

Nie dotyczy. Gradienty, kanał alfa i tryby mieszania to funkcje pakietu Core. Nie podlegają bramce Premium.