> 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/gum-tool/gum-elements/general-properties/blend.md).

# Blend

## Introduction

The `Blend` variable controls how the selected instance combines its colors with whatever is drawn before. The final appearance depends on its `Blend`, `Alpha`, `Source File`, and `Color` values.

`Blend` is available on the following types:

* [Circle](https://docs.flatredball.com/gum/gum-tool/gum-elements/circle.md)
* [ColoredRectangle](https://docs.flatredball.com/gum/gum-tool/gum-elements/coloredrectangle.md)
* [Container](https://docs.flatredball.com/gum/gum-tool/gum-elements/container.md) (if [Is Render Target](https://docs.flatredball.com/gum/gum-tool/gum-elements/container/is-render-target.md) is set to true)
* [NineSlice](https://docs.flatredball.com/gum/gum-tool/gum-elements/nineslice.md)
* [Rectangle](https://docs.flatredball.com/gum/gum-tool/gum-elements/rectangle.md)
* [Sprite](https://docs.flatredball.com/gum/gum-tool/gum-elements/sprite.md)

`Blend` is also available on all Skia elements:

* [Arc](https://docs.flatredball.com/gum/gum-tool/gum-elements/skia-standard-elements/arc.md)
* [ColoredCircle](https://docs.flatredball.com/gum/gum-tool/gum-elements/skia-standard-elements/coloredcircle.md)
* [LottieAnimation](https://docs.flatredball.com/gum/gum-tool/gum-elements/skia-standard-elements/lottieanimation.md)
* [RoundedRectangle](https://docs.flatredball.com/gum/gum-tool/gum-elements/skia-standard-elements/roundedrectangle.md)
* [Svg](https://docs.flatredball.com/gum/gum-tool/gum-elements/skia-standard-elements/svg.md)

Most examples on this page overlay a Sprite over ColoredRectangles, but the same `Blend` behavior applies to all items which support the `Blend` variable.

## Normal Blend

`Normal` `Blend` is the default value. When an instance uses `Normal` `Blend`, it *interpolates* its color with whatever it draws on top of using its `Alpha` value as a weight.

If a `Normal` `Blend` Sprite has an `Alpha` of `255`, then the Sprite completely replaces whatever is below.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-4edcc056a908ad3566bbc49924ffc3fa83507925%2Fimage%20(2)%20(1)%20(1)%20(1)%20(1)%20(1)%20(1)%20(1)%20(1).png?alt=media" alt=""><figcaption><p>Normal Blend Sprite with an Alpha of 255</p></figcaption></figure>

If a Sprite has an `Alpha` of `128` (roughly half of 255), then it averages its color with whatever is below.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-af8e3132bc4836d6b04755d878d75b690e41df56%2Fgb-005.png?alt=media" alt=""><figcaption><p>Normal Blend Sprite with an Alpha of 128</p></figcaption></figure>

A Sprite with an `Alpha` of `25` (roughly 10%) blends with whatever is below, but its color is given a weight of roughly 10%.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-6a3d5a44a48d89411b8ab452a340eef99393e4d9%2Fimage%20(2)%20(1)%20(1)%20(1)%20(1)%20(1)%20(1)%20(1)%20(1)%20(1).png?alt=media" alt=""><figcaption><p>Normal Blend Sprite with an Alpha of 25</p></figcaption></figure>

{% hint style="info" %}
The examples above use the `Alpha` value to apply transparency. Note that if the source file (.png) has transparency as part of the file, the same effect applies.
{% endhint %}

## Additive Blend

`Additive` `Blend` results in the color of a element being added to whatever is below. This typically results in brighter colors. `Additive` `Blend` can be used to simulate a light.

Since `Additive` `Blend` results in a modification of what is under instead of a replacement, an `Additive` `Blend` Sprite typically appear transparent even when `Alpha` is `255`.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-cdc10b05114d08eb5c1a73f2bffa729cc2a2a867%2Fimage%20(3)%20(1).png?alt=media" alt=""><figcaption><p>Additive Blend Sprite with an Alpha of 255</p></figcaption></figure>

As `Alpha` is reduced, the brightening effect is reduced. A Sprite with an `Alpha` of `128` only applies roughly half as much of a brightening effect.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-7b9bf72bda777aa969b24c249fbb006d18dc36b0%2Fimage%20(4)%20(1).png?alt=media" alt=""><figcaption><p>Additive Blend Sprite with an Alpha of 128</p></figcaption></figure>

A Sprite with an `Alpha` of `25` applies a slight brightening effect.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-239568bf0af41dfe816c1656260124cb86f286e0%2Fimage.png?alt=media" alt=""><figcaption><p>Additive Blend Sprite with an Alpha of 25</p></figcaption></figure>

Stacking multiple Sprites with `Additive` `Blend` results in the brightening effect stacking as well.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-43c2995b7e0294fa0bb96e4d99d52530c3af2432%2Fimage.png?alt=media" alt=""><figcaption><p>Four Additive Blend Sprites with an Alpha of 255</p></figcaption></figure>

## Replace Blend

`Replace` `Blend` results in the instance completely replacing whatever it is drawn on top of regardless of its `Alpha` or transparency in the source file.

A Sprite with no transparency in its source file drawn with `Alpha` of `255` looks the same whether it uses `Replace` or `Normal` `Blend`.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-f191485f51732626c3645b528f80c8b966c4576e%2Fimage.png?alt=media" alt=""><figcaption><p>Replace Blend Sprite with an Alpha of 255</p></figcaption></figure>

Changing the `Alpha` on a Sprite with `Replace` `Blend` does not affect how it is drawn - it is always drawn at full opacity.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-72e619bbf085d226ef7d53dd8aedd2a0b52388ed%2Fimage.png?alt=media" alt=""><figcaption><p>Replace Blend Sprite with an Alpha of 128</p></figcaption></figure>

`Replace` `Blend` results in a Sprite being fully opaque even if its source file has transparency. The following image shows two Sprites displaying the same image.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-e61da6effd8888d72e7430da10193fd45c58beb3%2Fimage.png?alt=media" alt=""><figcaption><p>Normal and Replace Blend on the same source file.</p></figcaption></figure>

## Subtract Blend

`Subtract` `Blend` subtracts the color of an instance from whatever is below. Each channel drops by the instance's color and stops at black, so dark colors clip to black first. It leaves alpha unchanged. `Subtract` can darken a whole scene with one gray rectangle, such as a retro HUD dimming the playfield behind a menu.

A `Subtract` `Blend` Sprite with an `Alpha` of `255` subtracts the photo from the color bars below it. Black stays black, and bright bars take on the inverse of the photo.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-ef8b46e4a9049db0a4bfb8828ae2551f03a88b72%2Fsubtract-blend-alpha-255.png?alt=media" alt=""><figcaption><p>Subtract Blend Sprite with an Alpha of 255</p></figcaption></figure>

As `Alpha` is reduced, less color is subtracted. A Sprite with an `Alpha` of `64` subtracts about a quarter as much.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-0b1ede2b2746f3c42478f1bbc734ed5f9b539e0f%2Fsubtract-blend-alpha-64.png?alt=media" alt=""><figcaption><p>Subtract Blend Sprite with an Alpha of 64</p></figcaption></figure>

{% hint style="info" %}
`Subtract` `Blend` is available in December 2026, or now if building Gum from source.
{% endhint %}

## Alpha-Only Blends

Gum supports **Blend** modes which modify the alpha (opacity) of whatever is under the instance using the alpha-only `Blend` . Alpha-only `Blend` modes ignore the color of the instance using the `Blend` - only the alpha matters (see note below about premultiplied alpha). Therefore, the following three circles would behave the same despite having different colors:

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-e5d6444c1b2809f822b19250f19210eda11429ea%2F09_06%2055%2032.png?alt=media" alt=""><figcaption><p>Color values are ignored with Alpha-only Blends</p></figcaption></figure>

{% hint style="warning" %}
Runtimes which use premultiplied alpha (such as FlatRedBall) require using objects that are fully white when modifying alpha. Otherwise, the color of the overlaying instance will blend with the underlying object.
{% endhint %}

Since alpha-only blends operate directly on the alpha of whatever is below, they are only intended to be used on Containers with `Is Render Target` set to true. Usually objects with these blend modes are drawn on top of all other items in the container. For example, the following image shows a RenderTargetContainer which holds a number of items including the AlphaOnlyCircle. AlphaOnlyCircle is an instance which can be used to apply Alpha-only Blends to whatever is below.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-031f6d9896fb2a8fd8f8e8e8fad43ea079364f3a%2F09_07%2013%2033.png?alt=media" alt=""><figcaption><p>AlphaOnlyCircle can be used to modify the alpha of what is below</p></figcaption></figure>

Using an alpha-only Blend outside of a container with Is Render Target set to true typically results in the instance either being drawn as pure black or being invisible.

{% hint style="warning" %}
On MonoGame, KNI, and FNA, text drawn with `Replace Alpha` or `Min Alpha` writes alpha one glyph box at a time. Glyph boxes that overlap (tight kerning, italics, large outlines) can overwrite each other's alpha. This is a known limitation that may change in a future version. Text with these blends is not a use case we currently see, so it is not being addressed now.
{% endhint %}

## Subtract Alpha Blend

**Subtract Alpha** **Blend** subtracts, or "cuts out", the alpha of whatever is below.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-e2cc21a77c41888be97f948b4eaffd7d73309560%2F09_07%2017%2014.gif?alt=media" alt=""><figcaption><p>Subtract Alpha removing the alpha of what is below</p></figcaption></figure>

As `Alpha` is reduced, the amount of opacity removed effect is also reduced. A Sprite with an `Alpha` of `128` only removes roughly half as much opacity from what is below.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-f3d5ea13f309d4afc948e31fc50f339533ac0e29%2F09_07%2028%2050.gif?alt=media" alt=""><figcaption><p>Reducing Alpha results in less opacity being removed</p></figcaption></figure>

Each `Subtract Alpha` instance removes its share of whatever opacity remains. Two instances with an `Alpha` of `128` do not remove everything: the first leaves about half of the original opacity, and the second leaves about half of that, or roughly a quarter.

## Replace Alpha Blend

Replace Alpha forcefully sets the opacity of whatever is below. Rather than subtracting alpha, replace can forcefully set the alpha.

Replace Alpha with an Alpha value of 255 results in no changes if what is under is already opaque, but it can add alpha if what is under is transparent.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-ed51f6718cd807d150c12415ae95eb27ebbc5a4c%2F09_08%2005%2033.gif?alt=media" alt=""><figcaption><p>Replace Alpha with Alpha of 255 results in no changes on already-opaque regions, but can add alpha</p></figcaption></figure>

If `Alpha` is reduced, then the resulting pixels display the explicitly set alpha. The following shows setting alpha explicitly to 128 (about 50%).

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-a6ab77497c720f6fd91ac96f7de9b5c5b01023bd%2F09_08%2007%2002.gif?alt=media" alt=""><figcaption><p>Explicitly setting alpha to 128 with Replace Alpha</p></figcaption></figure>

Setting `Alpha` to `0` forcefully sets whatever is under to fully transparent. This is similar to performing `Subtract Alpha` with an `Alpha` of `255`.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-0960c85c15bbff0883da203cfd90b9e0f1486162%2F09_08%2009%2037.gif?alt=media" alt=""><figcaption><p>Replace Alpha with Alpha of 0</p></figcaption></figure>

Keep in mind that `Replace Alpha` can apply different alpha values if the instance itself has variable alpha, such as a Sprite with some parts transparent and some parts opaque.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-3a555032cf8592b8a35fc9f20160a31139a2bfd0%2F09_08%2011%2021.gif?alt=media" alt=""><figcaption><p>Alpha being replaced to opaque in the center and transparent on the edges of the circle</p></figcaption></figure>

`Replace Alpha` applies to the whole bounds of the instance, not only the pixels it paints. See [Whole-Bounds Masking](#whole-bounds-masking).

## Min Alpha

`Min Alpha` modifies the underlying object so that the result is the minimum alpha between the instance and what is below. This can be used to create an alpha mask.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-1b712880eb42344f2c4e9916e48db43b2e062851%2F09_08%2016%2044.gif?alt=media" alt=""><figcaption><p>Min alpha creates a mask</p></figcaption></figure>

`Min Alpha` applies to the whole bounds of the instance, not only the pixels it paints. Pixels inside the shape keep their opacity, and pixels inside the bounds but outside the shape (such as the corners around a Circle) become transparent. This lets a Circle or a Rectangle with rounded corners mask a circular or rounded area without a custom texture. See [Whole-Bounds Masking](#whole-bounds-masking).

If the instance alpha is reduced, then the resulting transparency is reduced as well. The following shows setting `Alpha` to 128 (about 50%).

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-35ca44b3aad963e80226150c4c41a24af97ab511%2F09_08%2018%2017.gif?alt=media" alt=""><figcaption><p>Min alpha with an alpha of 128</p></figcaption></figure>

Keep in mind that multiple objects can be combined to create larger masks. For example, additional ColoredRectangles can be added to the circle above to create a larger mask. Each rectangle also has its `Blend` set to `Min Alpha`.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-683bbd4cdf796c411e0ba7f608961d0687b9b386%2F09_08%2022%2006.gif?alt=media" alt=""><figcaption><p>Extending masks with additional shapes</p></figcaption></figure>

## Whole-Bounds Masking

`Replace Alpha` and `Min Alpha` use the whole bounding rectangle of an instance as the mask. Pixels inside the bounds that the instance does not cover end up with an alpha of `0`. Pixels outside the bounds do not change.

This applies to Circle, Rectangle, RoundedRectangle, Arc, Sprite, NineSlice, and Text.

The following shows a blue Rectangle in a Container with `Is Render Target` set to true. A filled Circle drawn after it uses `Min Alpha`. The Circle keeps the Rectangle's pixels inside the Circle and clears the corners of the Circle's bounds, while the Rectangle outside those bounds is unchanged.

<figure><img src="https://2695663588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M_fzQmxQ1VeUFHcoo2c%2Fuploads%2Fgit-blob-7534bff3e73a04802e91a1ba78a1e811a22911a6%2F21_05%2023%2040.png?alt=media" alt=""><figcaption><p>Min Alpha on a Circle clears the corners of its bounds</p></figcaption></figure>

{% hint style="info" %}
Whole-bounds masking for shapes and text, and `Replace Alpha` on Skia elements, are available in November 2026, or now if building Gum from source. Before then, `Replace Alpha` on a Skia element drew like `Normal` `Blend`.
{% endhint %}

### Shapes With a Stroke

A shape with both a fill and a stroke masks as one shape. The fill and the stroke keep their opacity, and the rest of the bounds becomes transparent. A default Circle or Rectangle, which has a stroke and no fill, works as a mask without setting `Is Filled`.

### Text

Text uses the measured text block plus a 2 pixel margin as its bounds, and adds the drop shadow offset when it has a drop shadow. Skia also adds the outline thickness and the shadow blur. Glyph pixels keep their alpha, and the rest of the bounds becomes transparent.

The Gum tool has no `Blend` variable for text, so set `Blend` on the Text in code. Like the other alpha-only blends, Text masks the content below it when its Container has `Is Render Target` set to true.

### Edges Between Pixels

An edge of the bounds that falls between pixels (a fractional position or a rotation) is not exact, because a pixel partly covered by the edge cannot be both kept and cleared.


---

# 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/gum-tool/gum-elements/general-properties/blend.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.
