# 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);
    }

## See Also

`FS_LoadOverlay`
`FS_LoadOverlayImage`
`FS_LoadOverlayImageAsync`
`FS_LoadOverlayInfo`
`FS_OVERLAY_ID`
`FSOverlayInfo`
`FS_StartOverlay`
`FS_UnloadOverlay`

## 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.

CONFIDENTIAL