Module display 

Implements everything relating to things which are displayed on the screen.

Games written using agb typically follow the ‘update-render loop’. The way your components update will be very dependent on the game you are writing, but each frame you would normally do the following:

use agb::display::GraphicsFrame;

let mut my_game = MyGame::new();
let mut gfx = gba.graphics.get();

loop {
    my_game.update();

    let mut frame = gfx.frame();
    my_game.show(&mut frame);
    frame.commit();
}

The GraphicsFrame is the key mechanism for displaying anything on the screen (the frame variable you see above). Further sections e.g. Blend, Windows and dma will go into more detail about other effects you can apply once you’ve mastered the content of this article.

.show(frame: &mut GraphicsFrame)

The most common pattern involving GraphicsFrame you’ll see in the agb library is a .show() method which typically accepts a mutable reference to a GraphicsFrame e.g. RegularBackground::show and Object::show.

Due to this naming convention, it is also conventional in games written using agb to name the render method show() and have the same method signature. You should not be doing any mutation of state during the show() method, and as much loading and other CPU intensive work as possible should be done prior to the call to show().

See the frame lifecycle example for a simple walkthrough for how to manage a frame with a single player character.

.commit()

Once everything you want to be visible on the frame is ready, you should follow this up with a call to .commit() on the frame. This will wait for the current frame to finish rendering before quickly setting everything up for the next frame.

This method takes ownership of the current frame instance, so you won’t be able to use it for any further calls once this is done. You will need to create a new frame object from the gfx instance.

Modules

font

A system for including, rendering, and displaying dynamic text.

object

Sprites and objects

tile_data

Data produced by agb-image-converter

tiled

Anything to do with tiled backgrounds

utils

Utilities for graphics.

Macros

include_colours

Includes the colours of an image in the order that they appear as an array of Rgb15.

Structs

AffineMatrix

An affine matrix stored in a way that is efficient for the GBA to perform operations on. This implements multiplication.

Blend

Control the blending of two layers on the frame.

BlendAlphaEffect

Configure the alpha setting for an alpha blend

BlendFadeEffect

Configure the fade effect for a darken or lighten blend.

BlendObjectTransparency

Configure the fade effect for making objects optionally transparent.

Graphics

Manage the graphics for the Game Boy Advance.

GraphicsDist

Use to get the Graphics subsystem for agb.

GraphicsFrame

Manages everything to do with the current frame that is being rendered.

MovableWindow

A window that can be moved

Palette16

Represents a palette of 16 colours.

Rgb

Represents a full true-colour (24-bit) RGB colour.

Rgb15

Represents a pixel on the GBA.

Window

A non movable window

Windows

Access to the windows feature of the Game Boy Advance.

Enums

Layer

The layers, top layer will be blended into the bottom layer

Priority

The priority of a background layer or object. A higher priority should be thought of as rendering first, and so is behind that of a lower priority. For an equal priority background layer and object, the background has a higher priority and therefore is behind the object.

WinIn

The two Windows that have an effect inside of them.

Constants

HEIGHT

Height of the Game Boy advance screen in pixels

WIDTH

Width of the Game Boy advance screen in pixels

Functions

busy_wait_for_vblank

Waits until vblank using a busy wait loop, this should almost never be used. I only say almost because whilst I don’t believe there to be a reason to use this I can’t rule it out.