Disegnare gradienti e usare trasparenza e modalità di fusione

In breve

Riempire una regione con un gradiente assiale (lineare) o radiale con due stop, quindi comporre le forme sovrapposte usando un valore alpha costante e, se necessario, una modalità di fusione. Il codice segue examples/25-gradients.php e examples/20-transparency.php.

Un gradiente corrisponde a uno shading ISO 32000-2. linearGradient() emette uno shading di Type 2 (assiale) e radialGradient() emette uno shading di Type 3 (radiale). La trasparenza è la costante alpha dello stato grafico. setAlpha() imposta il valore ca per le operazioni non di tracciatura e il valore CA per quelle di tracciatura.

Installazione

composer require nextpdf/core:^3

Non è richiesta alcuna estensione facoltativa. L’API per gradienti, alpha e modalità di fusione è stabile fin dalla versione 1.0.0 e funziona nella matrice di backport 8.1–8.4.

Panoramica concettuale

linearGradient(x, y, w, h, start, end) disegna una sfumatura di colore lungo l’asse del riquadro, tra due stop Color. ISO 32000-2 definisce le Coords di uno shading assiale come [x0 y0 x1 y1]. Se gli estremi coincidono, non viene disegnato nulla. radialGradient(...) crea una sfumatura tra due cerchi. Le Coords radiali sono [x0 y0 r0 x1 y1 r1] ed entrambi i raggi devono essere ≥ 0.

setAlpha($alpha, $mode) imposta l’opacità costante per le operazioni di disegno successive. Il primo argomento è la costante alpha (ca/CA). Il secondo argomento seleziona la modalità di fusione (BM nel modello di imaging trasparente). Reimpostare l’alpha su 1.0 e la modalità di fusione su Normal prima di disegnare contenuti non correlati.

Superficie API

La superficie API viene generata automaticamente da PHPDoc. Questa ricetta usa i metodi seguenti:

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() forniscono gli stop del gradiente.
setFillColor(...) imposta il colore a cui si applicano la composizione alpha e la modalità di fusione.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

Questo è l’esempio completo, pronto per l’harness. Rispetta NEXTPDF_COOKBOOK_OUTPUT e non introduce entropia propria.

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

Casi limite e insidie

Estremi del gradiente coincidenti non disegnano nulla. Un riquadro di dimensione zero, in cui w o h azzera l’asse, produce uno shading assiale vuoto secondo ISO 32000-2. Verificare che il riquadro abbia un’estensione.
I raggi devono essere non negativi. Un raggio negativo passato a radialGradient() non è valido. Due raggi nulli non disegnano nulla.
L’alpha persiste tra un disegno e l’altro. setAlpha(0.7, …) resta in vigore per tutte le operazioni di disegno successive finché non viene reimpostato. Ripristinare setAlpha(1.0, BlendMode::Normal) dopo un blocco trasparente, altrimenti i contenuti successivi risultano sbiaditi.
Una modalità di fusione richiede uno sfondo. Una modalità di fusione come Multiply o Screen viene composta con ciò che è già stato disegnato. Su una pagina vuota l’effetto è invisibile, quindi disegnare prima uno sfondo.
La forma array della modalità di fusione di PDF 2.0 è deprecata. NextPDF emette un singolo nome di modalità di fusione, che è la forma di PDF 2.0. La vecchia forma array è deprecata nella specifica.

Prestazioni

Un gradiente consiste in un oggetto shading e in un riempimento. L’alpha e la modalità di fusione sono parametri dello stato grafico. Ciascun utilizzo ha un costo costante ed entrambi rientrano nel budget di 2000 ms / 64 MB. Non viene eseguita alcuna rasterizzazione, quindi i gradienti restano shading indipendenti dalla risoluzione.

Note sulla sicurezza

Questa ricetta disegna solo la geometria e i colori forniti dal codice. Non avviene alcuna analisi dell’input né alcun accesso alla rete. Convalidare i valori di colore e le coordinate provenienti da dati non attendibili prima di usarli.

Conformità

Dichiarazione	Specifica	Clausola
`ShadingType` 2 è assiale, 3 è radiale.	ISO 32000-2	§8.7.4.3
Le `Coords` assiali sono `[x0 y0 x1 y1]`; estremi coincidenti non disegnano nulla.	ISO 32000-2	§8.7.4.5.3
Le `Coords` radiali sono `[x0 y0 r0 x1 y1 r1]`; raggi ≥ 0.	ISO 32000-2	§8.7.4.5.4
`CA`/`ca` sono le costanti alpha stroking/non-stroking.	ISO 32000-2	§8.4.5
`BM` è la modalità di fusione corrente.	ISO 32000-2	§11.3.5

Profilo di riproducibilità — strutturale. Il /ID del trailer e gli atomi di data variano a ogni salvataggio. L’harness rimuove questi atomi e confronta la struttura normalizzata con qpdf. Questa ricetta descrive come NextPDF produce la struttura. Non formula alcuna dichiarazione generale di conformità a ISO 32000-2.

Contesto commerciale

Non applicabile. Gradienti, alpha e modalità di fusione sono funzionalità di Core. Non sono soggette ad alcuna barriera Premium.