Request to Move to Foreground

Gaining the Foreground

When a process receives the ACQUIRED_FOREGROUND message through the system message queue, your application is already in the foreground and you own all foreground resources simultaneously. All drivers are ready and the game threads on all three cores are being scheduled. For more information, see Multicore Processing and the ProcUI Library.

Your application must do the following.

Start or restart graphics.
Start or restart audio.
Resume what it was doing before it was placed into the background.

Switching from Background to Foreground

When not using ProcUI, a process has acquired the foreground when it receives a message from the system message queue with msg.data0 == OS_SYSTEM_MESSAGE_DATA0_ACQUIRED_FOREGROUND set.

When using ProcUI, a process has acquired the foreground when ProcUI receives PROCUI_MESSAGE_ACQUIRE and calls the appropriate callbacks.

After either of these events has happened, the process is in the foreground.

Before rendering graphics, it is necessary to recreate any resources in MEM1 or the foreground bucket because these resources are cleared on a foreground switch.
ProcUI provides functions to restore MEM1 and/or the foreground bucket automatically.

Call GX2SetContextState After Returning From a Process Switch

Upon reacquiring the foreground state, the application should make few assumptions about what GPU state remains from its previous foreground instance. MEM2 resources remained where they were. Any MEM1 resources will need to be reloaded. Display settings (see GX2DisplayPage) should not require resetting.

The application must start the rendering with a context state reset. This means it should begin the frame by calling either GX2ClearColor (or similar APIs, see GX2 Functions Which Disable State Shadowing) or GX2SetContextState. This is mandatory. It is not acceptable to attempt to reset every GX2 state manually, since this may not reset all of the GPU pipeline state.

Recommendations

Your game should block all threads until after it receives the ACQUIRED_FOREGROUND message.
You should call GX2GetLastFrame to get the previous frame and perform a crossfade.

Revision History

2013/08/08 Created