---
title: "Shape code points with custom cluster indices in C#"
url: https://recursiveai.org/onefont/cookbook/shape-code-points-with-custom-clusters/
description: "Cluster indices link shaped glyphs back to your document’s character positions. Runnable C# examples with onefont."
version: "1.4.0"
---

# Shape code points with custom cluster indices in C#

**onefont** is a free, open-source font and text-shaping library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneFont) · [GitHub](https://github.com/recursive-ai-oss/onefont-csharp) · [Docs](https://recursiveai.org/onefont/docs/) · [Download example (.zip)](https://recursiveai.org/onefont/cookbook/shape-code-points-with-custom-clusters/shape-code-points-with-custom-clusters.zip)

Cluster indices link shaped glyphs back to your document’s character positions.

```shell
dotnet add package RecursiveAI.OneFont
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

`sample.ttf` comes in the example zip below.

```csharp
using OneFont;

var face = FontFace.Load(
    File.ReadAllBytes("sample.ttf"));
var run = new CodePointRun();
uint script = 0;
// "1" at document offset 41
TextShaping.ShapeCodePoints(face, [49], [41],
    run, rightToLeft: false, options: null, ref script);
Console.WriteLine(run.Glyphs[0].Cluster);
```

```text
41
```

Unzip [the example](https://recursiveai.org/onefont/cookbook/shape-code-points-with-custom-clusters/shape-code-points-with-custom-clusters.zip), then `dotnet run`.

## The full program

`sample.ttf` is the Noto Sans bidi subset from the [pinned public repository](https://github.com/recursive-ai-oss/onefont-csharp/tree/7db48bc21a7eec46272aa73f4e76acf07645db03/tests/testdata/fonts), included in the zip with its SIL Open Font License. The snippet shapes “1” at document offset 41. The full program splits “ا123” into two style runs: Arabic alef at offset 40 and digits at offsets 41–43, carrying the script between calls. Unequal code-point and cluster-array lengths throw `ArgumentException`.

```csharp
using OneFont;

var face = FontFace.Load(File.ReadAllBytes("sample.ttf"));
var run = new CodePointRun();
uint script = 0;
// First style run: Arabic alef (ا), document offset 40.
TextShaping.ShapeCodePoints(face, [0x0627], [40],
    run, true, null, ref script);
foreach (var glyph in run.Glyphs)
    Console.WriteLine($"{glyph.GlyphId}: cluster {glyph.Cluster}");
// Next style run: 123, retaining the paragraph script.
TextShaping.ShapeCodePoints(face, [49, 50, 51], [41, 42, 43],
    run, false, null, ref script);
foreach (var glyph in run.Glyphs)
    Console.WriteLine($"{glyph.GlyphId}: cluster {glyph.Cluster}");
```

```text
1209: cluster 40
1853: cluster 41
2232: cluster 42
2215: cluster 43
```

## Variations

### Start a new paragraph without a carried script

```csharp
using OneFont;

var face = FontFace.Load(
    File.ReadAllBytes("sample.ttf"));
var run = new CodePointRun();
uint script = 0;
TextShaping.ShapeCodePoints(face, [49, 50, 51], [41, 42, 43],
    run, false, null, ref script);
foreach (var glyph in run.Glyphs)
    Console.WriteLine($"{glyph.GlyphId}: cluster {glyph.Cluster}");
```

```text
18: cluster 41
19: cluster 42
20: cluster 43
```

## Related recipes

[Shape text](https://recursiveai.org/onefont/cookbook/shape-text/) · [Shape without allocating](https://recursiveai.org/onefont/cookbook/shape-without-allocating/) · [Right-to-left text](https://recursiveai.org/onefont/cookbook/right-to-left-text/)

## The short answer

Use `TextShaping.ShapeCodePoints` when your layout engine already has Unicode code points and its own cluster indices. Supply one cluster value per input code point, a `CodePointRun` for the output, a direction, optional shaping options and a `ref uint` script value. Read the resulting glyphs before reusing the output run.

A cluster is a link back to input text, not a glyph number. A ligature can represent several characters, and one character can produce several glyphs. Keeping document positions on the input lets the shaper carry that association through substitutions and reordering. The [code-point API documentation](https://recursiveai.org/onefont/docs/shaping/#callers-that-split-text-into-runs-themselves) describes these entry points and their relationship to `ShapeRun`.

## How do you shape text with custom cluster indices in C#?

Create parallel code-point and cluster arrays. In the snippet at the top, 49 is the Unicode scalar value for “1” and 41 is the caller’s document position. The output prints 41 because the shaped glyph retains that caller-supplied cluster value. The font is included in the download, so the snippet does not depend on installed system fonts.

The full program uses an Arabic character followed by three digits, with separate calls representing two style runs in the same paragraph. Its indices are document offsets rather than offsets starting at zero inside each run. That makes it possible to associate the glyphs with their paragraph positions after shaping. A caller must still decide how to interpret those positions for selection, caret movement and rendering.

The code-point arrays contain scalars, not UTF-16 code units. If your document indices are UTF-16 offsets, advance the source offset by two for a supplementary character but add only one code point and one cluster entry. OneFont shapes values that are not valid scalars as U+FFFD. Mismatched array lengths are an error rather than an implicit truncation.

For a valid UTF-16 string, collect the scalar-start offsets first, then convert at those offsets:

```csharp
string text = "A😀B";
int[] clusters = [.. Enumerable.Range(0, text.Length).Where(i => !char.IsLowSurrogate(text[i]))];
int[] codePoints = [.. clusters.Select(i => char.ConvertToUtf32(text, i))];
```

Here `clusters` is `[0, 1, 3]` and `codePoints` is `[65, 128512, 66]`; the emoji takes two UTF-16 code units but one array entry.

## How do you preserve script between text shaping runs?

Initialize `script` to zero at the start of a paragraph, then pass the same variable by reference through its runs in logical order. It holds an OpenType script tag, not a direction flag. Spaces, punctuation and digits can take the script of the preceding text even when your layout engine has split the paragraph at a style boundary.

The download first shapes Arabic alef with `rightToLeft` set to true. It then shapes “123” with `rightToLeft` false while retaining the script. With this particular subset font, the resulting digit glyph IDs are 1853, 2232 and 2215. Starting the digits with a fresh zero script produces 18, 19 and 20 instead, as the variation shows. Glyph IDs belong to this font; they are not portable character identifiers.

Do not confuse script carry with paragraph layout. Direction runs, removal of format characters, break handling and visual reordering remain the caller’s work. The shaper returns glyphs in its produced order. For right-to-left display, the documented paragraph-layout example reverses the run’s glyphs and each cluster as part of line reordering.

## How do you read shaped glyphs without losing cluster indices?

Read `run.Glyphs` after each call. Each `CodePointGlyph` carries its glyph ID, caller’s cluster value, first code point, advance and offsets. Consume or copy any data needed for drawing before shaping the next run into that same result.

`CodePointRun` replaces its previous contents rather than appending. It retains its backing array for reuse, and the docs specify one run per thread. The list overload instead appends to the supplied list. Choose based on whether your caller wants a reusable current-run buffer or accumulated results; do not accidentally expect the reusable buffer to retain every style run in a paragraph.
