linebender / linebender/parley

Docs: document the coordinate space of GlyphRun::positioned_glyphs

Open Beginner friendly
#774 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
736
Forks
120
Avg merge
1d 3h
Merged PRs (30d)
53

Description

**Target repo**: https://github.com/linebender/parley
**Type**: Documentation
**Tested version**: parley 0.11.1

## Summary

`PositionedLayoutItem::GlyphRun::positioned_glyphs()` returns glyphs whose coordinates
are documented only implicitly:

- `x` — inline offset within the line (advance already accumulated)
- `y` — **layout-absolute** position (includes the line's baseline), NOT relative to
the line box top

When rendering each line yourself (e.g. paginated view, where lines of one layout are
drawn onto different pages), you must subtract the run's own baseline:

```rust
let transform = Affine::translate((
x_offset,
page_top + baseline_rel - glyph_run.baseline(), // <- subtract run baseline
));
```

Getting this wrong produces two classic symptoms that cost us real debugging time:
all glyphs stacked at x=0, and "page 2 blank" (glyphs drawn far below the page).

## Proposal

Add a short paragraph to `GlyphRun::positioned_glyphs` (and/or `Run::glyphs`) docs:

> The returned glyphs are positioned in layout coordinates: `x` is the inline offset
> within the line, `y` is the absolute baseline position within the whole laid-out
> text. To draw a single line at an arbitrary origin, translate by
> `(origin_x, origin_y + line_relative_baseline - glyph_run.baseline())`.

A minimal draw example (parley + vello) in the repo examples would also have prevented
this for us.

## Environment

- parley 0.11.1, vello 0.10.0, Windows

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the Rust API documentation for PositionedLayoutItem::GlyphRun::positioned_glyphs(), and check the related Run::glyphs documentation. Add the coordinate-space explanation and drawing guidance from the issue, then verify that the docs clearly distinguish inline x offsets from layout-absolute y positions.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.