KITAQFC LIBRARY

ワールド座標の軸に平行な矩形同士が重なるか調べます。

書式

unsigned char nes_actor_collide(struct NesActor* a, struct NesActor* b);

引数

a

1つ目のアクター。

b

2つ目のアクター。

戻り値

重なれば1、離れているか辺が接するだけなら0。

使用条件と制限

幅と高さは1以上、座標＋サイズは65535以下にします。画面座標・attr・flagsは判定に使いません。

使用例

result[3]=nes_actor_collide(&a,&b);nes_actor_set_world(&b,315,95);result[4]=nes_actor_collide(&a,&b);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

ワールド(300,95)のアクターへカメラ(268,32)を適用し、画面(32,64)と(40,64)へ赤と青の8×8パーツを並べます。生のOAM Y=63が表示では64になること、辺が接するだけでは衝突せず1ピクセル重なると衝突することを確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_actor.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_actor.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

Test overlap in world coordinates with exclusive right/bottom edges. Keep
position-plus-size sums within u16; touching edges are not collisions.
Require positive widths and heights; zero extents are not rejected before the edge tests.

unsigned char nes_actor_collide(struct NesActor* a, struct NesActor* b)
{
    unsigned short a_right;
    unsigned short b_right;
    unsigned short a_bottom;
    unsigned short b_bottom;

    a_right = (unsigned short)(a->world_x + a->width);
    b_right = (unsigned short)(b->world_x + b->width);
    a_bottom = (unsigned short)(a->world_y + a->height);
    b_bottom = (unsigned short)(b->world_y + b->height);

    if (a_right <= b->world_x)
    {
        return 0;
    }
    if (b_right <= a->world_x)
    {
        return 0;
    }
    if (a_bottom <= b->world_y)
    {
        return 0;
    }
    if (b_bottom <= a->world_y)
    {
        return 0;
    }

    return 1;
}

保存済み画面座標を基点に、メタスプライトをシャドーOAMへ書きます。

書式

unsigned char nes_actor_draw_metasprite(struct NesActor* actor, unsigned char oam_index, unsigned char* metasprite);

引数

actor

書き込み可能なNesActorへのポインタ。

oam_index

開始スロット0～63。全パーツ分の空きを確保します。

metasprite

dx,dy,tile,attrの4バイト列。dx=255が終端です。

戻り値

次のOAMスロット番号。64スロット末尾を越えると周回します。

使用条件と制限

runtime.cをリンクします。キューはデータをコピーし、後のNMIまたは安全な描画停止中のflushで反映します。キューへの登録と消費を競合させないでください。複数行の途中で容量不足になった場合、それまでの行は残ります。

attr/flagsフィールドは適用しません。Yは生のOAM値なので表示上端は1ピクセル下です。実際の表示にはOAM DMAが別途必要です。

使用例

result[5]=nes_actor_draw_metasprite(&a,0,parts);result[6]=nes_oam_shadow[3];result[7]=nes_oam_shadow[7];nes_oam_dma(2);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

ワールド(300,95)のアクターへカメラ(268,32)を適用し、画面(32,64)と(40,64)へ赤と青の8×8パーツを並べます。生のOAM Y=63が表示では64になること、辺が接するだけでは衝突せず1ピクセル重なると衝突することを確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_actor.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_actor.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

Draw the byte-stream metasprite at cached screen coordinates and return its
next OAM index. Actor attr/flags are not applied by this wrapper.

unsigned char nes_actor_draw_metasprite(struct NesActor* actor, unsigned char oam_index, unsigned char* metasprite)
{
    return nes_metasprite_draw(oam_index, actor->screen_x, actor->screen_y, metasprite);
}

アクターのワールドX/Yを更新します。

書式

void nes_actor_set_world(struct NesActor* actor, unsigned short x, unsigned short y);

引数

actor

書き込み可能なNesActorへのポインタ。

x

ワールドX、0～65535ピクセル。

y

ワールドY、0～65535ピクセル。

戻り値

戻り値はありません。

使用条件と制限

screen_x/screen_yは更新しません。カメラを反映するにはupdate_screenを呼びます。

使用例

nes_actor_set_world(&a,300,95);nes_actor_set_world(&b,316,95);result[0]=a.world_x;

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

ワールド(300,95)のアクターへカメラ(268,32)を適用し、画面(32,64)と(40,64)へ赤と青の8×8パーツを並べます。生のOAM Y=63が表示では64になること、辺が接するだけでは衝突せず1ピクセル重なると衝突することを確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_actor.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_actor.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

Set the actor's 16-bit world position without updating cached screen coordinates.

void nes_actor_set_world(struct NesActor* actor, unsigned short x, unsigned short y)
{
    actor->world_x = x;
    actor->world_y = y;
}

ワールド座標からカメラ座標を引き、下位8ビットを画面座標へ保存します。

書式

void nes_actor_update_screen(struct NesActor* actor, unsigned short camera_x, unsigned short camera_y);

引数

actor

書き込み可能なNesActorへのポインタ。

camera_x

カメラのワールドX。

camera_y

カメラのワールドY。

戻り値

戻り値はありません。

使用条件と制限

負や256以上の結果は周回します。画面外のアクターを自動で隠さないので、描画前にゲーム側で判定します。

使用例

nes_actor_update_screen(&a,268,32);result[1]=a.screen_x;result[2]=a.screen_y;

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

ワールド(300,95)のアクターへカメラ(268,32)を適用し、画面(32,64)と(40,64)へ赤と青の8×8パーツを並べます。生のOAM Y=63が表示では64になること、辺が接するだけでは衝突せず1ピクセル重なると衝突することを確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_actor.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_actor.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

Subtract the camera and retain only the low coordinate bytes. This performs
wrapping projection, not clipping; callers must hide actors outside the viewport.

void nes_actor_update_screen(struct NesActor* actor, unsigned short camera_x, unsigned short camera_y)
{
    unsigned short dx;
    unsigned short dy;

    dx = (unsigned short)(actor->world_x - camera_x);
    dy = (unsigned short)(actor->world_y - camera_y);

    actor->screen_x = (unsigned char)dx;
    actor->screen_y = (unsigned char)dy;
}

登録済み一覧のROMバンクからAssetDescを1件読み出し、呼び出し側が用意した領域へコピーします。取得するのは素材の情報であり、素材本体ではありません。

書式

u8 asset_get(u8 asset_id, AssetDesc* out_desc);

引数

asset_id

0から始まる素材番号です。登録済み一覧の件数をcountとすると、asset_id < countの範囲が有効です。

out_desc

6バイトの記述子1件を書き込める領域です。ヌルポインタなら一覧を読む前に失敗を返します。

戻り値

記述子をコピーしたら1、出力先がヌルまたはIDが範囲外なら0です。これらの失敗時は出力先を書き換えません。

使用条件と制限

検索前に一覧を登録してください。登録情報は共有のグローバル状態なので、検索と同時に変更してはいけません。ライブラリはIDとasset_getの出力ポインタを確認しますが、登録した一覧や素材のアドレス、カートリッジ内容の正しさまでは検査しません。

サンプルの呼び出し側コードは固定バンク0に配置し、コピー元の切り替えで実行中のコードが見えなくなることを防ぎます。転送は同期処理です。転送中に割り込み側から別のバンク切り替えコピーを実行したり、この関数だけでアプリ全体の割り込み安全性が確保されると考えたりしないでください。

使用例

loaded=asset_get(0,&descriptor);
expect(loaded==1,1);
expect(descriptor.type==ASSET_TYPE_TILES && descriptor.bank==2,2);
expect(descriptor.ptr==asset_shapes && descriptor.len==144,3);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

記述子0を読み、TILES種別・バンク2・素材ポインタ・144バイトの長さを確認します。範囲外IDとヌル出力先は失敗し、検索失敗時には出力先の元の値が残ることも確認します。

期待画像では、赤い横一列がピクセル座標(16,32)から始まり、72×8ピクセルを占めます。8×8の三角形、1ピクセル枠の8×8の正方形、左4列を塗ったタイルの順に、3回繰り返します。三角形は左上の1ピクセルから最下段の8ピクセルまで広がります。

FC版では、(16,64)の青い三角形と枠が__far_memcpyの結果、(16,96)の緑の組がasset_load_rawの後にCHRへ転送した結果です。黒地の各組は16×8ピクセルです。数値だけでなく、コピーした絵柄のバイト列が正しいことを目で確認できます。

期待する表示はFAILED CHECKS 000とFIRST FAILURE 00です。検証では300フレーム実行し、文字、図形の形、色を期待値と比較します。これはエミュレータ上の検証であり、実機試験ではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Copy a descriptor from its ROM bank into caller storage. Null output or an
out-of-range ID returns zero without reading the table.

u8 asset_get(u8 asset_id, AssetDesc* out_desc)
{
    if (out_desc == 0) return 0;
    if (asset_id >= asset_table_count) return 0;
    __far_memcpy((u8*)out_desc, asset_table_bank, (u16)(asset_table + asset_id), sizeof(AssetDesc));
    return 1;
}

記述子から素材本体のバンク番号を読み出します。一覧を置いたバンクの番号ではありません。取得後に素材本体のバンクが選ばれた状態になるわけでもありません。

書式

u8 asset_get_bank(u8 asset_id);

引数

asset_id

0から始まる素材番号です。登録済み一覧の件数をcountとすると、asset_id < countの範囲が有効です。

戻り値

記述子の8ビットのbankを返し、検索失敗なら0です。有効なバンク番号も0になり得るため、成否を区別する場合はasset_get()を使います。

使用条件と制限

検索前に一覧を登録してください。登録情報は共有のグローバル状態なので、検索と同時に変更してはいけません。ライブラリはIDとasset_getの出力ポインタを確認しますが、登録した一覧や素材のアドレス、カートリッジ内容の正しさまでは検査しません。

各取得関数はその都度asset_getを呼び、記述子をコピーします。バンク・ポインタ・長さをまとめて使うなら、asset_getを1回呼んで各フィールドを参照します。

サンプルの呼び出し側コードは固定バンク0に配置し、コピー元の切り替えで実行中のコードが見えなくなることを防ぎます。転送は同期処理です。転送中に割り込み側から別のバンク切り替えコピーを実行したり、この関数だけでアプリ全体の割り込み安全性が確保されると考えたりしないでください。

使用例

payload_bank=asset_get_bank(0);
expect(payload_bank==2,17); // Payload bank, not descriptor-table bank 3.
expect(asset_get_bank(4)==0,18); // Failure sentinel; a valid descriptor may also use bank 0.

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

一覧がバンク3にある場合でも、素材本体のバンク2が返ることを確認します。無効IDでは0を返すことも検査します。

期待画像では、赤い横一列がピクセル座標(16,32)から始まり、72×8ピクセルを占めます。8×8の三角形、1ピクセル枠の8×8の正方形、左4列を塗ったタイルの順に、3回繰り返します。三角形は左上の1ピクセルから最下段の8ピクセルまで広がります。

FC版では、(16,64)の青い三角形と枠が__far_memcpyの結果、(16,96)の緑の組がasset_load_rawの後にCHRへ転送した結果です。黒地の各組は16×8ピクセルです。数値だけでなく、コピーした絵柄のバイト列が正しいことを目で確認できます。

期待する表示はFAILED CHECKS 000とFIRST FAILURE 00です。検証では300フレーム実行し、文字、図形の形、色を期待値と比較します。これはエミュレータ上の検証であり、実機試験ではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Return the asset bank or zero on lookup failure; bank zero may also be valid.

u8 asset_get_bank(u8 asset_id)
{
    AssetDesc desc;
    if (asset_get(asset_id, &desc) == 0) return 0;
    return desc.bank;
}

記述子から素材の長さをバイト単位で取得します。返すのは登録情報であり、素材本体を調べたり、タイル数・要素数・フレーム数へ換算したりはしません。

書式

u16 asset_get_len(u8 asset_id);

引数

asset_id

0から始まる素材番号です。登録済み一覧の件数をcountとすると、asset_id < countの範囲が有効です。

戻り値

バイト単位の16ビット値lenを返し、検索失敗なら0です。空の素材も0なので、区別が必要ならasset_get()を使います。

使用条件と制限

検索前に一覧を登録してください。登録情報は共有のグローバル状態なので、検索と同時に変更してはいけません。ライブラリはIDとasset_getの出力ポインタを確認しますが、登録した一覧や素材のアドレス、カートリッジ内容の正しさまでは検査しません。

各取得関数はその都度asset_getを呼び、記述子をコピーします。バンク・ポインタ・長さをまとめて使うなら、asset_getを1回呼んで各フィールドを参照します。

サンプルの呼び出し側コードは固定バンク0に配置し、コピー元の切り替えで実行中のコードが見えなくなることを防ぎます。転送は同期処理です。転送中に割り込み側から別のバンク切り替えコピーを実行したり、この関数だけでアプリ全体の割り込み安全性が確保されると考えたりしないでください。

使用例

expect(asset_get_len(0)==144,21); // Bytes, not tiles.
expect(asset_get_len(3)==0 && asset_get_len(4)==0,22); // Empty asset and invalid ID both yield zero.

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

9タイルの素材について、9ではなくバイト数の144を返すことを確認します。空の素材と無効IDはいずれも0です。

期待画像では、赤い横一列がピクセル座標(16,32)から始まり、72×8ピクセルを占めます。8×8の三角形、1ピクセル枠の8×8の正方形、左4列を塗ったタイルの順に、3回繰り返します。三角形は左上の1ピクセルから最下段の8ピクセルまで広がります。

FC版では、(16,64)の青い三角形と枠が__far_memcpyの結果、(16,96)の緑の組がasset_load_rawの後にCHRへ転送した結果です。黒地の各組は16×8ピクセルです。数値だけでなく、コピーした絵柄のバイト列が正しいことを目で確認できます。

期待する表示はFAILED CHECKS 000とFIRST FAILURE 00です。検証では300フレーム実行し、文字、図形の形、色を期待値と比較します。これはエミュレータ上の検証であり、実機試験ではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Return the descriptor byte length, or zero for an invalid ID.

u16 asset_get_len(u8 asset_id)
{
    AssetDesc desc;
    if (asset_get(asset_id, &desc) == 0) return 0;
    return desc.len;
}

記述子に保存された16ビットの素材アドレスを取得します。戻るのはバンク番号を含まない近ポインタです。別のROMバンクの素材を読むには、asset_get_bank()で得た番号と組み合わせてバンク間コピー関数を使います。

書式

const u8* asset_get_ptr(u8 asset_id);

引数

asset_id

0から始まる素材番号です。登録済み一覧の件数をcountとすると、asset_id < countの範囲が有効です。

戻り値

保存されたconst u8*を返し、検索失敗ならヌルです。記述子の素材ポインタがヌルかどうかは検査しないため、検索の成否はasset_get()で区別します。

使用条件と制限

検索前に一覧を登録してください。登録情報は共有のグローバル状態なので、検索と同時に変更してはいけません。ライブラリはIDとasset_getの出力ポインタを確認しますが、登録した一覧や素材のアドレス、カートリッジ内容の正しさまでは検査しません。

各取得関数はその都度asset_getを呼び、記述子をコピーします。バンク・ポインタ・長さをまとめて使うなら、asset_getを1回呼んで各フィールドを参照します。

サンプルの呼び出し側コードは固定バンク0に配置し、コピー元の切り替えで実行中のコードが見えなくなることを防ぎます。転送は同期処理です。転送中に割り込み側から別のバンク切り替えコピーを実行したり、この関数だけでアプリ全体の割り込み安全性が確保されると考えたりしないでください。

使用例

payload_pointer=asset_get_ptr(0);
expect(payload_pointer==asset_shapes,19);
expect(*asset_bank_marker==0xA1,20); // Getting the pointer leaves bank 1 selected.
// Use payload_bank together with payload_pointer for a far copy; do not dereference it here.

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

取得したポインタがROM配置後の素材アドレスと一致し、バンク1の確認用データも引き続き読めることを確認します。その後、そのポインタと素材のバンク2をバンク間コピー関数へ渡します。

期待画像では、赤い横一列がピクセル座標(16,32)から始まり、72×8ピクセルを占めます。8×8の三角形、1ピクセル枠の8×8の正方形、左4列を塗ったタイルの順に、3回繰り返します。三角形は左上の1ピクセルから最下段の8ピクセルまで広がります。

FC版では、(16,64)の青い三角形と枠が__far_memcpyの結果、(16,96)の緑の組がasset_load_rawの後にCHRへ転送した結果です。黒地の各組は16×8ピクセルです。数値だけでなく、コピーした絵柄のバイト列が正しいことを目で確認できます。

期待する表示はFAILED CHECKS 000とFIRST FAILURE 00です。検証では300フレーム実行し、文字、図形の形、色を期待値と比較します。これはエミュレータ上の検証であり、実機試験ではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Return the stored address without switching banks. Pair it with the descriptor
bank before reading banked ROM; a failed lookup returns null.

const u8* asset_get_ptr(u8 asset_id)
{
    AssetDesc desc;
    if (asset_get(asset_id, &desc) == 0) return 0;
    return desc.ptr;
}

素材を検索し、そのROMバンクから書き込み先へmin(desc.len, max_len)バイトをコピーします。種別は判定せず、タイル・マップ・曲などもそのままバイト列として扱います。形式の解析や圧縮データの展開は行いません。

書式

u8 asset_load_raw(u8 asset_id, void* dst, u16 max_len);

引数

asset_id

0から始まる素材番号です。登録済み一覧の件数をcountとすると、asset_id < countの範囲が有効です。

dst

書き込み先のメモリです。実際のコピー量を収められる領域を確保してください。0バイト転送以外では、ヌルポインタや無効な書き込み先を検出する処理はありません。

max_len

コピーする最大バイト数を0～65535で指定します。素材より小さければ途中までコピーします。0では素材本体をコピーしません。

戻り値

検索失敗なら0、それ以外は1です。途中までのコピー、上限0、空の素材でも1になります。戻り値はコピーしたバイト数ではなく、素材全体が収まった保証にもなりません。

使用条件と制限

検索前に一覧を登録してください。登録情報は共有のグローバル状態なので、検索と同時に変更してはいけません。ライブラリはIDとasset_getの出力ポインタを確認しますが、登録した一覧や素材のアドレス、カートリッジ内容の正しさまでは検査しません。

コピー元全体が目的のROM配置で読め、コピー先全体が書き込み可能な範囲になるようにしてください。バンク窓の端で次のバンクへ進む処理、memmoveのような重なりへの対応、VRAMの安全な書き込み制御はありません。VRAMには描画用の転送APIを使います。

サンプルの呼び出し側コードは固定バンク0に配置し、コピー元の切り替えで実行中のコードが見えなくなることを防ぎます。転送は同期処理です。転送中に割り込み側から別のバンク切り替えコピーを実行したり、この関数だけでアプリ全体の割り込み安全性が確保されると考えたりしないでください。

使用例

loaded=asset_load_raw(0,buffer,7); // Success with truncation: copy seven of 144 bytes.
expect(loaded==1 && buffer[7]==0x55,7);
for(i=0;i<7;i++) expect(buffer[(__safe_index u8)i]==expected_shape_byte(i),8);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

144バイトの素材に上限7を指定し、先頭7バイトだけをコピーして次のバイトの0x55を残しながら、成功を返すことを確認します。全体コピー、上限0、空の素材、MAP種別のバイト列コピーも検査します。

