FS_LoadOverlay

C Specification

#include <nitro/fs.h>

BOOL FS_LoadOverlay(MIProcessor target, FSOverlayID id);

Arguments

target Load target (ARM9 processor/ARM7 processor)
id ID of module to load

Return Values

Returns a value of TRUE if the module is loaded properly. Otherwise, a value of FALSE is returned.

Description

This function loads an overlay module that is associated with a specified processor and a specified number.
When loading an overlay whose area conflicts with an existing loaded overlay, you must unload the previous overlay using the FS_UnloadOverlay function.
This function is equivalent to using the FSOverlayInfo function to acquire overlay module information and calling the FS_LoadOverlayImage function and the FS_StartOverlay function. For information about its relation to other overlay functions that perform equivalent processes see the following.

Example:

/*********************************************************
Overlay load method (all processes are internally equivalent)
 *********************************************************/

FS_EXTERN_OVERLAY(overlay_x);
FSOverlayID   overlay_id = FS_OVERLAY_ID(overlay_x);
MIProcessor   target = MI_PROCESSOR_ARM9;

/* Method 1: Runs everything synchronously.*/
{
FS_LoadOverlay(target, overlay_id);
}

/* Method 2: Runs manually in sections (synchronous) */
{
FS_LoadOverlayInfo  info;
FS_LoadOverlayInfo(&info, target, overlay_id);
FS_LoadOverlayImage(&info);
FS_StartOverlay(&info);
}

/* Method 3: Runs everything manually (asynchronous) */
{
FS_LoadOverlayInfo  info;
FS_LoadOverlayInfo(&info, target, overlay_id);
    {
FSFile         file;
FS_InitFile(&file);
FS_LoadOverlayInfo(&info, &file);
while(FS_IsBusy(&file)) {
/* Process the framework or message pump */
        }
FS_CloseFile(&file);
    }
FS_StartOverlay(&info);
}

See Also

FSOverlayInfo, FSOverlayID, FS_OVERLAY_ID, FS_LoadOverlayInfo, FS_LoadOverlayImage, FS_LoadOverlayImageAsync, FS_StartOverlay, FS_LoadOverlay, FS_UnloadOverlay

Revision History

06/02/2005 Changed '&' to '&'.
11/17/2004 Revised sample code due to the elimination of FS_RegisterOverlayToDebugger.
11/16/2004 Partially revised sample code, added note concerning FS_UnloadOverlay.
10/19/2004 Revised part of the sample code.
09/24/2004 Added description concerning the relationship with each type of overlay function.
06/11/2004 Added descriptions due to additional overlay functions.
04/08/2004 Revised description due to changing the FSOverlayID type.
04/05/2004 Revised description due to addition of FSOverlayID.
04/01/2004 Initial version.