@spec fill(
  Blendend.Canvas.t(),
  Blendend.Text.Font.t(),
  number(),
  number(),
  t(),
  keyword()
) :: :ok | {:error, term()}

Fills the glyph run on canvas using the given font.

The glyphs in glyph_run are taken as already shaped for font. The run is drawn with its origin at (x0, y0) in the current canvas transform.

opts is a style keyword list and supports the same options as Blendend.Canvas.Fill.path/3 (for example :color, :gradient, :alpha, :comp_op, etc.).

On success, returns :ok.

On failure, returns {:error, reason}.

@spec fill!(
  Blendend.Canvas.t(),
  Blendend.Text.Font.t(),
  number(),
  number(),
  t(),
  keyword()
) :: Blendend.Canvas.t()

Same as fill/6, but returns the canvas and raises on error.

On success, returns canvas.

On failure, raises Blendend.Error.

This is the typical end of the manual glyph pipeline:

alias Blendend.Text.{Face, Font, GlyphBuffer, GlyphRun}
alias Blendend.{Canvas, Style, Matrix2D}

face = Face.load!("priv/fonts/Alegreya-Regular.otf")
font = Font.create!(face, 42.0)
canvas = Canvas.new!(800, 200)

gb =
  GlyphBuffer.new!()
  |> GlyphBuffer.set_utf8_text!("Hello glyphs")
  |> Font.shape!(font)

run = GlyphRun.new!(gb)

canvas
|> GlyphRun.fill!(
  font,
  100.0,
  120.0,
  run,
  color: Style.color(240, 240, 240)
)

@spec info(t()) :: {:ok, map()} | {:error, term()}

Returns low-level information about a glyph run.

Map keys (from the NIF) typically include:

• :size – number of glyphs in the run
• :placement_type – numeric BLGlyphPlacementType
• :glyph_advance – byte stride between glyph ids
• :placement_advance – byte stride between placements
• :flags – BLGlyphRunFlags bitmask

@spec inspect_run(t()) :: {:ok, list()} | {:error, term()}

Returns a list describing each glyph in the run.

For runs with placement info, each element is:

{:glyph, id, {:advance_offset, {ax, ay}, {px, py}}}

where:

• id – glyph index
• {ax, ay} – pen advance in design units
• {px, py} – placement offset in design units

Returned as {:ok, list} or {:error, reason}.

@spec slice(t(), non_neg_integer(), non_neg_integer()) ::
  {:ok, t()} | {:error, term()}

Returns a view of the glyph run from start (0-based glyph index) spanning count glyphs. Shares the underlying GlyphBuffer.

On success returns {:ok, glyph_run}.

@spec stroke(
  Blendend.Canvas.t(),
  Blendend.Text.Font.t(),
  number(),
  number(),
  t(),
  keyword()
) :: :ok | {:error, term()}

Strokes the glyph run on canvas using the given font.

The glyphs in glyph_run are taken as already shaped for font. The run is stroked with its origin at (x0, y0) in the current canvas transform.

opts is a style keyword list and supports the same options as Blendend.Canvas.Stroke.path/3 (for example :stroke_color, :stroke_width, :stroke_cap, :stroke_line_join, :comp_op, etc.).

On success, returns :ok.

On failure, returns {:error, reason}.

@spec stroke!(
  Blendend.Canvas.t(),
  Blendend.Text.Font.t(),
  number(),
  number(),
  t(),
  keyword()
) :: Blendend.Canvas.t()

Same as stroke/6, but returns the canvas and raises on error.

On success, returns canvas.

On failure, raises Blendend.Error.

Example, continuing the manual glyph pipeline:

run = GlyphRun.new!(gb)

canvas
|> GlyphRun.stroke!(
  font,
  100.0,
  120.0,
  run,
  stroke_color: Style.color(80, 220, 255),
  stroke_width: 2.0,
  stroke_cap: :round
)