期待画像では、赤い横一列がピクセル座標(16,32)から始まり、72×8ピクセルを占めます。8×8の三角形、1ピクセル枠の8×8の正方形、左4列を塗ったタイルの順に、3回繰り返します。三角形は左上の1ピクセルから最下段の8ピクセルまで広がります。

FC版では、(16,64)の青い三角形と枠が__far_memcpyの結果、(16,96)の緑の組がasset_load_rawの後にCHRへ転送した結果です。黒地の各組は16×8ピクセルです。数値だけでなく、コピーした絵柄のバイト列が正しいことを目で確認できます。

期待する表示はFAILED CHECKS 000とFIRST FAILURE 00です。検証では300フレーム実行し、文字、図形の形、色を期待値と比較します。これはエミュレータ上の検証であり、実機試験ではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Copy the smaller of the asset length and max_len using a bank-aware transfer.
Return one for a valid ID even when the payload is truncated.

u8 asset_load_raw(u8 asset_id, void* dst, u16 max_len)
{
    AssetDesc desc;
    u16 len;
    if (asset_get(asset_id, &desc) == 0) return 0;
    len = desc.len;
    if (len > max_len) len = max_len;
    __far_memcpy((u8*)dst, desc.bank, (u16)desc.ptr, len);
    return 1;
}

RAWまたはTILES種別の素材を検索し、そのROMバンクへ切り替え、__vram_writeで最大128バイトずつ全データを転送します。最後にbank_get_current()で保存したバンクへ戻します。分割転送の途中で次のフレームを待つ処理はありません。

書式

u8 asset_load_tiles(u8 asset_id, u16 vram_dst);

引数

asset_id

0から始まる素材番号です。登録済み一覧の件数をcountとすると、asset_id < countの範囲が有効です。

vram_dst

CPUアドレスやタイル番号ではなく、PPUのバイトアドレスです。タイル絵柄の転送には$0000～$1FFFの書き込み可能なCHR RAMを使い、1タイルは16バイトです。全転送が目的のPPU領域内に収まるようにしてください。

戻り値

IDが無効、または種別がRAW/TILES以外なら0です。受け付けた転送を終えると1で、長さ0の素材も含みます。成功値はタイル形式やVRAM表示の正しさを検証した結果ではありません。

使用条件と制限

検索前に一覧を登録してください。登録情報は共有のグローバル状態なので、検索と同時に変更してはいけません。ライブラリはIDとasset_getの出力ポインタを確認しますが、登録した一覧や素材のアドレス、カートリッジ内容の正しさまでは検査しません。

サンプルの呼び出し側コードは固定バンク0に配置し、コピー元の切り替えで実行中のコードが見えなくなることを防ぎます。転送は同期処理です。転送中に割り込み側から別のバンク切り替えコピーを実行したり、この関数だけでアプリ全体の割り込み安全性が確保されると考えたりしないでください。

転送はバイトを書き込むだけで、マップへのタイル配置、配色、VRAMの割り当ては行いません。タイルマップとパレットは別途設定します。サンプルでは描画を止めて転送し、画像の準備ができてから表示を有効にします。

asset_load_tilesの復帰先は、マッパーから読み取った値ではなくbank.cが記録した値です。bank_switchで初期化・更新してください。マッパーへの直接書き込みや__bankswitchだけの呼び出しでは、ライブラリ側の記録は更新されません。バンク間コピーの組み込み関数は、これとは別にコンパイラ側のバンク状態を復帰します。

絵柄データには書き込み可能なCHR RAMを使い、大きな転送では描画を停止します。VBlank中に転送するなら処理全体がその時間内に収まる必要があり、128バイト分割だけでは時間制限を守れません。このサンプルは--mapper=mmc1 --board=surom512でビルドします。汎用ボードで--nes-chrを省略しても、作られるのは空のCHR ROMで、CHR RAMにはなりません。

使用例

loaded=asset_load_tiles(0,0x0010); // 144 bytes: library uploads chunks of 128 and 16 bytes.
expect(loaded==1 && bank_get_current()==1 && *asset_bank_marker==0xA1,24);
// LCD and NMI are off; CHR RAM is writable. The library selects payload bank 2 and restores bank 1.

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

タイル転送例は独自の8×8ピクセルの絵柄9枚、合計144バイトを使います。MAP種別と無効IDが拒否されることも確認します。FC版では144バイトを転送することで、128バイトの塊と残り16バイトの両方を検証します。

期待画像では、赤い横一列がピクセル座標(16,32)から始まり、72×8ピクセルを占めます。8×8の三角形、1ピクセル枠の8×8の正方形、左4列を塗ったタイルの順に、3回繰り返します。三角形は左上の1ピクセルから最下段の8ピクセルまで広がります。

FC版では、(16,64)の青い三角形と枠が__far_memcpyの結果、(16,96)の緑の組がasset_load_rawの後にCHRへ転送した結果です。黒地の各組は16×8ピクセルです。数値だけでなく、コピーした絵柄のバイト列が正しいことを目で確認できます。

期待する表示はFAILED CHECKS 000とFIRST FAILURE 00です。検証では300フレーム実行し、文字、図形の形、色を期待値と比較します。これはエミュレータ上の検証であり、実機試験ではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Switch to the asset bank, upload tile/raw data in chunks of at most 128 bytes,
then restore the bank recorded by this library. The caller supplies safe PPU timing.

u8 asset_load_tiles(u8 asset_id, u16 vram_dst)
{
    AssetDesc desc;
    const u8* src;
    u16 len;
    u8 chunk;
    u8 old_bank;

    if (asset_get(asset_id, &desc) == 0) return 0;
    if (desc.type != ASSET_TYPE_TILES && desc.type != ASSET_TYPE_RAW) return 0;

    // Restoration uses the library shadow, not a mapper readback; initialize and maintain that shadow.
    old_bank = bank_get_current();
    bank_switch(desc.bank);

    src = desc.ptr;
    len = desc.len;
    // This loop uploads the entire asset synchronously. Chunking does not wait for another frame.
    // Use writable CHR RAM for tile data and keep the source bank visible throughout the transfer.
    while (len != 0) {
        if (len > 128) chunk = 128;
        else chunk = (u8)len;
        __vram_write(vram_dst, src, chunk);
        vram_dst = (u16)(vram_dst + chunk);
        src = src + chunk;
        len = (u16)(len - chunk);
    }

    bank_switch(old_bank);
    return 1;
}

使用する素材一覧のバンク番号・アドレス・件数を登録します。有効な一覧は一つです。この関数は三つの値を保持するだけで、一覧のコピー、素材の読み込み、メモリ確保は行いません。

書式

void asset_set_table(u8 bank, const AssetDesc* table, u8 count);

引数

bank

素材本体ではなく、一覧を格納するROMバンクの番号です。8ビット値で指定します。

table

AssetDescをcount件連続して並べた領域への近ポインタです。登録中は、一覧のバンクでcount * 6バイトを読み出せる状態に保ってください。

count

件数を0～255で指定します。0ならすべてのIDが無効です。asset_set_table(0, 0, 0)で空の一覧を登録できます。

戻り値

ありません（void）。

使用条件と制限

検索前に一覧を登録してください。登録情報は共有のグローバル状態なので、検索と同時に変更してはいけません。ライブラリはIDとasset_getの出力ポインタを確認しますが、登録した一覧や素材のアドレス、カートリッジ内容の正しさまでは検査しません。

使用例

asset_set_table(3,asset_descriptors,4); // Four descriptors in bank 3, payloads in bank 2.

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

この例はバンク3の記述子4件を登録し、空でない素材本体をバンク2から取得します。空の一覧も登録して、アドレス0を読まずに検索が失敗することを確認します。

期待画像では、赤い横一列がピクセル座標(16,32)から始まり、72×8ピクセルを占めます。8×8の三角形、1ピクセル枠の8×8の正方形、左4列を塗ったタイルの順に、3回繰り返します。三角形は左上の1ピクセルから最下段の8ピクセルまで広がります。

FC版では、(16,64)の青い三角形と枠が__far_memcpyの結果、(16,96)の緑の組がasset_load_rawの後にCHRへ転送した結果です。黒地の各組は16×8ピクセルです。数値だけでなく、コピーした絵柄のバイト列が正しいことを目で確認できます。

期待する表示はFAILED CHECKS 000とFIRST FAILURE 00です。検証では300フレーム実行し、文字、図形の形、色を期待値と比較します。これはエミュレータ上の検証であり、実機試験ではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\asset_banks.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\asset_banks.nes --mapper=mmc1 --board=surom512 --no-cache --no-disasm

Retain a bank-qualified descriptor table; the caller keeps its storage valid.

void asset_set_table(u8 bank, const AssetDesc* table, u8 count)
{
    asset_table_bank = bank;
    asset_table = table;
    asset_table_count = count;
}

タイル矩形が触れる属性バイトを行単位でキューへコピーします。

書式

unsigned char nes_attr_queue_rect(unsigned short nt_base, unsigned char tile_x, unsigned char tile_y, unsigned char width, unsigned char height);

引数

nt_base

論理ネームテーブル先頭$2000/$2400/$2800/$2C00。物理的な独立性はミラーリング設定によります。

tile_x

左端のタイル列。可視範囲は0～31。

tile_y

上端のタイル行。可視範囲は0～29。

width

幅（タイル数）。

height

高さ（タイル数）。

戻り値

全行登録または空矩形なら1、範囲外または容量不足なら0。範囲外では登録を始めません。

使用条件と制限

共有属性シャドー64バイトはCPU RAM $03E0～$041Fです。ほかのデータと重ねないでください。属性1バイトは4×4タイル、各2ビットは2×2タイルのパレットを表します。

runtime.cをリンクします。キューはデータをコピーし、後のNMIまたは安全な描画停止中のflushで反映します。キューへの登録と消費を競合させないでください。複数行の途中で容量不足になった場合、それまでの行は残ります。

1属性バイトは4×4タイルです。関数は矩形に触れるバイト全体を転送するため、隣接区画の値もシャドーへ正しく保持しておきます。

使用例

result[5]=nes_attr_queue_rect(0x2000,2,4,4,4);result[6]=nes_vram_queue_used;result[7]=nes_attr_queue_rect(0x2000,10,4,4,4);result[8]=nes_attr_queue_rect(0x2000,30,28,2,2);nes_vram_queue_nmi_flush();

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

属性の矩形転送を学びます。(16,32)に赤の32×32、(80,32)に青の32×32、画面右下(240,224)に緑の16×16を表示します。隣の区画を壊さず、右下の属性バイトまで正しく転送する例です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_attributes.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_attributes.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

Queue the attribute bytes covering a tile rectangle within 32x30 tiles.
Empty rectangles succeed; invalid bounds fail without queuing.
Capacity failure may leave earlier rows queued.

unsigned char nes_attr_queue_rect(unsigned short nt_base, unsigned char tile_x, unsigned char tile_y, unsigned char width, unsigned char height)
{
    unsigned char qx0;
    unsigned char qy0;
    unsigned char qx1;
    unsigned char qy1;
    unsigned char row;
    unsigned char col;
    // The runtime queue copies these local bytes before return; they are not retained pointers.
    // Caller coordinates must keep each computed row length within eight bytes.
    unsigned char line[8];
    unsigned short ppu_addr;
    unsigned char len;

    if (width == 0 || height == 0) return 1;
    if (tile_x >= 32 || tile_y >= 30) return 0;
    if (width > (unsigned char)(32 - tile_x) || height > (unsigned char)(30 - tile_y)) return 0;

    qx0 = (unsigned char)(tile_x >> 2);
    qy0 = (unsigned char)(tile_y >> 2);
    qx1 = (unsigned char)((tile_x + width - 1) >> 2);
    qy1 = (unsigned char)((tile_y + height - 1) >> 2);

    row = qy0;
    while (1)
    {
        len = (unsigned char)(qx1 - qx0 + 1);
        col = 0;
        while (col != len)
        {
            line[col] = nes_attr_shadow[(unsigned char)(row * 8 + qx0 + col)];
            col = (unsigned char)(col + 1);
        }
        ppu_addr = (unsigned short)(nes_attr_base_from_nt(nt_base) + (unsigned short)(row * 8 + qx0));
        if (nes_vram_queue_try_write(ppu_addr, line, len) == 0)
        {
            return 0;
        }
        if (row == qy1)
        {
            break;
        }
        row = (unsigned char)(row + 1);
    }
    return 1;
}

完成済みの属性64バイトを共有シャドーへコピーします。

書式

void nes_attr_shadow_build_from_palette_map(unsigned char* src64);

引数

src64

読み取り可能な64バイトのpacked属性表。1タイルごとのパレット番号配列ではありません。

戻り値

戻り値はありません。

使用条件と制限

共有属性シャドー64バイトはCPU RAM $03E0～$041Fです。ほかのデータと重ねないでください。属性1バイトは4×4タイル、各2ビットは2×2タイルのパレットを表します。

使用例

for(i=0;i<64;i++)table[i]=0;table[0]=0xE4;nes_attr_shadow_build_from_palette_map(table);result[0]=nes_attr_shadow[0];

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

属性の矩形転送を学びます。(16,32)に赤の32×32、(80,32)に青の32×32、画面右下(240,224)に緑の16×16を表示します。隣の区画を壊さず、右下の属性バイトまで正しく転送する例です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_attributes.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_attributes.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

KITAQFC phase15 attribute patch helpers.


Copy 64 already-packed attribute bytes into shadow storage. This does not
convert one palette ID per tile into NES attribute bitfields.
The source must expose all 64 packed bytes and stay readable for the duration of this copy.

void nes_attr_shadow_build_from_palette_map(unsigned char* src64)
{
    unsigned char i;
    i = 0;
    while (i != 64)
    {
        nes_attr_shadow[i] = (unsigned char)(src64[i] & 0xFF);
        i = (unsigned char)(i + 1);
    }
}

矩形が触れる2×2タイル区画すべてのパレット番号を変更します。

書式

void nes_attr_shadow_fill_rect(unsigned char tile_x, unsigned char tile_y, unsigned char width, unsigned char height, unsigned char pal_index);

引数

tile_x

左端のタイル列。可視範囲は0～31。

tile_y

上端のタイル行。可視範囲は0～29。

width

幅（タイル数）。

height

高さ（タイル数）。

pal_index

パレット番号。下位2ビットを使います。

戻り値

戻り値はありません。

使用条件と制限

共有属性シャドー64バイトはCPU RAM $03E0～$041Fです。ほかのデータと重ねないでください。属性1バイトは4×4タイル、各2ビットは2×2タイルのパレットを表します。

矩形全体を32×30タイル内に収めます。空または範囲外の矩形では何も変更しません。奇数の境界は区画へ広がるので、矩形の外側の隣接タイルも同じパレットになります。

使用例

nes_attr_shadow_fill_rect(2,4,4,4,1);nes_attr_shadow_fill_rect(10,4,4,4,2);nes_attr_shadow_fill_rect(30,28,2,2,3);result[1]=nes_attr_shadow[8];result[2]=nes_attr_shadow[9];result[3]=nes_attr_shadow[15];result[4]=nes_attr_shadow[63];

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

属性の矩形転送を学びます。(16,32)に赤の32×32、(80,32)に青の32×32、画面右下(240,224)に緑の16×16を表示します。隣の区画を壊さず、右下の属性バイトまで正しく転送する例です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\runtime.c .\kitaq-docs\samples\api-examples\fc\batch3_attributes.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch3_attributes.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\vram_shapes.chr

Apply a palette to every two-by-two tile quadrant touched by the rectangle.
Empty or out-of-range rectangles leave the shadow unchanged.

void nes_attr_shadow_fill_rect(unsigned char tile_x, unsigned char tile_y, unsigned char width, unsigned char height, unsigned char pal_index)
{
    unsigned char qx0;
    unsigned char qy0;
    unsigned char qx1;
    unsigned char qy1;
    unsigned char qx;
    unsigned char qy;

    if (width == 0 || height == 0) return;
    if (tile_x >= 32 || tile_y >= 30) return;
    if (width > (unsigned char)(32 - tile_x) || height > (unsigned char)(30 - tile_y)) return;

    qx0 = nes_attr_rect_left(tile_x);
    qy0 = nes_attr_rect_top(tile_y);
    qx1 = nes_attr_rect_left((unsigned char)(tile_x + width - 1));
    qy1 = nes_attr_rect_top((unsigned char)(tile_y + height - 1));

    qy = qy0;
    while (1)
    {
        qx = qx0;
        while (1)
        {
            nes_attr_shadow_set_quad((unsigned char)(qx << 1), (unsigned char)(qy << 1), pal_index);
            if (qx == qx1)
            {
                break;
            }
            qx = (unsigned char)(qx + 1);
        }
        if (qy == qy1)
        {
            break;
        }
        qy = (unsigned char)(qy + 1);
    }
}

APUの5チャンネルの有効化状態を、指定マスクで丸ごと置き換えます。

書式

void nes_apu_channel_enable(u8 mask);

引数

mask

APU_STATUSへ書く完全な有効化マスク。bit0～4はpulse1、pulse2、triangle、noise、DMCで、上位3ビットは捨てます。

戻り値

戻り値はありません。音源レジスターまたはドライバーの状態を変更します。

使用例

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

期待する結果

pulse1、pulse2、三角波、ノイズ、tick、moveの順です。タイマー253はNTSCでパルス約440Hz、三角波約220Hzになります。tickは約111Hz、moveは約174Hzで、moveの方が短く終わります。最後は無音です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Replace all five channel-enable bits in APU_STATUS; this is not an additive enable.

void nes_apu_channel_enable(u8 mask)
{
    APU_STATUS = (u8)(mask & 0x1F);
}

フレームIRQを無効にして4音源を有効化し、無音の制御値を設定します。DMCは無効です。

書式

void nes_apu_init(void);

戻り値

戻り値はありません。音源レジスターまたはドライバーの状態を変更します。

使用例

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

期待する結果

pulse1、pulse2、三角波、ノイズ、tick、moveの順です。タイマー253はNTSCでパルス約440Hz、三角波約220Hzになります。tickは約111Hz、moveは約174Hzで、moveの方が短く終わります。最後は無音です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Disable frame IRQs, enable the four tonal/noise channels and install quiet
control defaults. DMC remains disabled.

void nes_apu_init(void)
{
    APU_FRAME = 0x40;
    APU_STATUS = 0x0F;
    SQ1_VOL = 0x10;
    SQ1_SWEEP = 0x08;
    SQ2_VOL = 0x10;
    SQ2_SWEEP = 0x08;
    TRI_LINEAR = 0x80;
    NOISE_VOL = 0x10;
    DMC_FREQ = 0x00;
    DMC_RAW = 0x00;
}

全チャンネルを無効化し、パルス・ノイズの音量とDMC出力を消します。

書式

void nes_apu_silence_all(void);

戻り値

戻り値はありません。音源レジスターまたはドライバーの状態を変更します。

使用例

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

期待する結果

pulse1、pulse2、三角波、ノイズ、tick、moveの順です。タイマー253はNTSCでパルス約440Hz、三角波約220Hzになります。tickは約111Hz、moveは約174Hzで、moveの方が短く終わります。最後は無音です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Disable every channel and clear volume/DMC output settings used by this helper.

void nes_apu_silence_all(void)
{
    APU_STATUS = 0x00;
    SQ1_VOL = 0x10;
    SQ2_VOL = 0x10;
    TRI_LINEAR = 0x80;
    NOISE_VOL = 0x10;
    DMC_FREQ = 0x00;
    DMC_RAW = 0x00;
}

DMCの制御・出力初期値・開始アドレス・長さをレジスター単位へ変換して設定します。

