Core Graphics

The limu-coregraphics crate draws limu’s scenes with Core Graphics, into a CGContext your app gives it or into a CGImage it makes. Text is shaped by Core Text, as the rest of an app’s text is on Apple’s platforms, so a diagram uses the system’s fonts or the fonts your app carries. It suits apps on macOS and iOS that draw in views of their own, through AppKit, UIKit or another toolkit that hands out a CGContext.

limu-rs is young, and its API will change in any 0.x release.

Installing

limu-coregraphics is a crate of its own, which keeps limu and limu-scene free of anything beyond Rust’s standard library. Add both crates.

cargo add limu limu-coregraphics

The crate calls Core Graphics and Core Text through objc2’s bindings, and re-exports them as limu_coregraphics::objc2_core_foundation, objc2_core_graphics and objc2_core_text. It is empty on platforms other than Apple’s, so a project that builds for other platforms too can depend on it everywhere. The examples below use limu::scene, which is the limu-scene crate as limu re-exports it.

Drawing an image

limu_coregraphics::render draws a scene into a new image. Lay out the diagram with the same fonts you draw it in, as explained under Fonts.

use limu::scene::style::{Look, Theme};use limu_coregraphics::{Fonts, Options};let fonts = Fonts::from_data(&std::fs::read("Inter-Regular.ttf")?)?;let layout = limu::layout::Options {    measurer: &fonts,    ..Default::default()};let scene = limu::layout(src, &layout)?;let o = Options {    look: Look::new(Theme::KOHU),    fonts: Some(&fonts),    scale: 2.0,    ..Options::default()};let image = limu_coregraphics::render(&scene, &o).ok_or("the diagram is too large to draw")?;

The image is in sRGB, as large as the scene times Options.scale, rounded up to whole pixels, and filled with the theme’s background. A scale of zero or less counts as 1. render returns None when the scene is too small or too large for an image. Show the image in a view or a layer, or write it to a file with Image I/O.

Options.look sets the theme and the overrides. See Theming. When the look changes, for example when the system switches to dark mode, draw the scene again. It doesn’t need to be laid out again.

Drawing in a view

limu_coregraphics::draw draws a scene into a context you give it, in the context’s user space, with y running down. A flipped view’s context is set up this way already, so in a flipped NSView, or in a UIView, draw straight into the context of draw(_:). Scale the context first to zoom.

use limu_coregraphics::objc2_core_graphics::CGContext;/// Draws a scene in a view's context, zoomed. A flipped view's context is y down, as/// the scene is.fn draw_zoomed(cx: &CGContext, scene: &Scene, o: &Options<'_>, zoom: f64) {    CGContext::save_g_state(Some(cx));    CGContext::scale_ctm(Some(cx), zoom, zoom);    limu_coregraphics::draw(scene, o, cx);    CGContext::restore_g_state(Some(cx));}

A context whose y runs up, such as a bitmap context’s or an unflipped view’s, needs to be turned over first, as render does with its own.

// A context whose y runs up, height units high, is turned over first.CGContext::translate_ctm(Some(cx), 0.0, height);CGContext::scale_ctm(Some(cx), 1.0, -1.0);

draw doesn’t fill a background, and it ignores Options.scale. It leaves the context’s state as it found it.

limu-coregraphics draws the same picture as the SVG writer, with one difference. When a corner radius is too large for a box, it uses the smaller of half the width and half the height. SVG uses elliptical corners instead.

As in SVG, an item’s opacity is drawn as a transparency layer, so where an item’s parts overlap, the lower part doesn’t show through.

Fonts

A diagram is laid out with a measurer and drawn with fonts. If the two don’t match, text won’t fit the space layout gave it. limu_coregraphics::Fonts does both jobs. It implements limu’s Measurer, and it measures each line as Core Text sets it for drawing.

Fonts::from_data takes the data of a TrueType or OpenType file as the regular font, for an app that carries its fonts, and set_data adds a font for a face. They return a FontError for data that isn’t a font. Fonts::new and set take a CTFont instead, for the system’s fonts. The faces are bold, italic and mono, and any mix of them.

