Verlopen tekenen en transparantie met overvloeimodi gebruiken

In een oogopslag

Vul een gebied met een axiaal (lineair) of radiaal verloop met twee stops. Combineer vervolgens overlappende vormen met constante alfa en een optionele overvloeimodus. De code volgt examples/25-gradients.php en examples/20-transparency.php.

Een verloop is een ISO 32000-2-arcering. linearGradient() maakt een Type 2-arcering (axiaal) en radialGradient() maakt een Type 3-arcering (radiaal). Transparantie gebruikt de alfaconstante van de grafische toestand. setAlpha() stelt de niet-tekenende ca-waarde en de tekenende CA-waarde in.

Installatie

composer require nextpdf/core:^3

Je hebt geen optionele extensie nodig. De API voor verlopen, alfa en overvloeimodi is stabiel sinds 1.0.0 en draait op de 8.1–8.4-backportmatrix.

Conceptueel overzicht

linearGradient(x, y, w, h, start, end) tekent een kleurovergang langs de as van het vak tussen twee Color-stops. ISO 32000-2 definieert de Coords van een axiale arcering als [x0 y0 x1 y1]. Als de eindpunten samenvallen, wordt er niets getekend. radialGradient(...) laat de kleur tussen twee cirkels verlopen. De radiale Coords is [x0 y0 r0 x1 y1 r1] en beide stralen moeten ≥ 0 zijn.

setAlpha($alpha, $mode) stelt een constante dekking in voor het tekenwerk dat volgt. Het eerste argument is de alfaconstante (ca/CA). Het tweede argument selecteert de overvloeimodus (BM in het transparante beeldmodel). Zet alfa terug op 1.0 en de overvloeimodus op Normal voordat je niet-gerelateerde inhoud tekent.

API-oppervlak

Het API-oppervlak wordt gegenereerd uit PHPDoc. Dit recipe gebruikt de volgende methoden:

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() leveren de verloop-stops.
setFillColor(...) stelt de kleur in die met alfa en de overvloeimodus wordt gecombineerd.

Codevoorbeeld — snelstart

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

Codevoorbeeld — productie

Dit is het volledige voorbeeld dat klaar is voor de harness. Het respecteert NEXTPDF_COOKBOOK_OUTPUT en voegt geen eigen entropie toe.

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

Randgevallen en valkuilen

Samenvallende verloop-eindpunten tekenen niets. Een vak met nulgrootte, waarbij w of h de as laat samenvallen, levert volgens ISO 32000-2 een lege axiale arcering op. Controleer of het vak afmetingen heeft.
Stralen moeten niet-negatief zijn. Een negatieve straal in radialGradient() is ongeldig. Twee stralen van nul tekenen niets.
Alfa blijft behouden tussen tekenbewerkingen. setAlpha(0.7, …) blijft van kracht voor elke latere tekenbewerking totdat je het opnieuw instelt. Herstel setAlpha(1.0, BlendMode::Normal) na een transparant blok, anders verschijnt latere inhoud vervaagd.
Een overvloeimodus heeft een achtergrond nodig. Een overvloeimodus zoals Multiply of Screen combineert met wat al is getekend. Boven een lege pagina is het effect onzichtbaar, dus teken eerst een achtergrond.
De PDF 2.0-overvloeimodus-array is verouderd. NextPDF produceert één enkele overvloeimodusnaam; dat is de PDF 2.0-vorm. De specificatie verklaart de verouderde array-vorm achterhaald.

Prestaties

Een verloop is één arceringobject plus een vulling. Alfa en overvloeimodus zijn parameters van de grafische toestand. Beide hebben constante kosten per gebruik en blijven binnen het budget van 2000 ms / 64 MB. Er vindt geen rasterisatie plaats, dus verlopen blijven resolutieonafhankelijke arceringen.

Beveiligingsnotities

Dit recipe tekent alleen de geometrie en kleuren die je code aanlevert. Het voert geen invoerparsing uit en gebruikt geen netwerktoegang. Valideer kleur- en coördinaatwaarden uit niet-vertrouwde gegevens voordat je ze gebruikt.

Conformiteit

Bewering	Specificatie	Clausule
`ShadingType` 2 is axiaal, 3 is radiaal.	ISO 32000-2	§8.7.4.3
Axiale `Coords` is `[x0 y0 x1 y1]`; samenvallende eindpunten tekenen niets.	ISO 32000-2	§8.7.4.5.3
Radiale `Coords` is `[x0 y0 r0 x1 y1 r1]`; stralen ≥ 0.	ISO 32000-2	§8.7.4.5.4
`CA`/`ca` zijn de alfaconstanten voor stroking/non-stroking.	ISO 32000-2	§8.4.5
`BM` is de huidige overvloeimodus.	ISO 32000-2	§11.3.5

Reproduceerbaarheidsprofiel — structureel. De trailer-/ID en datumatomen variëren bij elke save. De harness verwijdert die atomen en vergelijkt daarna de qpdf-genormaliseerde structuur. Dit recipe beschrijft hoe NextPDF de structuur produceert. Het doet geen algemene uitspraak over ISO 32000-2-conformiteit.

Commerciële context

Niet van toepassing. Verlopen, alfa en overvloeimodi zijn Core-functies. Ze hebben geen Premium-drempel.