그라데이션으로 칠하고 투명도와 혼합 모드 사용하기

한눈에 보기

영역을 두 정지점(two-stop)을 사용하는 축 방향(선형) 또는 방사형 그라데이션으로 채운 뒤, 상수 알파와 선택적 혼합 모드로 겹치는 도형을 합성합니다. 이 코드는 examples/25-gradients.php 및 examples/20-transparency.php를 기반으로 합니다.

그라데이션은 ISO 32000-2 셰이딩입니다. linearGradient()는 Type 2(축 방향) 셰이딩을 생성하고, radialGradient()는 Type 3(방사형) 셰이딩을 생성합니다. 투명도는 그래픽 상태(graphics-state) 알파 상수입니다. setAlpha()는 비획(non-stroking) ca 값과 획(stroking) CA 값을 설정합니다.

설치

composer require nextpdf/core:^3

선택적 확장 기능은 필요하지 않습니다. 그라데이션, 알파, 혼합 모드 API는 1.0.0부터 안정적으로 유지되어 왔으며, 8.1–8.4 백포트 매트릭스에서 동작합니다.

개념 개요

linearGradient(x, y, w, h, start, end)는 상자의 축을 따라 두 Color 정지점 사이의 색상 혼합을 칠합니다. ISO 32000-2는 축 방향 셰이딩의 Coords를 [x0 y0 x1 y1]로 정의합니다. 끝점이 일치하면 아무것도 칠해지지 않습니다. radialGradient(...)는 두 원 사이를 혼합합니다. 방사형 Coords는 [x0 y0 r0 x1 y1 r1]이며, 두 반지름은 모두 ≥ 0이어야 합니다.

setAlpha($alpha, $mode)는 이후 페인팅에 적용할 상수 불투명도를 설정합니다. 첫 번째 인수는 알파 상수(ca/CA)입니다. 두 번째 인수는 혼합 모드(투명 이미징 모델의 BM)를 선택합니다. 관련 없는 콘텐츠를 그리기 전에 알파를 1.0으로, 혼합 모드를 Normal로 재설정하세요.

API 표면

API 표면은 PHPDoc에서 자동으로 생성됩니다. 이 레시피는 다음 메서드를 사용합니다:

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()은 그라데이션 정지점으로 사용할 색상을 제공합니다.
setFillColor(...)는 알파와 혼합 모드가 합성할 색상을 설정합니다.

코드 샘플 — 빠른 시작

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

코드 샘플 — 프로덕션

이는 하니스(harness)에서 바로 실행할 수 있는 완전한 예제입니다. NEXTPDF_COOKBOOK_OUTPUT을 따르며, 자체적으로 어떤 엔트로피도 고정하지 않습니다.

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

엣지 케이스 및 주의 사항

그라데이션의 끝점이 일치하면 아무것도 칠해지지 않습니다. w 또는 h가 축을 붕괴시키는 크기 0의 상자는 ISO 32000-2에 따라 빈 축 방향 셰이딩을 생성합니다. 상자에 크기가 있는지 확인하세요.
반지름은 음수가 아니어야 합니다. radialGradient()에 음의 반지름을 전달하는 것은 유효하지 않습니다. 두 반지름이 모두 0이면 아무것도 칠해지지 않습니다.
알파는 여러 페인팅에 걸쳐 유지됩니다. setAlpha(0.7, …)은 재설정할 때까지 이후의 모든 페인팅에 계속 적용됩니다. 투명 블록 이후에는 setAlpha(1.0, BlendMode::Normal)을 복원하세요. 그렇지 않으면 이후 콘텐츠가 흐릿하게 표시됩니다.
혼합 모드에는 배경이 필요합니다. Multiply나 Screen 같은 혼합 모드는 이미 그려진 내용에 대해 합성됩니다. 빈 페이지 위에서는 효과가 보이지 않으므로, 먼저 배경을 그리세요.
PDF 2.0 혼합 모드 배열은 더 이상 사용되지 않습니다(deprecated). NextPDF는 단일 혼합 모드 이름을 생성하며, 이것이 PDF 2.0 형식입니다. 레거시 배열 형식은 사양에서 더 이상 사용되지 않습니다.

성능

그라데이션은 하나의 셰이딩 객체와 채우기로 구성됩니다. 알파와 혼합 모드는 그래픽 상태 매개변수입니다. 각각은 사용할 때마다 일정한 비용이 들며, 둘 다 2000 ms / 64 MB 예산 이내에 머무릅니다. 래스터화가 일어나지 않으므로, 그라데이션은 해상도 독립적인 셰이딩으로 유지됩니다.

보안 참고 사항

이 레시피는 코드에서 제공하는 도형과 색상만 칠합니다. 입력 파싱이나 네트워크 접근은 발생하지 않습니다. 신뢰할 수 없는 데이터에서 가져온 색상 및 좌표 값은 사용하기 전에 검증하세요.

적합성

진술	사양	조항
`ShadingType` 2는 축 방향, 3은 방사형입니다.	ISO 32000-2	§8.7.4.3
축 방향 `Coords`는 `[x0 y0 x1 y1]`이며, 끝점이 일치하면 아무것도 칠해지지 않습니다.	ISO 32000-2	§8.7.4.5.3
방사형 `Coords`는 `[x0 y0 r0 x1 y1 r1]`이며, 반지름 ≥ 0입니다.	ISO 32000-2	§8.7.4.5.4
`CA`/`ca`는 stroking/non-stroking 알파 상수입니다.	ISO 32000-2	§8.4.5
`BM`은 현재 혼합 모드입니다.	ISO 32000-2	§11.3.5

재현성 프로필 — 구조적(structural). 트레일러 /ID와 날짜 원자(atom)는 저장할 때마다 달라집니다. 하니스는 해당 원자를 제거한 다음, qpdf로 정규화된 구조를 비교합니다. 이 레시피는 NextPDF가 해당 구조를 생성하는 방식을 설명합니다. 이 레시피는 ISO 32000-2 적합성에 대해 포괄적인 주장을 하지 않습니다.

상업적 맥락

해당 없음. 그라데이션, 알파, 혼합 모드는 Core 기능입니다. 이 기능에는 Premium 게이트가 없습니다.