# FS_LoadOverlay

## C Specification

      #include <nitro/fs.h>

      BOOL FS_LoadOverlay(MIProcessor target, FSOverlayID id);

## 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) */
    {
        FSOverlayInfo  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);
    }

## Arguments

`target` | Load target (main processor/sub 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.

## See Also

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

## Revision History

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.