@gtkx/cairo 1.2.2

package/src/font-face.ts

@@ -0,0 +1,157 @@
+import {
+    type ExternalObject,
+    getHandle,
+    type Handle,
+    registerWrapperClass,
+    registerWrapperClassResolver,
+    t,
+    wrapHandle,
+    type WrapperClassResolver,
+} from "@gtkx/runtime";
+import { type FontSlant, FontType, type FontWeight, type Status } from "./enums.js";
+import { bindCairo, cairoGType, FC_PATTERN_T, FONT_FACE_FULL_T, FONT_FACE_T, FT_FACE_T } from "./lib.js";
+
+/** One of the `FtSynthesize` styles a FreeType font face synthesizes. */
+type FtSynthesize = (typeof FtSynthesize)[keyof typeof FtSynthesize];
+
+const FONT_FACE_TYPE = cairoGType("cairo_gobject_font_face_get_type");
+const cairoFontFaceStatus = bindCairo("cairo_font_face_status", [FONT_FACE_T], t.int32);
+const cairoFontFaceGetType = bindCairo("cairo_font_face_get_type", [FONT_FACE_T], t.int32);
+const cairoFontFaceGetReferenceCount = bindCairo("cairo_font_face_get_reference_count", [FONT_FACE_T], t.int32);
+const cairoToyFontFaceGetSlant = bindCairo("cairo_toy_font_face_get_slant", [FONT_FACE_T], t.int32);
+const cairoToyFontFaceGetWeight = bindCairo("cairo_toy_font_face_get_weight", [FONT_FACE_T], t.int32);
+const cairoFtFontFaceGetSynthesize = bindCairo("cairo_ft_font_face_get_synthesize", [FONT_FACE_T], t.int32);
+const cairoFtFontFaceSetSynthesize = bindCairo("cairo_ft_font_face_set_synthesize", [FONT_FACE_T, t.int32], t.void);
+const cairoToyFontFaceGetFamily = bindCairo("cairo_toy_font_face_get_family", [FONT_FACE_T], t.string("borrowed"));
+
+const cairoFtFontFaceCreateForPattern = bindCairo(
+    "cairo_ft_font_face_create_for_pattern",
+    [FC_PATTERN_T],
+    FONT_FACE_FULL_T,
+);
+
+const cairoToyFontFaceCreate = bindCairo(
+    "cairo_toy_font_face_create",
+    [t.string("full"), t.int32, t.int32],
+    FONT_FACE_FULL_T,
+);
+
+const cairoFtFontFaceCreateForFtFace = bindCairo(
+    "cairo_ft_font_face_create_for_ft_face",
+    [FT_FACE_T, t.int32],
+    FONT_FACE_FULL_T,
+);
+
+const cairoFtFontFaceUnsetSynthesize = bindCairo(
+    "cairo_ft_font_face_unset_synthesize",
+    [FONT_FACE_T, t.int32],
+    t.void,
+);
+
+/**
+ * Styles a FreeType font face synthesizes when the font itself lacks them.
+ * @enum
+ */
+const FtSynthesize = {
+    /** Embolden the glyphs. */
+    BOLD: 1,
+    /** Slant the glyphs. */
+    OBLIQUE: 2,
+} as const;
+
+const fontFaceClassFor: WrapperClassResolver = (handle) => {
+    const type = cairoFontFaceGetType(handle) as FontType;
+
+    if (type === FontType.TOY) {
+        return ToyFontFace;
+    }
+
+    if (type === FontType.FT) {
+        return FtFontFace;
+    }
+
+    return FontFace;
+};
+
+/**
+ * A cairo font face (`cairo_font_face_t`): a typeface independent of size and transformation. Font faces come
+ * from the `create*` statics or from a context, and wrap as the concrete class their type reports
+ * (`instanceof ToyFontFace` after `selectFontFace`).
+ */
+abstract class FontFace {
+    static {
+        registerWrapperClass(this, FONT_FACE_TYPE);
+        registerWrapperClassResolver(this, fontFaceClassFor);
+    }
+
+    /** Creates a toy font face from a family name, slant and weight. */
+    static create(family: string, slant: FontSlant, weight: FontWeight): ToyFontFace {
+        return wrapHandle(cairoToyFontFaceCreate(family, slant, weight) as ExternalObject<Handle>, ToyFontFace);
+    }
+
+    /** Creates a font face for a FreeType `FT_Face` handle, with the given `FT_LOAD_*` flags. */
+    static createForFtFace(face: ExternalObject<Handle>, loadFlags: number): FtFontFace {
+        return wrapHandle(cairoFtFontFaceCreateForFtFace(face, loadFlags) as ExternalObject<Handle>, FtFontFace);
+    }
+
+    /** Creates a font face for a fontconfig `FcPattern` handle. */
+    static createForPattern(pattern: ExternalObject<Handle>): FtFontFace {
+        return wrapHandle(cairoFtFontFaceCreateForPattern(pattern) as ExternalObject<Handle>, FtFontFace);
+    }
+
+    /** GType of `CairoFontFace`, the boxed type this class is registered under. */
+    declare __type__: bigint;
+
+    /** Returns the error status of the font face, `Status.SUCCESS` when it is usable. */
+    status(): Status {
+        return cairoFontFaceStatus(getHandle(this)) as Status;
+    }
+
+    /** Returns the backend the font face belongs to. */
+    getType(): FontType {
+        return cairoFontFaceGetType(getHandle(this)) as FontType;
+    }
+
+    /** Returns the reference count of the font face. */
+    getReferenceCount(): number {
+        return cairoFontFaceGetReferenceCount(getHandle(this)) as number;
+    }
+}
+
+/** A toy font face, created with `FontFace.create` or a context's `selectFontFace`. */
+class ToyFontFace extends FontFace {
+    /** Returns the family name the font face was created with. */
+    getFamily(): string {
+        return cairoToyFontFaceGetFamily(getHandle(this)) as string;
+    }
+
+    /** Returns the slant the font face was created with. */
+    getSlant(): FontSlant {
+        return cairoToyFontFaceGetSlant(getHandle(this)) as FontSlant;
+    }
+
+    /** Returns the weight the font face was created with. */
+    getWeight(): FontWeight {
+        return cairoToyFontFaceGetWeight(getHandle(this)) as FontWeight;
+    }
+}
+
+/** A FreeType font face, created with `FontFace.createForFtFace` or `FontFace.createForPattern`. */
+class FtFontFace extends FontFace {
+    /** Returns the styles currently synthesized for the font face. */
+    getSynthesize(): FtSynthesize {
+        return cairoFtFontFaceGetSynthesize(getHandle(this)) as FtSynthesize;
+    }
+
+    /** Enables synthesizing of the given styles. */
+    setSynthesize(synthFlags: FtSynthesize): void {
+        cairoFtFontFaceSetSynthesize(getHandle(this), synthFlags);
+    }
+
+    /** Disables synthesizing of the given styles. */
+    unsetSynthesize(synthFlags: FtSynthesize): void {
+        cairoFtFontFaceUnsetSynthesize(getHandle(this), synthFlags);
+    }
+}
+
+export { FontFace, FtFontFace, FtSynthesize, ToyFontFace };

