Cores

O TCPDF-Next fornece gerenciamento completo de cores através do trait HasColors, do value object Graphics\Color e da abstração Graphics\ColorSpace. As cores se aplicam independentemente a traços, preenchimentos e texto.

Definindo Cores

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setDrawColor(255, 0, 0)      // Traço vermelho
    ->setFillColor(0, 0, 255)      // Preenchimento azul
    ->setTextColor(51, 51, 51);    // Texto cinza escuro

Assinaturas

setDrawColor(int $r, int $g = -1, int $b = -1): static   // Cor do traço
setFillColor(int $r, int $g = -1, int $b = -1): static   // Cor de preenchimento
setTextColor(int $r, int $g = -1, int $b = -1): static   // Cor do texto

Quando apenas $r é fornecido ($g e $b padrão -1), o valor é tratado como escala de cinza (0 = preto, 255 = branco).

Value Object Color

use Yeeefang\TcpdfNext\Graphics\Color;

$red  = Color::rgb(255, 0, 0);
$cyan = Color::cmyk(100, 0, 0, 0);
$gray = Color::gray(128);
$spot = Color::spot('Pantone 151 C', 0, 60, 100, 0);

Método Factory	Parâmetros	Espaço de Cor
Color::rgb(r, g, b)	0--255 por canal	DeviceRGB
Color::cmyk(c, m, y, k)	0--100 por canal	DeviceCMYK
Color::gray(value)	0--255	DeviceGray
Color::spot(name, c, m, y, k)	Nome + fallback CMYK	Separation

Espaços de Cor

Espaço de Cor	Uso
DeviceRGB	Saída orientada a tela (web, apresentações)
DeviceCMYK	Saída orientada a impressão (impressão comercial)
DeviceGray	Documentos em escala de cinza
Separation	Cores spot/Pantone para impressão com precisão de marca

Valores CMYK são escritos diretamente no stream PDF. Para fluxos de trabalho com gerenciamento de cores, incorpore um perfil ICC via setColorProfile().

Transparência

setAlpha(float $opacity = 1.0, string $blendMode = 'Normal'): static

$pdf->setAlpha(0.5, 'Multiply')    // 50% opacidade, mistura Multiply
    ->rect(10, 10, 50, 30, 'F')
    ->setAlpha(1.0);                // Resetar para totalmente opaco

Sempre resete a opacidade após seções transparentes para evitar efeitos indesejados no conteúdo subsequente.

Modos de Mistura

Todos os 16 modos de mistura PDF são suportados:

Modo	Efeito
Normal	Origem sobre destino (padrão)
Multiply	Escurece — multiplica valores dos canais
Screen	Clareia — multiplicação inversa
Overlay	Combina Multiply e Screen
Darken / Lighten	Mantém valor mais escuro / mais claro por canal
ColorDodge / ColorBurn	Clareia / escurece o destino
HardLight / SoftLight	Efeito de luz forte / sutil
Difference / Exclusion	Diferença de canal (alto / baixo contraste)
Hue / Saturation	Matiz ou saturação da origem, luminosidade do destino
Color / Luminosity	Cor ou luminosidade da origem

Gradientes

Quatro tipos de gradiente são renderizados como objetos de sombreamento nativos do PDF:

$pdf->linearGradient(10, 10, 100, 50, '#ff0000', '#0000ff', [0, 0, 1, 1]);   // Linear
$pdf->radialGradient(60, 60, 80, 80, '#ffffff', '#000000');                    // Radial
$pdf->coonsPatchMesh(10, 10, 100, 100, $colors, $coords);       // Malha de patch Coons
$pdf->tensorProductPatchMesh(10, 10, 100, 100, $colors, $coords); // Produto tensorial

• Linear — gradiente de duas cores ao longo de um vetor de direção.
• Radial — gradiente de duas cores expandindo de um ponto central.
• Malha de patch Coons — preenchimentos complexos multi-cores definidos por pontos de controle Bezier.
• Malha de produto tensorial — extensão Coons com pontos de controle interiores adicionais.

Exemplo Completo

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setDrawColor(255, 0, 0)       // Traço vermelho
    ->setFillColor(0, 0, 255)       // Preenchimento azul
    ->rect(10, 10, 50, 30, 'DF')    // Desenhar + Preencher
    ->setAlpha(0.5, 'Multiply')     // 50% opacidade com mistura Multiply
    ->setFillColor(255, 255, 0)     // Amarelo
    ->rect(30, 20, 50, 30, 'F')     // Retângulo semi-transparente sobreposto
    ->setAlpha(1.0);                // Resetar opacidade

Dicas

• Use DeviceRGB para PDFs em tela e DeviceCMYK para impressão comercial.
• Cores spot requerem SpotColorManager — é inicializado de forma lazy no primeiro uso.
• Sempre resete alpha para 1.0 após seções transparentes.
• Coordenadas de gradiente usam o sistema de unidades do usuário atual (padrão: mm).