Gum Resolution


Gum and the Gum plugin provide a number of options for dealing with various game resolutions. This tutorial will walk you through the different ways to work with resolutions.

Default Values

When you work with a Gum project, you can specify the resolutions that you're targeting. This can be done as follows:

  1. Go to Edit->Project Properties

  2. Change the "DefaultCanvasHeight" or "DefaultCanvasWidth" to the desired values.

  3. Notice the blue dotted line changing in response to the changed values.

Zooming UI

Gum allows you to zoom your entire UI in or out at runtime. This can be useful in a number of situations:

  1. If you are creating a game that targets a lower-resolution device (such as a non-retina iOS device), but you want the game to also run on retina devices. In this case you may want to zoom your UI when running on retina displays.

  2. If you are intentionally creating a low-resolution game to give it a "retro feel".

void CustomInitialize()
    RenderingLibrary.SystemManagers.Default.Renderer.Camera.Zoom = 2;

Automatic (default) adjustment

If you are setting the resolution of your game through Glue, then the Gum canvas size will automatically adjust to the starting value as set by Glue in generated code. In other words, even though our Gum project was defined as a 400x300 project and our game is 800x600, the Gum canvas will expand to 800x600 automatically. Note that this requires that the game's resolution and orthogonal values are equal, as shown in the following image:

For situations where Orthogonal Values do not equal the game's resolution, see the section below. In the previous example the NineSlice still took up 1/4 of the screen even though the Gum canvas expanded. The reason for this is because the NineSlice was using "absolute" width and height values which were set to 400x300. If we change the width and height values to be relative to the container of the NineSlice (which is the entire screen) then the NineSlice will automatically expand to fill the entire Screen. To do this, set the NineSlice's width and height values to be relative to its container (which is the entire screen):

  1. Select the NineSlice instance

  2. Set the "Width Units" to "RelativeToContainer"

  3. Set the "Height Units" to "RelativeToContainer"

Dynamically changing the canvas dimensions

Although the generated code automatically adjusts the canvas width and height according to the Gum settings, your game may require adjustment of the resolution after launching. Common examples of this may include docking a Windows 8 app, or resizing a Windows desktop app. For this example my Screen will set the resolution to 500x500, and then I'll adjust the Gum canvas to match:

void CustomInitialize()
    // First we'll set the game window (and FlatRedBall) to be 500x500
    FlatRedBallServices.GraphicsOptions.SetResolution(500, 500);

    // Then we'll tell Gum to set its canvas size to match:
    Gum.Wireframe.GraphicalUiElement.CanvasWidth = 500;
    Gum.Wireframe.GraphicalUiElement.CanvasHeight = 500;

    // Finally we need to redo the layout for the entire Screen.
    // My screen is called "Screen1", so I use Screen1.Element:
void CustomInitialize()
    FlatRedBallServices.GraphicsOptions.SizeOrOrientationChanged += HandleResize;

private void HandleResize(object sender, EventArgs e)
    var newWidth = FlatRedBallServices.GraphicsOptions.ResolutionWidth;
    var newHeight = FlatRedBallServices.GraphicsOptions.ResolutionHeight;

    Gum.Wireframe.GraphicalUiElement.CanvasHeight = newHeight;
    Gum.Wireframe.GraphicalUiElement.CanvasWidth = newWidth;


// Unsubscribe when the screen destroys itself to prevent a memory leak:
void CustomDestroy()
    FlatRedBallServices.GraphicsOptions.SizeOrOrientationChanged -= HandleResize;

Working with Different Resolution and Orthogonal Values

So far we've looked at situations where the orthogonal value equals the resolution of the game. Games which use an orthogonal camera and target mobile devices may use fixed Orthogonal Width and Orthogonal Height values in Glue, but the resolution depends on the device. We can simulate this on PC by setting the values as shown in the following Glue Camera window (we'll set the resolution to be extra wide to help show the problem):

In this case, the Gum rendering engine will expand itself to fill the entire rendering area, but it will maintain its aspect ratio. In other words, our canvas will be 800 units tall (to match the game's resolution), but the width will be limited to the 4:3 aspect ratio as set in the Orthogonal Values.

In this case we will update the canvas width to match the game's aspect ratio as shown in the following code:

var aspectRatio = Camera.Main.AspectRatio;
Gum.Wireframe.GraphicalUiElement.CanvasWidth = Gum.Wireframe.GraphicalUiElement.CanvasHeight * aspectRatio;


This adjustment will result in the canvas widening to the appropriate aspect ratio. Since the nine slice automatically fills up the screen (when UpdateLayout is called), this will expand the nine slice to the full display width:

Last updated