package/src/font-options.ts

@@ -0,0 +1,142 @@
+import { type ExternalObject, getHandle, type Handle, registerWrapperClass, setHandle, t } from "@gtkx/runtime";
+import type { Antialias, HintMetrics, HintStyle, Status, SubpixelOrder } from "./enums.js";
+import { bindCairo, cairoGType, FONT_OPTIONS_FULL_T, FONT_OPTIONS_T } from "./lib.js";
+
+const FONT_OPTIONS_TYPE = cairoGType("cairo_gobject_font_options_get_type");
+const cairoFontOptionsCreate = bindCairo("cairo_font_options_create", [], FONT_OPTIONS_FULL_T);
+const cairoFontOptionsCopy = bindCairo("cairo_font_options_copy", [FONT_OPTIONS_T], FONT_OPTIONS_FULL_T);
+const cairoFontOptionsSetHintStyle = bindCairo("cairo_font_options_set_hint_style", [FONT_OPTIONS_T, t.int32], t.void);
+const cairoFontOptionsGetHintStyle = bindCairo("cairo_font_options_get_hint_style", [FONT_OPTIONS_T], t.int32);
+const cairoFontOptionsSetAntialias = bindCairo("cairo_font_options_set_antialias", [FONT_OPTIONS_T, t.int32], t.void);
+const cairoFontOptionsGetAntialias = bindCairo("cairo_font_options_get_antialias", [FONT_OPTIONS_T], t.int32);
+const cairoFontOptionsGetHintMetrics = bindCairo("cairo_font_options_get_hint_metrics", [FONT_OPTIONS_T], t.int32);
+const cairoFontOptionsEqual = bindCairo("cairo_font_options_equal", [FONT_OPTIONS_T, FONT_OPTIONS_T], t.boolean);
+const cairoFontOptionsMerge = bindCairo("cairo_font_options_merge", [FONT_OPTIONS_T, FONT_OPTIONS_T], t.void);
+const cairoFontOptionsStatus = bindCairo("cairo_font_options_status", [FONT_OPTIONS_T], t.int32);
+const cairoFontOptionsHash = bindCairo("cairo_font_options_hash", [FONT_OPTIONS_T], t.uint64);
+
+const cairoFontOptionsGetVariations = bindCairo(
+    "cairo_font_options_get_variations",
+    [FONT_OPTIONS_T],
+    t.string("borrowed"),
+);
+
+const cairoFontOptionsSetVariations = bindCairo(
+    "cairo_font_options_set_variations",
+    [FONT_OPTIONS_T, t.string("full")],
+    t.void,
+);
+
+const cairoFontOptionsSetHintMetrics = bindCairo(
+    "cairo_font_options_set_hint_metrics",
+    [FONT_OPTIONS_T, t.int32],
+    t.void,
+);
+
+const cairoFontOptionsSetSubpixelOrder = bindCairo(
+    "cairo_font_options_set_subpixel_order",
+    [FONT_OPTIONS_T, t.int32],
+    t.void,
+);
+
+const cairoFontOptionsGetSubpixelOrder = bindCairo(
+    "cairo_font_options_get_subpixel_order",
+    [FONT_OPTIONS_T],
+    t.int32,
+);
+
+/**
+ * Cairo font options (`cairo_font_options_t`): the rendering settings applied to text, such as antialiasing,
+ * hinting and font variations.
+ */
+class FontOptions {
+    static {
+        registerWrapperClass(this, FONT_OPTIONS_TYPE);
+    }
+
+    /** Creates a set of font options with all settings at their defaults, the same as `new FontOptions()`. */
+    static create(): FontOptions {
+        return new FontOptions();
+    }
+
+    /** GType of `CairoFontOptions`, the boxed type this class is registered under. */
+    declare __type__: bigint;
+
+    /** Creates a set of font options: a copy of `other` when given, otherwise all settings at their defaults. */
+    constructor(other?: FontOptions) {
+        const handle = other === undefined ? cairoFontOptionsCreate() : cairoFontOptionsCopy(getHandle(other));
+        setHandle(this, handle as ExternalObject<Handle>);
+    }
+
+    /** Sets how outlines are fitted to the pixel grid. */
+    setHintStyle(hintStyle: HintStyle): void {
+        cairoFontOptionsSetHintStyle(getHandle(this), hintStyle);
+    }
+
+    /** Returns how outlines are fitted to the pixel grid. */
+    getHintStyle(): HintStyle {
+        return cairoFontOptionsGetHintStyle(getHandle(this)) as HintStyle;
+    }
+
+    /** Sets the antialiasing mode used for text. */
+    setAntialias(antialias: Antialias): void {
+        cairoFontOptionsSetAntialias(getHandle(this), antialias);
+    }
+
+    /** Returns the antialiasing mode used for text. */
+    getAntialias(): Antialias {
+        return cairoFontOptionsGetAntialias(getHandle(this)) as Antialias;
+    }
+
+    /** Sets whether font metrics are quantized to integer pixels. */
+    setHintMetrics(hintMetrics: HintMetrics): void {
+        cairoFontOptionsSetHintMetrics(getHandle(this), hintMetrics);
+    }
+
+    /** Returns whether font metrics are quantized to integer pixels. */
+    getHintMetrics(): HintMetrics {
+        return cairoFontOptionsGetHintMetrics(getHandle(this)) as HintMetrics;
+    }
+
+    /** Sets the order of subpixels on the display, used by subpixel antialiasing. */
+    setSubpixelOrder(subpixelOrder: SubpixelOrder): void {
+        cairoFontOptionsSetSubpixelOrder(getHandle(this), subpixelOrder);
+    }
+
+    /** Returns the order of subpixels on the display. */
+    getSubpixelOrder(): SubpixelOrder {
+        return cairoFontOptionsGetSubpixelOrder(getHandle(this)) as SubpixelOrder;
+    }
+
+    /** Returns whether `other` holds the same settings. */
+    equal(other: FontOptions): boolean {
+        return cairoFontOptionsEqual(getHandle(this), getHandle(other)) as boolean;
+    }
+
+    /** Copies every non-default setting of `other` over this one. */
+    merge(other: FontOptions): void {
+        cairoFontOptionsMerge(getHandle(this), getHandle(other));
+    }
+
+    /** Returns the error status of the font options, `Status.SUCCESS` when they are usable. */
+    status(): Status {
+        return cairoFontOptionsStatus(getHandle(this)) as Status;
+    }
+
+    /** Returns a hash of the settings, equal for options that compare `equal`. */
+    hash(): number {
+        return cairoFontOptionsHash(getHandle(this)) as number;
+    }
+
+    /** Sets the OpenType font variations to apply, as a comma-separated `axis=value` string. */
+    setVariations(variations: string): void {
+        cairoFontOptionsSetVariations(getHandle(this), variations);
+    }
+
+    /** Returns the OpenType font variations to apply. */
+    getVariations(): string {
+        return cairoFontOptionsGetVariations(getHandle(this)) as string;
+    }
+}
+
+export { FontOptions };

