---
title: Surface views
tags: uikit
---

# Surface views

A `UISurfaceView` is a view, which redirects all its drawing (including its subviews) to an underlying texture. This allows for a handful of features to be implemented.

[TODO some image goes here]

:::info
You can disable all of the features of the `UISurfaceView` via the `bool UsesSurface` property. Setting it to `false` will make the `UISurfaceView` behave as if it was a normal `UIView`. This should only be used for debugging purposes.

This applies to all of the below features, so it will not be mentioned again.
:::

# Clipping

A `UISurfaceView` creates a texture only as big as its own size, and nothing can be drawn outside of its bounds. Anything drawn outside of those bounds is discarded.

This behavior is inherent to the implementation of `UISurfaceView` and cannot be disabled.

# Color/alpha

The `Color` property allows changing the color (and alpha) of the whole `UISurfaceView` (including its subviews). This is done for the whole resulting image, not for each subview individually, avoiding any potential problems with alpha blending.

Additionally, the `ColorChanged(UISurfaceView, Color, Color)` event can be used to be notified whenever this value changes.

# Scaling, rotation

The `UIVector2 RenderScale` property allows adding a scale transformation to the resulting image.
This defaults to `UIVector2.One` (original scale).

The `float RenderRotation` property allows adding a rotation transformation to the resulting image.
This property's value is measured in radians.
This defaults to `0f` (no rotation).

The `UIVector2 Origin` property controls the point from which the image should be scaled / rotated.
This defaults to `{0.5, 0.5}` (meaning the center of the view).

Additionally, the `RenderScaleChanged(UISurfaceView, UIVector2, UIVector2)`, `RenderRotationChanged(UISurfaceView, float, float)` and `OriginChanged(UISurfaceView, UIVector2, UIVector2)` events can be used to be notified whenever these values change.

:::warning
These transformations are not taken into consideration when handling input, they are purely visual.
:::

# Using the resulting image

The `UISurfaceView`'s resulting image can also be used for other purposes.
The `Texture2D? RenderedTexture` property exposes this image.

An example usage of this image would be to create an image snapshot of the view. This may be a better approach than just taking a screenshot, as the image also includes the alpha channel.

if (mySurfaceView.RenderedTexture is not null)
{
    using var stream = new FileStream("screenshot.png", FileMode.OpenOrCreate);
    mySurfaceView.RenderedTexture.SaveAsPng(
        stream,
        mySurfaceView.RenderedTexture.Width,
        mySurfaceView.RenderedTexture.Height
    );
}