書式

void nes_dmc_config(u8 flags_rate, u8 output_level, u16 sample_addr, u16 sample_len);

引数

flags_rate

DMCのbit7=IRQ、bit6=ループ、bit3～0=レート番号。サンプルではIRQを使いません。

output_level

DMC出力カウンターの初期値0～127。下位7ビットだけを書き込みます。

sample_addr

DMCデータ先頭のCPUアドレス。$C000～$FFC0の64バイト境界です。

sample_len

16×n+1のバイト数、1～4081。0や未対応の長さは渡さないでください。

戻り値

戻り値はありません。音源レジスターまたはドライバーの状態を変更します。

使用条件と制限

DMCは$C000～$FFC0の64バイト境界からROMを読みます。長さは16×n+1バイト（1～4081）です。ヘルパーは境界・範囲を検査せず、バンクも切り替えません。サンプルは固定バンク0に独自データを__aligned(64)で置き、配置を実行時にも検査します。

使用例

// A 17-byte original delta pattern, aligned to a 64-byte DMC start boundary.
#include "fc_sound_example.h"
#pragma bank 0
__aligned(64) __prg_rom u8 delta[17]={0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xAA};
void main(void) {
    sound_begin("DMC ORIGINAL DELTAS");
    sound_result[0]=(u8)(((u16)delta&63)==0);
    sound_result[1]=(u8)((u16)delta>=0xC000);
    // Loop at NTSC rate index 10; start the output accumulator at its midpoint.
    nes_dmc_config(0x4A,64,(u16)delta,17);
    nes_dmc_start();
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    nes_dmc_play(0x4C,64,(u16)delta,17);
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    sound_end();
}

期待する結果

独自のデルタ列をレート10、無音区間、より速いレート12の順で再生します。途中のDMC停止後は出力カウンターが保持されるため、録音では過渡成分が残る場合があります。最後はAPU全停止です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_dmc.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-dmc.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Convert a CPU sample address and byte length to DMC register units. Supply
an address in 0xC000-0xFFC0 aligned to 64 bytes and a representable length
16*n+1 in 1..4081; inputs are narrowed without validation or bank management.

void nes_dmc_config(u8 flags_rate, u8 output_level, u16 sample_addr, u16 sample_len)
{
    DMC_FREQ = flags_rate;
    DMC_RAW = (u8)(output_level & 0x7F);
    // Keep the sample bytes mapped at these CPU addresses during playback; this does not select a ROM bank.
    DMC_START = (u8)((sample_addr - 0xC000) >> 6);
    DMC_LEN = (u8)((sample_len - 1) >> 4);
}

サンプルのDMC設定を行い、直後にDMCを開始します。

書式

void nes_dmc_play(u8 flags_rate, u8 output_level, u16 sample_addr, u16 sample_len);

引数

flags_rate

DMCのbit7=IRQ、bit6=ループ、bit3～0=レート番号。サンプルではIRQを使いません。

output_level

DMC出力カウンターの初期値0～127。下位7ビットだけを書き込みます。

sample_addr

DMCデータ先頭のCPUアドレス。$C000～$FFC0の64バイト境界です。

sample_len

16×n+1のバイト数、1～4081。0や未対応の長さは渡さないでください。

戻り値

戻り値はありません。音源レジスターまたはドライバーの状態を変更します。

使用条件と制限

DMCは$C000～$FFC0の64バイト境界からROMを読みます。長さは16×n+1バイト（1～4081）です。ヘルパーは境界・範囲を検査せず、バンクも切り替えません。サンプルは固定バンク0に独自データを__aligned(64)で置き、配置を実行時にも検査します。

使用例

// A 17-byte original delta pattern, aligned to a 64-byte DMC start boundary.
#include "fc_sound_example.h"
#pragma bank 0
__aligned(64) __prg_rom u8 delta[17]={0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xAA};
void main(void) {
    sound_begin("DMC ORIGINAL DELTAS");
    sound_result[0]=(u8)(((u16)delta&63)==0);
    sound_result[1]=(u8)((u16)delta>=0xC000);
    // Loop at NTSC rate index 10; start the output accumulator at its midpoint.
    nes_dmc_config(0x4A,64,(u16)delta,17);
    nes_dmc_start();
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    nes_dmc_play(0x4C,64,(u16)delta,17);
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    sound_end();
}

期待する結果

独自のデルタ列をレート10、無音区間、より速いレート12の順で再生します。途中のDMC停止後は出力カウンターが保持されるため、録音では過渡成分が残る場合があります。最後はAPU全停止です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_dmc.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-dmc.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Install sample parameters, then start DMC using the full-channel enable mask.

void nes_dmc_play(u8 flags_rate, u8 output_level, u16 sample_addr, u16 sample_len)
{
    nes_dmc_config(flags_rate, output_level, sample_addr, sample_len);
    nes_dmc_start();
}

APU_STATUS=0x1FとしてDMCとほかの4音源を有効化します。

書式

void nes_dmc_start(void);

戻り値

戻り値はありません。音源レジスターまたはドライバーの状態を変更します。

使用条件と制限

DMCは$C000～$FFC0の64バイト境界からROMを読みます。長さは16×n+1バイト（1～4081）です。ヘルパーは境界・範囲を検査せず、バンクも切り替えません。サンプルは固定バンク0に独自データを__aligned(64)で置き、配置を実行時にも検査します。

使用例

// A 17-byte original delta pattern, aligned to a 64-byte DMC start boundary.
#include "fc_sound_example.h"
#pragma bank 0
__aligned(64) __prg_rom u8 delta[17]={0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xAA};
void main(void) {
    sound_begin("DMC ORIGINAL DELTAS");
    sound_result[0]=(u8)(((u16)delta&63)==0);
    sound_result[1]=(u8)((u16)delta>=0xC000);
    // Loop at NTSC rate index 10; start the output accumulator at its midpoint.
    nes_dmc_config(0x4A,64,(u16)delta,17);
    nes_dmc_start();
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    nes_dmc_play(0x4C,64,(u16)delta,17);
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    sound_end();
}

期待する結果

独自のデルタ列をレート10、無音区間、より速いレート12の順で再生します。途中のDMC停止後は出力カウンターが保持されるため、録音では過渡成分が残る場合があります。最後はAPU全停止です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_dmc.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-dmc.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Enable DMC together with all four other channels by replacing the status mask.

void nes_dmc_start(void)
{
    APU_STATUS = 0x1F;
}

APU_STATUS=0x0FとしてDMCを止め、ほかの4音源の有効化ビットを立てます。

書式

void nes_dmc_stop(void);

戻り値

戻り値はありません。音源レジスターまたはドライバーの状態を変更します。

使用条件と制限

DMCは$C000～$FFC0の64バイト境界からROMを読みます。長さは16×n+1バイト（1～4081）です。ヘルパーは境界・範囲を検査せず、バンクも切り替えません。サンプルは固定バンク0に独自データを__aligned(64)で置き、配置を実行時にも検査します。

使用例

// A 17-byte original delta pattern, aligned to a 64-byte DMC start boundary.
#include "fc_sound_example.h"
#pragma bank 0
__aligned(64) __prg_rom u8 delta[17]={0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xFF,0xFF,0,0,0xAA};
void main(void) {
    sound_begin("DMC ORIGINAL DELTAS");
    sound_result[0]=(u8)(((u16)delta&63)==0);
    sound_result[1]=(u8)((u16)delta>=0xC000);
    // Loop at NTSC rate index 10; start the output accumulator at its midpoint.
    nes_dmc_config(0x4A,64,(u16)delta,17);
    nes_dmc_start();
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    nes_dmc_play(0x4C,64,(u16)delta,17);
    sound_wait(60);
    nes_dmc_stop(); sound_wait(30);
    sound_end();
}

期待する結果

独自のデルタ列をレート10、無音区間、より速いレート12の順で再生します。途中のDMC停止後は出力カウンターが保持されるため、録音では過渡成分が残る場合があります。最後はAPU全停止です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_dmc.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-dmc.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Disable DMC while leaving all four other channel-enable bits set.

void nes_dmc_stop(void)
{
    APU_STATUS = 0x0F;
}

パルス1を0x5A・タイマー0x0280・長さ番号2で鳴らし、tickより高く短いmove音を作ります。

書式

void nes_sfx_move_blip(void);

戻り値

戻り値はありません。音源レジスターまたはドライバーの状態を変更します。

使用条件と制限

このヘルパーはAPU_STATUSへ単一チャンネルのマスクを書き、ほかのチャンネルを無効化します。複数音を同時に鳴らすミキサーではありません。periodはパルス・三角波のタイマー値で、小さいほど高い音です。サンプルの周波数と時間はNTSC設定で確認しています。

使用例

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

期待する結果

pulse1、pulse2、三角波、ノイズ、tick、moveの順です。タイマー253はNTSCでパルス約440Hz、三角波約220Hzになります。tickは約111Hz、moveは約174Hzで、moveの方が短く終わります。最後は無音です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Trigger the predefined pulse-1 movement effect.

void nes_sfx_move_blip(void)
{
    nes_sfx_square1(0x5A, 0x0280, 2);
}

ノイズだけを有効にし、エンベロープ・周期モード・長さ番号を書き込みます。

書式

void nes_sfx_noise(u8 volume, u8 period_mode, u8 length_index);

引数

volume

ノイズ制御の生値。bit5=長さ停止、bit4=固定音量、bit3～0=音量またはエンベロープ間隔です。

period_mode

ノイズのbit7=短周期モード、bit3～0=周期テーブル番号。

length_index

長さテーブル番号0～31。フレーム数そのものではなく、値の下位5ビットをレジスターへ格納します。

戻り値

戻り値はありません。音源レジスターまたはドライバーの状態を変更します。

使用条件と制限

このヘルパーはAPU_STATUSへ単一チャンネルのマスクを書き、ほかのチャンネルを無効化します。複数音を同時に鳴らすミキサーではありません。periodはパルス・三角波のタイマー値で、小さいほど高い音です。サンプルの周波数と時間はNTSC設定で確認しています。

使用例

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

期待する結果

pulse1、pulse2、三角波、ノイズ、tick、moveの順です。タイマー253はNTSCでパルス約440Hz、三角波約220Hzになります。tickは約111Hz、moveは約174Hzで、moveの方が短く終わります。最後は無音です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Enable only noise and load envelope/control, period/mode and length fields.

void nes_sfx_noise(u8 volume, u8 period_mode, u8 length_index)
{
    APU_STATUS = 0x08;
    NOISE_VOL = volume;
    NOISE_LO = period_mode;
    NOISE_HI = (u8)(length_index << 3);
}

パルス1だけを有効にし、スイープを止め、制御値・タイマー・長さ番号を書き込みます。

書式

void nes_sfx_square1(u8 duty_volume, u16 period, u8 length_index);

引数

duty_volume

パルス制御レジスターの生値。bit7～6=デューティ、bit5=長さ停止、bit4=固定音量、bit3～0=音量またはエンベロープ間隔。

period

11ビットタイマー値0～2047。パルスはCPU周波数/[16×(period+1)]、三角波はCPU周波数/[32×(period+1)]です。

length_index

長さテーブル番号0～31。フレーム数そのものではなく、値の下位5ビットをレジスターへ格納します。

戻り値

戻り値はありません。音源レジスターまたはドライバーの状態を変更します。

使用条件と制限

このヘルパーはAPU_STATUSへ単一チャンネルのマスクを書き、ほかのチャンネルを無効化します。複数音を同時に鳴らすミキサーではありません。periodはパルス・三角波のタイマー値で、小さいほど高い音です。サンプルの周波数と時間はNTSC設定で確認しています。

使用例

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

期待する結果

pulse1、pulse2、三角波、ノイズ、tick、moveの順です。タイマー253はNTSCでパルス約440Hz、三角波約220Hzになります。tickは約111Hz、moveは約174Hzで、moveの方が短く終わります。最後は無音です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Enable only pulse 1, disable its sweep and load control, 11-bit timer and
length-table index. Starting this effect disables the other APU channels.

void nes_sfx_square1(u8 duty_volume, u16 period, u8 length_index)
{
    APU_STATUS = 0x01;
    SQ1_SWEEP = 0x08;
    SQ1_VOL = duty_volume;
    SQ1_LO = (u8)period;
    // Only the low five length-index bits and low eleven timer bits reach the registers.
    SQ1_HI = (u8)((u8)(length_index << 3) | (u8)((period >> 8) & 0x07));
}

パルス2だけを有効にし、スイープを止め、制御値・タイマー・長さ番号を書き込みます。

書式

void nes_sfx_square2(u8 duty_volume, u16 period, u8 length_index);

引数

duty_volume

パルス制御レジスターの生値。bit7～6=デューティ、bit5=長さ停止、bit4=固定音量、bit3～0=音量またはエンベロープ間隔。

period

11ビットタイマー値0～2047。パルスはCPU周波数/[16×(period+1)]、三角波はCPU周波数/[32×(period+1)]です。

length_index

長さテーブル番号0～31。フレーム数そのものではなく、値の下位5ビットをレジスターへ格納します。

戻り値

戻り値はありません。音源レジスターまたはドライバーの状態を変更します。

使用条件と制限

このヘルパーはAPU_STATUSへ単一チャンネルのマスクを書き、ほかのチャンネルを無効化します。複数音を同時に鳴らすミキサーではありません。periodはパルス・三角波のタイマー値で、小さいほど高い音です。サンプルの周波数と時間はNTSC設定で確認しています。

使用例

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

期待する結果

pulse1、pulse2、三角波、ノイズ、tick、moveの順です。タイマー253はNTSCでパルス約440Hz、三角波約220Hzになります。tickは約111Hz、moveは約174Hzで、moveの方が短く終わります。最後は無音です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Enable only pulse 2 and load its control/timer/length fields, disabling other channels.

void nes_sfx_square2(u8 duty_volume, u16 period, u8 length_index)
{
    APU_STATUS = 0x02;
    SQ2_SWEEP = 0x08;
    SQ2_VOL = duty_volume;
    SQ2_LO = (u8)period;
    SQ2_HI = (u8)((u8)(length_index << 3) | (u8)((period >> 8) & 0x07));
}

パルス1を0x9A・タイマー0x03F0・長さ番号4で鳴らし、短い低音のtickを作ります。

書式

void nes_sfx_tick_blip(void);

戻り値

戻り値はありません。音源レジスターまたはドライバーの状態を変更します。

使用条件と制限

このヘルパーはAPU_STATUSへ単一チャンネルのマスクを書き、ほかのチャンネルを無効化します。複数音を同時に鳴らすミキサーではありません。periodはパルス・三角波のタイマー値で、小さいほど高い音です。サンプルの周波数と時間はNTSC設定で確認しています。

使用例

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

期待する結果

pulse1、pulse2、三角波、ノイズ、tick、moveの順です。タイマー253はNTSCでパルス約440Hz、三角波約220Hzになります。tickは約111Hz、moveは約174Hzで、moveの方が短く終わります。最後は無音です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Trigger the predefined pulse-1 tick effect; it inherits the exclusive-channel behavior.

void nes_sfx_tick_blip(void)
{
    nes_sfx_square1(0x9A, 0x03F0, 4);
}

三角波だけを有効にし、線形カウンター・タイマー・長さ番号を書き込みます。

書式

void nes_sfx_triangle(u8 linear, u16 period, u8 length_index);

引数

linear

三角波の線形カウンター。bit7=制御・長さ停止、下位7ビット=リロード値。

period

11ビットタイマー値0～2047。パルスはCPU周波数/[16×(period+1)]、三角波はCPU周波数/[32×(period+1)]です。

length_index

長さテーブル番号0～31。フレーム数そのものではなく、値の下位5ビットをレジスターへ格納します。

戻り値

戻り値はありません。音源レジスターまたはドライバーの状態を変更します。

使用条件と制限

このヘルパーはAPU_STATUSへ単一チャンネルのマスクを書き、ほかのチャンネルを無効化します。複数音を同時に鳴らすミキサーではありません。periodはパルス・三角波のタイマー値で、小さいほど高い音です。サンプルの周波数と時間はNTSC設定で確認しています。

使用例

// NTSC: pulse A4 (~440 Hz), triangle A3 (~220 Hz), noise, then two short effects.
#include "fc_sound_example.h"
void main(void) {
    sound_begin("APU CHANNELS AND BLIPS");
    // Constant volume 12, length halt and 50% duty. Each helper replaces 4015.
    nes_sfx_square1(0xBC,253,0);
    sound_result[0]=(u8)(APU_STATUS&0x1F);
    sound_wait(30);
    nes_apu_channel_enable(0); sound_wait(15);
    nes_sfx_square2(0x7C,253,0);
    sound_result[1]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_triangle(0xFF,253,0);
    sound_result[2]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_noise(0x3C,5,0);
    sound_result[3]=(u8)(APU_STATUS&0x1F);
    sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_tick_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    nes_sfx_move_blip(); sound_wait(30); nes_apu_silence_all(); sound_wait(15);
    sound_end();
}

期待する結果

pulse1、pulse2、三角波、ノイズ、tick、moveの順です。タイマー253はNTSCでパルス約440Hz、三角波約220Hzになります。tickは約111Hz、moveは約174Hzで、moveの方が短く終わります。最後は無音です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\sound_channels.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\fc-channels.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Enable only triangle and load linear-counter, timer and length fields.

void nes_sfx_triangle(u8 linear, u16 period, u8 length_index)
{
    APU_STATUS = 0x04;
    TRI_LINEAR = linear;
    TRI_LO = (u8)period;
    TRI_HI = (u8)((u8)(length_index << 3) | (u8)((period >> 8) & 0x07));
}

bank_switchが最後に記録したバンク番号を返します。カートリッジのレジスターではなく、ソフトウェア側の記録を読みます。

書式

u8 bank_get_current(void);

戻り値

bank_switchが最後に保存したu8値です。初期化前は0です。

使用条件と制限

ライブラリの記録は0で始まり、カートリッジの起動時のマッピングを調べるものではありません。bank_switchで初期化してください。組み込み関数による直接切り替えやマッパーへの直接書き込みではこの記録を更新しないため、bank_get_currentで実際のハードウェア状態を検証することはできません。

使用例

starting_bank=bank_get_current(); // Last value recorded by bank_switch.
bank_expect(starting_bank==2,1);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

最初のbank_switch(2)でバンク2を記録して選びます。その後の直接切り替えではバンク1を選び、home1からA1を読みますが、bank_get_currentの記録は2です。戻すとhome2から再びB2を読めます。

完成プログラムでは、バンク番号と近アドレスによるデータの指定、バンクをまたぐコールバック、ライブラリの記録と実際のマッピングの区別を学べます。数値はすべて16進数です。BANK INとBANK OUTは02、BYTE HEXはD3、WORD HEXは5C7A、FAILED CHECKSとFIRST FAILUREはどちらも00が期待値です。CGBとFCは青字、DMGは黒字で表示します。

CALL COUNTは02です。far_callマクロと__farcallがそれぞれ1回コールバックを実行します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Read this wrapper's bank shadow; arbitrary mapper writes do not update it.

u8 bank_get_current(void)
{
    return kq_bank_current;
}

要求したバンク番号をライブラリに記録し、コンパイラのマッパー別PRGバンク切り替え処理で選択します。

書式

void bank_switch(u8 bank);

引数

bank

符号なし8ビットのROMバンク番号です。呼び出しでは関数の配置と一致させ、読み出しでは転送元のマッピングを指定します。対象カートリッジで有効な範囲を使用してください。

