> For the complete documentation index, see [llms.txt](https://docs.flatredball.com/gum/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flatredball.com/gum/code/files-and-fonts/fonts/font-oversampling.md).

# Font Oversampling

## Introduction

When the camera or a layer zooms in, text is scaled up along with everything else. The font was drawn at its normal `FontSize`, so the letters end up soft or blocky next to art that is drawn at full size. Font oversampling fixes this. While the view is zoomed in, Gum builds the font again at a larger size, then draws the letters smaller so they fit. The text takes up the same space in your layout, but it is made of more pixels, so the edges stay sharp.

{% hint style="info" %}
Font oversampling is a preview feature. It first shipped in the `2026.8.18.1-preview.1` packages. You can also use it by building Gum from source.
{% endhint %}

{% hint style="info" %}
Works on MonoGame, KNI, FNA, and Raylib. [SkiaSharp-based runtimes](https://docs.flatredball.com/gum/code/about/runtimes.md) do not need it, since SkiaSharp draws text at whatever size it is asked for, so the text stays sharp when you zoom.
{% endhint %}

## Enabling Oversampling

You need two things:

1. Turn on the flag: `TextRuntime.UseFontOversampling = true`. This is one `static` switch for the whole game, not a property on each text. If you want blocky text in a pixel art game, leave it off.
2. Give Gum a way to get the larger fonts: either build them while the game runs, or build them ahead of time.

**Build them while the game runs.** Set `IInMemoryFontCreator` on MonoGame/KNI/FNA, or `IRaylibFontCreator` on Raylib. KernSmith does both, see [Dynamic KernSmith Generation](https://docs.flatredball.com/gum/code/files-and-fonts/fonts/font-strategies.md#dynamic-kernsmith-generation). This works for any zoom.

```csharp
// Initialize
TextRuntime.UseFontOversampling = true;
GumUI.UseKernSmith();
```

{% hint style="info" %}
Available in preview NuGet packages (use a `-preview` version), or now if building Gum from source.
{% endhint %}

**Build them ahead of time (MonoGame/KNI/FNA).** With no creator set, or when the creator returns `null`, Gum looks for the larger size in your project's `FontCache` folder, using the same file name any font of that size has. A text with `FontSize` 12 that is drawn at 2x needs `Font24...fnt`, and at 3x it needs `Font36...fnt`. No code is needed beyond the flag.

```csharp
// Initialize
TextRuntime.UseFontOversampling = true;
```

If a size is not in `FontCache`, that text keeps its normal font and is drawn larger, as if oversampling were off. Nothing is reported. Because only the sizes you built are used, oversample from a camera with a few known zoom levels. Gum asks for an exact size (`FontSize` times `FontScale` times zoom), so a zoom that lands between your sizes is not served; the font at the nearest size is not substituted. [gumcli fonts](https://docs.flatredball.com/gum/cli/cli/fonts.md) builds the sizes some element in the project uses, so the larger sizes need an element at that size, or a font file generated another way. Raylib does not read the `FontCache` for oversampling and needs `IRaylibFontCreator`.

After that it runs on its own. Each frame, every text you can see checks the zoom of the `Layer` it sits on. If that zoom moved enough to change the font by a full pixel, the text builds its font again. You do not need to write any code that runs each frame.

The layer matters here. A layer with `LayerCameraSettings.IsInScreenSpace = true`, which is how most HUDs are set up, keeps its own `Zoom` (1 by default) no matter where the camera goes. Text on that layer never builds a new font, which is right, because it never looks zoomed. Only text on a layer that follows the camera zoom is oversampled. See [Layer, LayerCameraSettings](https://docs.flatredball.com/gum/code/gum-code-reference/layer.md#layercamerasettings).

## Manual Control

`RegenerateOversampledFont(oversampleRatio)` builds the font again at a size you pick, such as during a cut scene that zooms without touching `Camera.Zoom`. The ratio is relative to the drawn size of the text (`FontSize` times `FontScale`), so passing the zoom keeps each pixel of the font on one pixel of the screen. Inline `[FontScale]` runs still look enlarged, because a text has only one font size. It returns `false` and does nothing if `UseFontOversampling` is off, if `oversampleRatio` is zero or less, or if nothing can supply that size: no creator is set (Raylib), or the creator returned nothing and `FontCache` has no font of that size (MonoGame/KNI/FNA).

The automatic path debounces continuous zooming: it only rebuilds a font's atlas once the requested size has moved `TextRuntime.OversamplingRegenerateThresholdPixels` (1 pixel by default) from what was last rasterized. That 1px absolute threshold is a bigger fraction of a small `FontSize` than a large one, so small text can stay noticeably blurry for longer while zooming. Lower the threshold (down to `0` to regenerate on any change) if you want small text to re-crisp sooner, at the cost of rebuilding the atlas more often.

## Limitation: System Fonts vs. Registered `.ttf`

For the text to keep the same size while its font is built again at other sizes, `Font` (or `CustomFontFile`) has to point at a real `.ttf` file, not just a font name like `"Arial"`. Oversampling still runs with a font name, but the width and the line breaks may shift a little each time the font is built. See [Font Strategies, System Fonts vs Registered Fonts](https://docs.flatredball.com/gum/code/files-and-fonts/fonts/font-strategies.md#system-fonts-vs-registered-fonts) to learn how to register a `.ttf`.

## Limitation: `[FontSize]`/`[IsBold]`/`[IsItalic]`/`[OutlineThickness]` BBCode Runs on Raylib

On Raylib, oversampling builds the base font of a `TextRuntime` again. Runs that only scale that font, meaning runs with no tag or with a `[FontScale=...]` tag, come out at the right size, the same as on MonoGame, KNI, and FNA. Runs that ask for a different font, meaning `[FontSize=...]`, `[IsBold=...]`, `[IsItalic=...]`, and `[OutlineThickness=...]`, keep their own size and are not oversampled. Changing them would upset the line height and baseline math they already rely on. MonoGame, KNI, and FNA do not have this limit, and oversampling works with every kind of run there.

## Try It

Drag the **Zoom** slider to zoom the camera. The text stays sharp because it is oversampled. Turn off **Oversampling** to see how the same text looks without it. The font (`std/DroidSans.ttf`) ships with XnaFiddle, so there is nothing to upload. This sample is MonoGame-only, since it uses `Content.RootDirectory` and the MonoGame `KernSmithFontCreator`.

```csharp
using MonoGameGum;
using Gum.Forms;
using Gum.Forms.Controls;
using Gum.Forms.DefaultVisuals.V3;
using MonoGameGum.GueDeriving;
using Gum.Wireframe;
using KernSmith.Gum;
using RenderingLibrary;

// Class scope
TextRuntime previewText;
Label zoomLabel;
Slider zoomSlider;
CheckBox oversampleCheck;

// Initialize
GumUI.UseKernSmith();
KernSmithFontCreator.RegisterFont("Droid Sans",
    System.IO.Path.Combine(Content.RootDirectory, "std/DroidSans.ttf"));

TextRuntime.UseFontOversampling = true;

previewText = new TextRuntime();
previewText.Font = "Droid Sans";
previewText.FontSize = 48;
previewText.Text = "Crisp under zoom";
previewText.AddToRoot();
previewText.Anchor(Gum.Wireframe.Anchor.Center);

oversampleCheck = new CheckBox();
oversampleCheck.Text = "Oversampling";
oversampleCheck.Width = 200;
oversampleCheck.IsChecked = true;
oversampleCheck.X = 8;
oversampleCheck.Y = 8;
oversampleCheck.AddToRoot();
oversampleCheck.Checked += (_, _) => TextRuntime.UseFontOversampling = true;
oversampleCheck.Unchecked += (_, _) => TextRuntime.UseFontOversampling = false;

zoomLabel = new Label();
zoomLabel.Text = "Zoom: 1.0x";
zoomLabel.Width = 200;
zoomLabel.X = 8;
zoomLabel.Y = 40;
zoomLabel.AddToRoot();

zoomSlider = new Slider();
zoomSlider.Minimum = 1;
zoomSlider.Maximum = 4;
zoomSlider.Value = 1;
zoomSlider.Width = 200;
zoomSlider.X = 8;
zoomSlider.Y = 70;
zoomSlider.AddToRoot();
zoomSlider.ValueChanged += (_, _) =>
{
    GumUI.SystemManagers.Renderer.Camera.Zoom = (float)zoomSlider.Value;
    zoomLabel.Text = $"Zoom: {zoomSlider.Value:0.0}x";
};

// Update
GumUI.Update(gameTime);

// Draw
GumUI.Draw();
```

[Try on XnaFiddle.NET](https://xnafiddle.net/#code=H4sIAAAAAAAACp1WbW_aMBD-zq-w0D4EDXl0q7SpVSdtQa3QhloBfdm-TCYcYDWxke2U0qn_fefECSZ1tmr5gnv3-O65N19zzcWKjKWQFyyDizw77eSFCI_0XKpMvxDQWAqjZBrQDGHJ8tTccJ2zVNObDxXEc0AvchiC4g8o9y3ccgVLhZhK-A2UmGbcrF8IqMdzAmKB1sTqO58rpna1R54oqeXS0DvB6Lk1vJXq_rTT2eTzlCckSZnWxJI6IifFb-d3h-B3odhmzRM9hAeewJgJtgJFVk56WmLybArK6u3xekTOPnuyKg_ozIJn8GgmuTA8A7JRaBW2VlRa-s7mkJInKbPiVAqnKcegCml5LMXxGpL7r_KRyAdQmmWbFAqR8-MCK0KKeoWojMh-FX9yRgRsw0FGZs11r_Rlv5Eey1wDlpPPU8CbRuVYHqt6di6VNJAYWBSUFFIlD5IvyEhww1nKn-AFkSJf1ANYp31y2Do3GB-XAjsI6dRX41wbzAiYKyU3oMzuUpTlZ0gPTY4hk2p3ju0ZK2BGKnJW37WfDbxuIg8WHWajTyZMG2yqJ1BfWXKPLujUzGcY_Gy3AS9BIWN0Aitur1tZ1B0qm48pE7rbPyAz3SEoo6NLesWwpWOZzbmAyA4XCEMnUpohjkSCJnd90tVm8a6wZU1RY5bdnp8ar8fotQbr-7JqEjsOVe3qC14jupbwTERejB4Qp1xYtB9UO3CK-UPw8acwxHnuxorrDclF1fAtFr8sFjNpk9LG7YtI1raU_lPihDTGjILy89WYIJeCasB8Hw1kzdtPb7cdfssXZo3494NBO2iki18cI3_GQsg7RHxqV__4uzqYxCaoovL2jES_-uRXzz5ur-2vNqPXWIj_MrvE18Dv2_qldCUrzn44NaCu1E-UnJAjOnjshmDBCu3VjYzvFTbXx8ErB2k-0LuHvaRe_tHkXkrpmAue5RlCj8J69uj0x0H9DUtzaL3dGrPTB4J2Ghv1x_ClYHc1KcVrJlaNNqjB-y2x3xTlO-k2lMbX1b4UaC3G-VaM2uIipWiZSmZ6TW97HsHWeON643fz3smADp79dnn2Cjln2m6b_YZ71Uq83iyYgchu55n9T2DlDuH96NA1aM-k8B5W_4PBULHtK_wf7EIap8AUbqXUPqNSCczzFtci5sjjVHIu7DeZFsIXPJ87fwBk4c0ZeQoAAA)

{% hint style="info" %}
A browser cannot run FreeType, KernSmith's default backend. In a browser, `UseKernSmith()` picks `StbTrueType` when the `KernSmith.Rasterizers.StbTrueType` package is referenced, and the fiddle passes it to `new KernSmithFontCreator(GraphicsDevice, KernSmith.RasterizerBackend.StbTrueType)` directly. See [Backend Selection](https://docs.flatredball.com/gum/code/files-and-fonts/fonts/advanced-font-effects.md#backend-selection-freetype-vs-stbtruetype).
{% endhint %}

## Related Pages

* [Font Strategies](https://docs.flatredball.com/gum/code/files-and-fonts/fonts/font-strategies.md): building fonts with KernSmith and registering `.ttf` files.
* [Automatic Glyph Growth](https://docs.flatredball.com/gum/code/files-and-fonts/fonts/font-automatic-growth.md): adding characters to a live font that weren't baked in ahead of time.
* [Camera](https://docs.flatredball.com/gum/code/gum-code-reference/camera.md): zooming the camera.
* [Layer](https://docs.flatredball.com/gum/code/gum-code-reference/layer.md): `LayerCameraSettings` and screen space layers.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flatredball.com/gum/code/files-and-fonts/fonts/font-oversampling.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
