FS_LoadOverlay

Syntax

#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 TRUE if the module is loaded properly; FALSE otherwise.

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 and FS_StartOverlay functions. For information about its relationship 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) */
{
    FSOverlayInfo  info;
    FS_LoadOverlayInfo(&info, target, overlay_id);
    FS_LoadOverlayImage(&info);
    FS_StartOverlay(&info);
}

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

/* Method 4: Execute all using low-level functions */
{
    FSOverlayInfo  info;
    FS_LoadOverlayInfo(&info, target, overlay_id);
    {
        FSFile         file;
        FS_InitFile(&file);
        /* Open the overlay image file directly and initialize the overlay region's memory  */
        FS_OpenFileFast(&file, FS_GetOverlayFileID(&info));
        FS_ClearOverlayImage(&info);
        /*
         * If you want to replay stream sounds in parallel, 
         * divide the application into convenient units and load.
         */
        {
            int len, pos;
            int small_size = 1024 * 32;
            for (pos = 0; pos < FS_GetFileLength(&file); pos += len)
            {
                len = FS_ReadFileAsync(&file, small_size);
                while(FS_IsBusy(&file))
                {
                    /* Process the framework or message pump */
                }
            }
        }
        FS_CloseFile(&file);
    }
    FS_StartOverlay(&info);
}

Revision History

2008/10/02 Revised the sample code.
2007/04/16 Added sample code.
2005/06/02 Changed & to &.
2004/11/17 Revised sample code due to the elimination of
FS_RegisterOverlayToDebugger.2004/11/16 Partially revised sample code and added a precaution concerning
FS_UnloadOverlay.2004/10/19 Revised part of the sample code.2004/09/24 Added text to the example concerning the relationship between the various types of overlay functions.2004/06/11 Made revisions reflecting the addition of overlay functions.2004/04/08 Revised description due to changes in the
FSOverlayID type.2004/04/05 Revised description due to addition of
FSOverlayID.2004/04/01 Initial version.