戻り値

ありません（void）。

使用条件と制限

切り替えを維持する操作では、実行中のコードや戻り先を見えなくしてはいけません。サンプルのように、この呼び出し、使用するbank_switch本体、その後に続くコードを共通・固定バンク0に置いてください。

ライブラリの記録は0で始まり、カートリッジの起動時のマッピングを調べるものではありません。bank_switchで初期化してください。組み込み関数による直接切り替えやマッパーへの直接書き込みではこの記録を更新しないため、bank_get_currentで実際のハードウェア状態を検証することはできません。

FCの切り替え番号はコンパイラの論理バンク番号です。0は共通ROMを示し、切り替え先ではありません。補助処理は0をバンク1として扱います。SUROM512の有効範囲は1〜30で、切り替え組み込み関数へ直接渡す範囲外の定数はビルドエラーです。範囲外の実行時値では1を選び、マッパー異常状態を設定します。共通ROMは、バンク0への切り替えを要求せず直接読んでください。

使用例

bank_switch(2); // Select the payload window and update library bookkeeping.

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

最初のbank_switch(2)でバンク2を記録して選びます。その後の直接切り替えではバンク1を選び、home1からA1を読みますが、bank_get_currentの記録は2です。戻すとhome2から再びB2を読めます。

完成プログラムでは、バンク番号と近アドレスによるデータの指定、バンクをまたぐコールバック、ライブラリの記録と実際のマッピングの区別を学べます。数値はすべて16進数です。BANK INとBANK OUTは02、BYTE HEXはD3、WORD HEXは5C7A、FAILED CHECKSとFIRST FAILUREはどちらも00が期待値です。CGBとFCは青字、DMGは黒字で表示します。

CALL COUNTは02です。far_callマクロと__farcallがそれぞれ1回コールバックを実行します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Record the bank in the library shadow and invoke the mapper-aware compiler intrinsic.

void bank_switch(u8 bank)
{
    kq_bank_current = bank;
    __bankswitch(bank);
}

__farcall((bank), func)へ展開するマクロです。コンパイラが関数名として処理できる形で対象を渡します。コールバックポインターによる間接呼び出しではありません。

書式

#define far_call(bank, func) __farcall((bank), func)

引数

bank

符号なし8ビットのROMバンク番号です。呼び出しでは関数の配置と一致させ、読み出しでは転送元のマッピングを指定します。対象カートリッジで有効な範囲を使用してください。

func

宣言済みの、引数のない関数名です。この名前指定の組み込み呼び出しには、関数アドレスを格納した変数を渡せません。bank引数をコールバックの引数として渡すこともありません。

戻り値

戻り値の型は呼び出した関数に従います。voidのコールバックは値を返さず、u8・u16のコールバックはその値を返します。掲載サンプルはvoidのコールバックを使います。

使用条件と制限

これらの呼び出しは、ユーザー引数を渡したり、コールバックを割り込みに対して再入可能にしたりするものではありません。コールバック自身のデータ・スタック・割り込みの使い方を適切に管理してください。バンク復帰は入れ子呼び出しと反復呼び出しで検証していますが、この例で実機や任意の割り込みタイミングを検証したわけではありません。

FCの切り替え番号はコンパイラの論理バンク番号です。0は共通ROMを示し、切り替え先ではありません。補助処理は0をバンク1として扱います。SUROM512の有効範囲は1〜30で、切り替え組み込み関数へ直接渡す範囲外の定数はビルドエラーです。範囲外の実行時値では1を選び、マッパー異常状態を設定します。共通ROMは、バンク0への切り替えを要求せず直接読んでください。

使用例

far_call(3,callback); // No arguments; callback reads payload[0] in bank 3.
bank_expect(callback_count==1 && callback_byte==0xD3,15);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

完成プログラムのこの位置では、far_callによってcallback_countが1になります。コールバックはバンク3からD3を読みます。その後にhome2を近ポインターで読んでB2を確認し、バンク2が選ばれた状態で復帰したことを確かめます。

完成プログラムでは、バンク番号と近アドレスによるデータの指定、バンクをまたぐコールバック、ライブラリの記録と実際のマッピングの区別を学べます。数値はすべて16進数です。BANK INとBANK OUTは02、BYTE HEXはD3、WORD HEXは5C7A、FAILED CHECKSとFIRST FAILUREはどちらも00が期待値です。CGBとFCは青字、DMGは黒字で表示します。

CALL COUNTは02です。far_callマクロと__farcallがそれぞれ1回コールバックを実行します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

遠方メモリー転送の組み込み関数を使い、指定ROMバンクから呼び出し側のRAM領域へlenバイトをコピーします。終了時に元のバンクへ戻します。

書式

void far_data_read(u8 bank, const void* addr, void* dst, u16 len);

引数

bank

符号なし8ビットのROMバンク番号です。呼び出しでは関数の配置と一致させ、読み出しでは転送元のマッピングを指定します。対象カートリッジで有効な範囲を使用してください。

addr

選んだROMバンク内の読み出せるバイト列を指す近ポインタです。ポインタ自体にはバンク番号を含みません。

dst

書き込み先のメモリです。実際のコピー量を収められる領域を確保してください。0バイト転送以外では、ヌルポインタや無効な書き込み先を検出する処理はありません。

len

バイト数を0～65535で指定します。0ならメモリはコピーしませんが、バンクの選択と復帰の処理は実行します。

戻り値

ありません（void）。

使用条件と制限

コピー元全体が目的のROM配置で読め、コピー先全体が書き込み可能な範囲になるようにしてください。バンク窓の端で次のバンクへ進む処理、memmoveのような重なりへの対応、VRAMの安全な書き込み制御はありません。VRAMには描画用の転送APIを使います。

遠方読み出しとコピーは同期処理で、コンパイラの共有作業領域を使います。処理中に割り込みから別のバンク転送を実行し、同じ作業領域を上書きしないでください。GBのコピー補助処理は、復帰バンクの保存にもHRAMの共有領域を1か所使います。例では競合する転送割り込みを設けず、固定コードから実行します。

FCの切り替え番号はコンパイラの論理バンク番号です。0は共通ROMを示し、切り替え先ではありません。補助処理は0をバンク1として扱います。SUROM512の有効範囲は1〜30で、切り替え組み込み関数へ直接渡す範囲外の定数はビルドエラーです。範囲外の実行時値では1を選び、マッパー異常状態を設定します。共通ROMは、バンク0への切り替えを要求せず直接読んでください。

使用例

far_data_read(3,payload,buffer,4); // Copy into four writable RAM bytes.
bank_expect(buffer[0]==0xD3 && buffer[1]==0x7A && buffer[2]==0x5C && buffer[3]==0x96,7);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

この断片はfar_data_readで4バイトをコピーし、バッファーをD3 7A 5C 96と照合します。呼び出し側の転送元記述子やポインターは維持されます。完成プログラムでは、長さ0のコピーとバンク復帰も別に確認します。

完成プログラムでは、バンク番号と近アドレスによるデータの指定、バンクをまたぐコールバック、ライブラリの記録と実際のマッピングの区別を学べます。数値はすべて16進数です。BANK INとBANK OUTは02、BYTE HEXはD3、WORD HEXは5C7A、FAILED CHECKSとFIRST FAILUREはどちらも00が期待値です。CGBとFCは青字、DMGは黒字で表示します。

CALL COUNTは02です。far_callマクロと__farcallがそれぞれ1回コールバックを実行します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Copy len bytes from banked ROM to caller-owned writable storage.

void far_data_read(u8 bank, const void* addr, void* dst, u16 len)
{
    __far_memcpy((u8*)dst, bank, (u16)addr, len);
}

__farpeek16で連続する2バイトを読み、リトルエンディアンのワードとして返します。先頭のバイトが下位8ビットになります。

書式

u16 far_data_read16(u8 bank, const void* addr);

引数

bank

符号なし8ビットのROMバンク番号です。呼び出しでは関数の配置と一致させ、読み出しでは転送元のマッピングを指定します。対象カートリッジで有効な範囲を使用してください。

addr

選んだROMバンク内の読み出せるバイト列を指す近ポインタです。ポインタ自体にはバンク番号を含みません。

戻り値

読み出したリトルエンディアンのワードをu16（0〜65535）で返します。

使用条件と制限

対象のバイトまたはワード全体を、選択したCPUマッピングで読める必要があります。ポインターの検査、アドレスの切り詰め、ウィンドウ境界での次バンクへの自動切り替えは行いません。ワード読み出しには連続する有効な2バイトが必要です。

遠方読み出しとコピーは同期処理で、コンパイラの共有作業領域を使います。処理中に割り込みから別のバンク転送を実行し、同じ作業領域を上書きしないでください。GBのコピー補助処理は、復帰バンクの保存にもHRAMの共有領域を1か所使います。例では競合する転送割り込みを設けず、固定コードから実行します。

FCの切り替え番号はコンパイラの論理バンク番号です。0は共通ROMを示し、切り替え先ではありません。補助処理は0をバンク1として扱います。SUROM512の有効範囲は1〜30で、切り替え組み込み関数へ直接渡す範囲外の定数はビルドエラーです。範囲外の実行時値では1を選び、マッパー異常状態を設定します。共通ROMは、バンク0への切り替えを要求せず直接読んでください。

使用例

word_value=far_data_read16(3,payload+1); // Little-endian 7A 5C -> 0x5C7A.
bank_expect(word_value==0x5C7A,6);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

この断片ではfar_data_read16でバンク3のpayload+1を読み、5C7Aを確認します。完成プログラムでは、home2の近ポインター読み出しでもバンク2への復帰を確認します。

完成プログラムでは、バンク番号と近アドレスによるデータの指定、バンクをまたぐコールバック、ライブラリの記録と実際のマッピングの区別を学べます。数値はすべて16進数です。BANK INとBANK OUTは02、BYTE HEXはD3、WORD HEXは5C7A、FAILED CHECKSとFIRST FAILUREはどちらも00が期待値です。CGBとFCは青字、DMGは黒字で表示します。

CALL COUNTは02です。far_callマクロと__farcallがそれぞれ1回コールバックを実行します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Read a 16-bit value through the bank-aware compiler intrinsic.

u16 far_data_read16(u8 bank, const void* addr)
{
    return __farpeek16(bank, (u16)addr);
}

指定したROMバンクとアドレスから__farpeek8で1バイト読み、元のバンクに戻して値を返します。

書式

u8 far_data_read8(u8 bank, const void* addr);

引数

bank

符号なし8ビットのROMバンク番号です。呼び出しでは関数の配置と一致させ、読み出しでは転送元のマッピングを指定します。対象カートリッジで有効な範囲を使用してください。

addr

選んだROMバンク内の読み出せるバイト列を指す近ポインタです。ポインタ自体にはバンク番号を含みません。

戻り値

読み出したバイトをu8（0〜255）で返します。

使用条件と制限

対象のバイトまたはワード全体を、選択したCPUマッピングで読める必要があります。ポインターの検査、アドレスの切り詰め、ウィンドウ境界での次バンクへの自動切り替えは行いません。ワード読み出しには連続する有効な2バイトが必要です。

遠方読み出しとコピーは同期処理で、コンパイラの共有作業領域を使います。処理中に割り込みから別のバンク転送を実行し、同じ作業領域を上書きしないでください。GBのコピー補助処理は、復帰バンクの保存にもHRAMの共有領域を1か所使います。例では競合する転送割り込みを設けず、固定コードから実行します。

FCの切り替え番号はコンパイラの論理バンク番号です。0は共通ROMを示し、切り替え先ではありません。補助処理は0をバンク1として扱います。SUROM512の有効範囲は1〜30で、切り替え組み込み関数へ直接渡す範囲外の定数はビルドエラーです。範囲外の実行時値では1を選び、マッパー異常状態を設定します。共通ROMは、バンク0への切り替えを要求せず直接読んでください。

使用例

byte_value=far_data_read8(3,payload); // One byte: 0xD3.
bank_expect(byte_value==0xD3,5);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

この断片ではfar_data_read8でバンク3のpayloadを読み、D3を確認します。完成プログラムでは、home2の近ポインター読み出しでもバンク2への復帰を確認します。

完成プログラムでは、バンク番号と近アドレスによるデータの指定、バンクをまたぐコールバック、ライブラリの記録と実際のマッピングの区別を学べます。数値はすべて16進数です。BANK INとBANK OUTは02、BYTE HEXはD3、WORD HEXは5C7A、FAILED CHECKSとFIRST FAILUREはどちらも00が期待値です。CGBとFCは青字、DMGは黒字で表示します。

CALL COUNTは02です。far_callマクロと__farcallがそれぞれ1回コールバックを実行します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Read one byte from an explicit ROM bank and 16-bit CPU address.

u8 far_data_read8(u8 bank, const void* addr)
{
    return __farpeek8(bank, (u16)addr);
}

バンク番号1バイトとCPUから見えるポインターを、呼び出し側のBankPtrに格納します。記述子を作るだけで、バンクの切り替えや参照先の読み出しは行いません。

書式

void farptr_make(BankPtr* out, u8 bank, const u8* ptr);

引数

out

3バイトのBankPtrを1件書き込める領域へのポインターです。outがヌルなら何も書かずに戻ります。

bank

符号なし8ビットのROMバンク番号です。呼び出しでは関数の配置と一致させ、読み出しでは転送元のマッピングを指定します。対象カートリッジで有効な範囲を使用してください。

ptr

記述子に格納する、CPUから見える16ビットのアドレスです。そのまま保存し、指定バンクにそのアドレスが存在するかは検査しません。

戻り値

ありません（void）。

使用例

farptr_make(&pointer,3,payload+1); // Store a bank and address; do not read ROM.
bank_expect(pointer.bank==3 && pointer.ptr==payload+1,8);
farptr_make(0,1,home1); // A null destination is ignored.

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

記述子にバンク3とpayload+1を設定します。その読み出し関数で7A、5C7A、3バイトの7A 5C 96を取得します。出力先がヌルの呼び出しでは状態を変えません。

完成プログラムでは、バンク番号と近アドレスによるデータの指定、バンクをまたぐコールバック、ライブラリの記録と実際のマッピングの区別を学べます。数値はすべて16進数です。BANK INとBANK OUTは02、BYTE HEXはD3、WORD HEXは5C7A、FAILED CHECKSとFIRST FAILUREはどちらも00が期待値です。CGBとFCは青字、DMGは黒字で表示します。

CALL COUNTは02です。far_callマクロと__farcallがそれぞれ1回コールバックを実行します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Store a bank/address pair without reading memory; null output is ignored.

void farptr_make(BankPtr* out, u8 bank, const u8* ptr)
{
    if (out == 0) return;
    out->bank = bank;
    out->ptr = ptr;
}

BankPtrの参照先から書き込み可能なRAMへlenバイトをコピーします。記述子は値渡しなので、呼び出し側のポインターは転送元の先頭を指したままです。

書式

void farptr_read(BankPtr ptr, void* dst, u16 len);

引数

ptr

bankとptrを持つBankPtrの値です。アドレスではなく記述子そのものを渡します。呼び出し側の記述子は変更しません。

dst

書き込み先のメモリです。実際のコピー量を収められる領域を確保してください。0バイト転送以外では、ヌルポインタや無効な書き込み先を検出する処理はありません。

len

バイト数を0～65535で指定します。0ならメモリはコピーしませんが、バンクの選択と復帰の処理は実行します。

戻り値

ありません（void）。

使用条件と制限

コピー元全体が目的のROM配置で読め、コピー先全体が書き込み可能な範囲になるようにしてください。バンク窓の端で次のバンクへ進む処理、memmoveのような重なりへの対応、VRAMの安全な書き込み制御はありません。VRAMには描画用の転送APIを使います。

遠方読み出しとコピーは同期処理で、コンパイラの共有作業領域を使います。処理中に割り込みから別のバンク転送を実行し、同じ作業領域を上書きしないでください。GBのコピー補助処理は、復帰バンクの保存にもHRAMの共有領域を1か所使います。例では競合する転送割り込みを設けず、固定コードから実行します。

FCの切り替え番号はコンパイラの論理バンク番号です。0は共通ROMを示し、切り替え先ではありません。補助処理は0をバンク1として扱います。SUROM512の有効範囲は1〜30で、切り替え組み込み関数へ直接渡す範囲外の定数はビルドエラーです。範囲外の実行時値では1を選び、マッパー異常状態を設定します。共通ROMは、バンク0への切り替えを要求せず直接読んでください。

使用例

farptr_read(pointer,buffer,3);
bank_expect(buffer[0]==0x7A && buffer[1]==0x5C && buffer[2]==0x96,11);
bank_expect(pointer.bank==3 && pointer.ptr==payload+1,23);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

この断片はfarptr_readで3バイトをコピーし、バッファーを7A 5C 96と照合します。呼び出し側の転送元記述子やポインターは維持されます。完成プログラムでは、長さ0のコピーとバンク復帰も別に確認します。

完成プログラムでは、バンク番号と近アドレスによるデータの指定、バンクをまたぐコールバック、ライブラリの記録と実際のマッピングの区別を学べます。数値はすべて16進数です。BANK INとBANK OUTは02、BYTE HEXはD3、WORD HEXは5C7A、FAILED CHECKSとFIRST FAILUREはどちらも00が期待値です。CGBとFCは青字、DMGは黒字で表示します。

CALL COUNTは02です。far_callマクロと__farcallがそれぞれ1回コールバックを実行します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Copy len bytes from a far pointer; the caller provides a sufficiently large destination.

void farptr_read(BankPtr ptr, void* dst, u16 len)
{
    __far_memcpy((u8*)dst, ptr.bank, (u16)ptr.ptr, len);
}

BankPtrが保持するバンクとアドレスから、リトルエンディアンのワードを読みます。記述子は値渡しで、ポインターは進めません。

書式

u16 farptr_read16(BankPtr ptr);

引数

ptr

bankとptrを持つBankPtrの値です。アドレスではなく記述子そのものを渡します。呼び出し側の記述子は変更しません。

戻り値

読み出したリトルエンディアンのワードをu16（0〜65535）で返します。

使用条件と制限

対象のバイトまたはワード全体を、選択したCPUマッピングで読める必要があります。ポインターの検査、アドレスの切り詰め、ウィンドウ境界での次バンクへの自動切り替えは行いません。ワード読み出しには連続する有効な2バイトが必要です。

遠方読み出しとコピーは同期処理で、コンパイラの共有作業領域を使います。処理中に割り込みから別のバンク転送を実行し、同じ作業領域を上書きしないでください。GBのコピー補助処理は、復帰バンクの保存にもHRAMの共有領域を1か所使います。例では競合する転送割り込みを設けず、固定コードから実行します。

FCの切り替え番号はコンパイラの論理バンク番号です。0は共通ROMを示し、切り替え先ではありません。補助処理は0をバンク1として扱います。SUROM512の有効範囲は1〜30で、切り替え組み込み関数へ直接渡す範囲外の定数はビルドエラーです。範囲外の実行時値では1を選び、マッパー異常状態を設定します。共通ROMは、バンク0への切り替えを要求せず直接読んでください。

使用例

bank_expect(farptr_read16(pointer)==0x5C7A,10);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

この断片ではfarptr_read16でバンク3のpointer.ptrを読み、5C7Aを確認します。完成プログラムでは、home2の近ポインター読み出しでもバンク2への復帰を確認します。