package/src/index.ts

@@ -0,0 +1,28 @@
+/** @public */
+export { Context } from "./context.js";
+/** @public */
+export { Device } from "./device.js";
+/** @public */
+export * from "./enums.js";
+/** @public */
+export { FontFace, FtFontFace, FtSynthesize, ToyFontFace } from "./font-face.js";
+/** @public */
+export { FontOptions } from "./font-options.js";
+/** @public */
+export { Matrix } from "./matrix.js";
+/** @public */
+export { Path } from "./path.js";
+/** @public */
+export { LinearPattern, MeshPattern, Pattern, RadialPattern } from "./pattern.js";
+/** @public */
+export { Region } from "./region.js";
+/** @public */
+export { ScaledFont } from "./scaled-font.js";
+/** @public */
+export * from "./structs.js";
+/** @public */
+export { ImageSurface, RecordingSurface, Surface } from "./surface.js";
+/** @public */
+export type * from "./types.js";
+/** @public */
+export { statusToString, version, versionString } from "./version.js";

package/src/lib.ts

@@ -0,0 +1,186 @@
+import { resolveType, t } from "@gtkx/runtime";
+
+type Descriptor = Parameters<typeof t.bind>[3];
+type BoundFunction = ReturnType<typeof t.bind>;
+type BoxedDescriptor = ReturnType<typeof t.boxed>;
+
+const CAIRO_LIBRARY = "libcairo.so.2";
+const CAIRO_GOBJECT_LIBRARY = "libcairo-gobject.so.2";
+
+const CONTEXT_T: BoxedDescriptor = t.boxed("CairoContext", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_context_get_type",
+});
+
+const CONTEXT_FULL_T: BoxedDescriptor = t.boxed("CairoContext", {
+    ownership: "full",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_context_get_type",
+});
+
+const SURFACE_T: BoxedDescriptor = t.boxed("CairoSurface", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_surface_get_type",
+});
+
+const SURFACE_FULL_T: BoxedDescriptor = t.boxed("CairoSurface", {
+    ownership: "full",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_surface_get_type",
+});
+
+const DEVICE_T: BoxedDescriptor = t.boxed("CairoDevice", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_device_get_type",
+});
+
+const PATTERN_T: BoxedDescriptor = t.boxed("CairoPattern", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_pattern_get_type",
+});
+
+const PATTERN_FULL_T: BoxedDescriptor = t.boxed("CairoPattern", {
+    ownership: "full",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_pattern_get_type",
+});
+
+const REGION_T: BoxedDescriptor = t.boxed("CairoRegion", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_region_get_type",
+});
+
+const REGION_FULL_T: BoxedDescriptor = t.boxed("CairoRegion", {
+    ownership: "full",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_region_get_type",
+});
+
+const FONT_OPTIONS_T: BoxedDescriptor = t.boxed("CairoFontOptions", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_font_options_get_type",
+});
+
+const FONT_OPTIONS_FULL_T: BoxedDescriptor = t.boxed("CairoFontOptions", {
+    ownership: "full",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_font_options_get_type",
+});
+
+const FONT_FACE_T: BoxedDescriptor = t.boxed("CairoFontFace", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_font_face_get_type",
+});
+
+const FONT_FACE_FULL_T: BoxedDescriptor = t.boxed("CairoFontFace", {
+    ownership: "full",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_font_face_get_type",
+});
+
+const SCALED_FONT_T: BoxedDescriptor = t.boxed("CairoScaledFont", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_scaled_font_get_type",
+});
+
+const SCALED_FONT_FULL_T: BoxedDescriptor = t.boxed("CairoScaledFont", {
+    ownership: "full",
+    sharedLibrary: CAIRO_GOBJECT_LIBRARY,
+    getTypeFnName: "cairo_gobject_scaled_font_get_type",
+});
+
+const FC_PATTERN_T: BoxedDescriptor = t.boxed("FcPattern", { ownership: "borrowed", sharedLibrary: CAIRO_LIBRARY });
+const FT_FACE_T: BoxedDescriptor = t.boxed("FT_Face", { ownership: "borrowed", sharedLibrary: CAIRO_LIBRARY });
+const MATRIX_T: BoxedDescriptor = t.boxed("cairo_matrix_t", { ownership: "borrowed", sharedLibrary: CAIRO_LIBRARY });
+
+const RECTANGLE_T: BoxedDescriptor = t.boxed("cairo_rectangle_t", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_LIBRARY,
+});
+
+const RECTANGLE_INT_T: BoxedDescriptor = t.boxed("cairo_rectangle_int_t", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_LIBRARY,
+});
+
+const RECTANGLE_INT_ARRAY_T: BoxedDescriptor = t.boxed("cairo_rectangle_int_t[]", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_LIBRARY,
+});
+
+const RECTANGLE_LIST_T: BoxedDescriptor = t.boxed("cairo_rectangle_list_t", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_LIBRARY,
+});
+
+const GLYPH_T: BoxedDescriptor = t.boxed("cairo_glyph_t", { ownership: "borrowed", sharedLibrary: CAIRO_LIBRARY });
+
+const TEXT_CLUSTER_T: BoxedDescriptor = t.boxed("cairo_text_cluster_t", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_LIBRARY,
+});
+
+const TEXT_EXTENTS_T: BoxedDescriptor = t.boxed("cairo_text_extents_t", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_LIBRARY,
+});
+
+const FONT_EXTENTS_T: BoxedDescriptor = t.boxed("cairo_font_extents_t", {
+    ownership: "borrowed",
+    sharedLibrary: CAIRO_LIBRARY,
+});
+
+const PATH_T: BoxedDescriptor = t.boxed("cairo_path_t", {
+    ownership: "full",
+    sharedLibrary: CAIRO_LIBRARY,
+    freeFnName: "cairo_path_destroy",
+});
+
+const DOUBLE_BUFFER_T: BoxedDescriptor = t.boxed("double[]", { ownership: "borrowed", sharedLibrary: CAIRO_LIBRARY });
+
+const bindCairo = (symbol: string, args: Descriptor[], returns: Descriptor): BoundFunction =>
+    t.bind(CAIRO_LIBRARY, symbol, args, returns);
+
+const cairoGType = (typeSymbol: string): bigint => resolveType(CAIRO_GOBJECT_LIBRARY, typeSymbol);
+
+export {
+    bindCairo,
+    type BoundFunction,
+    cairoGType,
+    CONTEXT_FULL_T,
+    CONTEXT_T,
+    DEVICE_T,
+    DOUBLE_BUFFER_T,
+    FC_PATTERN_T,
+    FONT_EXTENTS_T,
+    FONT_FACE_FULL_T,
+    FONT_FACE_T,
+    FONT_OPTIONS_FULL_T,
+    FONT_OPTIONS_T,
+    FT_FACE_T,
+    GLYPH_T,
+    MATRIX_T,
+    PATH_T,
+    PATTERN_FULL_T,
+    PATTERN_T,
+    RECTANGLE_INT_ARRAY_T,
+    RECTANGLE_INT_T,
+    RECTANGLE_LIST_T,
+    RECTANGLE_T,
+    REGION_FULL_T,
+    REGION_T,
+    SCALED_FONT_FULL_T,
+    SCALED_FONT_T,
+    SURFACE_FULL_T,
+    SURFACE_T,
+    TEXT_CLUSTER_T,
+    TEXT_EXTENTS_T,
+};

