Pintar degradados y usar transparencia y modos de fusión

De un vistazo

Rellenar una región con un degradado axial (lineal) o radial de dos paradas y, después, componer formas superpuestas con un alfa constante y un modo de fusión opcional. El código sigue examples/25-gradients.php y examples/20-transparency.php.

Un degradado es un sombreado de ISO 32000-2. linearGradient() emite un sombreado de tipo 2 (axial), y radialGradient() emite un sombreado de tipo 3 (radial). La transparencia se controla mediante la constante alfa del estado gráfico. setAlpha() establece el valor de no trazado ca y el valor de trazado CA.

Instalación

composer require nextpdf/core:^3

No se requiere ninguna extensión opcional. La API de degradados, alfa y modos de fusión es estable desde la 1.0.0 y se ejecuta dentro de la matriz de retrocompatibilidad 8.1–8.4.

Panorama conceptual

linearGradient(x, y, w, h, start, end) pinta una mezcla de color a lo largo del eje del cuadro, entre dos paradas Color. ISO 32000-2 define las Coords de un sombreado axial como [x0 y0 x1 y1]. Si los extremos coinciden, no se pinta nada. radialGradient(...) mezcla entre dos círculos. Las Coords radiales son [x0 y0 r0 x1 y1 r1], y ambos radios deben ser ≥ 0.

setAlpha($alpha, $mode) establece la opacidad constante para las operaciones de pintado siguientes. El primer argumento es la constante alfa (ca/CA). El segundo argumento selecciona el modo de fusión (BM en el modelo de imagen transparente). Restablecer el alfa a 1.0 y el modo de fusión a Normal antes de dibujar contenido no relacionado.

Superficie de la API

La superficie de la API se genera automáticamente a partir del PHPDoc. Esta receta se basa en estos métodos:

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() proporcionan las paradas del degradado.
setFillColor(...) establece el color que se compondrá con el alfa y el modo de fusión.

Ejemplo de código — Inicio rápido

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

Ejemplo de código — Producción

Este es el ejemplo completo, listo para el arnés de pruebas. Respeta NEXTPDF_COOKBOOK_OUTPUT y no introduce entropía propia.

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

Casos límite y trampas

Los extremos coincidentes del degradado no pintan nada. Un cuadro de tamaño cero, en el que w o h colapsa el eje, produce un sombreado axial vacío según ISO 32000-2. Confirmar que el cuadro tiene extensión.
Los radios deben ser no negativos. Un radio negativo en radialGradient() no es válido. Dos radios cero no pintan nada.
El alfa persiste entre pintados. setAlpha(0.7, …) sigue activo en cada operación de pintado posterior hasta que se restablezca. Restaurar setAlpha(1.0, BlendMode::Normal) después de un bloque transparente; de lo contrario, el contenido posterior saldrá atenuado.
Un modo de fusión necesita un fondo. Un modo de fusión como Multiply o Screen se compone con lo que ya está dibujado. En una página vacía el efecto es invisible, por lo que conviene dibujar primero un fondo.
El arreglo de modo de fusión de PDF 2.0 está obsoleto. NextPDF emite un único nombre de modo de fusión, que es la forma de PDF 2.0. La forma heredada con arreglo está obsoleta en la especificación.

Rendimiento

Un degradado es un objeto de sombreado más un relleno. El alfa y el modo de fusión son parámetros del estado gráfico. Cada uso tiene coste constante, y ambos se mantienen dentro del presupuesto de 2000 ms / 64 MB. No se produce rasterización, así que los degradados siguen siendo sombreados independientes de la resolución.

Notas de seguridad

Esta receta solo pinta la geometría y los colores que proporciona el código. No analiza entradas ni accede a la red. Validar los valores de color y de coordenadas que provengan de datos no confiables antes de usarlos.

Conformidad

Afirmación	Especificación	Cláusula
`ShadingType` 2 es axial, 3 es radial.	ISO 32000-2	§8.7.4.3
Las `Coords` axiales son `[x0 y0 x1 y1]`; los extremos coincidentes no pintan nada.	ISO 32000-2	§8.7.4.5.3
Las `Coords` radiales son `[x0 y0 r0 x1 y1 r1]`; radios ≥ 0.	ISO 32000-2	§8.7.4.5.4
`CA`/`ca` son las constantes alfa de stroking/non-stroking.	ISO 32000-2	§8.4.5
`BM` es el modo de fusión actual.	ISO 32000-2	§11.3.5

Perfil de reproducibilidad — estructural. El /ID del tráiler y los átomos de fecha varían en cada guardado. El arnés de pruebas elimina esos átomos y luego compara la estructura normalizada con qpdf. Esta receta describe cómo NextPDF produce la estructura. No formula una afirmación general de conformidad con ISO 32000-2.

Contexto comercial

No aplica. Los degradados, el alfa y los modos de fusión son capacidades del Core. No están sujetos a ningún gate de Premium.