完成プログラムでは、バンク番号と近アドレスによるデータの指定、バンクをまたぐコールバック、ライブラリの記録と実際のマッピングの区別を学べます。数値はすべて16進数です。BANK INとBANK OUTは02、BYTE HEXはD3、WORD HEXは5C7A、FAILED CHECKSとFIRST FAILUREはどちらも00が期待値です。CGBとFCは青字、DMGは黒字で表示します。

CALL COUNTは02です。far_callマクロと__farcallがそれぞれ1回コールバックを実行します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Read a 16-bit value using both components of the far pointer.

u16 farptr_read16(BankPtr ptr)
{
    return __farpeek16(ptr.bank, (u16)ptr.ptr);
}

値渡しされたBankPtrの両フィールドを使って1バイト読みます。通常の近ポインターには含まれないバンク番号を記述子から取得します。

書式

u8 farptr_read8(BankPtr ptr);

引数

ptr

bankとptrを持つBankPtrの値です。アドレスではなく記述子そのものを渡します。呼び出し側の記述子は変更しません。

戻り値

読み出したバイトをu8（0〜255）で返します。

使用条件と制限

対象のバイトまたはワード全体を、選択したCPUマッピングで読める必要があります。ポインターの検査、アドレスの切り詰め、ウィンドウ境界での次バンクへの自動切り替えは行いません。ワード読み出しには連続する有効な2バイトが必要です。

遠方読み出しとコピーは同期処理で、コンパイラの共有作業領域を使います。処理中に割り込みから別のバンク転送を実行し、同じ作業領域を上書きしないでください。GBのコピー補助処理は、復帰バンクの保存にもHRAMの共有領域を1か所使います。例では競合する転送割り込みを設けず、固定コードから実行します。

FCの切り替え番号はコンパイラの論理バンク番号です。0は共通ROMを示し、切り替え先ではありません。補助処理は0をバンク1として扱います。SUROM512の有効範囲は1〜30で、切り替え組み込み関数へ直接渡す範囲外の定数はビルドエラーです。範囲外の実行時値では1を選び、マッパー異常状態を設定します。共通ROMは、バンク0への切り替えを要求せず直接読んでください。

使用例

bank_expect(farptr_read8(pointer)==0x7A,9);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

この断片ではfarptr_read8でバンク3のpointer.ptrを読み、7Aを確認します。完成プログラムでは、home2の近ポインター読み出しでもバンク2への復帰を確認します。

完成プログラムでは、バンク番号と近アドレスによるデータの指定、バンクをまたぐコールバック、ライブラリの記録と実際のマッピングの区別を学べます。数値はすべて16進数です。BANK INとBANK OUTは02、BYTE HEXはD3、WORD HEXは5C7A、FAILED CHECKSとFIRST FAILUREはどちらも00が期待値です。CGBとFCは青字、DMGは黒字で表示します。

CALL COUNTは02です。far_callマクロと__farcallがそれぞれ1回コールバックを実行します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\banked_data_calls.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.nes --mapper=mmc3 --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Read one byte using both the bank and address of the supplied far pointer.

u8 farptr_read8(BankPtr ptr)
{
    return __farpeek8(ptr.bank, (u16)ptr.ptr);
}

両端がつながった1本の座標軸で、現在位置から目標位置までの最短の符号付き差分を計算します。画面端をまたぐ追従や距離比較に使えます。

書式

s16 chain_wrap_delta(u8 target, u8 current, u16 size);

引数

target

目標位置。0～size−1の範囲で指定します。

current

現在位置。0～size−1の範囲で指定します。

size

折り返す座標軸の長さ、1～256。X座標なら幅、Y座標なら高さです。256も渡せる16ビット引数です。

戻り値

最短差分をs16で返します。正は座標が増える方向、負は減る方向、0は同じ位置です。有効な入力では−128～+128に収まります。画面の右や下へ向かう差分が正になります。

使用条件と制限

chain.hを読み込み、chain.cを1回だけコンパイルします。ChainやChainBodyの初期化は必要ありません。関数は計算だけを行い、座標配列、節数、画面を変更しません。

入力の範囲検査や正規化は行いません。size=0、size>256、またはsize以上の座標を渡さないでください。広い座標系から値を渡す場合は、呼び出し前に0～size−1へ折り返します。

左右の経路が同じ長さなら、直接計算したtarget−currentの符号を保ちます。size=160では0→80が+80、80→0が−80です。サイズが1なら有効な座標は0だけで、結果も0です。

使用例

distances[0]=chain_wrap_delta(1,159,160);   // +2: cross the right edge.
    distances[1]=chain_wrap_delta(159,1,160);   // -2: cross the left edge.
    distances[2]=chain_wrap_delta(80,0,160);    // +80: keep the direct sign.
    distances[3]=chain_wrap_delta(0,80,160);    // -80: same-length routes.
    distances[4]=chain_wrap_delta(0,0,1);       // 0: the only valid position.

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

このサンプルは座標の折り返しを学ぶためのものです。矢印の左が現在位置、右が目標位置です。幅160で画面端をまたぐ+02/−02、半周の+80/−80、幅1の+00を、関数の戻り値から表示します。先頭の0は2桁表示用です。物体を描画・移動する例ではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\chain_wrap.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\chain_wrap.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-cache --no-disasm

Return target minus current along the shortest wrapped route.
Supply size 1..256 and coordinates in 0..size-1; inputs are not normalized.
Exactly half a field retains the direct displacement sign.

s16 chain_wrap_delta(u8 target, u8 current, u16 size)
{
    s16 delta;
    s16 half;
    delta = (s16)((s16)target - (s16)current);
    half = (s16)(size >> 1);
    // At exactly half a field, retain the sign of the direct displacement.
    if (((u16)delta & 0x8000) != 0) {
        if ((u16)(0 - delta) > (u16)half) delta = (s16)(delta + (s16)size);
    } else if ((u16)delta > (u16)half) delta = (s16)(delta - (s16)size);
    return delta;
}

呼び出し側の3配列を関節データに割り当て、節数を0にします。メモリは確保しません。

書式

u8 chain_body_init(ChainBody* body, u8* x, u8* y, u8* heading, u8 capacity, u16 width, u16 height);

引数

body

対象のChainBody。0なら処理しません。初期化以外は初期化済みの状態を渡します。

x

各節のX座標を保持する配列。

y

各節のY座標を保持する配列。

heading

各節の向きを保持する配列。

capacity

確保済み配列の長さ、1～255。

width

折り返す画面の幅、1～256。

height

折り返す画面の高さ、1～256。

戻り値

成功なら1、無効な引数なら0です。有効なbodyに対する失敗ではcapacityとcountを0にし、以後の更新を無効にします。

使用条件と制限

chain.hを読み込み、chain.cを1回だけコンパイルします。ChainBodyは各節の現在位置と向きを保持します。座標履歴を蓄積するChainとは別の状態型です。

x、y、headingはそれぞれcapacityバイトの書き込み可能な配列です。相互に重ねず、使用中は保持してください。添字0が頭で、countには頭も含みます。初期化後にポインター・容量・画面サイズを直接変更しないでください。

向きは時計回りの16方向で、0=右、4=下、8=左、12=上です。入力は下位4ビットを使います。画面座標は右・下が正で、幅・高さは1～256ピクセルです。

使用例

chain_body_init(&body,joint_x,joint_y,joint_heading,8,160,144);
    // Eight caller-owned slots, including the head, on a wrapped 160x144 field.

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

画像は上から直線、下向きへ曲がって1回更新、4回更新の姿です。座標を2倍に拡大して描き、右端の頭から曲がりが後ろへ伝わります。CGB・FCでは頭が赤、胴が青、尾が緑、DMGでは黒です。成長時に重ねた尾を4回の更新で離してから比較しています。画像は同じ8節を3時点で並べたもので、24節の1本の鎖ではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\chain_body.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\chain_body.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\chain_body.chr --no-cache --no-disasm

Attach three non-overlapping capacity-byte arrays. Return 1 on success.
Invalid storage, zero capacity or dimensions outside 1..256 disable the body.

u8 chain_body_init(ChainBody* body, u8* x, u8* y, u8* heading, u8 capacity, u16 width, u16 height)
{
    if (body == 0) return 0;
    body->x = x;
    body->y = y;
    body->heading = heading;
    body->count = 0;
    body->capacity = 0;
    body->width = width;
    body->height = height;
    if (x == 0 || y == 0 || heading == 0 || capacity == 0) return 0;
    if (width == 0 || width > 256 || height == 0 || height > 256) return 0;
    body->capacity = capacity;
    return 1;
}

指定した頭の位置から後方へ節を並べ、直線の初期姿勢を作ります。

書式

u8 chain_body_reset(ChainBody* body, u8 count, u8 head_x, u8 head_y, u8 heading);

引数

body

対象のChainBody。0なら処理しません。初期化以外は初期化済みの状態を渡します。

count

頭を含む節数。1～capacity。

head_x

頭のX座標。画面幅に合わせて折り返します。

head_y

頭のY座標。画面高さに合わせて折り返します。

heading

頭の16方向の向き。

戻り値

成功なら1。節数が0、容量超過、またはbodyが0なら姿勢を変えず0です。

使用条件と制限

chain.hを読み込み、chain.cを1回だけコンパイルします。ChainBodyは各節の現在位置と向きを保持します。座標履歴を蓄積するChainとは別の状態型です。

x、y、headingはそれぞれcapacityバイトの書き込み可能な配列です。相互に重ねず、使用中は保持してください。添字0が頭で、countには頭も含みます。初期化後にポインター・容量・画面サイズを直接変更しないでください。

向きは時計回りの16方向で、0=右、4=下、8=左、12=上です。入力は下位4ビットを使います。画面座標は右・下が正で、幅・高さは1～256ピクセルです。

上下左右は4ピクセル間隔です。斜めは整数ベクトル(4,1)、(3,3)、(1,4)などを使うため、実距離は厳密に4ピクセルではありません。画面端をまたぐ姿勢も生成できます。

使用例

chain_body_reset(&body,7,48,16,0); // Seven joints, facing right.

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

画像は上から直線、下向きへ曲がって1回更新、4回更新の姿です。座標を2倍に拡大して描き、右端の頭から曲がりが後ろへ伝わります。CGB・FCでは頭が赤、胴が青、尾が緑、DMGでは黒です。成長時に重ねた尾を4回の更新で離してから比較しています。画像は同じ8節を3時点で並べたもので、24節の1本の鎖ではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\chain_body.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\chain_body.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\chain_body.chr --no-cache --no-disasm

Seed count joints in a straight pose behind the head; count includes the head.
Return 0 without changing the pose if count is zero or exceeds capacity.
Coordinates wrap to the playfield and headings are masked to 0..15.

u8 chain_body_reset(ChainBody* body, u8 count, u8 head_x, u8 head_y, u8 heading)
{
    // Cache caller storage once; following math and old-heading propagation
    // use these local values. Avoid decoding packed struct pointers per joint.
    u8* coord_x;u8* coord_y;u8* directions;u16 width;u16 height;
    u8 i;
    u8 x;
    u8 y;
    s16 ox;
    s16 oy;
    if (body == 0) return 0;
    if (count == 0 || count > body->capacity) return 0;
    coord_x=body->x;coord_y=body->y;directions=body->heading;
    width=body->width;height=body->height;
    heading = (u8)(heading & 15);
    x = chain_body_wrap((s16)head_x, width);
    y = chain_body_wrap((s16)head_y, height);
    ox = chain_body_offset_x(heading);
    oy = chain_body_offset_y(heading);
    i = 0;
    while (i < count) {
        coord_x[(__safe_index u8)i] = x;
        coord_y[(__safe_index u8)i] = y;
        directions[(__safe_index u8)i] = heading;
        x = chain_body_wrap((s16)((s16)x - ox), width);
        y = chain_body_wrap((s16)((s16)y - oy), height);
        i = (u8)(i + 1);
    }
    body->count = count;
    return 1;
}

頭を指定位置へ置き、前の節の後方へ各関節を少しずつ引き寄せます。曲がりが1更新につき1節ずつ後方へ伝わります。

書式

void chain_body_step(ChainBody* body, u8 head_x, u8 head_y, u8 heading);

引数

body

対象のChainBody。0なら処理しません。初期化以外は初期化済みの状態を渡します。

head_x

頭のX座標。画面幅に合わせて折り返します。

head_y

頭のY座標。画面高さに合わせて折り返します。

heading

頭の16方向の向き。

戻り値

戻り値はありません。

使用条件と制限

chain.hを読み込み、chain.cを1回だけコンパイルします。ChainBodyは各節の現在位置と向きを保持します。座標履歴を蓄積するChainとは別の状態型です。

x、y、headingはそれぞれcapacityバイトの書き込み可能な配列です。相互に重ねず、使用中は保持してください。添字0が頭で、countには頭も含みます。初期化後にポインター・容量・画面サイズを直接変更しないでください。

向きは時計回りの16方向で、0=右、4=下、8=左、12=上です。入力は下位4ビットを使います。画面座標は右・下が正で、幅・高さは1～256ピクセルです。

前の節の更新済み座標から目標位置を求め、画面端をまたぐ最短差分を各軸で計算します。差分0なら移動せず、絶対値1～4なら1ピクセル、5以上なら2ピクセル動きます。ちょうど画面半分の距離では元の差分の符号を保ちます。

次の節へ渡すのは、上書きする前に保存した向きです。全身へ頭の新しい向きを一度に配る処理ではありません。空の状態では何もしません。

頭の速度・加速度、当たり判定、描画、待機は呼び出し側で行います。通常は頭を動かした後、シミュレーション1回につきchain_body_stepを1回呼びます。これは関節追従であり、剛体や厳密な長さ拘束を解く物理ソルバーではありません。

使用例

chain_body_step(&body,48,20,4); // The head turns down; only joint 1 receives 4.
    show_pose(8,34);
    for(step=1;step<4;step++) {
        chain_body_step(&body,48,(u8)(20+step),4);
    }
    // After four ticks, the new heading has reached joints 1 through 4.

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

画像は上から直線、下向きへ曲がって1回更新、4回更新の姿です。座標を2倍に拡大して描き、右端の頭から曲がりが後ろへ伝わります。CGB・FCでは頭が赤、胴が青、尾が緑、DMGでは黒です。成長時に重ねた尾を4回の更新で離してから比較しています。画像は同じ8節を3時点で並べたもので、24節の1本の鎖ではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\chain_body.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\chain_body.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\chain_body.chr --no-cache --no-disasm

Install the caller's head pose, then pull joints from front to rear.
Each joint aims four pixels behind its updated predecessor and receives that
predecessor's OLD heading. Each axis moves 1 pixel, or 2 when error exceeds 4.
Call once per simulation tick; this does not advance head physics or render.

void chain_body_step(ChainBody* body, u8 head_x, u8 head_y, u8 heading)
{
    // Cache caller storage once; following math and old-heading propagation
    // use these local values. Avoid decoding packed struct pointers per joint.
    u8* coord_x;u8* coord_y;u8* directions;u16 width;u16 height;
    u8 i;
    u8 previous;
    u8 pull;
    u8 old;
    u8 x;
    u8 y;
    u8 tx;
    u8 ty;
    s16 sx;
    s16 sy;
    if (body == 0) return;
    if (body->count == 0) return;
    coord_x=body->x;coord_y=body->y;directions=body->heading;
    width=body->width;height=body->height;
    heading = (u8)(heading & 15);
    coord_x[0] = chain_body_wrap((s16)head_x, width);
    coord_y[0] = chain_body_wrap((s16)head_y, height);
    directions[0] = heading;
    pull = heading;
    i = 1;
    while (i < body->count) {
        previous = (u8)(i - 1);
        old = directions[(__safe_index u8)i];
        x = coord_x[(__safe_index u8)i];
        y = coord_y[(__safe_index u8)i];
        tx = chain_body_wrap((s16)((s16)coord_x[(__safe_index u8)previous] - chain_body_offset_x(pull)), width);
        ty = chain_body_wrap((s16)((s16)coord_y[(__safe_index u8)previous] - chain_body_offset_y(pull)), height);
        sx = chain_body_correction(chain_wrap_delta(tx, x, width));
        sy = chain_body_correction(chain_wrap_delta(ty, y, height));
        directions[(__safe_index u8)i] = pull;
        coord_x[(__safe_index u8)i] = chain_body_wrap((s16)((s16)x + sx), width);
        coord_y[(__safe_index u8)i] = chain_body_wrap((s16)((s16)y + sy), height);
        // Save before overwriting: a bend advances by one joint per update.
        pull = old;
        i = (u8)(i + 1);
    }
}

尾の現在位置と向きを次の空きスロットへ複製し、節数を1増やします。

書式

u8 chain_body_grow(ChainBody* body);

引数

body

対象のChainBody。0なら処理しません。初期化以外は初期化済みの状態を渡します。

戻り値

追加できたら1。空、容量一杯、無効化された状態、またはbodyが0なら0です。

使用条件と制限

chain.hを読み込み、chain.cを1回だけコンパイルします。ChainBodyは各節の現在位置と向きを保持します。座標履歴を蓄積するChainとは別の状態型です。

x、y、headingはそれぞれcapacityバイトの書き込み可能な配列です。相互に重ねず、使用中は保持してください。添字0が頭で、countには頭も含みます。初期化後にポインター・容量・画面サイズを直接変更しないでください。

向きは時計回りの16方向で、0=右、4=下、8=左、12=上です。入力は下位4ビットを使います。画面座標は右・下が正で、幅・高さは1～256ピクセルです。

追加直後の尾は前の尾と重なります。以後のchain_body_stepで徐々に離れます。成長そのものでは頭や他の節を移動させません。

使用例

chain_body_grow(&body); // Copy the tail pose into the eighth slot.
    chain_body_step(&body,48,16,0);
    chain_body_step(&body,48,16,0);
    chain_body_step(&body,48,16,0);
    chain_body_step(&body,48,16,0); // Allow the duplicated tail to separate.

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

画像は上から直線、下向きへ曲がって1回更新、4回更新の姿です。座標を2倍に拡大して描き、右端の頭から曲がりが後ろへ伝わります。CGB・FCでは頭が赤、胴が青、尾が緑、DMGでは黒です。成長時に重ねた尾を4回の更新で離してから比較しています。画像は同じ8節を3時点で並べたもので、24節の1本の鎖ではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\chain_body.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\chain_body.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\chain_body.chr --no-cache --no-disasm

Append a copy of the current tail; later steps separate the new joint.
Return 1 on growth, or 0 for an empty, disabled or full body.

u8 chain_body_grow(ChainBody* body)
{
    u8 tail;
    u8 next;
    if (body == 0) return 0;
    next = body->count;
    if (next == 0 || next >= body->capacity) return 0;
    tail = (u8)(next - 1);
    body->x[(__safe_index u8)next] = body->x[(__safe_index u8)tail];
    body->y[(__safe_index u8)next] = body->y[(__safe_index u8)tail];
    body->heading[(__safe_index u8)next] = body->heading[(__safe_index u8)tail];
    body->count = (u8)(next + 1);
    return 1;
}

節数だけを0にして、同じ配列と画面設定を再利用できるようにします。

書式

void chain_body_clear(ChainBody* body);

引数

body

対象のChainBody。0なら処理しません。初期化以外は初期化済みの状態を渡します。

戻り値

戻り値はありません。

使用条件と制限

chain.hを読み込み、chain.cを1回だけコンパイルします。ChainBodyは各節の現在位置と向きを保持します。座標履歴を蓄積するChainとは別の状態型です。

