##### Sound Library - データユーティリティ関数

# sdBankDownload

Bankの転送

### 書式

> `SDE_ERR sdBankDownload( handle, bank_type, bank_num )
> SDMEMBLK handle
> const SDE_DATA_TYPE bank_type
> const Sint8 bank_num
> `

### 引数

> handle | 転送元のBankのメモリブロックのハンドル
> bank_type | 転送先のBankの種類
> bank_num | 転送先のBankの番号

### 戻り値

> SDE_ERR_NOTHING | エラーなし
> SDE_ERR_NO_INIT | Sound Library が初期化されていない
> SDE_ERR_HANDLE_NULL | ハンドルがNULL
> SDE_ERR_HANDLE_ILLEGAL_VALUE | ハンドルが不正なアドレスを指している
> SDE_ERR_BANK_ILLEGAL_TYPE | Bank タイプが異常
> SDE_ERR_BANK_ILLEGAL_CHECK_SUM | Bank内のチェックサムが合わなかった

### 解説

> Bankをメインメモリからサウンドメモリへ転送します。

> Bankの種類を指定する引数 bank_type には次の指定が可能です。

> 定義 | 意味
> SDE_DATA_TYPE_MIDI_SEQ_BANK | MIDI Sequence Bank
> SDE_DATA_TYPE_MIDI_PRG_BANK | MIDI Program Bank
> SDE_DATA_TYPE_SHOT_BANK | One Shot Bank
> SDE_DATA_TYPE_FX_OUT_BANK | FX Output Bank
> SDE_DATA_TYPE_FX_PRG_BANK | FX Program Bank

> この関数を使用する前に、Multi Unitをサウンドメモリに転送してメモリマッピングされている必要があります。

> sdMltDownload()関数またはsdMltDownloadEx()関数の実行で Multi Unitの転送が可能です。

> エラーのタイプが SDE_ERR_BANK_ILLEGAL_TYPE(Bankタイプが異常)の場合、 ライブラリが識別できないBank IDが入った Bankを転送しようとしたことが考えられます。 実際に転送されたかどうかの確認が必要な場合は、メモリブロックの転送モードをSDD_MEMBLK_SYNC_FUNCにしてください。

### 用例

>     Void BankLoad( char *file_name, SDE_DATA_TYPE bank_type, Sint8 bank_num)
>     {
>         SDMEMBLK memblk = NULL;
>         GDFS gdfs = NULL;
>         Void *bank_ptr;
>         Sint32 bank_sz;

>         /*
>          * Load Bank File into memory
>          */
>         gdfs = gdFsOpen( SMPD_PSTM_R_SRC_FILE_NAME, NULL);

>         /* Get Bank File size */
>         gdFsGetFileSize( gdfs, &bank_sz);

>         /* Get buffer to read */
>         /* Allocate enough amount of memory to support loading from GD */
>         bank_ptr = syMalloc( gSrcWaveSz + GDD_FS_SCTSIZE);

>         /* Load Bank File */
>         gdFsRead( gdfs, gdFsCalcSctSize( bank_sz), bank_ptr);

>         gdFsClose( gdfs);

>         /*
>          * Transfer sound memory
>          */
>         sdMemBlkCreate( &memblk);
>         sdMemBlkSetPrm( memblk, bank_ptr, bank_sz, SDD_MEMBLK_SYNC_FUNC, NULL);
>         sdBankDownload( memblk, bank_type, bank_num);
>         sdMemBlkDestroy( memblk);
>     }

### 備考

> 通常ではメモリブロック転送をDMAモードにした場合、Bankのダウンロードは1度のDMAで行います。 しかしこれはMiddlewareライブラリやPCM Stream音源での音声の再生に影響がある(BankのダウンロードにDMAが占有される)ので、こういう場面はsdBankDownloadSetDivSz()関数を利用し、内部処理としてDMA転送のサイズを制限して分割ダウンロードを行うようにしてください。

> この関数でSDE_ERR_BANK_ILLEGAL_CHECK_SUMが返ってきた場合Bankファイル作成時に記録されたチェクサムと実際にダウンロードした内容のチェクサムが合わなかったことを表します。 この場合Bankファイルが壊れている可能性がありますので、サウンドクリエーターに確認してください。

> Bankのダウンロードを行う場合、その時点で各種音源(MIDI音源・One Shot音源・PCM Stream音源・GD-DA音源)で再生している音に関係あるBankを更新しないようにしてください。 例えばOne Shot Bank番号0番・One Shot Data番号0番を再生している時に、One Shot Bank番号0番を更新すると再生中の波形が破壊されることになり、ノイズが発生します。 この場合、それぞれの該当音源ポートの再生を停止する処置(sdMidiSeqStop()関数・sdShotStop()関数など)を取ってください。 また、Host Commandのバッファリング等の関係から、停止処理を行った後数V同期割り込み分待ったうえでダウンロードを行う方が安全です。

> この関数を使用する時にはFXはsdSndClearFxPrg()関数で使用しないようにしてください。

### 参照

> sdBankDownloadSetDivSz() | BankのDMA転送時の分割サイズの指定
> sdBankDownloadEx() | Bankの分割転送
> sdMltDownload() | Multi Unitの転送
> sdMltDownloadEx() | Multi Unitの分割転送
> sdSndClearFxPrg() | FX Programのクリア

sdBankDownload

COPYRIGHT © SEGA ENTERPRISES, LTD., 1998-2000