package/src/matrix.ts

@@ -0,0 +1,135 @@
+import { alloc, type ExternalObject, getHandle, type Handle, setHandle, t, wrapHandle } from "@gtkx/runtime";
+import type { Status } from "./enums.js";
+import type { Distance, Point } from "./types.js";
+import { bindCairo, MATRIX_T } from "./lib.js";
+
+type MatrixAllocation = { handle: ExternalObject<Handle>; matrix: Matrix };
+
+const MATRIX_SIZE = 48;
+
+const cairoMatrixInit = bindCairo(
+    "cairo_matrix_init",
+    [MATRIX_T, t.float64, t.float64, t.float64, t.float64, t.float64, t.float64],
+    t.void,
+);
+
+const cairoMatrixInitIdentity = bindCairo("cairo_matrix_init_identity", [MATRIX_T], t.void);
+const cairoMatrixInitTranslate = bindCairo("cairo_matrix_init_translate", [MATRIX_T, t.float64, t.float64], t.void);
+const cairoMatrixInitScale = bindCairo("cairo_matrix_init_scale", [MATRIX_T, t.float64, t.float64], t.void);
+const cairoMatrixInitRotate = bindCairo("cairo_matrix_init_rotate", [MATRIX_T, t.float64], t.void);
+const cairoMatrixMultiply = bindCairo("cairo_matrix_multiply", [MATRIX_T, MATRIX_T, MATRIX_T], t.void);
+const cairoMatrixTranslate = bindCairo("cairo_matrix_translate", [MATRIX_T, t.float64, t.float64], t.void);
+const cairoMatrixScale = bindCairo("cairo_matrix_scale", [MATRIX_T, t.float64, t.float64], t.void);
+const cairoMatrixRotate = bindCairo("cairo_matrix_rotate", [MATRIX_T, t.float64], t.void);
+const cairoMatrixInvert = bindCairo("cairo_matrix_invert", [MATRIX_T], t.int32);
+
+const cairoMatrixTransformPoint = bindCairo(
+    "cairo_matrix_transform_point",
+    [MATRIX_T, t.ref(t.float64), t.ref(t.float64)],
+    t.void,
+);
+
+const cairoMatrixTransformDistance = bindCairo(
+    "cairo_matrix_transform_distance",
+    [MATRIX_T, t.ref(t.float64), t.ref(t.float64)],
+    t.void,
+);
+
+const allocMatrix = (): MatrixAllocation => {
+    const handle = alloc(MATRIX_SIZE);
+
+    return { handle, matrix: wrapHandle(handle, Matrix) };
+};
+
+/**
+ * An affine transformation (`cairo_matrix_t`) mapping user space to device space:
+ * `x' = xx * x + xy * y + x0` and `y' = yx * x + yy * y + y0`.
+ */
+class Matrix {
+    /** Returns the identity transformation. */
+    static initIdentity(): Matrix {
+        const { handle, matrix } = allocMatrix();
+        cairoMatrixInitIdentity(handle);
+
+        return matrix;
+    }
+
+    /** Returns a transformation translating by `tx` and `ty`. */
+    static initTranslate(tx: number, ty: number): Matrix {
+        const { handle, matrix } = allocMatrix();
+        cairoMatrixInitTranslate(handle, tx, ty);
+
+        return matrix;
+    }
+
+    /** Returns a transformation scaling by `sx` and `sy`. */
+    static initScale(sx: number, sy: number): Matrix {
+        const { handle, matrix } = allocMatrix();
+        cairoMatrixInitScale(handle, sx, sy);
+
+        return matrix;
+    }
+
+    /** Returns a transformation rotating by `radians`, positive angles turning from the X axis toward the Y axis. */
+    static initRotate(radians: number): Matrix {
+        const { handle, matrix } = allocMatrix();
+        cairoMatrixInitRotate(handle, radians);
+
+        return matrix;
+    }
+
+    /** Returns the product of `a` and `b`: the transformation that applies `a` first, then `b`. */
+    static multiply(a: Matrix, b: Matrix): Matrix {
+        const { handle, matrix } = allocMatrix();
+        cairoMatrixMultiply(handle, getHandle(a), getHandle(b));
+
+        return matrix;
+    }
+
+    /** Creates a matrix from its six affine components. */
+    constructor(xx: number, yx: number, xy: number, yy: number, x0: number, y0: number) {
+        const handle = alloc(MATRIX_SIZE);
+        setHandle(this, handle);
+        cairoMatrixInit(handle, xx, yx, xy, yy, x0, y0);
+    }
+
+    /** Applies a translation by `tx` and `ty` before the existing transformation. */
+    translate(tx: number, ty: number): void {
+        cairoMatrixTranslate(getHandle(this), tx, ty);
+    }
+
+    /** Applies a scaling by `sx` and `sy` before the existing transformation. */
+    scale(sx: number, sy: number): void {
+        cairoMatrixScale(getHandle(this), sx, sy);
+    }
+
+    /** Applies a rotation by `radians` before the existing transformation. */
+    rotate(radians: number): void {
+        cairoMatrixRotate(getHandle(this), radians);
+    }
+
+    /** Replaces the matrix with its inverse, returning `Status.INVALID_MATRIX` when it has none. */
+    invert(): Status {
+        return cairoMatrixInvert(getHandle(this)) as Status;
+    }
+
+    /** Transforms the point `(x, y)`, translation included. */
+    transformPoint(x: number, y: number): Point {
+        const xRef = { value: x };
+        const yRef = { value: y };
+        cairoMatrixTransformPoint(getHandle(this), xRef, yRef);
+
+        return { x: xRef.value, y: yRef.value };
+    }
+
+    /** Transforms the distance vector `(dx, dy)`, ignoring translation. */
+    transformDistance(dx: number, dy: number): Distance {
+        const dxRef = { value: dx };
+        const dyRef = { value: dy };
+        cairoMatrixTransformDistance(getHandle(this), dxRef, dyRef);
+
+        return { dx: dxRef.value, dy: dyRef.value };
+    }
+}
+
+export { allocMatrix, Matrix };