Skip to content

Pango.Matrix

record (struct)

A PangoMatrix specifies a transformation between user-space and device coordinates.

The transformation is given by

x_device = x_user * matrix->xx + y_user * matrix->xy + matrix->x0;
y_device = x_user * matrix->yx + y_user * matrix->yy + matrix->y0;

Methods

concat

def concat(self, new_matrix: Matrix) -> None

Changes the transformation represented by matrix to be the transformation given by first applying transformation given by new_matrix then applying the original transformation.

Parameters:

  • new_matrix — a PangoMatrix

copy

def copy(self) -> Matrix | None

Copies a PangoMatrix.

free

def free(self) -> None

Free a PangoMatrix.

get_font_scale_factor

def get_font_scale_factor(self) -> float

Returns the scale factor of a matrix on the height of the font.

That is, the scale factor in the direction perpendicular to the vector that the X coordinate is mapped to. If the scale in the X coordinate is needed as well, use Matrix.get_font_scale_factors.

get_font_scale_factors

def get_font_scale_factors(self) -> tuple[float, float]

Calculates the scale factor of a matrix on the width and height of the font.

That is, xscale is the scale factor in the direction of the X coordinate, and yscale is the scale factor in the direction perpendicular to the vector that the X coordinate is mapped to.

Note that output numbers will always be non-negative.

get_slant_ratio

def get_slant_ratio(self) -> float

Gets the slant ratio of a matrix.

For a simple shear matrix in the form:

1 λ
0 1

this is simply λ.

rotate

def rotate(self, degrees: float) -> None

Changes the transformation represented by matrix to be the transformation given by first rotating by degrees degrees counter-clockwise then applying the original transformation.

Parameters:

  • degrees — degrees to rotate counter-clockwise

scale

def scale(self, scale_x: float, scale_y: float) -> None

Changes the transformation represented by matrix to be the transformation given by first scaling by sx in the X direction and sy in the Y direction then applying the original transformation.

Parameters:

  • scale_x — amount to scale by in X direction
  • scale_y — amount to scale by in Y direction

transform_distance

def transform_distance(self, dx: float, dy: float) -> tuple[float, float]

Transforms the distance vector (dx,dy) by matrix.

This is similar to Matrix.transform_point, except that the translation components of the transformation are ignored. The calculation of the returned vector is as follows:

dx2 = dx1 * xx + dy1 * xy;
dy2 = dx1 * yx + dy1 * yy;

Affine transformations are position invariant, so the same vector always transforms to the same vector. If (x1,y1) transforms to (x2,y2) then (x1+dx1,y1+dy1) will transform to (x1+dx2,y1+dy2) for all values of x1 and x2.

Parameters:

  • dx — in/out X component of a distance vector
  • dy — in/out Y component of a distance vector

transform_pixel_rectangle

def transform_pixel_rectangle(self, rect: Rectangle) -> Rectangle

First transforms the rect using matrix, then calculates the bounding box of the transformed rectangle.

This function is useful for example when you want to draw a rotated PangoLayout to an image buffer, and want to know how large the image should be and how much you should shift the layout when rendering.

For better accuracy, you should use Matrix.transform_rectangle on original rectangle in Pango units and convert to pixels afterward using extents_to_pixels's first argument.

Parameters:

  • rect — in/out bounding box in device units

transform_point

def transform_point(self, x: float, y: float) -> tuple[float, float]

Transforms the point (x, y) by matrix.

Parameters:

  • x — in/out X position
  • y — in/out Y position

transform_rectangle

def transform_rectangle(self, rect: Rectangle) -> Rectangle

First transforms rect using matrix, then calculates the bounding box of the transformed rectangle.

This function is useful for example when you want to draw a rotated PangoLayout to an image buffer, and want to know how large the image should be and how much you should shift the layout when rendering.

If you have a rectangle in device units (pixels), use Matrix.transform_pixel_rectangle.

If you have the rectangle in Pango units and want to convert to transformed pixel bounding box, it is more accurate to transform it first (using this function) and pass the result to extents_to_pixels, first argument, for an inclusive rounded rectangle. However, there are valid reasons that you may want to convert to pixels first and then transform, for example when the transformed coordinates may overflow in Pango units (large matrix translation for example).

Parameters:

  • rect — in/out bounding box in Pango units

translate

def translate(self, tx: float, ty: float) -> None

Changes the transformation represented by matrix to be the transformation given by first translating by (tx, ty) then applying the original transformation.

Parameters:

  • tx — amount to translate in the X direction
  • ty — amount to translate in the Y direction

Properties

xx

xx: float  # read/write

xy

xy: float  # read/write

yx

yx: float  # read/write

yy

yy: float  # read/write

x0

x0: float  # read/write

y0

y0: float  # read/write