x、y、headingはそれぞれcapacityバイトの書き込み可能な配列です。相互に重ねず、使用中は保持してください。添字0が頭で、countには頭も含みます。初期化後にポインター・容量・画面サイズを直接変更しないでください。

向きは時計回りの16方向で、0=右、4=下、8=左、12=上です。入力は下位4ビットを使います。画面座標は右・下が正で、幅・高さは1～256ピクセルです。

配列のバイト列は消去しません。再開にはchain_body_resetを使います。クリア直後にchain_body_growしても追加されません。

使用例

chain_body_clear(&body); // Forget the pose; the three arrays remain owned by us.

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

画像は上から直線、下向きへ曲がって1回更新、4回更新の姿です。座標を2倍に拡大して描き、右端の頭から曲がりが後ろへ伝わります。CGB・FCでは頭が赤、胴が青、尾が緑、DMGでは黒です。成長時に重ねた尾を4回の更新で離してから比較しています。画像は同じ8節を3時点で並べたもので、24節の1本の鎖ではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\chain_body.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\chain_body.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\api-examples\fc\chain_body.chr --no-cache --no-disasm

Remove all joints while retaining caller-owned storage and playfield settings.

void chain_body_clear(ChainBody* body)
{
    if (body == 0) return;
    body->count = 0;
}

保存している座標履歴を論理的に空にし、同じ配列を再利用できるようにします。

書式

void chain_clear(Chain* chain);

引数

chain

対象の初期化済み Chain へのポインター。

戻り値

戻り値はありません。

使用条件と制限

点数と先頭位置を0に戻します。保存配列のバイト列は消去せず、メモリも解放しません。Chain と座標配列は呼び出し側が用意し、使用中は保持します。要素番号の8ビット加算があふれないよう、容量は128以下にしてください。

FC版は chain == 0 なら何もしません。

使用例

chain_clear(&trail);result[11]=chain_get_count(&trail);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

4点を保持している履歴を消去し、点数が0になることを確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_chain.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_chain.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Forget the recorded points without clearing or freeing the backing storage.

void chain_clear(Chain* chain)
{
    if (chain == 0) return;
    chain->count = 0;
    chain->head = 0;
}

現在取り出せる座標の点数を調べます。

書式

u8 chain_get_count(const Chain* chain);

引数

chain

対象の初期化済み Chain へのポインター。

戻り値

0～容量の点数。ヌルの履歴なら0です。

使用条件と制限

Chain と座標配列は呼び出し側が用意し、使用中は保持します。要素番号の8ビット加算があふれないよう、容量は128以下にしてください。

使用例

result[4]=chain_get_count(&trail);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

容量4へ5回追加しても点数は4です。消去後と容量0の履歴では0になることも確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_chain.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_chain.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Return the number of stored points, or zero for a null chain.

u8 chain_get_count(const Chain* chain)
{
    if (chain == 0) return 0;
    return chain->count;
}

座標履歴から、何個前の点かを指定して座標を取り出します。

書式

u8 chain_get_segment(const Chain* chain, u8 index, ChainPoint* out);

引数

chain

対象の初期化済み Chain へのポインター。

index

点の古さ。0が最新、count - 1 が保存中の最古です。

out

結果を書き込む独立した ChainPoint。ヌルなら失敗します。

戻り値

読み出せれば1、不正な要求なら0です。ヌルでない out は検査前に(0,0)へ初期化されます。

使用条件と制限

out を履歴配列や Chain 自体と重ねないでください。先に出力を消去するため、元データが壊れます。Chain と座標配列は呼び出し側が用意し、使用中は保持します。要素番号の8ビット加算があふれないよう、容量は128以下にしてください。

使用例

result[1]=chain_get_segment(&trail,0,&point);result[2]=point.x;result[3]=point.y;

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

番号0から最新点(40,24)を読み、番号3から最古点(16,8)を読みます。範囲外の番号4では失敗し、出力は(0,0)になります。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_chain.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_chain.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Read a point by age, with index zero denoting the newest point. Return zero
for an invalid request and clear a non-null output first. Keep head + index
within the 8-bit range: addition is narrowed before the capacity wrap.

u8 chain_get_segment(const Chain* chain, u8 index, ChainPoint* out)
{
    u8 pos;
    // Do not alias out with the backing ring: it is cleared before the requested point is read.
    if (out != 0) {
        out->x = 0;
        out->y = 0;
    }

    if (out == 0) return 0;
    if (chain == 0) return 0;
    if (chain->capacity == 0) return 0;
    if (index >= chain->count) return 0;

    pos = (u8)(chain->head + index);
    while (pos >= chain->capacity) {
        pos = (u8)(pos - chain->capacity);
    }
    out->x = chain->points[(__safe_index u8)pos].x;
    out->y = chain->points[(__safe_index u8)pos].y;
    return 1;
}

座標履歴用のリングバッファに保存領域を割り当て、履歴を空にします。

書式

void chain_init(Chain* chain, ChainPoint* storage, u8 capacity);

引数

chain

初期化する書き込み可能な Chain。

storage

capacity 個の ChainPoint を格納できる配列。

capacity

保存できる点数。1～128を推奨します。0では記録しません。

戻り値

戻り値はありません。

使用条件と制限

Chain と座標配列は呼び出し側が用意し、使用中は保持します。要素番号の8ビット加算があふれないよう、容量は128以下にしてください。

FC版は chain == 0 なら何もしません。

使用例

chain_init(&trail,storage,4);result[0]=chain_get_count(&trail);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

4点分の保存領域を登録し、点数が0から始まることを確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_chain.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_chain.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Attach caller-owned ring storage and start with no recorded points.
The storage must remain valid for the lifetime of the chain.

void chain_init(Chain* chain, ChainPoint* storage, u8 capacity)
{
    if (chain == 0) return;
    // A nonzero capacity requires writable storage for that many complete ChainPoint records.
    chain->points = storage;
    chain->capacity = capacity;
    chain->count = 0;
    chain->head = 0;
}

最新の座標を履歴の先頭に追加します。容量に達すると最も古い点を置き換えます。

書式

void chain_push_head(Chain* chain, s16 x, s16 y);

引数

chain

対象の初期化済み Chain へのポインター。

x

追加する点の符号付きX座標。

y

追加する点の符号付きY座標。

戻り値

戻り値はありません。

使用条件と制限

ヌルの履歴または容量0なら何もしません。Chain と座標配列は呼び出し側が用意し、使用中は保持します。要素番号の8ビット加算があふれないよう、容量は128以下にしてください。

使用例

chain_push_head(&trail,8,8);chain_push_head(&trail,16,8);chain_push_head(&trail,24,16);chain_push_head(&trail,32,16);chain_push_head(&trail,40,24);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

容量4に5点を記録します。最新点は(40,24)、残っている最古の点は(16,8)になり、最初の(8,8)は押し出されます。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_chain.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_chain.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Move the ring head backward and store the newest point. Once full, each push
replaces the oldest point; zero capacity is a no-op.

void chain_push_head(Chain* chain, s16 x, s16 y)
{
    if (chain == 0) return;
    if (chain->capacity == 0) return;

    if (chain->head == 0) chain->head = (u8)(chain->capacity - 1);
    else chain->head = (u8)(chain->head - 1);

    chain->points[(__safe_index u8)chain->head].x = x;
    chain->points[(__safe_index u8)chain->head].y = y;

    if (chain->count < chain->capacity) chain->count = (u8)(chain->count + 1);
}

FC用の矩形に点が含まれるかを調べます。左・上辺を含み、右・下辺を除きます。

書式

unsigned char nes_box16_contains_point(struct NesBox16* box, unsigned short px, unsigned short py);

引数

box

読み取り可能な NesBox16。ヌルは渡しません。

px

点の符号なし16ビットX座標。

py

点の符号なし16ビットY座標。

戻り値

内部なら1、外部なら0です。

使用条件と制限

x, y は符号なし16ビット、幅・高さは8ビットです。正の大きさを指定し、座標と大きさの和を65535以下に保ってください。座標の折り返しをまたぐ矩形には使いません。

使用例

result[6]=nes_box16_contains_point(&na,9,1);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

座標1単位を1タイルとして、A=(1,1)、B=(5,4)、両方8×6の矩形を表示します。Aだけの領域はA、BだけはB、重なり4×3=12マスはOです。Aの右辺x=9は内部に含みません。CGBではAが赤、Bが青、Oが緑です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_geometry.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_geometry.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Test a half-open box: left/top edges are included and right/bottom edges
excluded. Callers provide valid pointers and non-overflowing edge coordinates.

unsigned char nes_box16_contains_point(struct NesBox16* box, unsigned short px, unsigned short py)
{
    unsigned short right;
    unsigned short bottom;

    right = (unsigned short)(box->x + box->w);
    bottom = (unsigned short)(box->y + box->h);

    if (px < box->x)
    {
        return 0;
    }
    if (py < box->y)
    {
        return 0;
    }
    if (px >= right)
    {
        return 0;
    }
    if (py >= bottom)
    {
        return 0;
    }

    return 1;
}

FC用の二つの矩形をポインターで渡し、面積のある重なりを調べます。

書式

unsigned char nes_box16_intersects(struct NesBox16* a, struct NesBox16* b);

引数

a

一つ目の読み取り可能な NesBox16。ヌルは渡しません。

b

二つ目の読み取り可能な NesBox16。

戻り値

重なれば1、離れているか辺が接するだけなら0です。

使用条件と制限

x, y は符号なし16ビット、幅・高さは8ビットです。正の大きさを指定し、座標と大きさの和を65535以下に保ってください。座標の折り返しをまたぐ矩形には使いません。

使用例

result[5]=nes_box16_intersects(&na,&nb);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

座標1単位を1タイルとして、A=(1,1)、B=(5,4)、両方8×6の矩形を表示します。Aだけの領域はA、BだけはB、重なり4×3=12マスはOです。Aの右辺x=9は内部に含みません。CGBではAが赤、Bが青、Oが緑です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_geometry.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_geometry.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Test two axis-aligned world boxes using exclusive right/bottom edges.
Coordinate-plus-size sums must fit u16; touching edges return false.
Both boxes must have positive dimensions; the overlap test has no separate empty-box guard.

unsigned char nes_box16_intersects(struct NesBox16* a, struct NesBox16* b)
{
    unsigned short a_right;
    unsigned short b_right;
    unsigned short a_bottom;
    unsigned short b_bottom;

    a_right = (unsigned short)(a->x + a->w);
    b_right = (unsigned short)(b->x + b->w);
    a_bottom = (unsigned short)(a->y + a->h);
    b_bottom = (unsigned short)(b->y + b->h);

    if (a_right <= b->x)
    {
        return 0;
    }
    if (b_right <= a->x)
    {
        return 0;
    }
    if (a_bottom <= b->y)
    {
        return 0;
    }
    if (b_bottom <= a->y)
    {
        return 0;
    }

    return 1;
}

アサート失敗のコードを保持し、ASSERTというログの追加を試みます。

書式

void debug_assert_fail(u16 code);

引数

code

保持する16ビットのエラー識別コード。

戻り値

戻り値はありません。

使用条件と制限

実行を停止しません。ログが満杯でも最後のアサートコードは更新されます。ログ容量は既定32件です。満杯では追加を捨てます。DEBUG_TRACE_MAX を変更するなら1～255で全翻訳単位を統一してください。名前の文字列はコピーせずポインターを保存するため、検査が終わるまで有効に保ちます。割り込みとメイン処理の同時書き込みは呼び出し側で防いでください。

使用例

debug_assert_fail(42);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

コード42を記録します。その後ログを満杯にしてコード999を記録し、件数は32のままでも最後のコードは999になることを確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Store the assertion code even if the log is full, then attempt an ASSERT
entry. The helper records failure but does not stop execution.

void debug_assert_fail(u16 code)
{
    kq_debug_last_assert = code;
    debug_push(debug_assert_label, code);
}

最後に記録されたアサートコードを、ログの空きに関係なく取得します。

書式

u16 debug_get_last_assert(void);

戻り値

最後の16ビットコード。初期化直後は0です。

使用条件と制限

0は初期値であり、コード0の失敗と区別できません。読み出しても値を消去しません。

使用例

result[22]=debug_get_last_assert();

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

マクロで記録した77、満杯後の999、再初期化後の0を確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Read the latest assertion code, initially zero after debug_init.

u16 debug_get_last_assert(void)
{
    return kq_debug_last_assert;
}

ログ配列に入っている有効エントリー数を調べます。

書式

u8 debug_get_trace_count(void);

戻り値

0～DEBUG_TRACE_MAX の件数です。

使用条件と制限

ログ容量は既定32件です。満杯では追加を捨てます。DEBUG_TRACE_MAX を変更するなら1～255で全翻訳単位を統一してください。名前の文字列はコピーせずポインターを保存するため、検査が終わるまで有効に保ちます。割り込みとメイン処理の同時書き込みは呼び出し側で防いでください。

使用例

result[1]=debug_get_trace_count();

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

通常の10件と、追加し続けた後の上限32件を確認します。満杯になっても件数は折り返しません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Read the number of valid entries in the fixed trace buffer.

u8 debug_get_trace_count(void)
{
    return kq_debug_trace_count;
}

記録済みの名前・値・フレームを読み出すため、内部配列への参照を取得します。

書式

const DebugTraceEntry* debug_get_trace_log(void);

戻り値

内部 DebugTraceEntry 配列への読み取り用ポインターです。

使用条件と制限

配列の複製ではありません。有効範囲は debug_get_trace_count() までです。初期化後に残る古いバイト列を有効な記録として扱わないでください。ログ容量は既定32件です。満杯では追加を捨てます。DEBUG_TRACE_MAX を変更するなら1～255で全翻訳単位を統一してください。名前の文字列はコピーせずポインターを保存するため、検査が終わるまで有効に保ちます。割り込みとメイン処理の同時書き込みは呼び出し側で防いでください。

使用例

entries=debug_get_trace_log();for(i=0;i<10;i++){result[2+i]=entries[i].value;result[12+i]=entries[i].frame;}

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

10件の値とフレーム欄を順に読み出し、名前BEGINの先頭文字Bも確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Borrow the internal trace array; bound inspection by debug_get_trace_count.

const DebugTraceEntry* debug_get_trace_log(void)
{
    return kq_debug_trace_log;
}

デバッグログの有効件数・フレームタグ・最後のアサートコードを初期化します。

書式

void debug_init(void);

戻り値

戻り値はありません。

使用条件と制限

既存エントリーのバイト列は消去しません。初回の記録前に呼び出してください。ログ容量は既定32件です。満杯では追加を捨てます。DEBUG_TRACE_MAX を変更するなら1～255で全翻訳単位を統一してください。名前の文字列はコピーせずポインターを保存するため、検査が終わるまで有効に保ちます。割り込みとメイン処理の同時書き込みは呼び出し側で防いでください。

使用例

debug_init();result[0]=debug_get_trace_count();

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

初期件数0を確認し、記録後に再初期化して件数とアサートコードだけが0に戻り、配列の古い値は残ることを確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Build the RAM-resident ASSERT label and reset log length, frame tag and last
assertion code. Old log storage bytes are not erased.

void debug_init(void)
{
    debug_assert_label[0] = 'A';
    debug_assert_label[1] = 'S';
    debug_assert_label[2] = 'S';
    debug_assert_label[3] = 'E';
    debug_assert_label[4] = 'R';
    debug_assert_label[5] = 'T';
    debug_assert_label[6] = 0;
    kq_debug_trace_count = 0;
    kq_debug_frame = 0;
    kq_debug_last_assert = 0;
}

処理の区切りを、名前付きのフレームマーカーとして記録します。

書式

void debug_mark_frame(const u8* label);

引数

label

記録を識別する終端0の文字列。検査まで読み出せる領域に置きます。

戻り値

戻り値はありません。

使用条件と制限

ログ容量は既定32件です。満杯では追加を捨てます。DEBUG_TRACE_MAX を変更するなら1～255で全翻訳単位を統一してください。名前の文字列はコピーせずポインターを保存するため、検査が終わるまで有効に保ちます。割り込みとメイン処理の同時書き込みは呼び出し側で防いでください。

使用例

debug_mark_frame("BEGIN");

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

BEGINというマーカーを追加します。値は65535（0xFFFF）、フレームは513として記録されます。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Append a named marker with the reserved marker value 0xFFFF.

void debug_mark_frame(const u8* label)
{
    debug_push(label, 0xFFFF);
}

これ以降に追加するログに付けるフレーム番号を指定します。

書式

void debug_set_frame(u16 frame);

引数

frame

以後の記録に付ける16ビットのフレーム番号。

戻り値

戻り値はありません。

使用条件と制限

フレームを待つ処理や自動加算はありません。ゲームのフレームカウンターを明示的に渡します。ログ容量は既定32件です。満杯では追加を捨てます。DEBUG_TRACE_MAX を変更するなら1～255で全翻訳単位を統一してください。名前の文字列はコピーせずポインターを保存するため、検査が終わるまで有効に保ちます。割り込みとメイン処理の同時書き込みは呼び出し側で防いでください。

使用例

debug_set_frame(513);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

513を設定して10件を記録し、すべてのフレーム欄が513になることを読み出して確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Choose the frame tag stored in subsequent debug entries.

void debug_set_frame(u16 frame)
{
    kq_debug_frame = frame;
}

16ビットのスコアやカウンターを名前付きで記録します。

書式

void debug_trace_u16(const u8* name, u16 value);

引数

name

記録を識別する終端0の文字列。検査まで読み出せる領域に置きます。

value

保存する0～65535の値。

戻り値

戻り値はありません。

使用条件と制限

ログ容量は既定32件です。満杯では追加を捨てます。DEBUG_TRACE_MAX を変更するなら1～255で全翻訳単位を統一してください。名前の文字列はコピーせずポインターを保存するため、検査が終わるまで有効に保ちます。割り込みとメイン処理の同時書き込みは呼び出し側で防いでください。

使用例

debug_trace_u16("WORD",4660);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

WORDに4660（0x1234）を記録し、上位バイトを含む値を読み戻します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Append a 16-bit value with the current frame tag.

void debug_trace_u16(const u8* name, u16 value)
{
    debug_push(name, value);
}

8ビットの状態値を名前と現在のフレーム番号とともに記録します。

書式

void debug_trace_u8(const u8* name, u8 value);

引数

name

記録を識別する終端0の文字列。検査まで読み出せる領域に置きます。

value

保存する0～255の値。ログ内では16ビットにゼロ拡張されます。

戻り値

戻り値はありません。

使用条件と制限

ログ容量は既定32件です。満杯では追加を捨てます。DEBUG_TRACE_MAX を変更するなら1～255で全翻訳単位を統一してください。名前の文字列はコピーせずポインターを保存するため、検査が終わるまで有効に保ちます。割り込みとメイン処理の同時書き込みは呼び出し側で防いでください。

使用例

debug_trace_u8("BYTE",255);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

BYTEに255を記録し、ログの16ビット値欄にも255として保存されることを確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Widen a byte value into the trace entry's 16-bit value field.

void debug_trace_u8(const u8* name, u8 value)
{
    debug_push(name, (u16)value);
}

条件が偽ならコード1のアサート失敗を記録する、文として使えるマクロです。

書式

#define KITAQGB_ASSERT(cond) do { if (!(cond)) debug_assert_fail((u16)1); } while (0)

引数

cond

成立していることを確認する条件式。0なら失敗です。

戻り値

戻り値はありません。

使用条件と制限

条件は一度評価します。真なら記録しません。失敗しても実行を続けます。do…while (0) 形式なので if…else の中でも一つの文として使えます。

