Dessiner des dégradés et utiliser la transparence et les modes de fusion

En bref

Remplis une zone avec un dégradé axial (linéaire) ou radial à deux arrêts, puis compose des formes qui se chevauchent avec une constante alpha et, éventuellement, un mode de fusion. Le code suit examples/25-gradients.php et examples/20-transparency.php.

Un dégradé correspond à un shading ISO 32000-2. linearGradient() émet un shading de Type 2 (axial), tandis que radialGradient() émet un shading de Type 3 (radial). La transparence repose sur la constante alpha de l’état graphique. setAlpha() définit la valeur de non-tracé ca et la valeur de tracé CA.

Installation

composer require nextpdf/core:^3

Aucune extension facultative n’est requise. L’API des dégradés, de l’alpha et des modes de fusion est stable depuis la version 1.0.0 et fonctionne sur la matrice de backport 8.1–8.4.

Aperçu conceptuel

linearGradient(x, y, w, h, start, end) peint un dégradé de couleur le long de l’axe de la boîte, entre deux arrêts Color. ISO 32000-2 définit les Coords d’un shading axial comme [x0 y0 x1 y1]. Si les extrémités coïncident, rien n’est peint. radialGradient(...) crée un dégradé entre deux cercles. Les Coords radiaux sont [x0 y0 r0 x1 y1 r1], et les deux rayons doivent être ≥ 0.

setAlpha($alpha, $mode) définit l’opacité constante des opérations de dessin suivantes. Le premier argument est la constante alpha (ca/CA). Le second argument sélectionne le mode de fusion (BM dans le modèle d’imagerie transparente). Réinitialise l’alpha à 1.0 et le mode de fusion à Normal avant de dessiner du contenu indépendant.

Surface de l’API

La surface de l’API est générée automatiquement à partir du PHPDoc. Cette recette s’appuie sur ces méthodes :

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() fournissent les arrêts du dégradé.
setFillColor(...) définit la couleur à laquelle l’alpha et le mode de fusion s’appliquent.

Exemple de code — Démarrage rapide

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

Exemple de code — Production

Voici l’exemple complet, prêt pour le harnais. Il respecte NEXTPDF_COOKBOOK_OUTPUT et n’introduit aucune entropie propre.

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

Cas limites et pièges

Des extrémités de dégradé coïncidentes ne peignent rien. Une boîte de taille nulle, ou une valeur w ou h qui annule l’axe, donne un shading axial vide selon ISO 32000-2. Vérifie que la boîte présente une étendue.
Les rayons doivent être positifs ou nuls. Un rayon négatif passé à radialGradient() est invalide. Deux rayons nuls ne peignent rien.
L’alpha persiste d’un tracé à l’autre. setAlpha(0.7, …) reste en vigueur pour chaque opération de dessin ultérieure jusqu’à ce que tu le réinitialises. Rétablis setAlpha(1.0, BlendMode::Normal) après un bloc transparent, sinon le contenu suivant paraîtra délavé.
Un mode de fusion a besoin d’un arrière-plan. Un mode de fusion comme Multiply ou Screen se combine avec ce qui est déjà dessiné. Sur une page vide, l’effet est invisible ; dessine donc d’abord un arrière-plan.
La forme tableau des modes de fusion de PDF 2.0 est dépréciée. NextPDF émet un seul nom de mode de fusion, qui est la forme PDF 2.0. La forme historique en tableau est dépréciée dans la spécification.

Performances

Un dégradé correspond à un objet shading plus un remplissage. L’alpha et le mode de fusion sont des paramètres de l’état graphique. Chaque utilisation a un coût constant, et l’ensemble reste dans le budget de 2000 ms / 64 Mo. Aucune rastérisation n’a lieu ; les dégradés restent donc des shadings indépendants de la résolution.

Notes de sécurité

Cette recette ne peint que la géométrie et les couleurs fournies par ton code. Elle n’analyse aucune entrée et n’effectue aucun accès réseau. Valide les valeurs de couleur et de coordonnées issues de données non fiables avant de les utiliser.

Conformité

Énoncé	Spéc.	Clause
`ShadingType` 2 est axial, 3 est radial.	ISO 32000-2	§8.7.4.3
Les `Coords` axiaux sont `[x0 y0 x1 y1]` ; des extrémités coïncidentes ne peignent rien.	ISO 32000-2	§8.7.4.5.3
Les `Coords` radiaux sont `[x0 y0 r0 x1 y1 r1]` ; les rayons sont ≥ 0.	ISO 32000-2	§8.7.4.5.4
`CA`/`ca` sont les constantes alpha de stroking/non-stroking.	ISO 32000-2	§8.4.5
`BM` est le mode de fusion courant.	ISO 32000-2	§11.3.5

Profil de reproductibilité — structurel. Le /ID du trailer et les atomes de date varient à chaque enregistrement. Le harnais supprime ces atomes, puis compare la structure normalisée par qpdf. Cette recette décrit comment NextPDF produit la structure. Elle ne formule aucune revendication globale de conformité ISO 32000-2.

Contexte commercial

Sans objet. Les dégradés, l’alpha et les modes de fusion sont des fonctionnalités du cœur (Core). Ils ne sont soumis à aucune barrière Premium.