Transformaciones (HasTransforms)

El trait HasTransforms proporciona transformaciones geométricas que modifican cómo se renderizan las operaciones de dibujo posteriores. Las transformaciones operan sobre la Matriz de Transformación Actual (CTM) y deben estar envueltas en pares startTransform() / stopTransform() para aislar sus efectos.

Todos los métodos retornan static, por lo que cada llamada puede ser encadenada.

Referencia rápida

Método	Efecto
startTransform()	Guardar estado gráfico (push CTM)
stopTransform()	Restaurar estado gráfico (pop CTM)
rotate()	Rotar alrededor de un punto
scale()	Escalar horizontal y verticalmente
translate()	Mover el origen de coordenadas
skew()	Sesgar a lo largo de los ejes X e Y
mirrorH()	Reflejar horizontalmente
mirrorV()	Reflejar verticalmente
mirrorP()	Reflejar sobre un punto
mirrorL()	Reflejar sobre una línea arbitraria

Ejemplo básico

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)

    // Texto rotado
    ->startTransform()
    ->rotate(45, 105, 60)
    ->text(100, 55, 'Rotated 45°')
    ->stopTransform()

    // Rectángulo escalado
    ->startTransform()
    ->scale(150, 150, 50, 150)
    ->rect(40, 140, 20, 20, 'DF')
    ->stopTransform()

    // Texto reflejado
    ->startTransform()
    ->mirrorH(105)
    ->text(100, 200, 'Mirrored')
    ->stopTransform();

WARNING

Siempre envuelve las transformaciones en pares startTransform() / stopTransform(). Olvidar stopTransform() deja el estado gráfico modificado para todas las operaciones posteriores.

startTransform / stopTransform

$pdf->startTransform();  // Push del estado gráfico actual
// ... operaciones de dibujo con transformaciones ...
$pdf->stopTransform();   // Pop y restaurar estado anterior

Estas llamadas pueden anidarse. Cada startTransform() empuja un nuevo estado a la pila.

rotate()

$pdf->rotate(float $angle, float $x = '', float $y = '');

Rota el contenido posterior $angle grados en sentido antihorario alrededor del punto (x, y). Si x e y se omiten, se usa la posición actual.

scale()

$pdf->scale(float $sx, float $sy, float $x = '', float $y = '');

Escala el contenido $sx por ciento horizontal y $sy por ciento verticalmente, relativo al punto (x, y). Un valor de 100 significa sin cambio; 200 duplica el tamaño.

translate()

$pdf->translate(float $tx, float $ty);

Desplaza el origen de coordenadas $tx horizontalmente y $ty verticalmente. Todas las coordenadas posteriores se desplazan por esta cantidad hasta que la transformación se detenga.

skew()

$pdf->skew(float $angleX, float $angleY, float $x = '', float $y = '');

Aplica una transformación de sesgo. $angleX sesga a lo largo del eje X y $angleY a lo largo del eje Y, ambos en grados.

Métodos de reflejo

$pdf->mirrorH(float $x = '');                              // Reflejo horizontal sobre eje vertical en x
$pdf->mirrorV(float $y = '');                              // Reflejo vertical sobre eje horizontal en y
$pdf->mirrorP(float $x = '', float $y = '');               // Reflejo sobre un punto
$pdf->mirrorL(float $angle, float $x = '', float $y = ''); // Reflejo sobre una línea a través de (x, y) con ángulo

$pdf->startTransform()
    ->mirrorH(105)
    ->setFont('Helvetica', '', 14)
    ->text(80, 50, 'Flipped horizontally')
    ->stopTransform();

Combinar transformaciones

Se pueden apilar múltiples transformaciones dentro de un solo bloque. Se aplican en el orden en que se llaman.

$pdf->startTransform()
    ->translate(20, 20)
    ->rotate(30)
    ->scale(120, 120)
    ->rect(10, 10, 40, 20, 'DF')
    ->stopTransform();

Soporte completo de CTM

Para casos de uso avanzados, la Matriz de Transformación Actual subyacente es completamente accesible. La matriz de seis elementos [a, b, c, d, e, f] se mapea a la matriz de transformación PDF estándar, dando control completo sobre las transformaciones afines cuando los métodos de conveniencia no son suficientes.