:right-sidebar: True Matrix =================================================================== .. currentmodule:: gi.repository.Pango .. versionadded:: 1.6 .. class:: Matrix(*args, **kwargs) :no-contents-entry: A ``PangoMatrix`` specifies a transformation between user-space and device coordinates. The transformation is given by .. code-block:: :dedent: 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 ------- .. rst-class:: interim-class .. class:: Matrix :no-index: .. method:: concat(new_matrix: ~gi.repository.Pango.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. .. versionadded:: 1.6 :param new_matrix: a ``PangoMatrix`` .. method:: free() -> None Free a ``PangoMatrix``\. .. versionadded:: 1.6 .. method:: get_font_scale_factor() -> 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 :obj:`~gi.repository.Pango.Matrix.get_font_scale_factors`\. .. versionadded:: 1.12 .. method:: get_font_scale_factors() -> ~typing.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. .. versionadded:: 1.38 .. method:: get_slant_ratio() -> float Gets the slant ratio of a matrix. For a simple shear matrix in the form: 1 λ 0 1 this is simply λ. .. versionadded:: 1.50 .. method:: rotate(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. .. versionadded:: 1.6 :param degrees: degrees to rotate counter-clockwise .. method:: scale(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. .. versionadded:: 1.6 :param scale_x: amount to scale by in X direction :param scale_y: amount to scale by in Y direction .. method:: transform_distance(dx: float, dy: float) -> ~typing.Tuple[float, float] Transforms the distance vector (``dx``\,``dy``\) by ``matrix``\. This is similar to :obj:`~gi.repository.Pango.Matrix.transform_point`\, except that the translation components of the transformation are ignored. The calculation of the returned vector is as follows: .. code-block:: :dedent: 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``\. .. versionadded:: 1.16 :param dx: in/out X component of a distance vector :param dy: in/out Y component of a distance vector .. method:: transform_pixel_rectangle(rect: ~gi.repository.Pango.Rectangle = Ellipsis) -> ~gi.repository.Pango.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 :obj:`~gi.repository.Pango.Matrix.transform_rectangle` on original rectangle in Pango units and convert to pixels afterward using :obj:`~gi.repository.Pango.extents_to_pixels`\'s first argument. .. versionadded:: 1.16 :param rect: in/out bounding box in device units .. method:: transform_point(x: float, y: float) -> ~typing.Tuple[float, float] Transforms the point (``x``\, ``y``\) by ``matrix``\. .. versionadded:: 1.16 :param x: in/out X position :param y: in/out Y position .. method:: transform_rectangle(rect: ~gi.repository.Pango.Rectangle = Ellipsis) -> ~gi.repository.Pango.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 :obj:`~gi.repository.Pango.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 :func:`~gi.repository.Pango.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). .. versionadded:: 1.16 :param rect: in/out bounding box in Pango units .. method:: translate(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. .. versionadded:: 1.6 :param tx: amount to translate in the X direction :param ty: amount to translate in the Y direction Fields ------ .. rst-class:: interim-class .. class:: Matrix :no-index: .. attribute:: x0 X translation .. attribute:: xx 1st component of the transformation matrix .. attribute:: xy 2nd component of the transformation matrix .. attribute:: y0 Y translation .. attribute:: yx 3rd component of the transformation matrix .. attribute:: yy 4th component of the transformation matrix