使用例

KITAQGB_ASSERT(1);KITAQGB_ASSERT(0);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

真と偽を一回ずつ渡し、追加されるログはコード1の一件だけであることを確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

#define KITAQGB_ASSERT(cond) do { if (!(cond)) debug_assert_fail((u16)1); } while (0)

条件が偽のときだけ、指定したコードのアサート失敗を記録します。

書式

#define KITAQGB_ASSERT_CODE(cond, code) do { if (!(cond)) debug_assert_fail((u16)(code)); } while (0)

引数

cond

成立を確認する条件式。

code

失敗した場合に評価し、16ビットへ変換するコードの式。

戻り値

戻り値はありません。

使用条件と制限

条件は一度評価し、コードの式は失敗した場合だけ評価します。記録後も実行を続けます。

使用例

KITAQGB_ASSERT_CODE(1,++side_effect);KITAQGB_ASSERT_CODE(0,77);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

真の条件で ++side_effect を指定しても変数は0のままです。偽の条件ではコード77が記録されます。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

#define KITAQGB_ASSERT_CODE(cond, code) do { if (!(cond)) debug_assert_fail((u16)(code)); } while (0)

ラベルを文字列ポインターへ変換し、値0xFFFFのフレームマーカーを追加するマクロです。

書式

#define KITAQGB_MARK_FRAME(label) debug_mark_frame((const u8*)(label))

引数

label

記録を識別する終端0の文字列。検査まで読み出せる領域に置きます。

戻り値

戻り値はありません。

使用条件と制限

ログ容量は既定32件です。満杯では追加を捨てます。DEBUG_TRACE_MAX を変更するなら1～255で全翻訳単位を統一してください。名前の文字列はコピーせずポインターを保存するため、検査が終わるまで有効に保ちます。割り込みとメイン処理の同時書き込みは呼び出し側で防いでください。

使用例

KITAQGB_MARK_FRAME("END");

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

ENDというラベルを記録し、値65535とフレーム513を確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

#define KITAQGB_MARK_FRAME(label) debug_mark_frame((const u8*)(label))

名前付きの値を16ビットへ明示変換してデバッグログへ渡すマクロです。

書式

#define KITAQGB_TRACE(name, value) debug_trace_u16((const u8*)(name), (u16)(value))

引数

name

記録を識別する終端0の文字列。検査まで読み出せる領域に置きます。

value

16ビットへ変換して保存する式。

戻り値

戻り値はありません。

使用条件と制限

常に有効なマクロで、ビルド設定による自動無効化はありません。KITAQGB_TRACE_U16 と同じ16ビット記録です。ログ容量は既定32件です。満杯では追加を捨てます。DEBUG_TRACE_MAX を変更するなら1～255で全翻訳単位を統一してください。名前の文字列はコピーせずポインターを保存するため、検査が終わるまで有効に保ちます。割り込みとメイン処理の同時書き込みは呼び出し側で防いでください。

使用例

KITAQGB_TRACE("SCORE",600);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

例の記録値は600です。値をログ配列から読み戻して確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

#define KITAQGB_TRACE(name, value) debug_trace_u16((const u8*)(name), (u16)(value))

名前付きの値を16ビットへ明示変換してデバッグログへ渡すマクロです。

書式

#define KITAQGB_TRACE_U16(name, value) debug_trace_u16((const u8*)(name), (u16)(value))

引数

name

記録を識別する終端0の文字列。検査まで読み出せる領域に置きます。

value

16ビットへ変換して保存する式。

戻り値

戻り値はありません。

使用条件と制限

常に有効なマクロで、ビルド設定による自動無効化はありません。ログ容量は既定32件です。満杯では追加を捨てます。DEBUG_TRACE_MAX を変更するなら1～255で全翻訳単位を統一してください。名前の文字列はコピーせずポインターを保存するため、検査が終わるまで有効に保ちます。割り込みとメイン処理の同時書き込みは呼び出し側で防いでください。

使用例

KITAQGB_TRACE_U16("WORD2",500);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

例の記録値は500です。値をログ配列から読み戻して確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

#define KITAQGB_TRACE_U16(name, value) debug_trace_u16((const u8*)(name), (u16)(value))

名前付きの値を8ビットへ明示変換してデバッグログへ渡すマクロです。

書式

#define KITAQGB_TRACE_U8(name, value) debug_trace_u8((const u8*)(name), (u8)(value))

引数

name

記録を識別する終端0の文字列。検査まで読み出せる領域に置きます。

value

8ビットへ変換して保存する式。

戻り値

戻り値はありません。

使用条件と制限

常に有効なマクロで、ビルド設定による自動無効化はありません。ログ容量は既定32件です。満杯では追加を捨てます。DEBUG_TRACE_MAX を変更するなら1～255で全翻訳単位を統一してください。名前の文字列はコピーせずポインターを保存するため、検査が終わるまで有効に保ちます。割り込みとメイン処理の同時書き込みは呼び出し側で防いでください。

使用例

KITAQGB_TRACE_U8("CAST",0x1234);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

例の記録値は52です。0x1234の下位8ビット0x34だけを記録します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_debug.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_debug.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

#define KITAQGB_TRACE_U8(name, value) debug_trace_u8((const u8*)(name), (u8)(value))

全エンティティを解放し、スプライト未割当の印を含む各項目を初期値へ戻します。

書式

void entity_clear_all(void);

戻り値

ありません（void）。

使用条件と制限

プールは固定配列で、ヒープからの動的確保は行いません。ENTITY_MAX の既定値は16で、1～255の範囲を全コンパイル単位で同じ値にしてください。IDは0から始まり、0xFF は失敗を表します。

全スロットの active,type,x,y,vx,vy,state,timer を0、sprite を 0xFF にします。ハードウェアのスプライトを隠したり解放したりはしません。描画資源は別途片付けてください。

使用例

entity_clear_all();
after_clear = entity_count_active();
if (after_clear != 0 || entity_get(reused) != 0) { failures++; }

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

完全なプログラムでは、再利用されるプールのスロットがどう変化するかを学びます。数字はラベルと組み合わせて読んでください。2個確保すると CREATED 002、1個目を解放すると AFTER FREE 001、最小の空きIDを再利用すると REUSED ID 000、全解放後は AFTER CLEAR 000 です。解放後の取得がnullになることと、再確保時にフィールドが初期化されることも確認します。FAILED CHECKS 000 は期待値に一致したことを表します。

FC版の巡回は使用中の2個に対してそれぞれコールバックを呼ぶので、UPDATE CALLS 002、DRAW CALLS 002 になります。サンプルの更新コールバックは両方を右へ1タイル動かします。描画コールバックは2個の物体を表す A をタイル (3,12)、B を (7,12) に置きます。コールバックが描いた背景の文字タイルであり、自動確保されたスプライトではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Release every entity and restore deterministic defaults, including the no-sprite sentinel.

void entity_clear_all(void)
{
    u8 i;
    i = 0;
    while (i < ENTITY_MAX) {
        entity_pool[(__safe_index u8)i].active = 0;
        entity_pool[(__safe_index u8)i].type = 0;
        entity_pool[(__safe_index u8)i].x = 0;
        entity_pool[(__safe_index u8)i].y = 0;
        entity_pool[(__safe_index u8)i].vx = 0;
        entity_pool[(__safe_index u8)i].vy = 0;
        entity_pool[(__safe_index u8)i].state = 0;
        entity_pool[(__safe_index u8)i].timer = 0;
        entity_pool[(__safe_index u8)i].sprite = 0xFF;
        i = (u8)(i + 1);
    }
}

エンティティの状態を変えずに、使用中スロットの数を返します。

書式

u8 entity_count_active(void);

戻り値

active が0以外のスロット数で、0～ENTITY_MAX です。使用数を表し、最も大きいIDや画面上のスプライト数ではありません。

使用条件と制限

プールは固定配列で、ヒープからの動的確保は行いません。ENTITY_MAX の既定値は16で、1～255の範囲を全コンパイル単位で同じ値にしてください。IDは0から始まり、0xFF は失敗を表します。

使用例

created = entity_count_active();
if (created != 2) { failures++; }

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

完全なプログラムでは、再利用されるプールのスロットがどう変化するかを学びます。数字はラベルと組み合わせて読んでください。2個確保すると CREATED 002、1個目を解放すると AFTER FREE 001、最小の空きIDを再利用すると REUSED ID 000、全解放後は AFTER CLEAR 000 です。解放後の取得がnullになることと、再確保時にフィールドが初期化されることも確認します。FAILED CHECKS 000 は期待値に一致したことを表します。

FC版の巡回は使用中の2個に対してそれぞれコールバックを呼ぶので、UPDATE CALLS 002、DRAW CALLS 002 になります。サンプルの更新コールバックは両方を右へ1タイル動かします。描画コールバックは2個の物体を表す A をタイル (3,12)、B を (7,12) に置きます。コールバックが描いた背景の文字タイルであり、自動確保されたスプライトではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Count occupied slots without changing entity state.

u8 entity_count_active(void)
{
    u8 i;
    u8 count;
    i = 0;
    count = 0;
    while (i < ENTITY_MAX) {
        if (entity_pool[(__safe_index u8)i].active != 0) count = (u8)(count + 1);
        i = (u8)(i + 1);
    }
    return count;
}

指定した種類・座標でエンティティを確保し、再利用可能なIDを返します。空きがなければ 0xFF です。

書式

u8 entity_create(u8 type, s16 x, s16 y);

引数

type

ゲーム側で定義する0～255の種類番号です。プールは値を保存するだけで、種類に応じた動作や描画処理は選びません。

x, y

符号付き16ビットの座標（-32768～32767）です。ピクセルやQ8.8などの単位はゲーム側で決めます。プールは単位変換、座標の切り詰め、速度に応じた自動移動を行いません。

戻り値

最も小さい空きスロットのID（0～ENTITY_MAX-1）を返します。空きがなければ 0xFF です。成功時は active=1 とし、種類・座標を保存し、速度・状態・タイマーを0、sprite を 0xFF にします。

使用条件と制限

プールは固定配列で、ヒープからの動的確保は行いません。ENTITY_MAX の既定値は16で、1～255の範囲を全コンパイル単位で同じ値にしてください。IDは0から始まり、0xFF は失敗を表します。

使用例

first = entity_create(1, 2, 12);
second = entity_create(2, 6, 12);
if (first == 0xFF || second == 0xFF) { failures++; }

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

完全なプログラムでは、再利用されるプールのスロットがどう変化するかを学びます。数字はラベルと組み合わせて読んでください。2個確保すると CREATED 002、1個目を解放すると AFTER FREE 001、最小の空きIDを再利用すると REUSED ID 000、全解放後は AFTER CLEAR 000 です。解放後の取得がnullになることと、再確保時にフィールドが初期化されることも確認します。FAILED CHECKS 000 は期待値に一致したことを表します。

FC版の巡回は使用中の2個に対してそれぞれコールバックを呼ぶので、UPDATE CALLS 002、DRAW CALLS 002 になります。サンプルの更新コールバックは両方を右へ1タイル動かします。描画コールバックは2個の物体を表す A をタイル (3,12)、B を (7,12) に置きます。コールバックが描いた背景の文字タイルであり、自動確保されたスプライトではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Returns a reusable slot ID, or 0xFF if no slot is free.

u8 entity_create(u8 type, s16 x, s16 y)
{
    u8 i;
    i = 0;
    while (i < ENTITY_MAX) {
        if (entity_pool[(__safe_index u8)i].active == 0) {
            entity_pool[(__safe_index u8)i].active = 1;
            entity_pool[(__safe_index u8)i].type = type;
            entity_pool[(__safe_index u8)i].x = x;
            entity_pool[(__safe_index u8)i].y = y;
            entity_pool[(__safe_index u8)i].vx = 0;
            entity_pool[(__safe_index u8)i].vy = 0;
            entity_pool[(__safe_index u8)i].state = 0;
            entity_pool[(__safe_index u8)i].timer = 0;
            entity_pool[(__safe_index u8)i].sprite = 0xFF;
            return i;
        }
        i = (u8)(i + 1);
    }
    return 0xFF;
}

id のエンティティを解放します。保持データは直ちには消さず、再確保時に初期化します。

書式

void entity_destroy(u8 id);

引数

id

0～ENTITY_MAX-1 の再利用可能なスロット番号です。範囲外のIDは無効です。無効なIDを解放しても変化せず、取得するとnullを返します。

戻り値

ありません（void）。

使用条件と制限

プールは固定配列で、ヒープからの動的確保は行いません。ENTITY_MAX の既定値は16で、1～255の範囲を全コンパイル単位で同じ値にしてください。IDは0から始まり、0xFF は失敗を表します。

解放時は active だけを0にします。他のフィールドの消去、スプライトや素材の解放は行いません。次の確保で同じID・アドレスが別のエンティティに再利用されることがあります。関連資源の片付けはゲーム側で行ってください。

使用例

entity_destroy(first);
after_free = entity_count_active();
if (entity_get(first) != 0 || after_free != 1) { failures++; }

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

完全なプログラムでは、再利用されるプールのスロットがどう変化するかを学びます。数字はラベルと組み合わせて読んでください。2個確保すると CREATED 002、1個目を解放すると AFTER FREE 001、最小の空きIDを再利用すると REUSED ID 000、全解放後は AFTER CLEAR 000 です。解放後の取得がnullになることと、再確保時にフィールドが初期化されることも確認します。FAILED CHECKS 000 は期待値に一致したことを表します。

FC版の巡回は使用中の2個に対してそれぞれコールバックを呼ぶので、UPDATE CALLS 002、DRAW CALLS 002 になります。サンプルの更新コールバックは両方を右へ1タイル動かします。描画コールバックは2個の物体を表す A をタイル (3,12)、B を (7,12) に置きます。コールバックが描いた背景の文字タイルであり、自動確保されたスプライトではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Release a valid slot without clearing its payload. Reallocation resets the payload;
a saved pointer or ID must not be treated as a persistent entity identity.

void entity_destroy(u8 id)
{
    if (id >= ENTITY_MAX) return;
    entity_pool[(__safe_index u8)id].active = 0;
}

使用中のエンティティを巡回し、各IDを描画コールバックに渡します。巡回方法は entity_update_all と同じです。コールバックが描画データを書き込まなければ、スプライトや画素は描画されません。

書式

void entity_draw_all(EntityFn fn);

引数

fn

void fn(u8 id) という書式の関数ポインタです。渡されるのはスロットIDなので、フィールドの参照には entity_get(id) を使います。nullも指定でき、その場合は呼び出しません。

戻り値

ありません（void）。

使用条件と制限

プールは固定配列で、ヒープからの動的確保は行いません。ENTITY_MAX の既定値は16で、1～255の範囲を全コンパイル単位で同じ値にしてください。IDは0から始まり、0xFF は失敗を表します。

巡回がそのスロットに到達した時点で使用状態を調べます。コールバックで後方のスロットを解放すれば処理を飛ばし、後方を確保すれば同じ巡回で処理することがあります。開始時の対象一覧を固定して処理する方式ではありません。

コールバックは共通PRGバンク0に置くか、呼び出し中はそのバンクが見える状態を保ってください。関数ポインタは16ビットのCPUアドレスであり、バンクを選択しません。FCの関数引数とローカル変数は固定領域を使うため、エンティティの巡回を再帰的に呼び出したり、割り込みから同じ巡回処理に再入したりしないでください。

使用例

void demo_draw(u8 id) {
    Entity* entity;
    entity = entity_get(id);
    if (entity != 0) {
        m_put((u8)entity->x, (u8)entity->y, (u8)('A' + entity->type - 1));
        draw_calls++;
    }
}

// From main(), after creating two entities:
draw_calls = 0;
entity_draw_all(demo_draw);
automatic_draws = draw_calls;
if (automatic_draws != 2) { failures++; }

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

完全なプログラムでは、再利用されるプールのスロットがどう変化するかを学びます。数字はラベルと組み合わせて読んでください。2個確保すると CREATED 002、1個目を解放すると AFTER FREE 001、最小の空きIDを再利用すると REUSED ID 000、全解放後は AFTER CLEAR 000 です。解放後の取得がnullになることと、再確保時にフィールドが初期化されることも確認します。FAILED CHECKS 000 は期待値に一致したことを表します。

FC版の巡回は使用中の2個に対してそれぞれコールバックを呼ぶので、UPDATE CALLS 002、DRAW CALLS 002 になります。サンプルの更新コールバックは両方を右へ1タイル動かします。描画コールバックは2個の物体を表す A をタイル (3,12)、B を (7,12) に置きます。コールバックが描いた背景の文字タイルであり、自動確保されたスプライトではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Call the drawing callback for each active slot, using the same traversal rules as update.
The callback submits drawing data; the pool does not allocate sprites.

void entity_draw_all(EntityFn fn)
{
    entity_update_all(fn);
}

有効で使用中のIDならエンティティへのポインタを返し、それ以外はnullを返します。指す領域はプール内で再利用されます。

書式

Entity* entity_get(u8 id);

引数

id

0～ENTITY_MAX-1 の再利用可能なスロット番号です。範囲外のIDは無効です。無効なIDを解放しても変化せず、取得するとnullを返します。

戻り値

使用中のスロットへの書き換え可能なポインタを返します。IDが無効または未使用ならnullです。領域はプールが所有します。自分で解放したり、削除・再確保をまたぐ永続的な識別子として使ったりしないでください。

使用条件と制限

プールは固定配列で、ヒープからの動的確保は行いません。ENTITY_MAX の既定値は16で、1～255の範囲を全コンパイル単位で同じ値にしてください。IDは0から始まり、0xFF は失敗を表します。

解放時は active だけを0にします。他のフィールドの消去、スプライトや素材の解放は行いません。次の確保で同じID・アドレスが別のエンティティに再利用されることがあります。関連資源の片付けはゲーム側で行ってください。

使用例

current_entity = entity_get(first);
if (current_entity != 0) { current_entity->vx = 5; }
else { failures++; }

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

完全なプログラムでは、再利用されるプールのスロットがどう変化するかを学びます。数字はラベルと組み合わせて読んでください。2個確保すると CREATED 002、1個目を解放すると AFTER FREE 001、最小の空きIDを再利用すると REUSED ID 000、全解放後は AFTER CLEAR 000 です。解放後の取得がnullになることと、再確保時にフィールドが初期化されることも確認します。FAILED CHECKS 000 は期待値に一致したことを表します。

FC版の巡回は使用中の2個に対してそれぞれコールバックを呼ぶので、UPDATE CALLS 002、DRAW CALLS 002 になります。サンプルの更新コールバックは両方を右へ1タイル動かします。描画コールバックは2個の物体を表す A をタイル (3,12)、B を (7,12) に置きます。コールバックが描いた背景の文字タイルであり、自動確保されたスプライトではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Returns null for an invalid or inactive ID; the returned pointer aliases reusable pool storage.

Entity* entity_get(u8 id)
{
    if (id >= ENTITY_MAX) return 0;
    if (entity_pool[(__safe_index u8)id].active == 0) return 0;
    return &entity_pool[(__safe_index u8)id];
}

エンティティプールの全スロットを初期化します。

書式

void entity_init(void);

戻り値

ありません（void）。

使用条件と制限

プールは固定配列で、ヒープからの動的確保は行いません。ENTITY_MAX の既定値は16で、1～255の範囲を全コンパイル単位で同じ値にしてください。IDは0から始まり、0xFF は失敗を表します。