use limu::scene::text::Face;use limu_coregraphics::Fonts;use limu_coregraphics::objc2_core_foundation::{CFRetained, CFString};use limu_coregraphics::objc2_core_text::CTFont;fn font(name: &str) -> CFRetained<CTFont> {    // SAFETY: a null matrix stands for the identity.    unsafe { CTFont::with_name(&CFString::from_str(name), 12.0, std::ptr::null()) }}let mut fonts = Fonts::new(font("Helvetica"));fonts    .set(Face::BOLD, font("Helvetica-Bold"))    .set(Face::ITALIC, font("Helvetica-Oblique"))    .set(Face::MONO, font("Menlo-Regular"));

The size a font was made at doesn’t matter, because text is set at the size its label asks for. Text in a face you gave no font for is set in the nearest one you did. limu-coregraphics tries the face without italic, then without bold, and then takes the regular font. Without Options.fonts, text is left out. If you don’t give layout a measurer, it measures text as Arial, so a diagram drawn in another font only fits when that font has Arial’s widths.

Core Text falls back to the system’s fonts for characters the font doesn’t have, such as Chinese, Japanese or Korean in a Latin font. Fonts measures the line with the fallback fonts in it, so that text fits too. Glyphs are drawn from their outlines, so a halo is stroked the way any path is. An underline follows the font’s own position and thickness. Subscripts are lowered a fifth of the label’s size and superscripts raised a third, about where a browser puts them.

Icons and images

limu-coregraphics never loads images or follows links on its own. Your app knows where its images come from, so it makes those decisions.

Options.icons gives an icon’s parts by its name, such as fa:fa-car. Every backend of limu-rs takes icons in this one form, limu::scene::Icons, so the icon set written for tiny-skia works here as it is. The parts sit on a box of 24 by 24. A filled part is filled in the color of the item’s text, and a stroked part is stroked in it, 2 wide with round ends and corners. Layout leaves room in labels only for icons you report through layout::Options::icons, so give both the same set.

Options.images gives a CGImage for an image’s URL. When an image’s fit is set, it keeps its proportions and is centered in its box. Otherwise it’s stretched to fill the box. Layout only passes through URLs whose scheme layout::Options::image_schemes allows, and loading and caching the images is up to you. Without icons or images, icons and images are left out.

let o = Options {    fonts: Some(&fonts),    icons: Some(Box::new(icon)),    // images is a HashMap<String, CFRetained<CGImage>> of the images loaded already.    images: Some(Box::new(|src| images.get(src).cloned())),    ..Options::default()};

When an item with a link is clicked, its link field holds the target. Open it the same way your app opens any other link, or don’t. Scene::item_at finds the item at a point in the scene’s units, as described on the GPUI page.

Custom drawing

limu_coregraphics::draw_with draws each item with a hook in place of the default. The hook receives a Painter, the item and its style as a Resolved, with every color already worked out. The painter’s item draws the item the default way, and parts, ends, picture and label draw the default’s pieces. Its canvas is a ContextCanvas, whose context lets the hook draw with Core Graphics directly, in the scene’s units.

use limu::scene::Kind;use limu_coregraphics::objc2_core_foundation::{CGPoint, CGRect, CGSize};use limu_coregraphics::objc2_core_graphics::CGContext;limu_coregraphics::draw_with(&scene, &o, cx, |p, it, s| {    if !matches!(it.kind, Kind::Node) {        p.item(it, s);        return;    }    // Draw the node as a box of our own with square corners, and its label the default way.    let cx = Some(p.canvas().context());    let (b, c) = (it.bounds, s.fill.color);    let k = |v: u8| f64::from(v) / 255.0;    CGContext::set_rgb_fill_color(cx, k(c.r), k(c.g), k(c.b), k(c.a));    CGContext::fill_rect(cx, CGRect::new(CGPoint::new(b.x, b.y), CGSize::new(b.w, b.h)));    p.label(it, s);});

The hook draws inside the transparency layer of the item’s opacity, so the style it receives is always opaque.