linebender / linebender/parley
Docs: document the coordinate space of GlyphRun::positioned_glyphs
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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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