# FS_LoadOverlay

## 構文

  `#include <nitro/fs.h>`
  `BOOL FS_LoadOverlay(MIProcessor target, FSOverlayID id);`

## 引数

target | ロードする対象（ARM9プロセッサ/ARM7プロセッサ）
id | ロードするモジュールのID

## 返り値

モジュールが正しくロードされれば TRUE を返し、そうでない場合は、FALSE を返します。

## 説明

指定したプロセッサの指定した番号に関連付けられたオーバーレイモジュールをロードします。
ロードされた既存のオーバーレイと領域を競合する他のオーバーレイをロードする場合、
必ず以前のオーバーレイを `FS_UnloadOverlay()` でアンロードする必要があります。
この関数は、`FS_LoadOverlayInfo()` でオーバーレイモジュール情報を取得して
`FS_LoadOverlayImage()` および `FS_StartOverlay()` を呼び出すことと等価です。
同等の処理を行う他のオーバーレイ関数との関係については以下の例を参照ください。

    例)

    /*********************************************************
     *  オーバーレイ読み込みの方法. (全て内部的に等価な処理)
     *********************************************************/

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

    /* 方法1: 全てを同期的に実行 */
    {
        FS_LoadOverlay(target, overlay_id);
    }

    /* 方法2: 部分的に手作業で実行 (同期的) */
    {
        FSOverlayInfo  info;
        FS_LoadOverlayInfo(&info, target, overlay_id);
        FS_LoadOverlayImage(&info);
        FS_StartOverlay(&info);
    }

    /* 方法3: 全てを手作業で実行 (非同期的) */
    {
        FSOverlayInfo  info;
        FS_LoadOverlayInfo(&info, target, overlay_id);
        {
            FSFile         file;
            FS_InitFile(&file);
            FS_LoadOverlayImageAsync(&info, &file);
            while(FS_IsBusy(&file))
            {
                /* フレームワークまたはメッセージポンプを処理 */
            }
            FS_CloseFile(&file);
        }
        FS_StartOverlay(&info);
    }

    /* 方法4: 全てを低水準関数で実行 */
    {
        FSOverlayInfo  info;
        FS_LoadOverlayInfo(&info, target, overlay_id);
        {
            FSFile         file;
            FS_InitFile(&file);
            /* オーバーレイイメージのファイルを直接開きオーバーレイ領域のメモリを初期化する */
            FS_OpenFileFast(&file, FS_GetOverlayFileID(&info));
            FS_ClearOverlayImage(&info);
            /*
             * 並行してストリームサウンドを再生したい場合など,
             * アプリケーションに都合の良い単位で分割してロードする.
             */
            {
                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))
                    {
                        /* フレームワークまたはメッセージポンプを処理 */
                    }
                }
            }
            FS_CloseFile(&file);
        }
        FS_StartOverlay(&info);
    }

## 参照

`FSOverlayInfo FSOverlayID FS_OVERLAY_ID
FS_LoadOverlayInfo FS_LoadOverlayImage FS_LoadOverlayImageAsync FS_StartOverlay FS_LoadOverlay FS_UnloadOverlay`

## 履歴

2008/10/02 サンプルコードを一部訂正
2007/04/16 サンプルコードを追加
2005/06/02 &を&amp;へ修正
2004/11/17 `FS_RegisterOverlayToDebugger()`廃止に伴うサンプルコード例修正
2004/11/16 サンプルコード例を一部修正、`FS_UnloadOverlay()`に関する注意を追加
2004/10/19 サンプルコード例を一部修正
2004/09/24 各種オーバーレイ関数の関係について例を記述追加
2004/06/11 他のオーバーレイ関数追加による記述修正
2004/04/08 FSOverlayID の型変更による記述修正
2004/04/05 FSOverlayID 追加による記述修正
2004/04/01 初版