FMatrix and transforms

Introduction

Objects on a PDF page get their size and position from a transformation matrix that is the sum of its own and those of the chain of parent nodes, up to the page root. These transformations are expressed in the form of a matrix. In Mako you can create matrices and apply them to objects to move, resize, or rotate content.

When you need to move, resize, or rotate content, you create an FMatrix and apply it with .setRenderTransform().

Creating an FMatrix

The FMatrix constructor can be used in three different ways:

1.	`FMatrix()`	Default. Use this to create a default matrix, then use the following methods to change individual values.
2.	`FMatrix(double xx, double xy, double yx, double yy, double dx, double dy);`	Specifies the full range of values.
3.	`FMatrix(FRect sourceRect, FRect destRect);`	This is a very useful constructor. It calculates a matrix for you based on source and destination rectangles, each expressed as an `FRect` (`x,y` origin and `dX`, `dY` dimensions).

The values (xx, xy, yx, yy, dx, and dy) are described below.

Setting values individually

The API documentation refers to a TItem, which is defined (via a typedef) as a double.

`void setXX (TItem x)`	Sets `xx` component.
`void setXY (TItem x)`	Sets `xy` component.
`void setYX (TItem x)`	Sets `yx` component.
`void setYY (TItem x)`	Sets `yy` component.
`void setDX (TItem x)`	Sets `dx` component.
`void setDY (TItem x)`	Sets `dy` component.

Matrix values

Matrix values and their effects are shown below, alternatively you can use the transformation methods to apply these transformations for you.

Rotations will always be performed using the top left corner of the page as the origin, which may result in the object being displaced from its original position.

Transformation methods

The following methods are available for FMatrix.

C#

void FMatrix.translate(double dx, double dy)
void FMatrix.scale(double xscale, double yscale)
void FMatrix.rotate(double radians)

Using translate() in conjunction with rotate() may lead to unexpected results. It is recommended to use setDX() and setDY() to perform translations in this case.

Here is an example of how to use FMatrix to transform an IDOMGroup containing ILayout content.

C++

CPP

//First create an FMatrix and apply transformations
FMatrix transform;
transform.translate(400.0, 0.0);
transform.scale(1.0, 2.0);
transform.rotate(PI / 2.0);

//Then create a group and add the content
IDOMGroupPtr group = IDOMGroup::create(mako, transform);
group->appendChild(layout->layout(paragraphs));

// Finally add the group to the page
fixedPage->appendChild(group);

C#

//First create an FMatrix and apply transformations
var rotate = new FMatrix();
rotate.translate(400.0, 0.0);
rotate.scale(1.0, 2.0);
rotate.rotate(Math.PI / 2);

//Then create a group and add the content
var group = IDOMGroup.create(mako, rotate);
group.appendChild(layout.layout(paragraphs));

// Finally add the group to the page
fixedPage.appendChild(group);

Original	After transformation