OSGetForegroundBucket

Syntax

#include <cafe/os.h>

BOOL OSGetForegroundBucket(void ** appRetArea, u32 * apRetSizeBytes);

Parameters

appRetArea Pointer to pointer in which to return the address of the foreground "bucket" memory area. Argument may be NULL.
apRetSizeBytes Pointer to u32 in which to return the size of the foreground "bucket" memory area. Argument may be NULL.

Return Values

Returns TRUE if the calling process is in the foreground, in which case the return arguments are valid. Returns FALSE if the calling process is not in the foreground.

Description

This function retrieves the address and size of the entire foreground memory area.

The foreground area is a memory area that is available only to the process that is currently in the foreground. When the foreground is released (via OSReleaseForeground), the foreground area is cleared and is made available to the process that has moved into the foreground.

The foreground area may not be at the same virtual address each time a process is in the foreground.

The foreground area is divided into two regions. One region, called the free area, is 40 MB and is exclusively for use by the foreground application. Use the OSGetForegroundBucketFreeArea function to get this memory area. The second region, called the save area, is 24 MB and is reserved for system use.

NOTE:
This function should be used only to test whether a pointer is in foreground memory area. For example, the GX2GetLastFrame function returns a pointer into the save area. If you need to test if a pointer refers to a specific memory area, and if the pointer returned by GX2GetLastFrame might be subject to such a test, use this function to verify that it refers to the foreground area.

Do Not Call From

None.

See Also

Foreground Bucket
APP_IN_FOREGROUND
OSGetCallArgs
OSGetForegroundBucketFreeArea
OSGetSystemMessageQueue
OSReleaseForeground
OSSavesDone_ReadyToRelease
OSSendAppSwitchRequest

Revision History

2013/09/06 Clarified proper usage and limits.
2013/05/08 Automated cleanup pass.
2012/12/03 Add memory sizes.
2012/07/27 Cleanup Pass
2011/08/29 Initial version.


CONFIDENTIAL