The sample projects are required to follow this recipe. We will be working with the ViewportSample.java file.

Even though every recipe so far uses this approach to handle multiple screen sizes, we have not gone into a lot of detail about how it works until now. Feel free to dig into any of those ApplicationListener implementations; for simplicity, SpriteBatchSample might be a good choice.

You already know that game worlds are typically modeled using world units. When working with user interfaces and screen sizes, an option is to assume the screen to have a set of specific dimensions in virtual screen units. The aspect ratio strategy will then work out how to map the virtual-screen-sized image to the actual screen.

Let's start off with some static constants that define the screen dimensions we want to support:

private static final float MIN_SCENE_WIDTH = 800.0f;
private static final float MIN_SCENE_HEIGHT = 600.0f;
private static final float MAX_SCENE_WIDTH = 1280.0f;
private static final float MAX_SCENE_HEIGHT = 720.0f;

The Viewport class is the base class from which the different resolution handling strategies inherit. Since we want the user to cycle the basic ones, Let's add an ArrayMap of String and Viewport pairs, so we can associate each viewport with its name. We also need the current viewport index, a camera, a batch, and a texture object:

private ArrayMap<String, Viewport> viewports;
private int currentViewport;

The create() method contains no magic; we instantiate our camera, batch, and texture and call the createViewport() and selectNextViewport() methods. Remember to dispose of the batch and texture once you are done, in the dispose() method:

@Override
public void create() {	
   
   ...
   
   createViewports();
   selectNextViewport();
   
...
}

The createViewports() method populates the associative array. Here you will find the list of built-in Libgdx Viewport implementations, which, like we said, are the ones responsible for handling multiple resolutions. Their constructors typically take scene dimensions in world units and the camera instance they are supposed to work with. Finally, we initialize our currentViewport index to -1:

private void createViewports() {
   viewports = new ArrayMap<String, Viewport>();
   viewports.put("StretchViewport", new StretchViewport(MIN_SCENE_WIDTH, MIN_SCENE_HEIGHT, camera));
   viewports.put("FitViewport", new FitViewport(MIN_SCENE_WIDTH, MIN_SCENE_HEIGHT, camera));
   viewports.put("FillViewport", new FillViewport(MIN_SCENE_WIDTH, MIN_SCENE_HEIGHT, camera));
   viewports.put("ScreenViewport", new ScreenViewport(camera));
   viewports.put("ExtendViewport (no max)", new ExtendViewport(MIN_SCENE_WIDTH, MIN_SCENE_HEIGHT, camera));
   viewports.put("ExtendViewport (max)", new ExtendViewport(MIN_SCENE_WIDTH, MIN_SCENE_HEIGHT, MAX_SCENE_HEIGHT, MAX_SCENE_WIDTH, camera));
   
   currentViewport = -1;
}

The render() method contains no secrets either. We simply render our texture centered on the screen as one would normally do:

@Override
public void render() {		
   ...
   
   batch.setProjectionMatrix(camera.combined);
   batch.begin();
   batch.draw(background, -background.getWidth() * 0.5f, -background.getHeight() * 0.5f);
   batch.end();
}

Every time the actual screen dimensions change, the resize() method is called with the new size in pixel units. The current viewport needs to be notified of such an event to recalculate its strategy. Remember that resize() also gets called right after create():

@Override
public void resize(int width, int height) {
   viewports.getValueAt(currentViewport).update(width, height);
}

In order to cycle through our collection of viewports whenever the user taps the screen or clicks the mouse, we need to override the touchDown event and call the selectNextViewport() method:

@Override
public boolean touchDown (int screenX, int screenY, int pointer, int button) {
   selectNextViewport();
   return true;
}

The selectNextViewport() function simply increments the currentViewport index, being careful not to escape the bounds of the viewport's ArrayMap. It needs to call an update on the newly selected viewport so as to let it adjust its strategy for the actual screen dimensions. Finally, it outputs the name of the viewport:

private void selectNextViewport() {
   currentViewport = (currentViewport + 1) % viewports.size;
viewports.getValueAt(currentViewport).update(Gdx.graphics.getWidth(), Gdx.graphics.getHeight());
   Gdx.app.log(TAG, "selected " + viewports.getKeyAt(currentViewport));
}

That is all! Feel free to launch the application on your desktop and resize the window with different viewports selected. This way, you will yourself experience how they behave. Nevertheless, we will cover them in great detail soon.

Allow us to go through the list of built-in Viewport implementation describing their behavior.

The StretchViewport class takes a virtual screen's dimensions and always stretches them to fit the screen. The plus side is that you will not find any black bars, but if the virtual ratio significantly differs from the one on the screen, the image can potentially appear greatly distorted, as shown in the following screenshot:

The FitViewport class will scale the image to fit the screen while maintaining the virtual aspect ratio. Even though the image will not be distorted, black bars will appear if both aspect ratios do not match. Our rendered result will always be centered on the screen, as shown in the following screenshot:

The FillViewport class keeps the aspect ratio, just like FitViewport. However, it does not introduce black bars, which means parts of the resulting image will end up being cut off, as shown in the following screenshot. Depending on the type of application you are working on, this may or may not be acceptable:

The ScreenViewport class will always match the actual screen dimensions, so no scaling is applied and you will not see any black bars at all, as shown in the following screenshot. Similar to FillViewport, this may affect gameplay since players with different screen sizes will see different portions of the world:

The ExtendViewport class is possibly the most complete and flexible solution. It keeps the provided aspect ratio without introducing black bars by extending the visible portion of the world in one direction. When a maximum set of dimensions is provided to the ExtendViewport dimensions, black bars will be added when the screen aspect ratio falls out of the supported range, as shown in the following screenshot:

Internally, the Viewport class calls glViewport() inside its update() method. This is a direct OpenGL call that defines the drawable area of the screen in screen pixel units.

We have already seen how cool Viewport is, but there is more to it. Here we are going to take a look at some of the additional functionality you can get out of it.

int getViewportHeight()
int getViewportWidth()
int getViewportX()
int getViewportY()
float getWorldHeight()
float getWorldWidth()

Vector2 project(Vector2 worldCoords)
Vector3 project(Vector3 worldCoords)
Vector2 unproject(Vector2 screenCoords)
Vector3 unproject(Vector3 screenCoords)

Floating elements

Strategies such as ExtendViewport are great because they look good across a bigger set of devices. However, you cannot predict which portion of the screen is going to be shown to the end user. We do not generally care about background elements, but we need to make sure the essential ones, such as buttons, are well positioned.

Imagine we need to add a Facebook icon to our background scene. If we place it in one of the texture corners, it may be hidden on 4:3 screens. We cannot put it closer to the center as it would look really odd on 16:9 devices. What we really want is to dynamically position certain elements depending on the viewport configuration and the actual screen size, just as shown in the following figure:

Assuming the UI camera has its bottom-left corner at (0, 0) and that it uses pixel units, the code to position the icon would be something like this:

icon.setPosition(viewport.getViewportWidth() - 20.0f, 20.0f);

Now, you can dynamically position floating elements to make your game look good everywhere without too much hassle.

Note

Hardcoding positioning for UI elements is always a bad practice. It is always advisable to define them in some sort of file, thus using a data-driven approach.