全スロットの active,type,x,y,vx,vy,state,timer を0、sprite を 0xFF にします。ハードウェアのスプライトを隠したり解放したりはしません。描画資源は別途片付けてください。

使用例

entity_init();
if (entity_count_active() != 0) { failures++; }

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

完全なプログラムでは、再利用されるプールのスロットがどう変化するかを学びます。数字はラベルと組み合わせて読んでください。2個確保すると CREATED 002、1個目を解放すると AFTER FREE 001、最小の空きIDを再利用すると REUSED ID 000、全解放後は AFTER CLEAR 000 です。解放後の取得がnullになることと、再確保時にフィールドが初期化されることも確認します。FAILED CHECKS 000 は期待値に一致したことを表します。

FC版の巡回は使用中の2個に対してそれぞれコールバックを呼ぶので、UPDATE CALLS 002、DRAW CALLS 002 になります。サンプルの更新コールバックは両方を右へ1タイル動かします。描画コールバックは2個の物体を表す A をタイル (3,12)、B を (7,12) に置きます。コールバックが描いた背景の文字タイルであり、自動確保されたスプライトではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Reset every slot before the game starts using the pool.

void entity_init(void)
{
    entity_clear_all();
}

IDの小さい順に使用中スロットを調べ、各スロットで fn(id) を1回呼びます。移動・衝突・タイマーなどの処理はコールバック側に書きます。プール自体はその処理を提供しません。コールバックがnullなら何もしません。

書式

void entity_update_all(EntityFn fn);

引数

fn

void fn(u8 id) という書式の関数ポインタです。渡されるのはスロットIDなので、フィールドの参照には entity_get(id) を使います。nullも指定でき、その場合は呼び出しません。

戻り値

ありません（void）。

使用条件と制限

プールは固定配列で、ヒープからの動的確保は行いません。ENTITY_MAX の既定値は16で、1～255の範囲を全コンパイル単位で同じ値にしてください。IDは0から始まり、0xFF は失敗を表します。

巡回がそのスロットに到達した時点で使用状態を調べます。コールバックで後方のスロットを解放すれば処理を飛ばし、後方を確保すれば同じ巡回で処理することがあります。開始時の対象一覧を固定して処理する方式ではありません。

コールバックは共通PRGバンク0に置くか、呼び出し中はそのバンクが見える状態を保ってください。関数ポインタは16ビットのCPUアドレスであり、バンクを選択しません。FCの関数引数とローカル変数は固定領域を使うため、エンティティの巡回を再帰的に呼び出したり、割り込みから同じ巡回処理に再入したりしないでください。

使用例

void demo_update(u8 id) {
    Entity* entity;
    entity = entity_get(id);
    if (entity != 0) { entity->x = entity->x + 1; update_calls++; }
}

// From main(), after creating two entities:
update_calls = 0;
entity_update_all(demo_update);
automatic_updates = update_calls;
if (automatic_updates != 2) { failures++; }

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

完全なプログラムでは、再利用されるプールのスロットがどう変化するかを学びます。数字はラベルと組み合わせて読んでください。2個確保すると CREATED 002、1個目を解放すると AFTER FREE 001、最小の空きIDを再利用すると REUSED ID 000、全解放後は AFTER CLEAR 000 です。解放後の取得がnullになることと、再確保時にフィールドが初期化されることも確認します。FAILED CHECKS 000 は期待値に一致したことを表します。

FC版の巡回は使用中の2個に対してそれぞれコールバックを呼ぶので、UPDATE CALLS 002、DRAW CALLS 002 になります。サンプルの更新コールバックは両方を右へ1タイル動かします。描画コールバックは2個の物体を表す A をタイル (3,12)、B を (7,12) に置きます。コールバックが描いた背景の文字タイルであり、自動確保されたスプライトではありません。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\entity.c .\kitaq-docs\samples\api-examples\fc\entity_pool.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\entity_pool.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm

Call fn(id) for each active slot in ascending order. A null callback does nothing.
Changes to later slots take effect during the same traversal. Do not reenter this traversal.

void entity_update_all(EntityFn fn)
{
    u8 i;
    if (fn == 0) return;
    i = 0;
    while (i < ENTITY_MAX) {
        if (entity_pool[(__safe_index u8)i].active != 0) fn(i);
        i = (u8)(i + 1);
    }
}

Q8.8値を、入力を縮小してから除算します。

書式

fix8 fix_div(fix8 a, fix8 b);

引数

a

演算の左辺となるQ8.8の値。

b

演算の右辺となるQ8.8の値。

戻り値

Q8.8の商を返します。b == 0 の場合は0です。

使用条件と制限

式は ((a >> 4) * 256) / (b >> 4) です。b が0以外でも b >> 4 が0になる値（正の生の値1～15）は渡さないでください。積も16ビットに収めてください。

使用例

result[3]=fix_div(768,512);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

3.0を2.0で割り、1.5（生の値384）を得ます。明示的なゼロ除算入力では0を返すことも確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Scale the reduced-precision quotient back to 8.8 and return zero for b == 0.
Callers must also ensure (b >> 4) is nonzero; the explicit check only tests b.
The intermediate product must fit the compiler's integer arithmetic.

fix8 fix_div(fix8 a, fix8 b)
{
    if (b == 0) return 0;
    return (fix8)(((a >> 4) * 256) / (b >> 4));
}

整数の座標や速度を、小数部分を扱えるQ8.8形式に変換します。

書式

fix8 fix_from_int(s16 n);

引数

n

変換する整数。表現可能な範囲は−128～127です。

戻り値

n × 256 の生の値を返します。

使用条件と制限

fix8 は符号付きQ8.8です。生の値256が1.0を表します。中間値と結果が16ビットに収まる範囲で使用してください。

使用例

result[0]=fix_from_int(-3);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

例では整数−3を変換します。画面の−00768は、Q8.8の生の値−768を表します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Convert an integer to signed 8.8 fixed point by moving it into the high byte.
The caller must keep the result within the representable 16-bit range.

fix8 fix_from_int(s16 n)
{
    return (fix8)(n << 8);
}

Q8.8の始点から終点へ、8ビットの割合で補間します。

書式

fix8 fix_lerp(fix8 a, fix8 b, u8 t_q8);

引数

a

演算の左辺となるQ8.8の値。

b

演算の右辺となるQ8.8の値。

t_q8

補間割合。0～255で指定します。

戻り値

近似補間したQ8.8値を返します。

使用条件と制限

差分と割合をそれぞれ4ビット右シフトします。割合は16段階になり、255でも終点に一致するとは限りません。b - a と最終値が16ビットに収まるようにしてください。

使用例

result[4]=fix_lerp(0,1024,128);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

0から4.0への割合128で2.0（512）を得ます。割合255では3.75（960）となり、4.0には達しないことも確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Interpolate toward b using a quantized Q0.8 weight. Both shifts discard low
bits, so small changes may vanish and a weight of 255 need not reach b.

fix8 fix_lerp(fix8 a, fix8 b, u8 t_q8)
{
    fix8 d;
    // The endpoint difference must fit s16 before the reduced-precision interpolation.
    d = (fix8)(b - a);
    return (fix8)(a + (fix8)((d >> 4) * (s16)(t_q8 >> 4)));
}

二つのQ8.8値を、低コストの近似演算で乗算します。

書式

fix8 fix_mul(fix8 a, fix8 b);

引数

a

演算の左辺となるQ8.8の値。

b

演算の右辺となるQ8.8の値。

戻り値

Q8.8形式の積を返します。

使用条件と制限

各入力を先に4ビット右シフトしてから乗算します。両方の下位4ビットが失われるため、完全な16×16ビット乗算とは精度が異なります。fix8 は符号付きQ8.8です。生の値256が1.0を表します。中間値と結果が16ビットに収まる範囲で使用してください。

使用例

result[2]=fix_mul(384,512);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

1.5と2.0から3.0（生の値768）を得ます。生の値271同士の積は256になることも確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Approximate 8.8 multiplication by discarding four low bits from each operand
before multiplying. This trades precision for a smaller intermediate product.

fix8 fix_mul(fix8 a, fix8 b)
{
    return (fix8)((a >> 4) * (b >> 4));
}

Q8.8の小数部分を捨てて整数座標を取り出します。負数は負の無限大方向へ丸めます。

書式

s16 fix_to_int(fix8 x);

引数

x

整数に変換するQ8.8の値。

戻り値

符号付き整数を返します。

使用条件と制限

fix8 は符号付きQ8.8です。生の値256が1.0を表します。中間値と結果が16ビットに収まる範囲で使用してください。

使用例

result[1]=fix_to_int(-384);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

−1.5の生の値−384を渡し、−2を得ます。画面では−00002と表示します。−1の生の値からは−1を得る境界例も実行します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Discard the eight fractional bits using a signed right shift.

s16 fix_to_int(fix8 x)
{
    return (s16)(x >> 8);
}

符号付き16ビット値の絶対値を求めます。

書式

s16 kq_abs_s16(s16 v);

引数

v

絶対値を求める符号付き16ビット値。

戻り値

非負の絶対値を返します（入力−32768を除く）。

使用条件と制限

−32768の正の絶対値32768は s16 に収まりません。非負の結果が必要な場合はこの入力を除外してください。

使用例

result[0]=kq_abs_s16(-123);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

−123を渡して123を得る例です。座標差の大きさを求める場合などに使えます。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math_limits.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math_limits.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Return the magnitude in s16. The most-negative s16 has no positive s16
representation and must be excluded by callers needing a nonnegative result.

s16 kq_abs_s16(s16 v)
{
    if (v < 0) return (s16)(0 - v);
    return v;
}

座標や速度を、指定した上下限の範囲に収めます。

書式

s16 kq_clamp_s16(s16 v, s16 lo, s16 hi);

引数

v

制限する符号付き値。

lo

含まれる下限値。

hi

含まれる上限値。

戻り値

下限未満なら lo、上限超過なら hi、範囲内なら v を返します。

使用条件と制限

lo <= hi を満たす範囲を指定してください。

使用例

result[3]=kq_clamp_s16(25,-10,10);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

25を−10～10に制限して10を得ます。下限側−11→−10と、範囲内3→3も確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math_limits.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math_limits.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Clamp to an inclusive interval; callers must provide lo <= hi.

s16 kq_clamp_s16(s16 v, s16 lo, s16 hi)
{
    if (v < lo) return lo;
    if (v > hi) return hi;
    return v;
}

二つの符号付き16ビット値から大きい方を選びます。

書式

s16 kq_max_s16(s16 a, s16 b);

引数

a

比較する一つ目の符号付き値。

b

比較する二つ目の符号付き値。

戻り値

選択した入力値を返します。

使用条件と制限

符号付きで比較します。同値の場合もその値を返し、入力を書き換えません。

使用例

result[2]=kq_max_s16(-7,4);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

−7と4を比較し、4を得ます。負の結果にはマイナス記号を付けて表示します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math_limits.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math_limits.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Select the larger signed value.

s16 kq_max_s16(s16 a, s16 b)
{
    if (a > b) return a;
    return b;
}

二つの符号付き16ビット値から小さい方を選びます。

書式

s16 kq_min_s16(s16 a, s16 b);

引数

a

比較する一つ目の符号付き値。

b

比較する二つ目の符号付き値。

戻り値

選択した入力値を返します。

使用条件と制限

符号付きで比較します。同値の場合もその値を返し、入力を書き換えません。

使用例

result[1]=kq_min_s16(-7,4);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

−7と4を比較し、-7を得ます。負の結果にはマイナス記号を付けて表示します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_math_limits.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_math_limits.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Select the smaller signed value.

s16 kq_min_s16(s16 a, s16 b)
{
    if (a < b) return a;
    return b;
}

点が矩形の内部にあるかを判定します。左端と上端上の点も内部です。

書式

u8 kq_point_in_rect(s16 x, s16 y, KQRect r);

引数

x

点のX座標。矩形と同じ座標系を使います。

y

点のY座標。

r

調べる矩形。構造体を値で渡します。

戻り値

内部なら1、外部なら0です。

使用条件と制限

幅・高さは正数にし、座標と大きさの和を s16 に収めてください。右端・下端は領域に含みません。ゼロ面積を自動的に拒否する処理はありません。

使用例

result[1]=kq_point_in_rect(9,1,a);
for(gy=0;gy<11;gy++){for(gx=0;gx<15;gx++){
inside_a=kq_point_in_rect(gx,gy,a);inside_b=kq_point_in_rect(gx,gy,b);
tile=0;if(inside_a){tile=65;result[3]=result[3]+1;}if(inside_b)tile=66;if(inside_a && inside_b){tile=79;result[4]=result[4]+1;}
m_put(1+gx,2+gy,tile);__vramq_commit();__vramq_exec();
}}

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

座標1単位を1タイルとして、A=(1,1)、B=(5,4)、両方8×6の矩形を表示します。Aだけの領域はA、BだけはB、重なり4×3=12マスはOです。Aの右辺x=9は内部に含みません。CGBではAが赤、Bが青、Oが緑です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_geometry.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_geometry.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Test a half-open rectangle: left/top edges are included, right/bottom excluded.
The coordinate-plus-size sums must remain representable as s16.

u8 kq_point_in_rect(s16 x, s16 y, KQRect r)
{
    if (x < r.x) return 0;
    if (y < r.y) return 0;
    if (x >= (s16)(r.x + r.w)) return 0;
    if (y >= (s16)(r.y + r.h)) return 0;
    return 1;
}

二つの軸に平行な矩形が面積を持って重なるかを判定します。

書式

u8 kq_rect_intersect(KQRect a, KQRect b);

引数

a

一つ目の矩形。x, y は左上、w, h は幅・高さです。構造体を値で渡します。

b

二つ目の矩形。Aと同じ座標系で指定します。

戻り値

重なれば1、離れているか辺が接するだけなら0です。

使用条件と制限

幅・高さは正数にし、座標と大きさの和を s16 に収めてください。右端・下端は領域に含みません。ゼロ面積を自動的に拒否する処理はありません。

使用例

result[0]=kq_rect_intersect(a,b);result[2]=kq_rect_intersect(a,touch);

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

座標1単位を1タイルとして、A=(1,1)、B=(5,4)、両方8×6の矩形を表示します。Aだけの領域はA、BだけはB、重なり4×3=12マスはOです。Aの右辺x=9は内部に含みません。CGBではAが赤、Bが青、Oが緑です。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaq-docs\samples\api-examples\fc\batch_geometry.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\batch_geometry.nes --no-cache --no-disasm --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr

Test overlap using exclusive right/bottom edges; touching edges do not collide.
Require positive dimensions and edge sums that fit s16; zero-sized rectangles
are not explicitly rejected and may be reported as overlapping.

u8 kq_rect_intersect(KQRect a, KQRect b)
{
    if ((s16)(a.x + a.w) <= b.x) return 0;
    if ((s16)(b.x + b.w) <= a.x) return 0;
    if ((s16)(a.y + a.h) <= b.y) return 0;
    if ((s16)(b.y + b.h) <= a.y) return 0;
    return 1;
}

btn_downはinput_downを呼ぶ別名です。指定したボタンが現在押されているかを調べます。

mask に含まれるボタンのどれかが、現在押されているかを返します。

書式

u8 btn_down(u8 mask);

引数

mask

一つの BTN_*、または複数を | で組み合わせたマスクです。選んだボタンのどれかが該当すれば真になり、BTN_A | BTN_B で両方の同時押しを要求するわけではありません。マスク0は常に0を返します。すべての同時押しは (input_current() & mask) == mask で調べます。

戻り値

選択したボタンのどれかが調べる条件に合えば1、それ以外は0です。戻り値はボタンのビットマスクではありません。

使用条件と制限

ヘッダーの#defineで同じ実装名へ置き換わります。引数の評価、戻り値、状態の読み書きは参照先と同じで、別の状態や処理は追加しません。入力はinput.hとinput.c、システム制御はsystem.hとsystem.cを、完成サンプルのビルド例に従って使います。

共通マスクは BTN_RIGHT=0x01、BTN_LEFT=0x02、BTN_UP=0x04、BTN_DOWN=0x08、BTN_A=0x10、BTN_B=0x20、BTN_SELECT=0x40、BTN_START=0x80 です。ビット1が押下中を表します。GB・FCの input_* はこの形式ですが、FCの生のパッド関数は別のビット順です。

取得関数は直近の input_update() が保存した値を調べます。入力の再読込、押下イベントの消費、リピートタイマーの更新は行いません。同じ入力処理内で何度調べても結果は同じです。ボタンを押したまま input_update() を2回呼ぶと、2回目には押下イベントが消えます。

input_down

使用例

if (btn_down(BTN_A)!=0) held_ticks++;

呼び出し部分のコード例です。完全なプログラムに組み込む際は、記載した初期化とバッファの条件を満たしてください。

期待する結果

押している状態・押した瞬間・離した瞬間・自動リピートの違いを学ぶプログラムです。Aを40回の更新にわたって押し、離します。FIRST DOWN、FIRST PRESS、FIRST REPEATは1、FIRST CURRENTは16になります。HELD TICKSは40、PRESS COUNTは1、REPEAT COUNTは5です。離すとRELEASEは1、LAST CURRENTは0、LAST PREVIOUSは16になります。FAILED CHECKSは0が正常です。押す長さを変えると回数も変わり、プログラムは実際に観測した長さを基にリピートの間隔を確認します。

使用例の完全なプログラム

ビルドコマンド

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqfc\kitaqfc.exe .\kitaqfc\lib\input.c .\kitaq-docs\samples\api-examples\fc\input_aliases.c -I .\kitaqfc\lib -I .\kitaq-docs\samples -o .\out\input_aliases.nes --mapper=nrom --nes-chr=.\kitaq-docs\samples\font.chr --no-disasm --no-cache

#define btn_down input_down

u8 input_down(u8 mask) { return (u8)((kq_input_keys & mask) != 0); }

btn_pressedはinput_pressedを呼ぶ別名です。直近の入力更新で新しく押されたボタンを調べます。

直近の入力更新で、mask のボタンが離された状態から押された状態へ変わったかを返します。

書式

u8 btn_pressed(u8 mask);

引数

mask

一つの BTN_*、または複数を | で組み合わせたマスクです。選んだボタンのどれかが該当すれば真になり、BTN_A | BTN_B で両方の同時押しを要求するわけではありません。マスク0は常に0を返します。すべての同時押しは (input_current() & mask) == mask で調べます。

戻り値

選択したボタンのどれかが調べる条件に合えば1、それ以外は0です。戻り値はボタンのビットマスクではありません。

使用条件と制限

ヘッダーの#defineで同じ実装名へ置き換わります。引数の評価、戻り値、状態の読み書きは参照先と同じで、別の状態や処理は追加しません。入力はinput.hとinput.c、システム制御はsystem.hとsystem.cを、完成サンプルのビルド例に従って使います。

共通マスクは BTN_RIGHT=0x01、BTN_LEFT=0x02、BTN_UP=0x04、BTN_DOWN=0x08、BTN_A=0x10、BTN_B=0x20、BTN_SELECT=0x40、BTN_START=0x80 です。ビット1が押下中を表します。GB・FCの input_* はこの形式ですが、FCの生のパッド関数は別のビット順です。

取得関数は直近の input_update() が保存した値を調べます。入力の再読込、押下イベントの消費、リピートタイマーの更新は行いません。同じ入力処理内で何度調べても結果は同じです。ボタンを押したまま input_update() を2回呼ぶと、2回目には押下イベントが消えます。

input_pressed