KITAQFC-BIBLIOTHEK

Prüft die Überlappung achsenparalleler Akteursrechtecke in Weltkoordinaten.

Syntax

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

Parameter

a

Erster Akteur.

b

Zweiter Akteur.

Rückgabewert

Gibt bei Überlappung 1 zurück, bei Trennung oder bloßer Kantenberührung 0.

Bedingungen und Grenzen

Verwenden Sie positive Breiten und Höhen und halten Sie Position+Größe≤65535. Bildschirmkoordinaten, attr und flags werden ignoriert.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Projizieren Sie Weltposition (300,95) durch Kamera (268,32): Rote und blaue 8×8-Teile erscheinen bei (32,64) und (40,64). Dies zeigt den rohen OAM-Y-Wert 63 als sichtbares Y=64 sowie den Wechsel des Kollisionsergebnisses von null bei Kantenberührung zu eins bei einem Pixel Überlappung.

Vollständiges Beispielprogramm

Build-Befehl

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

Schreibt mit den zwischengespeicherten Bildschirmkoordinaten des Akteurs ein Metasprite in das Schatten-OAM.

Syntax

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

Parameter

actor

Zeiger auf einen beschreibbaren NesActor.

oam_index

Erster Slot, 0..63; reservieren Sie Platz für alle Teile.

metasprite

Vier-Byte-Datensätze dx,dy,tile,attr; dx=255 beendet die Liste.

Rückgabewert

Gibt den nächsten OAM-Slotindex zurück, mit Umlauf am Ende der 64 Slots.

Bedingungen und Grenzen

Binden Sie runtime.c ein. Die Warteschlange kopiert Nutzdaten für eine spätere NMI oder eine sichere Übertragung bei ausgeschalteter Darstellung. Serialisieren Sie Erzeugung und Verbrauch. Geht bei mehreren Zeilen die Kapazität aus, bleiben zuvor aufgenommene Zeilen eingereiht.

Wendet die attr/flags-Felder des Akteurs nicht an. Y ist ein rohes OAM-Byte, daher liegt die sichtbare Oberkante ein Pixel tiefer. Zum Anzeigen des Schattenpuffers ist ein OAM-DMA erforderlich.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Projizieren Sie Weltposition (300,95) durch Kamera (268,32): Rote und blaue 8×8-Teile erscheinen bei (32,64) und (40,64). Dies zeigt den rohen OAM-Y-Wert 63 als sichtbares Y=64 sowie den Wechsel des Kollisionsergebnisses von null bei Kantenberührung zu eins bei einem Pixel Überlappung.

Vollständiges Beispielprogramm

Build-Befehl

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

Setzt Welt-X/Y eines Akteurs.

Syntax

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

Parameter

actor

Zeiger auf einen beschreibbaren NesActor.

x

Welt-X, 0..65535 Pixel.

y

Welt-Y, 0..65535 Pixel.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Aktualisiert screen_x/screen_y nicht. Rufen Sie update_screen zur Projektion durch die Kamera auf.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Projizieren Sie Weltposition (300,95) durch Kamera (268,32): Rote und blaue 8×8-Teile erscheinen bei (32,64) und (40,64). Dies zeigt den rohen OAM-Y-Wert 63 als sichtbares Y=64 sowie den Wechsel des Kollisionsergebnisses von null bei Kantenberührung zu eins bei einem Pixel Überlappung.

Vollständiges Beispielprogramm

Build-Befehl

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

Zieht Kamerakoordinaten von Weltkoordinaten ab und speichert die unteren Bytes als Bildschirmkoordinaten zwischen.

Syntax

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

Parameter

actor

Zeiger auf einen beschreibbaren NesActor.

camera_x

Welt-X der Kamera.

camera_y

Welt-Y der Kamera.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Negative Ergebnisse oder Werte ≥256 laufen um. Akteure außerhalb des Bildschirms werden nicht ausgeblendet; das Spiel muss sie vor dem Zeichnen aussortieren.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Projizieren Sie Weltposition (300,95) durch Kamera (268,32): Rote und blaue 8×8-Teile erscheinen bei (32,64) und (40,64). Dies zeigt den rohen OAM-Y-Wert 63 als sichtbares Y=64 sowie den Wechsel des Kollisionsergebnisses von null bei Kantenberührung zu eins bei einem Pixel Überlappung.

Vollständiges Beispielprogramm

Build-Befehl

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

Kopiert einen AssetDesc aus der ROM-Bank der registrierten Tabelle in den bereitgestellten Speicher. Damit werden die Metadaten der Ressource gelesen, nicht ihre Nutzdaten.

Syntax

u8 asset_get(u8 asset_id, AssetDesc* out_desc);

Parameter

asset_id

Ressourcenindex ab null. In der registrierten Tabelle gilt für eine gültige ID asset_id < count.

out_desc

Beschreibbarer Speicher für einen 6-Byte-Deskriptor. Ein Nullzeiger wird vor dem Tabellenzugriff zurückgewiesen.

Rückgabewert

1 nach dem Kopieren des Deskriptors; 0 bei Nullzeiger oder ungültiger ID. Bei diesen Fehlern bleibt der Zielspeicher unverändert.

Bedingungen und Grenzen

Registrieren Sie die Tabelle vor der ersten Suche. Die Registrierung ist ein gemeinsamer globaler Zustand und darf nicht gleichzeitig mit einer Suche geändert werden. Geprüft werden IDs und der Ausgabezeiger von asset_get, nicht jedoch Tabelle, Nutzdatenadressen oder Cartridge-Inhalt.

Die Beispiele legen den aufrufenden Code in die feste Bank 0, damit ein Wechsel der Quellbank den laufenden Code nicht ausblendet. Die Übertragungen sind synchron. Unterbrechen Sie sie nicht durch eine weitere bankwechselnde Kopie. Die Hilfsfunktion allein macht nicht die gesamte Anwendung interruptsicher.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel liest Deskriptor 0 und prüft Typ TILES, Bank 2, Zeiger und Länge 144 Byte. Ungültige IDs und Nullzeiger müssen scheitern; bei einer fehlgeschlagenen Suche bleibt der vorherige Ausgabewert erhalten.

Erwartetes Bild: Eine rote Reihe beginnt bei (16,32) und belegt 72×8 Pixel. Dreimal folgen ein 8×8-Dreieck, ein 8×8-Quadrat mit einem Pixel Rand und eine Kachel mit vier gefüllten linken Spalten. Das Dreieck wächst von einem Pixel oben links auf acht Pixel in der untersten Zeile.

Auf dem FC zeigt das blaue Paar bei (16,64) __far_memcpy, das grüne bei (16,96) asset_load_raw mit anschließender CHR-Übertragung. Jedes Paar belegt 16×8 Pixel auf schwarzem Hintergrund. So werden die kopierten Bilddaten sichtbar, nicht nur numerische Statuswerte.

Erwartet werden FAILED CHECKS 000 und FIRST FAILURE 00. Die Prüfung führt 300 Bilder aus und vergleicht Text, Formmasken und Farben mit den Sollwerten. Dies ist ein Emulatornachweis, kein Test auf physischer Hardware.

Vollständiges Beispielprogramm

Build-Befehl

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

Liest die Banknummer der Nutzdaten aus dem Deskriptor. Dies ist nicht die Banknummer der Tabelle. Nach dem Aufruf bleibt diese ROM-Bank auch nicht ausgewählt.

Syntax

u8 asset_get_bank(u8 asset_id);

Parameter

asset_id

Ressourcenindex ab null. In der registrierten Tabelle gilt für eine gültige ID asset_id < count.

Rückgabewert

Das 8-Bit-Feld bank oder 0, wenn die Suche scheitert. Bank null kann ebenfalls gültig sein. Nutzen Sie asset_get(), um den Erfolg unabhängig vom Wert zu erkennen.

Bedingungen und Grenzen

Registrieren Sie die Tabelle vor der ersten Suche. Die Registrierung ist ein gemeinsamer globaler Zustand und darf nicht gleichzeitig mit einer Suche geändert werden. Geprüft werden IDs und der Ausgabezeiger von asset_get, nicht jedoch Tabelle, Nutzdatenadressen oder Cartridge-Inhalt.

Jede Abfrage ruft erneut asset_get auf und kopiert einen Deskriptor. Wenn Bank, Zeiger und Länge gemeinsam benötigt werden, genügt ein Aufruf von asset_get mit anschließendem Lesen der Felder.

Die Beispiele legen den aufrufenden Code in die feste Bank 0, damit ein Wechsel der Quellbank den laufenden Code nicht ausblendet. Die Übertragungen sind synchron. Unterbrechen Sie sie nicht durch eine weitere bankwechselnde Kopie. Die Hilfsfunktion allein macht nicht die gesamte Anwendung interruptsicher.

Anwendungsbeispiel

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.

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Erwartet wird ROM-Bank 2 der Nutzdaten, obwohl die Tabelle in Bank 3 liegt. Zusätzlich muss eine ungültige ID null zurückgeben.

Erwartetes Bild: Eine rote Reihe beginnt bei (16,32) und belegt 72×8 Pixel. Dreimal folgen ein 8×8-Dreieck, ein 8×8-Quadrat mit einem Pixel Rand und eine Kachel mit vier gefüllten linken Spalten. Das Dreieck wächst von einem Pixel oben links auf acht Pixel in der untersten Zeile.

Auf dem FC zeigt das blaue Paar bei (16,64) __far_memcpy, das grüne bei (16,96) asset_load_raw mit anschließender CHR-Übertragung. Jedes Paar belegt 16×8 Pixel auf schwarzem Hintergrund. So werden die kopierten Bilddaten sichtbar, nicht nur numerische Statuswerte.

Erwartet werden FAILED CHECKS 000 und FIRST FAILURE 00. Die Prüfung führt 300 Bilder aus und vergleicht Text, Formmasken und Farben mit den Sollwerten. Dies ist ein Emulatornachweis, kein Test auf physischer Hardware.

Vollständiges Beispielprogramm

Build-Befehl

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

Liest die Länge der Ressource in Byte aus dem Deskriptor. Der Wert ist eine Metadatenangabe. Die Funktion untersucht keine Nutzdaten und rechnet die Länge nicht in Kacheln, Elemente oder Bilder um.

Syntax

u16 asset_get_len(u8 asset_id);

Parameter

asset_id

Ressourcenindex ab null. In der registrierten Tabelle gilt für eine gültige ID asset_id < count.

Rückgabewert

Das 16-Bit-Feld len in Byte oder 0 bei erfolgloser Suche. Auch eine leere Ressource hat Länge null. Unterscheiden Sie diese Fälle mit asset_get().

Bedingungen und Grenzen

Registrieren Sie die Tabelle vor der ersten Suche. Die Registrierung ist ein gemeinsamer globaler Zustand und darf nicht gleichzeitig mit einer Suche geändert werden. Geprüft werden IDs und der Ausgabezeiger von asset_get, nicht jedoch Tabelle, Nutzdatenadressen oder Cartridge-Inhalt.

Jede Abfrage ruft erneut asset_get auf und kopiert einen Deskriptor. Wenn Bank, Zeiger und Länge gemeinsam benötigt werden, genügt ein Aufruf von asset_get mit anschließendem Lesen der Felder.

Die Beispiele legen den aufrufenden Code in die feste Bank 0, damit ein Wechsel der Quellbank den laufenden Code nicht ausblendet. Die Übertragungen sind synchron. Unterbrechen Sie sie nicht durch eine weitere bankwechselnde Kopie. Die Hilfsfunktion allein macht nicht die gesamte Anwendung interruptsicher.

Anwendungsbeispiel

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.

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Die Ressource mit neun Kacheln muss 144 Byte melden, nicht neun Kacheln. Eine leere Ressource und eine ungültige ID müssen beide null liefern.

Erwartetes Bild: Eine rote Reihe beginnt bei (16,32) und belegt 72×8 Pixel. Dreimal folgen ein 8×8-Dreieck, ein 8×8-Quadrat mit einem Pixel Rand und eine Kachel mit vier gefüllten linken Spalten. Das Dreieck wächst von einem Pixel oben links auf acht Pixel in der untersten Zeile.

Auf dem FC zeigt das blaue Paar bei (16,64) __far_memcpy, das grüne bei (16,96) asset_load_raw mit anschließender CHR-Übertragung. Jedes Paar belegt 16×8 Pixel auf schwarzem Hintergrund. So werden die kopierten Bilddaten sichtbar, nicht nur numerische Statuswerte.

Erwartet werden FAILED CHECKS 000 und FIRST FAILURE 00. Die Prüfung führt 300 Bilder aus und vergleicht Text, Formmasken und Farben mit den Sollwerten. Dies ist ein Emulatornachweis, kein Test auf physischer Hardware.

Vollständiges Beispielprogramm

Build-Befehl

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

Liest die im Deskriptor gespeicherte 16-Bit-Adresse der Nutzdaten. Der zurückgegebene Nahzeiger enthält keine Banknummer. Verwenden Sie ihn zusammen mit asset_get_bank() und einer bankübergreifenden Kopierfunktion, um Daten aus einer anderen ROM-Bank zu lesen.

Syntax

const u8* asset_get_ptr(u8 asset_id);

Parameter

asset_id

Ressourcenindex ab null. In der registrierten Tabelle gilt für eine gültige ID asset_id < count.

Rückgabewert

Der gespeicherte const u8* oder ein Nullzeiger bei erfolgloser Suche. Der Nutzdatenzeiger im Deskriptor wird nicht auf null geprüft. Mit asset_get() lässt sich ein Suchfehler eindeutig erkennen.

Bedingungen und Grenzen

Registrieren Sie die Tabelle vor der ersten Suche. Die Registrierung ist ein gemeinsamer globaler Zustand und darf nicht gleichzeitig mit einer Suche geändert werden. Geprüft werden IDs und der Ausgabezeiger von asset_get, nicht jedoch Tabelle, Nutzdatenadressen oder Cartridge-Inhalt.

Jede Abfrage ruft erneut asset_get auf und kopiert einen Deskriptor. Wenn Bank, Zeiger und Länge gemeinsam benötigt werden, genügt ein Aufruf von asset_get mit anschließendem Lesen der Felder.

Die Beispiele legen den aufrufenden Code in die feste Bank 0, damit ein Wechsel der Quellbank den laufenden Code nicht ausblendet. Die Übertragungen sind synchron. Unterbrechen Sie sie nicht durch eine weitere bankwechselnde Kopie. Die Hilfsfunktion allein macht nicht die gesamte Anwendung interruptsicher.

Anwendungsbeispiel

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.

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Der Zeiger muss der nach dem Linken feststehenden ROM-Adresse entsprechen, während ein Marker in Bank 1 weiterhin lesbar ist. Danach werden Zeiger und ROM-Bank 2 an die bankübergreifende Kopie übergeben.

Erwartetes Bild: Eine rote Reihe beginnt bei (16,32) und belegt 72×8 Pixel. Dreimal folgen ein 8×8-Dreieck, ein 8×8-Quadrat mit einem Pixel Rand und eine Kachel mit vier gefüllten linken Spalten. Das Dreieck wächst von einem Pixel oben links auf acht Pixel in der untersten Zeile.

Auf dem FC zeigt das blaue Paar bei (16,64) __far_memcpy, das grüne bei (16,96) asset_load_raw mit anschließender CHR-Übertragung. Jedes Paar belegt 16×8 Pixel auf schwarzem Hintergrund. So werden die kopierten Bilddaten sichtbar, nicht nur numerische Statuswerte.

Erwartet werden FAILED CHECKS 000 und FIRST FAILURE 00. Die Prüfung führt 300 Bilder aus und vergleicht Text, Formmasken und Farben mit den Sollwerten. Dies ist ein Emulatornachweis, kein Test auf physischer Hardware.

Vollständiges Beispielprogramm

Build-Befehl

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

Sucht die Ressource und kopiert min(desc.len, max_len) Byte aus ihrer ROM-Bank in beschreibbaren Speicher. Der Typ wird nicht geprüft: Grafik-, Karten- und Musikdaten werden unverändert kopiert, ohne Dekodierung oder Dekomprimierung.

Syntax

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

Parameter

asset_id

Ressourcenindex ab null. In der registrierten Tabelle gilt für eine gültige ID asset_id < count.

dst

Ziel in beschreibbarem Speicher mit genügend Platz für alle kopierten Byte. Abgesehen von einem Transfer mit Länge null erfolgt keine Prüfung auf Nullzeiger oder ungültige Zieladressen.

max_len

Höchstens zu kopierende Byte, 0–65535. Eine kleinere Grenze kürzt die Kopie; bei null werden keine Nutzdaten kopiert.

Rückgabewert

0, wenn die Suche scheitert, sonst 1 – auch bei gekürzter Kopie, Grenze null oder leerer Ressource. Der Rückgabewert ist keine Byteanzahl und bestätigt nicht, dass die gesamte Ressource in den Puffer passte.

Bedingungen und Grenzen

Registrieren Sie die Tabelle vor der ersten Suche. Die Registrierung ist ein gemeinsamer globaler Zustand und darf nicht gleichzeitig mit einer Suche geändert werden. Geprüft werden IDs und der Ausgabezeiger von asset_get, nicht jedoch Tabelle, Nutzdatenadressen oder Cartridge-Inhalt.

Der gesamte Quellbereich muss in der vorgesehenen ROM-Zuordnung lesbar und der gesamte Zielbereich beschreibbar sein. Die Kopie schaltet am Fensterende nicht automatisch zur nächsten Bank, behandelt Überlappungen nicht wie memmove und steuert keine sicheren VRAM-Schreibzeitpunkte. Verwenden Sie für VRAM die Grafikübertragungs-APIs.

Die Beispiele legen den aufrufenden Code in die feste Bank 0, damit ein Wechsel der Quellbank den laufenden Code nicht ausblendet. Die Übertragungen sind synchron. Unterbrechen Sie sie nicht durch eine weitere bankwechselnde Kopie. Die Hilfsfunktion allein macht nicht die gesamte Anwendung interruptsicher.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Eine Grenze von sieben kopiert nur sieben Byte einer 144-Byte-Ressource und lässt das nächste Byte auf 0x55, meldet aber Erfolg. Außerdem werden vollständige Kopie, Grenze null, leere Ressource und das Kopieren von MAP-Daten geprüft.

Erwartetes Bild: Eine rote Reihe beginnt bei (16,32) und belegt 72×8 Pixel. Dreimal folgen ein 8×8-Dreieck, ein 8×8-Quadrat mit einem Pixel Rand und eine Kachel mit vier gefüllten linken Spalten. Das Dreieck wächst von einem Pixel oben links auf acht Pixel in der untersten Zeile.

Auf dem FC zeigt das blaue Paar bei (16,64) __far_memcpy, das grüne bei (16,96) asset_load_raw mit anschließender CHR-Übertragung. Jedes Paar belegt 16×8 Pixel auf schwarzem Hintergrund. So werden die kopierten Bilddaten sichtbar, nicht nur numerische Statuswerte.

Erwartet werden FAILED CHECKS 000 und FIRST FAILURE 00. Die Prüfung führt 300 Bilder aus und vergleicht Text, Formmasken und Farben mit den Sollwerten. Dies ist ein Emulatornachweis, kein Test auf physischer Hardware.

Vollständiges Beispielprogramm

Build-Befehl

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

Sucht eine RAW- oder TILES-Ressource, wählt deren ROM-Bank und überträgt sämtliche Daten mit __vram_write in Blöcken von höchstens 128 Byte. Anschließend wird die von bank_get_current() gespeicherte Bank wiederhergestellt. Zwischen den Blöcken wird nicht auf das nächste Bild gewartet.

Syntax

u8 asset_load_tiles(u8 asset_id, u16 vram_dst);

Parameter

asset_id

Ressourcenindex ab null. In der registrierten Tabelle gilt für eine gültige ID asset_id < count.

vram_dst

Byteadresse des PPU, keine CPU-Adresse oder Kachelnummer. Kachelmuster werden in beschreibbaren CHR RAM bei $0000–$1FFF geladen, mit 16 Byte je Kachel. Der gesamte Transfer muss im vorgesehenen PPU-Bereich bleiben.

Rückgabewert

0 bei ungültiger ID oder einem anderen Typ als RAW/TILES; 1 nach einem akzeptierten Transfer, auch bei Länge null. Erfolg bestätigt weder das Kachelformat noch die korrekte Darstellung im VRAM.

Bedingungen und Grenzen

Registrieren Sie die Tabelle vor der ersten Suche. Die Registrierung ist ein gemeinsamer globaler Zustand und darf nicht gleichzeitig mit einer Suche geändert werden. Geprüft werden IDs und der Ausgabezeiger von asset_get, nicht jedoch Tabelle, Nutzdatenadressen oder Cartridge-Inhalt.

Die Beispiele legen den aufrufenden Code in die feste Bank 0, damit ein Wechsel der Quellbank den laufenden Code nicht ausblendet. Die Übertragungen sind synchron. Unterbrechen Sie sie nicht durch eine weitere bankwechselnde Kopie. Die Hilfsfunktion allein macht nicht die gesamte Anwendung interruptsicher.

Der Transfer schreibt nur Bytes. Er platziert keine Kacheln auf der Karte, weist keine Farben zu und reserviert keinen VRAM. Kachelkarte und Paletten werden separat eingerichtet. Die Beispiele übertragen bei abgeschalteter Darstellung und schalten sie erst nach dem Bildaufbau ein.

asset_load_tiles stellt die von bank.c vermerkte Bank wieder her, keinen vom Mapper zurückgelesenen Wert. Initialisieren und pflegen Sie diesen Zustand mit bank_switch. Direkte Mapper-Zugriffe oder alleinige Aufrufe von __bankswitch aktualisieren den Bibliothekszustand nicht. Die Kopier-Intrinsic stellt separat den Compilerzustand wieder her.

Verwenden Sie beschreibbaren CHR RAM für Muster und schalten Sie die Darstellung bei langen Transfers ab. Innerhalb von VBlank muss der gesamte Vorgang in die verfügbare Zeit passen; 128-Byte-Blöcke gewährleisten das nicht. Das Beispiel nutzt --mapper=mmc1 --board=surom512. Bei generischen Boards erzeugt das Weglassen von --nes-chr leeren CHR ROM, keinen CHR RAM.

Anwendungsbeispiel

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.

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel lädt neun eigene Muster mit je 8×8 Pixeln, insgesamt 144 Byte, und prüft die Ablehnung von MAP und ungültigen IDs. Auf dem FC werden damit sowohl der 128-Byte-Block als auch die verbleibenden 16 Byte geprüft.

Erwartetes Bild: Eine rote Reihe beginnt bei (16,32) und belegt 72×8 Pixel. Dreimal folgen ein 8×8-Dreieck, ein 8×8-Quadrat mit einem Pixel Rand und eine Kachel mit vier gefüllten linken Spalten. Das Dreieck wächst von einem Pixel oben links auf acht Pixel in der untersten Zeile.

Auf dem FC zeigt das blaue Paar bei (16,64) __far_memcpy, das grüne bei (16,96) asset_load_raw mit anschließender CHR-Übertragung. Jedes Paar belegt 16×8 Pixel auf schwarzem Hintergrund. So werden die kopierten Bilddaten sichtbar, nicht nur numerische Statuswerte.

Erwartet werden FAILED CHECKS 000 und FIRST FAILURE 00. Die Prüfung führt 300 Bilder aus und vergleicht Text, Formmasken und Farben mit den Sollwerten. Dies ist ein Emulatornachweis, kein Test auf physischer Hardware.

Vollständiges Beispielprogramm

Build-Befehl

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

Registriert Banknummer, Adresse und Eintragszahl der einzigen aktiven Deskriptortabelle. Die Funktion speichert nur diese drei Werte. Sie kopiert weder die Tabelle noch Nutzdaten und reserviert keinen Speicher.

Syntax

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

Parameter

bank

8-Bit-Nummer der ROM-Bank mit der Deskriptortabelle, nicht mit den Nutzdaten.

table

Nahzeiger auf count aufeinanderfolgende AssetDesc-Einträge. Solange die Tabelle registriert ist, müssen alle count * 6 Byte in ihrer ROM-Bank lesbar bleiben.

count

Anzahl der Einträge, 0–255. Bei null ist keine ID gültig. Mit asset_set_table(0, 0, 0) lässt sich sicher eine leere Tabelle registrieren.

Rückgabewert

Keiner (void).

Bedingungen und Grenzen

Registrieren Sie die Tabelle vor der ersten Suche. Die Registrierung ist ein gemeinsamer globaler Zustand und darf nicht gleichzeitig mit einer Suche geändert werden. Geprüft werden IDs und der Ausgabezeiger von asset_get, nicht jedoch Tabelle, Nutzdatenadressen oder Cartridge-Inhalt.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel registriert vier Deskriptoren in Bank 3; ihre nicht leeren Nutzdaten liegen in Bank 2. Zusätzlich wird geprüft, dass die Suche in einer leeren Tabelle ohne Lesen von Adresse null scheitert.

Erwartetes Bild: Eine rote Reihe beginnt bei (16,32) und belegt 72×8 Pixel. Dreimal folgen ein 8×8-Dreieck, ein 8×8-Quadrat mit einem Pixel Rand und eine Kachel mit vier gefüllten linken Spalten. Das Dreieck wächst von einem Pixel oben links auf acht Pixel in der untersten Zeile.

Auf dem FC zeigt das blaue Paar bei (16,64) __far_memcpy, das grüne bei (16,96) asset_load_raw mit anschließender CHR-Übertragung. Jedes Paar belegt 16×8 Pixel auf schwarzem Hintergrund. So werden die kopierten Bilddaten sichtbar, nicht nur numerische Statuswerte.

Erwartet werden FAILED CHECKS 000 und FIRST FAILURE 00. Die Prüfung führt 300 Bilder aus und vergleicht Text, Formmasken und Farben mit den Sollwerten. Dies ist ein Emulatornachweis, kein Test auf physischer Hardware.

Vollständiges Beispielprogramm

Build-Befehl

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

Kopiert die ein Kachelrechteck abdeckenden Attributbytezeilen in die Warteschlange.

Syntax

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

Parameter

nt_base

Logische Nametable-Basis $2000/$2400/$2800/$2C00; die Spiegelung bestimmt die physische Unabhängigkeit.

tile_x

Linke Kachelspalte, sichtbarer Bereich 0..31.

tile_y

Obere Kachelzeile, sichtbarer Bereich 0..29.

width

Breite in Kacheln.

height

Höhe in Kacheln.

Rückgabewert

Gibt bei vollständiger Aufnahme oder leerem Rechteck 1 zurück, bei ungültigen Grenzen oder unzureichender Kapazität 0. Ungültige Grenzen reihen nichts ein.

Bedingungen und Grenzen

Der gemeinsame 64-Byte-Attributschattenpuffer belegt CPU-RAM $03E0..$041F. Reservieren Sie diesen Bereich. Ein Attributbyte deckt 4×4 Kacheln ab; jedes Zwei-Bit-Feld wählt die Palette für einen 2×2-Kachelquadranten.

Binden Sie runtime.c ein. Die Warteschlange kopiert Nutzdaten für eine spätere NMI oder eine sichere Übertragung bei ausgeschalteter Darstellung. Serialisieren Sie Erzeugung und Verbrauch. Geht bei mehreren Zeilen die Kapazität aus, bleiben zuvor aufgenommene Zeilen eingereiht.

Ein Attributbyte deckt 4×4 Kacheln ab. Betroffene Bytes werden vollständig übertragen; erhalten Sie daher im Schattenpuffer die richtigen Werte benachbarter Quadranten.

Anwendungsbeispiel

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();

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Lernen Sie rechteckige Attributübertragungen: Rot 32×32 bei (16,32), Blau 32×32 bei (80,32), Grün 16×16 rechts unten bei (240,224). Das Beispiel erhält benachbarte Quadranten und erreicht korrekt das letzte Attributbyte.

Vollständiges Beispielprogramm

Build-Befehl

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

Kopiert 64 bereits gepackte Attributbytes in den gemeinsamen Schattenpuffer.

Syntax

void nes_attr_shadow_build_from_palette_map(unsigned char* src64);

Parameter

src64

Lesbare, gepackte 64-Byte-Attributtabelle, kein Array einzelner Paletten-IDs je Kachel.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Der gemeinsame 64-Byte-Attributschattenpuffer belegt CPU-RAM $03E0..$041F. Reservieren Sie diesen Bereich. Ein Attributbyte deckt 4×4 Kacheln ab; jedes Zwei-Bit-Feld wählt die Palette für einen 2×2-Kachelquadranten.

Anwendungsbeispiel

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];

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Lernen Sie rechteckige Attributübertragungen: Rot 32×32 bei (16,32), Blau 32×32 bei (80,32), Grün 16×16 rechts unten bei (240,224). Das Beispiel erhält benachbarte Quadranten und erreicht korrekt das letzte Attributbyte.

Vollständiges Beispielprogramm

Build-Befehl

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

Ersetzt die Palettenfelder aller 2×2-Kachelquadranten, die ein Rechteck berührt.

Syntax

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

Parameter

tile_x

Linke Kachelspalte, sichtbarer Bereich 0..31.

tile_y

Obere Kachelzeile, sichtbarer Bereich 0..29.

width

Breite in Kacheln.

height

Höhe in Kacheln.

pal_index

Palettenindex; nur die unteren zwei Bits werden verwendet.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Der gemeinsame 64-Byte-Attributschattenpuffer belegt CPU-RAM $03E0..$041F. Reservieren Sie diesen Bereich. Ein Attributbyte deckt 4×4 Kacheln ab; jedes Zwei-Bit-Feld wählt die Palette für einen 2×2-Kachelquadranten.

Halten Sie das gesamte Rechteck innerhalb von 32×30 Kacheln. Leere oder ungültige Rechtecke ändern nichts. Ungerade Grenzen werden auf Quadrantengrenzen erweitert, sodass benachbarte Kacheln außerhalb ebenfalls die neue Palette erhalten können.

Anwendungsbeispiel

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];

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Lernen Sie rechteckige Attributübertragungen: Rot 32×32 bei (16,32), Blau 32×32 bei (80,32), Grün 16×16 rechts unten bei (240,224). Das Beispiel erhält benachbarte Quadranten und erreicht korrekt das letzte Attributbyte.

Vollständiges Beispielprogramm

Build-Befehl

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

Ersetzt den Aktivierungszustand aller fünf APU-Kanäle durch die angegebene Maske.

Syntax

void nes_apu_channel_enable(u8 mask);

Parameter

mask

Vollständige APU_STATUS-Aktivierungsmaske. Bits 0..4 wählen pulse1, pulse2, triangle, noise und DMC; obere Bits werden verworfen.

Rückgabewert

Kein Rückgabewert. Ändert Audioregister oder Treiberzustand.

Anwendungsbeispiel

// 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();
}

Erwartetes Ergebnis

Zu hören sind pulse1, pulse2, triangle, noise, tick und move. Timer 253 ergibt unter NTSC etwa 440-Hz-Pulse und ein 220-Hz-Dreieck. Tick liegt bei etwa 111 Hz, move bei etwa 174 Hz und endet früher. Der letzte Abschnitt ist still.

Vollständiges Beispielprogramm

Build-Befehl

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

Deaktiviert Frame-IRQ, aktiviert vier Stimmen und setzt stille Steuerwerte. DMC bleibt deaktiviert.

Syntax

void nes_apu_init(void);

Rückgabewert

Kein Rückgabewert. Ändert Audioregister oder Treiberzustand.

Anwendungsbeispiel

// 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();
}

Erwartetes Ergebnis

Zu hören sind pulse1, pulse2, triangle, noise, tick und move. Timer 253 ergibt unter NTSC etwa 440-Hz-Pulse und ein 220-Hz-Dreieck. Tick liegt bei etwa 111 Hz, move bei etwa 174 Hz und endet früher. Der letzte Abschnitt ist still.

Vollständiges Beispielprogramm

Build-Befehl

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

Deaktiviert alle Kanäle und löscht Puls-/Rauschlautstärke sowie DMC-Ausgabe.

Syntax

void nes_apu_silence_all(void);

Rückgabewert

Kein Rückgabewert. Ändert Audioregister oder Treiberzustand.

Anwendungsbeispiel

// 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();
}

Erwartetes Ergebnis

Zu hören sind pulse1, pulse2, triangle, noise, tick und move. Timer 253 ergibt unter NTSC etwa 440-Hz-Pulse und ein 220-Hz-Dreieck. Tick liegt bei etwa 111 Hz, move bei etwa 174 Hz und endet früher. Der letzte Abschnitt ist still.

Vollständiges Beispielprogramm

Build-Befehl

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

Konfiguriert DMC-Steuerung/-Ausgabe und wandelt Sampleadresse und -länge in Registereinheiten um.

Syntax

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

Parameter

flags_rate

DMC: Bit 7 IRQ, Bit 6 Schleife, unteres Halbbyte Ratenindex. Das Beispiel aktiviert IRQ nicht.

output_level

Anfänglicher DMC-Ausgabezähler 0..127; geschrieben werden nur die unteren sieben Bits.

sample_addr

CPU-Adresse der DMC-Daten: eine 64-Byte-Grenze in $C000..$FFC0.

sample_len

Bytelänge 16*n+1 in 1..4081. Übergeben Sie weder null noch eine nicht darstellbare Länge.

Rückgabewert

Kein Rückgabewert. Ändert Audioregister oder Treiberzustand.

Bedingungen und Grenzen

DMC liest ROM ab einer 64-Byte-Grenze in $C000..$FFC0. Die Länge beträgt 16*n+1 Bytes in 1..4081. Diese Hilfen prüfen weder Ausrichtung noch Bereiche und wechseln keine Banken. Das Beispiel legt eigene Daten mit __aligned(64) in der festen Bank 0 ab und prüft deren Lage zur Laufzeit.

Anwendungsbeispiel

// 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();
}

Erwartetes Ergebnis

Ein eigenes Deltamuster spielt mit Rate 10, pausiert und spielt dann schneller mit Rate 12. Der DMC-Stopp erhält den Ausgabezähler, daher kann die Pause einen Transienten enthalten. Der letzte Vorgang schaltet die gesamte APU stumm.

Vollständiges Beispielprogramm

Build-Befehl

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

Konfiguriert das DMC-Sample und startet sofort die Wiedergabe.

Syntax

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

Parameter

flags_rate

DMC: Bit 7 IRQ, Bit 6 Schleife, unteres Halbbyte Ratenindex. Das Beispiel aktiviert IRQ nicht.

output_level

Anfänglicher DMC-Ausgabezähler 0..127; geschrieben werden nur die unteren sieben Bits.

sample_addr

CPU-Adresse der DMC-Daten: eine 64-Byte-Grenze in $C000..$FFC0.

sample_len

Bytelänge 16*n+1 in 1..4081. Übergeben Sie weder null noch eine nicht darstellbare Länge.

Rückgabewert

Kein Rückgabewert. Ändert Audioregister oder Treiberzustand.

Bedingungen und Grenzen

DMC liest ROM ab einer 64-Byte-Grenze in $C000..$FFC0. Die Länge beträgt 16*n+1 Bytes in 1..4081. Diese Hilfen prüfen weder Ausrichtung noch Bereiche und wechseln keine Banken. Das Beispiel legt eigene Daten mit __aligned(64) in der festen Bank 0 ab und prüft deren Lage zur Laufzeit.

Anwendungsbeispiel

// 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();
}

Erwartetes Ergebnis

Ein eigenes Deltamuster spielt mit Rate 10, pausiert und spielt dann schneller mit Rate 12. Der DMC-Stopp erhält den Ausgabezähler, daher kann die Pause einen Transienten enthalten. Der letzte Vorgang schaltet die gesamte APU stumm.

Vollständiges Beispielprogramm

Build-Befehl

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

Schreibt APU_STATUS=0x1F und aktiviert DMC sowie alle vier anderen Stimmen.

Syntax

void nes_dmc_start(void);

Rückgabewert

Kein Rückgabewert. Ändert Audioregister oder Treiberzustand.

Bedingungen und Grenzen

DMC liest ROM ab einer 64-Byte-Grenze in $C000..$FFC0. Die Länge beträgt 16*n+1 Bytes in 1..4081. Diese Hilfen prüfen weder Ausrichtung noch Bereiche und wechseln keine Banken. Das Beispiel legt eigene Daten mit __aligned(64) in der festen Bank 0 ab und prüft deren Lage zur Laufzeit.

Anwendungsbeispiel

// 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();
}

Erwartetes Ergebnis

Ein eigenes Deltamuster spielt mit Rate 10, pausiert und spielt dann schneller mit Rate 12. Der DMC-Stopp erhält den Ausgabezähler, daher kann die Pause einen Transienten enthalten. Der letzte Vorgang schaltet die gesamte APU stumm.

Vollständiges Beispielprogramm

Build-Befehl

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

Schreibt APU_STATUS=0x0F, stoppt DMC und setzt die Aktivierungsbits aller vier anderen Stimmen.

Syntax

void nes_dmc_stop(void);

Rückgabewert

Kein Rückgabewert. Ändert Audioregister oder Treiberzustand.

Bedingungen und Grenzen

DMC liest ROM ab einer 64-Byte-Grenze in $C000..$FFC0. Die Länge beträgt 16*n+1 Bytes in 1..4081. Diese Hilfen prüfen weder Ausrichtung noch Bereiche und wechseln keine Banken. Das Beispiel legt eigene Daten mit __aligned(64) in der festen Bank 0 ab und prüft deren Lage zur Laufzeit.

Anwendungsbeispiel

// 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();
}

Erwartetes Ergebnis

Ein eigenes Deltamuster spielt mit Rate 10, pausiert und spielt dann schneller mit Rate 12. Der DMC-Stopp erhält den Ausgabezähler, daher kann die Pause einen Transienten enthalten. Der letzte Vorgang schaltet die gesamte APU stumm.

Vollständiges Beispielprogramm

Build-Befehl

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

Triggert Puls 1 mit Steuerwert 0x5A, Timer 0x0280 und Längenindex 2 für einen höheren, kürzeren Bewegungston.

Syntax

void nes_sfx_move_blip(void);

Rückgabewert

Kein Rückgabewert. Ändert Audioregister oder Treiberzustand.

Bedingungen und Grenzen

Diese Hilfe schreibt eine Einkanal-APU_STATUS-Maske und deaktiviert andere Stimmen; sie ist kein Mehrstimmenmischer. Bei Puls und Dreieck ist period ein Timerwert: Kleinere Werte erzeugen höhere Töne. Beispieltonhöhen und -dauern wurden mit NTSC-Timing geprüft.

Anwendungsbeispiel

// 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();
}

Erwartetes Ergebnis

Zu hören sind pulse1, pulse2, triangle, noise, tick und move. Timer 253 ergibt unter NTSC etwa 440-Hz-Pulse und ein 220-Hz-Dreieck. Tick liegt bei etwa 111 Hz, move bei etwa 174 Hz und endet früher. Der letzte Abschnitt ist still.

Vollständiges Beispielprogramm

Build-Befehl

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

Aktiviert nur Rauschen und schreibt Hüllkurve, Periode/Modus und Längenindex.

Syntax

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

Parameter

volume

Rohe Rauschsteuerung: Bit 5 Längenzählerstopp, Bit 4 konstante Lautstärke, unteres Halbbyte Lautstärke oder Hüllkurvenperiode.

period_mode

Rauschregister: Bit 7 Kurzmodus, unteres Halbbyte Periodentabellenindex.

length_index

Längentabellenindex 0..31, keine Frameanzahl. Nur die unteren fünf Bits erreichen das Register.

Rückgabewert

Kein Rückgabewert. Ändert Audioregister oder Treiberzustand.

Bedingungen und Grenzen

Diese Hilfe schreibt eine Einkanal-APU_STATUS-Maske und deaktiviert andere Stimmen; sie ist kein Mehrstimmenmischer. Bei Puls und Dreieck ist period ein Timerwert: Kleinere Werte erzeugen höhere Töne. Beispieltonhöhen und -dauern wurden mit NTSC-Timing geprüft.

Anwendungsbeispiel

// 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();
}

Erwartetes Ergebnis

Zu hören sind pulse1, pulse2, triangle, noise, tick und move. Timer 253 ergibt unter NTSC etwa 440-Hz-Pulse und ein 220-Hz-Dreieck. Tick liegt bei etwa 111 Hz, move bei etwa 174 Hz und endet früher. Der letzte Abschnitt ist still.

Vollständiges Beispielprogramm

Build-Befehl

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

Aktiviert nur Puls 1, deaktiviert Sweep und schreibt Steuerwert, Timer und Längenindex.

Syntax

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

Parameter

duty_volume

Rohe Pulssteuerung: Bits 7..6 Tastgrad, Bit 5 Längenzählerstopp, Bit 4 konstante Lautstärke, unteres Halbbyte Lautstärke oder Hüllkurvenperiode.

period

11-Bit-Timer 0..2047. Pulsfrequenz: CPU-Takt/[16*(period+1)]; Dreieckfrequenz: CPU-Takt/[32*(period+1)].

length_index

Längentabellenindex 0..31, keine Frameanzahl. Nur die unteren fünf Bits erreichen das Register.

Rückgabewert

Kein Rückgabewert. Ändert Audioregister oder Treiberzustand.

Bedingungen und Grenzen

Diese Hilfe schreibt eine Einkanal-APU_STATUS-Maske und deaktiviert andere Stimmen; sie ist kein Mehrstimmenmischer. Bei Puls und Dreieck ist period ein Timerwert: Kleinere Werte erzeugen höhere Töne. Beispieltonhöhen und -dauern wurden mit NTSC-Timing geprüft.

Anwendungsbeispiel

// 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();
}

Erwartetes Ergebnis

Zu hören sind pulse1, pulse2, triangle, noise, tick und move. Timer 253 ergibt unter NTSC etwa 440-Hz-Pulse und ein 220-Hz-Dreieck. Tick liegt bei etwa 111 Hz, move bei etwa 174 Hz und endet früher. Der letzte Abschnitt ist still.

Vollständiges Beispielprogramm

Build-Befehl

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

Aktiviert nur Puls 2, deaktiviert Sweep und schreibt Steuerwert, Timer und Längenindex.

Syntax

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

Parameter

duty_volume

Rohe Pulssteuerung: Bits 7..6 Tastgrad, Bit 5 Längenzählerstopp, Bit 4 konstante Lautstärke, unteres Halbbyte Lautstärke oder Hüllkurvenperiode.

period

11-Bit-Timer 0..2047. Pulsfrequenz: CPU-Takt/[16*(period+1)]; Dreieckfrequenz: CPU-Takt/[32*(period+1)].

length_index

Längentabellenindex 0..31, keine Frameanzahl. Nur die unteren fünf Bits erreichen das Register.

Rückgabewert

Kein Rückgabewert. Ändert Audioregister oder Treiberzustand.

Bedingungen und Grenzen

Diese Hilfe schreibt eine Einkanal-APU_STATUS-Maske und deaktiviert andere Stimmen; sie ist kein Mehrstimmenmischer. Bei Puls und Dreieck ist period ein Timerwert: Kleinere Werte erzeugen höhere Töne. Beispieltonhöhen und -dauern wurden mit NTSC-Timing geprüft.

Anwendungsbeispiel

// 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();
}

Erwartetes Ergebnis

Zu hören sind pulse1, pulse2, triangle, noise, tick und move. Timer 253 ergibt unter NTSC etwa 440-Hz-Pulse und ein 220-Hz-Dreieck. Tick liegt bei etwa 111 Hz, move bei etwa 174 Hz und endet früher. Der letzte Abschnitt ist still.

Vollständiges Beispielprogramm

Build-Befehl

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

Triggert Puls 1 mit Steuerwert 0x9A, Timer 0x03F0 und Längenindex 4 für einen kurzen tiefen Tick.

Syntax

void nes_sfx_tick_blip(void);

Rückgabewert

Kein Rückgabewert. Ändert Audioregister oder Treiberzustand.

Bedingungen und Grenzen

Diese Hilfe schreibt eine Einkanal-APU_STATUS-Maske und deaktiviert andere Stimmen; sie ist kein Mehrstimmenmischer. Bei Puls und Dreieck ist period ein Timerwert: Kleinere Werte erzeugen höhere Töne. Beispieltonhöhen und -dauern wurden mit NTSC-Timing geprüft.

Anwendungsbeispiel

// 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();
}

Erwartetes Ergebnis

Zu hören sind pulse1, pulse2, triangle, noise, tick und move. Timer 253 ergibt unter NTSC etwa 440-Hz-Pulse und ein 220-Hz-Dreieck. Tick liegt bei etwa 111 Hz, move bei etwa 174 Hz und endet früher. Der letzte Abschnitt ist still.

Vollständiges Beispielprogramm

Build-Befehl

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

Aktiviert nur Dreieck und schreibt Linearcounter, Timer und Längenindex.

Syntax

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

Parameter

linear

Dreieck-Linearcounter: Bit 7 Steuerung/Längenstopp, untere sieben Bits Nachladewert.

period

11-Bit-Timer 0..2047. Pulsfrequenz: CPU-Takt/[16*(period+1)]; Dreieckfrequenz: CPU-Takt/[32*(period+1)].

length_index

Längentabellenindex 0..31, keine Frameanzahl. Nur die unteren fünf Bits erreichen das Register.

Rückgabewert

Kein Rückgabewert. Ändert Audioregister oder Treiberzustand.

Bedingungen und Grenzen

Diese Hilfe schreibt eine Einkanal-APU_STATUS-Maske und deaktiviert andere Stimmen; sie ist kein Mehrstimmenmischer. Bei Puls und Dreieck ist period ein Timerwert: Kleinere Werte erzeugen höhere Töne. Beispieltonhöhen und -dauern wurden mit NTSC-Timing geprüft.

Anwendungsbeispiel

// 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();
}

Erwartetes Ergebnis

Zu hören sind pulse1, pulse2, triangle, noise, tick und move. Timer 253 ergibt unter NTSC etwa 440-Hz-Pulse und ein 220-Hz-Dreieck. Tick liegt bei etwa 111 Hz, move bei etwa 174 Hz und endet früher. Der letzte Abschnitt ist still.

Vollständiges Beispielprogramm

Build-Befehl

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

Liefert die zuletzt von bank_switch gespeicherte Banknummer. Gelesen wird der Softwarezustand, nicht ein Register des Moduls.

Syntax

u8 bank_get_current(void);

Rückgabewert

Der zuletzt von bank_switch gespeicherte u8-Wert; vor der Initialisierung null.

Bedingungen und Grenzen

Der Bibliothekszustand beginnt bei null und erkennt die Startzuordnung des Moduls nicht. Initialisieren Sie ihn mit bank_switch. Direkte Intrinsics und Mapper-Schreibzugriffe aktualisieren diesen separaten Zustand nicht; bank_get_current kann die tatsächliche Hardwarezuordnung daher nicht prüfen.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Der anfängliche Aufruf bank_switch(2) speichert und wählt Bank 2. Ein späterer direkter Wechsel wählt Bank 1 und liest A1 aus home1, während bank_get_current weiterhin 2 meldet. Nach dem Zurückschalten liefert home2 wieder B2.

Das vollständige Programm zeigt Datenzugriffe über Bank und Nahadresse, bankübergreifende Callbacks und den Unterschied zwischen Bibliothekszustand und tatsächlicher Zuordnung. Alle Zahlen sind hexadezimal. BANK IN und BANK OUT müssen 02 zeigen, BYTE HEX D3, WORD HEX 5C7A sowie FAILED CHECKS und FIRST FAILURE jeweils 00. CGB und FC zeigen blaue Schrift, DMG schwarze.

CALL COUNT zeigt 02: Das Makro far_call und __farcall rufen den Callback jeweils einmal auf.

Vollständiges Beispielprogramm

Build-Befehl

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

Speichert die angeforderte Bank in der Bibliothek und wählt sie anschließend über die zum Mapper passende PRG-Umschaltung des Compilers.

Syntax

void bank_switch(u8 bank);

Parameter

bank

Vorzeichenlose 8-Bit-ROM-Banknummer. Bei Aufrufen muss sie zur Funktionsplatzierung passen, bei Lesezugriffen wählt sie die Quelle. Verwenden Sie den gültigen Bereich des Modultyps.

Rückgabewert

Keiner (void).

Bedingungen und Grenzen

Ein dauerhafter Bankwechsel darf weder den laufenden Code noch seine Rückkehradresse ausblenden. Legen Sie den Aufruf, gegebenenfalls bank_switch selbst und den anschließend ausgeführten Code wie im Beispiel in die gemeinsame beziehungsweise feste Bank 0.

Der Bibliothekszustand beginnt bei null und erkennt die Startzuordnung des Moduls nicht. Initialisieren Sie ihn mit bank_switch. Direkte Intrinsics und Mapper-Schreibzugriffe aktualisieren diesen separaten Zustand nicht; bank_get_current kann die tatsächliche Hardwarezuordnung daher nicht prüfen.

FC-Banknummern sind logische Nummern des Compilers. Null bezeichnet gemeinsames ROM, kein Umschaltziel; die Hilfsroutine setzt null auf Bank 1 um. Bei SUROM512 sind nur 1–30 gültig: Eine direkt an das Umschalt-Intrinsic übergebene Konstante außerhalb des Bereichs führt zu einem Buildfehler; ein ungültiger Laufzeitwert wählt 1 und setzt den Mapper-Fehlerzustand. Lesen Sie gemeinsames ROM direkt, statt Bank null anzufordern.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Der anfängliche Aufruf bank_switch(2) speichert und wählt Bank 2. Ein späterer direkter Wechsel wählt Bank 1 und liest A1 aus home1, während bank_get_current weiterhin 2 meldet. Nach dem Zurückschalten liefert home2 wieder B2.

Das vollständige Programm zeigt Datenzugriffe über Bank und Nahadresse, bankübergreifende Callbacks und den Unterschied zwischen Bibliothekszustand und tatsächlicher Zuordnung. Alle Zahlen sind hexadezimal. BANK IN und BANK OUT müssen 02 zeigen, BYTE HEX D3, WORD HEX 5C7A sowie FAILED CHECKS und FIRST FAILURE jeweils 00. CGB und FC zeigen blaue Schrift, DMG schwarze.

CALL COUNT zeigt 02: Das Makro far_call und __farcall rufen den Callback jeweils einmal auf.

Vollständiges Beispielprogramm

Build-Befehl

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

Wird zu __farcall((bank), func) expandiert. Das Makro erhält das Ziel als für den Compiler sichtbaren Funktionsnamen; es ist kein indirekter Aufruf über einen Callback-Zeiger.

Syntax

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

Parameter

bank

Vorzeichenlose 8-Bit-ROM-Banknummer. Bei Aufrufen muss sie zur Funktionsplatzierung passen, bei Lesezugriffen wählt sie die Quelle. Verwenden Sie den gültigen Bereich des Modultyps.

func

Deklarierter Name einer Funktion ohne Parameter. Dieses Intrinsic für benannte Aufrufe akzeptiert keine Variable mit einer Funktionsadresse. Das Argument bank wird nicht als Callback-Parameter weitergereicht.

Rückgabewert

Der Ergebnistyp richtet sich nach der aufgerufenen Funktion. Ein void-Callback liefert keinen Wert; u8- und u16-Callbacks liefern ihren Skalarwert. Das gezeigte Beispiel verwendet void-Callbacks.

Bedingungen und Grenzen

Diese Aufrufe reichen keine Benutzerargumente weiter und machen den Callback nicht interrupt-reentrant. Verwalten Sie seine Daten, seinen Stack und seine Interruptnutzung korrekt. Die Bankwiederherstellung ist mit verschachtelten und wiederholten Aufrufen geprüft; reale Hardware und beliebige Interruptverschachtelungen deckt dieses Beispiel nicht ab.

FC-Banknummern sind logische Nummern des Compilers. Null bezeichnet gemeinsames ROM, kein Umschaltziel; die Hilfsroutine setzt null auf Bank 1 um. Bei SUROM512 sind nur 1–30 gültig: Eine direkt an das Umschalt-Intrinsic übergebene Konstante außerhalb des Bereichs führt zu einem Buildfehler; ein ungültiger Laufzeitwert wählt 1 und setzt den Mapper-Fehlerzustand. Lesen Sie gemeinsames ROM direkt, statt Bank null anzufordern.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

An dieser Stelle des vollständigen Programms erhöht far_call den Wert von callback_count auf 1. Der Callback liest D3 aus Bank 3. Ein späterer Nahzugriff auf home2 mit Ergebnis B2 bestätigt die Rückkehr bei eingeblendeter Bank 2.

Das vollständige Programm zeigt Datenzugriffe über Bank und Nahadresse, bankübergreifende Callbacks und den Unterschied zwischen Bibliothekszustand und tatsächlicher Zuordnung. Alle Zahlen sind hexadezimal. BANK IN und BANK OUT müssen 02 zeigen, BYTE HEX D3, WORD HEX 5C7A sowie FAILED CHECKS und FIRST FAILURE jeweils 00. CGB und FC zeigen blaue Schrift, DMG schwarze.

CALL COUNT zeigt 02: Das Makro far_call und __farcall rufen den Callback jeweils einmal auf.

Vollständiges Beispielprogramm

Build-Befehl

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

Kopiert über das Fernspeicher-Intrinsic len Bytes aus der angegebenen ROM-Bank in den RAM-Puffer des Aufrufers. Vor der Rückkehr wird die vorherige Bank wiederhergestellt.

Syntax

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

Parameter

bank

Vorzeichenlose 8-Bit-ROM-Banknummer. Bei Aufrufen muss sie zur Funktionsplatzierung passen, bei Lesezugriffen wählt sie die Quelle. Verwenden Sie den gültigen Bereich des Modultyps.

addr

Nahzeiger auf lesbare Bytes in der gewählten ROM-Bank. Er enthält keine Banknummer.

dst

Ziel in beschreibbarem Speicher mit genügend Platz für alle kopierten Byte. Abgesehen von einem Transfer mit Länge null erfolgt keine Prüfung auf Nullzeiger oder ungültige Zieladressen.

len

Byteanzahl, 0–65535. Bei null wird kein Speicher kopiert; Bankauswahl und Wiederherstellung werden trotzdem ausgeführt.

Rückgabewert

Keiner (void).

Bedingungen und Grenzen

Der gesamte Quellbereich muss in der vorgesehenen ROM-Zuordnung lesbar und der gesamte Zielbereich beschreibbar sein. Die Kopie schaltet am Fensterende nicht automatisch zur nächsten Bank, behandelt Überlappungen nicht wie memmove und steuert keine sicheren VRAM-Schreibzeitpunkte. Verwenden Sie für VRAM die Grafikübertragungs-APIs.

Fernlesezugriffe und Kopien arbeiten synchron und nutzen gemeinsamen Arbeitsspeicher des Compilers. Ein Interrupt darf währenddessen keinen weiteren Banktransfer über denselben Speicher ausführen. Auf GB nutzt die Kopierhilfe außerdem einen gemeinsamen HRAM-Platz für die gespeicherte Bank. Das Beispiel führt die Operationen aus festem Code ohne konkurrierenden Transfer-Handler aus.

FC-Banknummern sind logische Nummern des Compilers. Null bezeichnet gemeinsames ROM, kein Umschaltziel; die Hilfsroutine setzt null auf Bank 1 um. Bei SUROM512 sind nur 1–30 gültig: Eine direkt an das Umschalt-Intrinsic übergebene Konstante außerhalb des Bereichs führt zu einem Buildfehler; ein ungültiger Laufzeitwert wählt 1 und setzt den Mapper-Fehlerzustand. Lesen Sie gemeinsames ROM direkt, statt Bank null anzufordern.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Dieser Ausschnitt kopiert mit far_data_read 4 Bytes und prüft den Puffer gegen D3 7A 5C 96. Quelldeskriptor oder Quellzeiger des Aufrufers bleiben erhalten; das vollständige Programm prüft zusätzlich eine Kopie der Länge null und die Bankwiederherstellung.

Das vollständige Programm zeigt Datenzugriffe über Bank und Nahadresse, bankübergreifende Callbacks und den Unterschied zwischen Bibliothekszustand und tatsächlicher Zuordnung. Alle Zahlen sind hexadezimal. BANK IN und BANK OUT müssen 02 zeigen, BYTE HEX D3, WORD HEX 5C7A sowie FAILED CHECKS und FIRST FAILURE jeweils 00. CGB und FC zeigen blaue Schrift, DMG schwarze.

CALL COUNT zeigt 02: Das Makro far_call und __farcall rufen den Callback jeweils einmal auf.

Vollständiges Beispielprogramm

Build-Befehl

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

Liest mit __farpeek16 zwei aufeinanderfolgende Bytes als Little-Endian-Wort. Das erste Byte bildet die unteren acht Bits.

Syntax

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

Parameter

bank

Vorzeichenlose 8-Bit-ROM-Banknummer. Bei Aufrufen muss sie zur Funktionsplatzierung passen, bei Lesezugriffen wählt sie die Quelle. Verwenden Sie den gültigen Bereich des Modultyps.

addr

Nahzeiger auf lesbare Bytes in der gewählten ROM-Bank. Er enthält keine Banknummer.

Rückgabewert

Das gelesene Little-Endian-Wort als u16 (0–65535).

Bedingungen und Grenzen

Das gesamte Byte oder Wort muss in der gewählten CPU-Zuordnung lesbar sein. Zeiger werden nicht geprüft, Adressen nicht begrenzt und Fenstergrenzen lösen keinen automatischen Wechsel zur nächsten ROM-Bank aus. Ein Wort benötigt zwei gültige aufeinanderfolgende Bytes.

Fernlesezugriffe und Kopien arbeiten synchron und nutzen gemeinsamen Arbeitsspeicher des Compilers. Ein Interrupt darf währenddessen keinen weiteren Banktransfer über denselben Speicher ausführen. Auf GB nutzt die Kopierhilfe außerdem einen gemeinsamen HRAM-Platz für die gespeicherte Bank. Das Beispiel führt die Operationen aus festem Code ohne konkurrierenden Transfer-Handler aus.

FC-Banknummern sind logische Nummern des Compilers. Null bezeichnet gemeinsames ROM, kein Umschaltziel; die Hilfsroutine setzt null auf Bank 1 um. Bei SUROM512 sind nur 1–30 gültig: Eine direkt an das Umschalt-Intrinsic übergebene Konstante außerhalb des Bereichs führt zu einem Buildfehler; ein ungültiger Laufzeitwert wählt 1 und setzt den Mapper-Fehlerzustand. Lesen Sie gemeinsames ROM direkt, statt Bank null anzufordern.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Dieser Ausschnitt liest mit far_data_read16 den Ausdruck payload+1 in Bank 3 und prüft 5C7A. Das vollständige Programm bestätigt durch einen Nahzugriff auf home2 außerdem die Wiederherstellung von Bank 2.

Das vollständige Programm zeigt Datenzugriffe über Bank und Nahadresse, bankübergreifende Callbacks und den Unterschied zwischen Bibliothekszustand und tatsächlicher Zuordnung. Alle Zahlen sind hexadezimal. BANK IN und BANK OUT müssen 02 zeigen, BYTE HEX D3, WORD HEX 5C7A sowie FAILED CHECKS und FIRST FAILURE jeweils 00. CGB und FC zeigen blaue Schrift, DMG schwarze.

CALL COUNT zeigt 02: Das Makro far_call und __farcall rufen den Callback jeweils einmal auf.

Vollständiges Beispielprogramm

Build-Befehl

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

Liest über __farpeek8 ein Byte aus der angegebenen ROM-Bank und Adresse, stellt die vorherige Bank wieder her und liefert den Wert.

Syntax

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

Parameter

bank

Vorzeichenlose 8-Bit-ROM-Banknummer. Bei Aufrufen muss sie zur Funktionsplatzierung passen, bei Lesezugriffen wählt sie die Quelle. Verwenden Sie den gültigen Bereich des Modultyps.

addr

Nahzeiger auf lesbare Bytes in der gewählten ROM-Bank. Er enthält keine Banknummer.

Rückgabewert

Das gelesene Byte als u8 (0–255).

Bedingungen und Grenzen

Das gesamte Byte oder Wort muss in der gewählten CPU-Zuordnung lesbar sein. Zeiger werden nicht geprüft, Adressen nicht begrenzt und Fenstergrenzen lösen keinen automatischen Wechsel zur nächsten ROM-Bank aus. Ein Wort benötigt zwei gültige aufeinanderfolgende Bytes.

Fernlesezugriffe und Kopien arbeiten synchron und nutzen gemeinsamen Arbeitsspeicher des Compilers. Ein Interrupt darf währenddessen keinen weiteren Banktransfer über denselben Speicher ausführen. Auf GB nutzt die Kopierhilfe außerdem einen gemeinsamen HRAM-Platz für die gespeicherte Bank. Das Beispiel führt die Operationen aus festem Code ohne konkurrierenden Transfer-Handler aus.

FC-Banknummern sind logische Nummern des Compilers. Null bezeichnet gemeinsames ROM, kein Umschaltziel; die Hilfsroutine setzt null auf Bank 1 um. Bei SUROM512 sind nur 1–30 gültig: Eine direkt an das Umschalt-Intrinsic übergebene Konstante außerhalb des Bereichs führt zu einem Buildfehler; ein ungültiger Laufzeitwert wählt 1 und setzt den Mapper-Fehlerzustand. Lesen Sie gemeinsames ROM direkt, statt Bank null anzufordern.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Dieser Ausschnitt liest mit far_data_read8 den Ausdruck payload in Bank 3 und prüft D3. Das vollständige Programm bestätigt durch einen Nahzugriff auf home2 außerdem die Wiederherstellung von Bank 2.

Das vollständige Programm zeigt Datenzugriffe über Bank und Nahadresse, bankübergreifende Callbacks und den Unterschied zwischen Bibliothekszustand und tatsächlicher Zuordnung. Alle Zahlen sind hexadezimal. BANK IN und BANK OUT müssen 02 zeigen, BYTE HEX D3, WORD HEX 5C7A sowie FAILED CHECKS und FIRST FAILURE jeweils 00. CGB und FC zeigen blaue Schrift, DMG schwarze.

CALL COUNT zeigt 02: Das Makro far_call und __farcall rufen den Callback jeweils einmal auf.

Vollständiges Beispielprogramm

Build-Befehl

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

Speichert ein Bankbyte und einen CPU-sichtbaren Zeiger im BankPtr des Aufrufers. Dabei entsteht nur ein Deskriptor; weder wird die Bank umgeschaltet noch werden die referenzierten Daten gelesen.

Syntax

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

Parameter

out

Zeiger auf beschreibbaren Speicher für einen drei Byte großen BankPtr. Ein Nullzeiger für out führt zu keiner Schreiboperation.

bank

Vorzeichenlose 8-Bit-ROM-Banknummer. Bei Aufrufen muss sie zur Funktionsplatzierung passen, bei Lesezugriffen wählt sie die Quelle. Verwenden Sie den gültigen Bereich des Modultyps.

ptr

Im Deskriptor zu speichernde CPU-sichtbare 16-Bit-Adresse. Sie wird unverändert übernommen; ihre Gültigkeit in der gewählten Bank wird nicht geprüft.

Rückgabewert

Keiner (void).

Anwendungsbeispiel

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.

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Der Deskriptor erhält Bank 3 und payload+1. Seine Leseoperationen liefern 7A, 5C7A und die drei Bytes 7A 5C 96. Der Aufruf mit Nullausgabe darf keinen Zustand ändern.

Das vollständige Programm zeigt Datenzugriffe über Bank und Nahadresse, bankübergreifende Callbacks und den Unterschied zwischen Bibliothekszustand und tatsächlicher Zuordnung. Alle Zahlen sind hexadezimal. BANK IN und BANK OUT müssen 02 zeigen, BYTE HEX D3, WORD HEX 5C7A sowie FAILED CHECKS und FIRST FAILURE jeweils 00. CGB und FC zeigen blaue Schrift, DMG schwarze.

CALL COUNT zeigt 02: Das Makro far_call und __farcall rufen den Callback jeweils einmal auf.

Vollständiges Beispielprogramm

Build-Befehl

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

Kopiert len Bytes von einem BankPtr in beschreibbaren RAM. Da der Deskriptor als Wert übergeben wird, zeigt der Zeiger des Aufrufers weiterhin auf den Anfang der Quelle.

Syntax

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

Parameter

ptr

Ein BankPtr-Wert mit den Feldern bank und ptr. Übergeben Sie den Deskriptor selbst, nicht seine Adresse. Der Deskriptor des Aufrufers bleibt unverändert.

dst

Ziel in beschreibbarem Speicher mit genügend Platz für alle kopierten Byte. Abgesehen von einem Transfer mit Länge null erfolgt keine Prüfung auf Nullzeiger oder ungültige Zieladressen.

len

Byteanzahl, 0–65535. Bei null wird kein Speicher kopiert; Bankauswahl und Wiederherstellung werden trotzdem ausgeführt.

Rückgabewert

Keiner (void).

Bedingungen und Grenzen

Der gesamte Quellbereich muss in der vorgesehenen ROM-Zuordnung lesbar und der gesamte Zielbereich beschreibbar sein. Die Kopie schaltet am Fensterende nicht automatisch zur nächsten Bank, behandelt Überlappungen nicht wie memmove und steuert keine sicheren VRAM-Schreibzeitpunkte. Verwenden Sie für VRAM die Grafikübertragungs-APIs.

Fernlesezugriffe und Kopien arbeiten synchron und nutzen gemeinsamen Arbeitsspeicher des Compilers. Ein Interrupt darf währenddessen keinen weiteren Banktransfer über denselben Speicher ausführen. Auf GB nutzt die Kopierhilfe außerdem einen gemeinsamen HRAM-Platz für die gespeicherte Bank. Das Beispiel führt die Operationen aus festem Code ohne konkurrierenden Transfer-Handler aus.

FC-Banknummern sind logische Nummern des Compilers. Null bezeichnet gemeinsames ROM, kein Umschaltziel; die Hilfsroutine setzt null auf Bank 1 um. Bei SUROM512 sind nur 1–30 gültig: Eine direkt an das Umschalt-Intrinsic übergebene Konstante außerhalb des Bereichs führt zu einem Buildfehler; ein ungültiger Laufzeitwert wählt 1 und setzt den Mapper-Fehlerzustand. Lesen Sie gemeinsames ROM direkt, statt Bank null anzufordern.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Dieser Ausschnitt kopiert mit farptr_read 3 Bytes und prüft den Puffer gegen 7A 5C 96. Quelldeskriptor oder Quellzeiger des Aufrufers bleiben erhalten; das vollständige Programm prüft zusätzlich eine Kopie der Länge null und die Bankwiederherstellung.

Das vollständige Programm zeigt Datenzugriffe über Bank und Nahadresse, bankübergreifende Callbacks und den Unterschied zwischen Bibliothekszustand und tatsächlicher Zuordnung. Alle Zahlen sind hexadezimal. BANK IN und BANK OUT müssen 02 zeigen, BYTE HEX D3, WORD HEX 5C7A sowie FAILED CHECKS und FIRST FAILURE jeweils 00. CGB und FC zeigen blaue Schrift, DMG schwarze.

CALL COUNT zeigt 02: Das Makro far_call und __farcall rufen den Callback jeweils einmal auf.

Vollständiges Beispielprogramm

Build-Befehl

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

Liest ein Little-Endian-Wort aus Bank und Adresse eines BankPtr. Der Deskriptor wird als Wert übergeben; sein Zeiger wird nicht weitergesetzt.

Syntax

u16 farptr_read16(BankPtr ptr);

Parameter

ptr

Ein BankPtr-Wert mit den Feldern bank und ptr. Übergeben Sie den Deskriptor selbst, nicht seine Adresse. Der Deskriptor des Aufrufers bleibt unverändert.

Rückgabewert

Das gelesene Little-Endian-Wort als u16 (0–65535).

Bedingungen und Grenzen

Das gesamte Byte oder Wort muss in der gewählten CPU-Zuordnung lesbar sein. Zeiger werden nicht geprüft, Adressen nicht begrenzt und Fenstergrenzen lösen keinen automatischen Wechsel zur nächsten ROM-Bank aus. Ein Wort benötigt zwei gültige aufeinanderfolgende Bytes.

Fernlesezugriffe und Kopien arbeiten synchron und nutzen gemeinsamen Arbeitsspeicher des Compilers. Ein Interrupt darf währenddessen keinen weiteren Banktransfer über denselben Speicher ausführen. Auf GB nutzt die Kopierhilfe außerdem einen gemeinsamen HRAM-Platz für die gespeicherte Bank. Das Beispiel führt die Operationen aus festem Code ohne konkurrierenden Transfer-Handler aus.

FC-Banknummern sind logische Nummern des Compilers. Null bezeichnet gemeinsames ROM, kein Umschaltziel; die Hilfsroutine setzt null auf Bank 1 um. Bei SUROM512 sind nur 1–30 gültig: Eine direkt an das Umschalt-Intrinsic übergebene Konstante außerhalb des Bereichs führt zu einem Buildfehler; ein ungültiger Laufzeitwert wählt 1 und setzt den Mapper-Fehlerzustand. Lesen Sie gemeinsames ROM direkt, statt Bank null anzufordern.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Dieser Ausschnitt liest mit farptr_read16 den Ausdruck pointer.ptr in Bank 3 und prüft 5C7A. Das vollständige Programm bestätigt durch einen Nahzugriff auf home2 außerdem die Wiederherstellung von Bank 2.

Das vollständige Programm zeigt Datenzugriffe über Bank und Nahadresse, bankübergreifende Callbacks und den Unterschied zwischen Bibliothekszustand und tatsächlicher Zuordnung. Alle Zahlen sind hexadezimal. BANK IN und BANK OUT müssen 02 zeigen, BYTE HEX D3, WORD HEX 5C7A sowie FAILED CHECKS und FIRST FAILURE jeweils 00. CGB und FC zeigen blaue Schrift, DMG schwarze.

CALL COUNT zeigt 02: Das Makro far_call und __farcall rufen den Callback jeweils einmal auf.

Vollständiges Beispielprogramm

Build-Befehl

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

Liest ein Byte über beide Felder eines als Wert übergebenen BankPtr. Der Deskriptor ergänzt die Banknummer, die einem gewöhnlichen Nahzeiger fehlt.

Syntax

u8 farptr_read8(BankPtr ptr);

Parameter

ptr

Ein BankPtr-Wert mit den Feldern bank und ptr. Übergeben Sie den Deskriptor selbst, nicht seine Adresse. Der Deskriptor des Aufrufers bleibt unverändert.

Rückgabewert

Das gelesene Byte als u8 (0–255).

Bedingungen und Grenzen

Das gesamte Byte oder Wort muss in der gewählten CPU-Zuordnung lesbar sein. Zeiger werden nicht geprüft, Adressen nicht begrenzt und Fenstergrenzen lösen keinen automatischen Wechsel zur nächsten ROM-Bank aus. Ein Wort benötigt zwei gültige aufeinanderfolgende Bytes.

Fernlesezugriffe und Kopien arbeiten synchron und nutzen gemeinsamen Arbeitsspeicher des Compilers. Ein Interrupt darf währenddessen keinen weiteren Banktransfer über denselben Speicher ausführen. Auf GB nutzt die Kopierhilfe außerdem einen gemeinsamen HRAM-Platz für die gespeicherte Bank. Das Beispiel führt die Operationen aus festem Code ohne konkurrierenden Transfer-Handler aus.

FC-Banknummern sind logische Nummern des Compilers. Null bezeichnet gemeinsames ROM, kein Umschaltziel; die Hilfsroutine setzt null auf Bank 1 um. Bei SUROM512 sind nur 1–30 gültig: Eine direkt an das Umschalt-Intrinsic übergebene Konstante außerhalb des Bereichs führt zu einem Buildfehler; ein ungültiger Laufzeitwert wählt 1 und setzt den Mapper-Fehlerzustand. Lesen Sie gemeinsames ROM direkt, statt Bank null anzufordern.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Dieser Ausschnitt liest mit farptr_read8 den Ausdruck pointer.ptr in Bank 3 und prüft 7A. Das vollständige Programm bestätigt durch einen Nahzugriff auf home2 außerdem die Wiederherstellung von Bank 2.

Das vollständige Programm zeigt Datenzugriffe über Bank und Nahadresse, bankübergreifende Callbacks und den Unterschied zwischen Bibliothekszustand und tatsächlicher Zuordnung. Alle Zahlen sind hexadezimal. BANK IN und BANK OUT müssen 02 zeigen, BYTE HEX D3, WORD HEX 5C7A sowie FAILED CHECKS und FIRST FAILURE jeweils 00. CGB und FC zeigen blaue Schrift, DMG schwarze.

CALL COUNT zeigt 02: Das Makro far_call und __farcall rufen den Callback jeweils einmal auf.

Vollständiges Beispielprogramm

Build-Befehl

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

Berechnet die kürzeste vorzeichenbehaftete Verschiebung von der aktuellen Position zu einem Ziel auf einer Achse mit verbundenen Enden. Verwenden Sie dies für Verfolgung oder Distanzvergleiche über einen Feldrand hinweg.

Syntax

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

Parameter

target

Zielkoordinate, 0..size−1.

current

Aktuelle Koordinate, 0..size−1.

size

Länge der umlaufenden Achse, 1..256: Breite für X, Höhe für Y. Das Argument hat 16 Bit, damit 256 darstellbar ist.

Rückgabewert

Gibt die kürzeste Verschiebung als s16 zurück: positiv zu steigenden, negativ zu fallenden Koordinaten, null bei gleicher Position. Gültige Eingaben ergeben −128..+128. Auf dem Bildschirm sind Verschiebungen nach rechts und unten positiv.

Bedingungen und Grenzen

Binden Sie chain.h ein und kompilieren Sie chain.c genau einmal. Chain oder ChainBody müssen nicht initialisiert werden. Die Funktion berechnet nur eine Verschiebung und ändert weder Koordinatenarrays noch Gelenkanzahl oder Bildschirm.

Die Funktion prüft und normalisiert Eingaben nicht. Übergeben Sie weder size=0 noch size>256 noch Koordinaten ab size. Bilden Sie Koordinaten aus einem größeren System vor dem Aufruf umlaufend auf 0..size−1 ab.

Bei gleich langen Wegen bleibt das Vorzeichen der direkten Differenz target−current erhalten. Bei size=160 liefert 0→80 den Wert +80 und 80→0 den Wert −80. Bei size=1 ist null die einzige gültige Koordinate und auch das Ergebnis ist null.

Anwendungsbeispiel

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.

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Dieses Beispiel zeigt umlaufende Koordinaten. Jeder Pfeil führt von der aktuellen Position zum Ziel. Angezeigt werden +02/−02 beim Überqueren eines Rands bei Breite 160, +80/−80 für ein halbes Feld und +00 bei Breite 1. Die führende Null ist dezimale Stellenfüllung. Das Beispiel zeichnet und bewegt kein Objekt.

Vollständiges Beispielprogramm

Build-Befehl

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

Verknüpft drei Gelenkarrays des aufrufenden Codes und setzt die Gelenkanzahl auf null, ohne Speicher zu reservieren.

Syntax

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

Parameter

body

Ziel-ChainBody; null wird ignoriert. Übergeben Sie außer bei der Initialisierung einen initialisierten Zustand.

x

Array der Gelenk-X-Koordinaten.

y

Array der Gelenk-Y-Koordinaten.

heading

Array der Gelenkrichtungen.

capacity

Reservierte Array-Länge, 1..255.

width

Breite des umlaufenden Felds, 1..256.

height

Höhe des umlaufenden Felds, 1..256.

Rückgabewert

Gibt bei Erfolg 1 zurück, bei ungültigen Argumenten 0. Ein Fehlschlag bei nicht leerem Körperzeiger setzt capacity und count auf null und deaktiviert Aktualisierungen.

Bedingungen und Grenzen

Binden Sie chain.h ein und kompilieren Sie chain.c genau einmal. ChainBody speichert die aktuelle Position und Richtung jedes Gelenks. Es ist ein eigener Zustandstyp, getrennt vom Positionsverlaufsring Chain.

Stellen Sie drei getrennte beschreibbare Arrays x, y und heading mit je capacity Bytes bereit und halten Sie sie während der Körpernutzung gültig. Index null ist der Kopf und in count enthalten. Ändern Sie nach der Initialisierung weder Speicherzeiger noch Kapazität oder Feldabmessungen.

Richtungen verwenden 16 Sektoren im Uhrzeigersinn: 0=rechts, 4=unten, 8=links, 12=oben. Nur die unteren vier Eingabebits werden verwendet. Bildschirmkoordinaten steigen nach rechts und unten; jede Abmessung beträgt 1..256 Pixel.

Anwendungsbeispiel

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.

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Bild zeigt oben einen geraden Körper, in der Mitte eine Aktualisierung nach einer Abwärtskurve und unten vier Aktualisierungen danach. Koordinaten werden in doppelter logischer Größe gezeichnet. Die Biegung wandert vom Kopf rechts nach hinten. CGB und FC zeigen Kopf rot, Körper blau und Schwanz grün; DMG verwendet Schwarz. Vier Ausgleichsaktualisierungen trennen das duplizierte Schwanzende nach dem Wachstum. Es sind drei Ansichten derselben acht Gelenke, kein Körper mit 24 Gelenken.

Vollständiges Beispielprogramm

Build-Befehl

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

Erzeugt eine gerade Anfangsanordnung, indem Gelenke hinter dem angegebenen Kopf platziert werden.

Syntax

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

Parameter

body

Ziel-ChainBody; null wird ignoriert. Übergeben Sie außer bei der Initialisierung einen initialisierten Zustand.

count

Gelenkanzahl einschließlich Kopf, 1..capacity.

head_x

Kopf-X-Koordinate, auf die Feldbreite umlaufend abgebildet.

head_y

Kopf-Y-Koordinate, auf die Feldhöhe umlaufend abgebildet.

heading

Kopfrichtung im System mit 16 Sektoren.

Rückgabewert

Gibt bei Erfolg 1 zurück. Eine Anzahl von null oder über der Kapazität oder ein Nullzeiger liefert 0, ohne die Anordnung zu ändern.

Bedingungen und Grenzen

Binden Sie chain.h ein und kompilieren Sie chain.c genau einmal. ChainBody speichert die aktuelle Position und Richtung jedes Gelenks. Es ist ein eigener Zustandstyp, getrennt vom Positionsverlaufsring Chain.

Stellen Sie drei getrennte beschreibbare Arrays x, y und heading mit je capacity Bytes bereit und halten Sie sie während der Körpernutzung gültig. Index null ist der Kopf und in count enthalten. Ändern Sie nach der Initialisierung weder Speicherzeiger noch Kapazität oder Feldabmessungen.

Richtungen verwenden 16 Sektoren im Uhrzeigersinn: 0=rechts, 4=unten, 8=links, 12=oben. Nur die unteren vier Eingabebits werden verwendet. Bildschirmkoordinaten steigen nach rechts und unten; jede Abmessung beträgt 1..256 Pixel.

Der orthogonale Abstand beträgt vier Pixel. Zwischenrichtungen verwenden Ganzzahlvektoren wie (4,1), (3,3) und (1,4); die euklidische Distanz beträgt daher nicht exakt vier Pixel. Die anfängliche Anordnung kann einen Feldrand überschreiten.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Bild zeigt oben einen geraden Körper, in der Mitte eine Aktualisierung nach einer Abwärtskurve und unten vier Aktualisierungen danach. Koordinaten werden in doppelter logischer Größe gezeichnet. Die Biegung wandert vom Kopf rechts nach hinten. CGB und FC zeigen Kopf rot, Körper blau und Schwanz grün; DMG verwendet Schwarz. Vier Ausgleichsaktualisierungen trennen das duplizierte Schwanzende nach dem Wachstum. Es sind drei Ansichten derselben acht Gelenke, kein Körper mit 24 Gelenken.

Vollständiges Beispielprogramm

Build-Befehl

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

Setzt die Kopfanordnung und zieht jedes Gelenk schrittweise zu einem Anschlusspunkt hinter seinem Vorgänger. Richtungsänderungen wandern pro Aktualisierung um ein Gelenk weiter.

Syntax

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

Parameter

body

Ziel-ChainBody; null wird ignoriert. Übergeben Sie außer bei der Initialisierung einen initialisierten Zustand.

head_x

Kopf-X-Koordinate, auf die Feldbreite umlaufend abgebildet.

head_y

Kopf-Y-Koordinate, auf die Feldhöhe umlaufend abgebildet.

heading

Kopfrichtung im System mit 16 Sektoren.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Binden Sie chain.h ein und kompilieren Sie chain.c genau einmal. ChainBody speichert die aktuelle Position und Richtung jedes Gelenks. Es ist ein eigener Zustandstyp, getrennt vom Positionsverlaufsring Chain.

Stellen Sie drei getrennte beschreibbare Arrays x, y und heading mit je capacity Bytes bereit und halten Sie sie während der Körpernutzung gültig. Index null ist der Kopf und in count enthalten. Ändern Sie nach der Initialisierung weder Speicherzeiger noch Kapazität oder Feldabmessungen.

Richtungen verwenden 16 Sektoren im Uhrzeigersinn: 0=rechts, 4=unten, 8=links, 12=oben. Nur die unteren vier Eingabebits werden verwendet. Bildschirmkoordinaten steigen nach rechts und unten; jede Abmessung beträgt 1..256 Pixel.

Ermittelt aus der aktualisierten Position des Vorgängers den Zielanschlusspunkt und berechnet dann je Achse die kürzeste umlaufende Verschiebung. Null bewegt nicht; Betrag 1..4 bewegt ein Pixel, ab 5 zwei Pixel. Bei genau einer halben Feldlänge bleibt das ursprüngliche Vorzeichen erhalten.

Gibt die vor der Aktualisierung gespeicherte Richtung jedes Gelenks an das nächste weiter, sodass eine Biegung durch den Körper wandert. Ein leerer Körper bleibt unverändert.

Der aufrufende Code verwaltet Kopfgeschwindigkeit, Beschleunigung, Kollisionen, Zeichnen und Warten. Aktualisieren Sie gewöhnlich zuerst den Kopf und rufen Sie chain_body_step einmal pro Simulationsschritt auf. Dies ist Gelenkverfolgung, kein Starrkörper- oder exakter Längenbedingungslöser.

Anwendungsbeispiel

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.

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Bild zeigt oben einen geraden Körper, in der Mitte eine Aktualisierung nach einer Abwärtskurve und unten vier Aktualisierungen danach. Koordinaten werden in doppelter logischer Größe gezeichnet. Die Biegung wandert vom Kopf rechts nach hinten. CGB und FC zeigen Kopf rot, Körper blau und Schwanz grün; DMG verwendet Schwarz. Vier Ausgleichsaktualisierungen trennen das duplizierte Schwanzende nach dem Wachstum. Es sind drei Ansichten derselben acht Gelenke, kein Körper mit 24 Gelenken.

Vollständiges Beispielprogramm

Build-Befehl

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

Kopiert aktuelle Position und Richtung des Schwanzendes in den nächsten freien Platz und erhöht die Anzahl um eins.

Syntax

u8 chain_body_grow(ChainBody* body);

Parameter

body

Ziel-ChainBody; null wird ignoriert. Übergeben Sie außer bei der Initialisierung einen initialisierten Zustand.

Rückgabewert

Gibt beim Anhängen eines Gelenks 1 zurück; bei leerem, vollem, deaktiviertem Körper oder Nullzeiger 0.

Bedingungen und Grenzen

Binden Sie chain.h ein und kompilieren Sie chain.c genau einmal. ChainBody speichert die aktuelle Position und Richtung jedes Gelenks. Es ist ein eigener Zustandstyp, getrennt vom Positionsverlaufsring Chain.

Stellen Sie drei getrennte beschreibbare Arrays x, y und heading mit je capacity Bytes bereit und halten Sie sie während der Körpernutzung gültig. Index null ist der Kopf und in count enthalten. Ändern Sie nach der Initialisierung weder Speicherzeiger noch Kapazität oder Feldabmessungen.

Richtungen verwenden 16 Sektoren im Uhrzeigersinn: 0=rechts, 4=unten, 8=links, 12=oben. Nur die unteren vier Eingabebits werden verwendet. Bildschirmkoordinaten steigen nach rechts und unten; jede Abmessung beträgt 1..256 Pixel.

Das neue Schwanzende überlappt zunächst das vorige und trennt sich bei folgenden chain_body_step-Aufrufen. Wachstum allein bewegt weder Kopf noch andere Gelenke.

Anwendungsbeispiel

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.

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Bild zeigt oben einen geraden Körper, in der Mitte eine Aktualisierung nach einer Abwärtskurve und unten vier Aktualisierungen danach. Koordinaten werden in doppelter logischer Größe gezeichnet. Die Biegung wandert vom Kopf rechts nach hinten. CGB und FC zeigen Kopf rot, Körper blau und Schwanz grün; DMG verwendet Schwarz. Vier Ausgleichsaktualisierungen trennen das duplizierte Schwanzende nach dem Wachstum. Es sind drei Ansichten derselben acht Gelenke, kein Körper mit 24 Gelenken.

Vollständiges Beispielprogramm

Build-Befehl

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

Setzt die Gelenkanzahl auf null und erhält Arrays sowie Feldeinstellungen.

Syntax

void chain_body_clear(ChainBody* body);

Parameter

body

Ziel-ChainBody; null wird ignoriert. Übergeben Sie außer bei der Initialisierung einen initialisierten Zustand.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Binden Sie chain.h ein und kompilieren Sie chain.c genau einmal. ChainBody speichert die aktuelle Position und Richtung jedes Gelenks. Es ist ein eigener Zustandstyp, getrennt vom Positionsverlaufsring Chain.

Stellen Sie drei getrennte beschreibbare Arrays x, y und heading mit je capacity Bytes bereit und halten Sie sie während der Körpernutzung gültig. Index null ist der Kopf und in count enthalten. Ändern Sie nach der Initialisierung weder Speicherzeiger noch Kapazität oder Feldabmessungen.

Richtungen verwenden 16 Sektoren im Uhrzeigersinn: 0=rechts, 4=unten, 8=links, 12=oben. Nur die unteren vier Eingabebits werden verwendet. Bildschirmkoordinaten steigen nach rechts und unten; jede Abmessung beträgt 1..256 Pixel.

Die Array-Bytes werden nicht gelöscht. Beginnen Sie mit chain_body_reset neu; chain_body_grow unmittelbar nach dem Leeren hängt kein Gelenk an.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Bild zeigt oben einen geraden Körper, in der Mitte eine Aktualisierung nach einer Abwärtskurve und unten vier Aktualisierungen danach. Koordinaten werden in doppelter logischer Größe gezeichnet. Die Biegung wandert vom Kopf rechts nach hinten. CGB und FC zeigen Kopf rot, Körper blau und Schwanz grün; DMG verwendet Schwarz. Vier Ausgleichsaktualisierungen trennen das duplizierte Schwanzende nach dem Wachstum. Es sind drei Ansichten derselben acht Gelenke, kein Körper mit 24 Gelenken.

Vollständiges Beispielprogramm

Build-Befehl

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

Verwirft den aufgezeichneten Verlauf, damit dasselbe Speicherarray erneut verwendet werden kann.

Syntax

void chain_clear(Chain* chain);

Parameter

chain

Zeiger auf das initialisierte Chain-Objekt.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Setzt Anzahl und head auf null, ohne das Speicherarray zu löschen oder freizugeben. Der Aufrufer verwaltet Chain und das Punktarray und muss beide gültig halten. Die Kapazität darf höchstens 128 betragen, damit die 8-Bit-Indexaddition beim Lesen nicht überläuft.

Die FC-Version tut bei chain == 0 nichts.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel leert einen Verlauf mit vier Punkten und prüft, dass die Anzahl danach null ist.

Vollständiges Beispielprogramm

Build-Befehl

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

Liest die Anzahl der aktuell im Verlauf verfügbaren Positionen.

Syntax

u8 chain_get_count(const Chain* chain);

Parameter

chain

Zeiger auf das initialisierte Chain-Objekt.

Rückgabewert

Gibt eine Anzahl zwischen null und der Kapazität zurück, bei Nullzeiger null.

Bedingungen und Grenzen

Der Aufrufer verwaltet sowohl Chain als auch das Punktarray und muss beide gültig halten. Verwenden Sie höchstens 128 Plätze, damit die 8-Bit-Indexaddition beim Lesen nicht überläuft.

Anwendungsbeispiel

result[4]=chain_get_count(&trail);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Nach fünf Einfügungen in vier Plätze bleibt die Anzahl vier. Nach dem Leeren ist sie null; bei Kapazität null bleibt sie stets null.

Vollständiges Beispielprogramm

Build-Befehl

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

Liest eine gespeicherte Position anhand ihres Alters im Verlauf.

Syntax

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

Parameter

chain

Zeiger auf das initialisierte Chain-Objekt.

index

Alter des Punkts: 0 bezeichnet den neuesten, count - 1 den ältesten noch gespeicherten Punkt.

out

Eigenständiges, beschreibbares ChainPoint-Objekt für das Ergebnis; ein Nullzeiger führt zum Fehlschlag.

Rückgabewert

Gibt bei Erfolg 1, bei ungültiger Anfrage 0 zurück. Ein nichtnulliger out-Zeiger wird vor der Prüfung auf (0,0) gesetzt.

Bedingungen und Grenzen

out darf keinen Speicher mit dem zugrunde liegenden Array oder mit Chain teilen, da das Nullsetzen der Ausgabe Quelldaten zerstören würde. Der Aufrufer verwaltet Chain und das Punktarray und muss beide gültig halten. Höchstens 128 Plätze verhindern einen Überlauf der 8-Bit-Indexaddition beim Lesen.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Index 0 liest den neuesten Punkt (40,24), Index 3 den ältesten (16,8). Der ungültige Index 4 meldet einen Fehler und setzt die Ausgabe auf (0,0).

Vollständiges Beispielprogramm

Build-Befehl

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

Verknüpft Speicher mit einem Ringpuffer für Positionsverläufe und beginnt ohne aufgezeichnete Punkte.

Syntax

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

Parameter

chain

Zu initialisierendes, beschreibbares Chain-Objekt.

storage

Array mit Platz für capacity Einträge vom Typ ChainPoint.

capacity

Anzahl der Punktplätze. Für einen nutzbaren Verlauf sind 1 bis 128 zulässig; null deaktiviert die Aufzeichnung.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Der Aufrufer verwaltet sowohl Chain als auch das Punktarray und muss beide gültig halten. Verwenden Sie höchstens 128 Plätze, damit die 8-Bit-Indexaddition beim Lesen nicht überläuft.

Die FC-Version tut bei chain == 0 nichts.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel bindet vier Punktplätze ein und prüft, dass die anfängliche Anzahl null ist.

Vollständiges Beispielprogramm

Build-Befehl

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

Fügt die neueste Position am Kopf des Verlaufs ein und ersetzt bei vollem Puffer den ältesten Punkt.

Syntax

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

Parameter

chain

Zeiger auf das initialisierte Chain-Objekt.

x

X-Koordinate des neuen Punkts mit Vorzeichen.

y

Y-Koordinate des neuen Punkts mit Vorzeichen.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Bei Nullzeiger oder Kapazität null geschieht nichts. Der Aufrufer verwaltet Chain und das Punktarray und muss beide gültig halten. Die Kapazität darf höchstens 128 betragen, damit die 8-Bit-Indexaddition beim Lesen nicht überläuft.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Nach fünf Einfügungen in vier Plätze ist (40,24) der neueste und (16,8) der älteste noch vorhandene Punkt. Der ursprüngliche Punkt (8,8) wurde ersetzt.

Vollständiges Beispielprogramm

Build-Befehl

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

Prüft, ob ein Punkt innerhalb eines FC-Rechtecks liegt. Die linke und obere Kante zählen dazu, die rechte und untere nicht.

Syntax

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

Parameter

box

Lesbares NesBox16; übergeben Sie keinen Nullzeiger.

px

X-Koordinate des Punkts als vorzeichenloser 16-Bit-Wert.

py

Y-Koordinate des Punkts als vorzeichenloser 16-Bit-Wert.

Rückgabewert

Gibt innerhalb 1 zurück, außerhalb 0.

Bedingungen und Grenzen

x, y sind vorzeichenlose 16-Bit-Koordinaten; Breite und Höhe sind Byte-Werte. Verwenden Sie positive Abmessungen und halten Sie die Summen aus Koordinate und Abmessung bei höchstens 65535. Rechtecke über einen Koordinatenüberlauf hinweg werden nicht unterstützt.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Jede Koordinateneinheit entspricht einer Kachel. Rechteck A bei (1,1) und B bei (5,4) sind jeweils 8×6 groß. Nur von A belegte Zellen zeigen A, nur von B belegte zeigen B, und die 4×3 große Überlappung zeigt zwölf O-Zellen. Die rechte Kante von A bei x=9 zählt nicht dazu. Auf dem CGB ist A rot, B blau und O grün.

Vollständiges Beispielprogramm

Build-Befehl

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

Prüft, ob sich zwei per Zeiger übergebene FC-Rechtecke mit einer Fläche größer als null überlappen.

Syntax

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

Parameter

a

Erstes lesbares NesBox16; übergeben Sie keinen Nullzeiger.

b

Zweites lesbares NesBox16.

Rückgabewert

Gibt bei Überlappung 1 zurück, bei getrennten Rechtecken oder bloßer Kantenberührung 0.

Bedingungen und Grenzen

x, y sind vorzeichenlose 16-Bit-Koordinaten; Breite und Höhe sind Byte-Werte. Verwenden Sie positive Abmessungen und halten Sie die Summen aus Koordinate und Abmessung bei höchstens 65535. Rechtecke über einen Koordinatenüberlauf hinweg werden nicht unterstützt.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Jede Koordinateneinheit entspricht einer Kachel. Rechteck A bei (1,1) und B bei (5,4) sind jeweils 8×6 groß. Nur von A belegte Zellen zeigen A, nur von B belegte zeigen B, und die 4×3 große Überlappung zeigt zwölf O-Zellen. Die rechte Kante von A bei x=9 zählt nicht dazu. Auf dem CGB ist A rot, B blau und O grün.

Vollständiges Beispielprogramm

Build-Befehl

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

Speichert einen Assertion-Fehlercode und versucht, einen ASSERT-Eintrag anzuhängen.

Syntax

void debug_assert_fail(u16 code);

Parameter

code

Zu speichernde 16-Bit-Fehlerkennung.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Die Ausführung läuft weiter. Der letzte Assertion-Code wird auch bei vollem Protokoll aktualisiert. Das Protokoll fasst standardmäßig 32 Einträge und verwirft bei voller Belegung neue Einträge. Wenn Sie DEBUG_TRACE_MAX überschreiben, verwenden Sie in allen Übersetzungseinheiten denselben Wert zwischen 1 und 255. Namen werden als Zeiger gespeichert, nicht kopiert; ihr Speicher muss bis zum Ende der Auswertung lesbar bleiben. Zugriffe aus Hauptprogramm und Interrupts müssen Sie selbst gegeneinander absichern.

Anwendungsbeispiel

debug_assert_fail(42);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel speichert Code 42, füllt das Protokoll und speichert dann Code 999. Die Anzahl bleibt 32, der letzte Code wird jedoch zu 999.

Vollständiges Beispielprogramm

Build-Befehl

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

Liest den letzten Assertion-Code unabhängig vom verfügbaren Protokollspeicher.

Syntax

u16 debug_get_last_assert(void);

Rückgabewert

Gibt den letzten 16-Bit-Code zurück; nach der Initialisierung ist er null.

Bedingungen und Grenzen

Null ist zugleich der Anfangswert und lässt sich daher nicht von einem mit Code null protokollierten Fehler unterscheiden. Das Lesen löscht den Code nicht.

Anwendungsbeispiel

result[22]=debug_get_last_assert();

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel prüft 77 aus dem Assertion-Makro, 999 nach dem Füllen des Protokolls und null nach erneuter Initialisierung.

Vollständiges Beispielprogramm

Build-Befehl

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

Liest die Anzahl gültiger Einträge im Trace-Array.

Syntax

u8 debug_get_trace_count(void);

Rückgabewert

Gibt eine Anzahl von null bis DEBUG_TRACE_MAX zurück.

Bedingungen und Grenzen

Das Protokoll fasst standardmäßig 32 Einträge und verwirft bei voller Belegung neue Einträge. Wenn Sie DEBUG_TRACE_MAX überschreiben, verwenden Sie in allen Übersetzungseinheiten denselben Wert zwischen 1 und 255. Namen werden als Zeiger gespeichert, nicht kopiert; ihr Speicher muss bis zum Ende der Auswertung lesbar bleiben. Zugriffe aus Hauptprogramm und Interrupts müssen Sie selbst gegeneinander absichern.

Anwendungsbeispiel

result[1]=debug_get_trace_count();

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel prüft die ersten zehn Einträge und nach weiteren Schreibzugriffen die Grenze von 32. Bei voller Belegung läuft der Zähler nicht auf null über.

Vollständiges Beispielprogramm

Build-Befehl

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

Liefert eine Referenz auf das interne Array zur Auswertung gespeicherter Namen, Werte und Frame-Kennungen.

Syntax

const DebugTraceEntry* debug_get_trace_log(void);

Rückgabewert

Gibt einen schreibgeschützten Zeiger auf das interne DebugTraceEntry-Array zurück.

Bedingungen und Grenzen

Dies ist keine Kopie. Lesen Sie nur die von debug_get_trace_count() gemeldete Anzahl von Einträgen. Nach der Initialisierung verbliebene alte Bytes sind keine gültigen Datensätze. Das Protokoll fasst standardmäßig 32 Einträge und verwirft bei voller Belegung neue Einträge. Wenn Sie DEBUG_TRACE_MAX überschreiben, verwenden Sie in allen Übersetzungseinheiten denselben Wert zwischen 1 und 255. Namen werden als Zeiger gespeichert, nicht kopiert; ihr Speicher muss bis zum Ende der Auswertung lesbar bleiben. Zugriffe aus Hauptprogramm und Interrupts müssen Sie selbst gegeneinander absichern.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel liest alle zehn Wert- und Frame-Felder und prüft das führende B der Bezeichnung BEGIN.

Vollständiges Beispielprogramm

Build-Befehl

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

Initialisiert die gültige Protokolllänge, die Frame-Kennung und den letzten Assertion-Code.

Syntax

void debug_init(void);

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Die Bytes vorhandener Einträge werden nicht gelöscht. Rufen Sie die Funktion vor dem ersten Protokolleintrag auf. Das Protokoll fasst standardmäßig 32 Einträge und verwirft bei voller Belegung neue Einträge. Wenn Sie DEBUG_TRACE_MAX überschreiben, verwenden Sie in allen Übersetzungseinheiten denselben Wert zwischen 1 und 255. Namen werden als Zeiger gespeichert, nicht kopiert; ihr Speicher muss bis zum Ende der Auswertung lesbar bleiben. Zugriffe aus Hauptprogramm und Interrupts müssen Sie selbst gegeneinander absichern.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel prüft zunächst die Anzahl null, setzt dann ein gefülltes Protokoll zurück und bestätigt, dass Anzahl und Assertion-Code gelöscht sind, während die alten Arraywerte erhalten bleiben.

Vollständiges Beispielprogramm

Build-Befehl

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

Schreibt eine benannte Frame-Markierung, um eine Stelle im Ablauf zu kennzeichnen.

Syntax

void debug_mark_frame(const u8* label);

Parameter

label

Nullterminierte Bezeichnung in Speicher, der bis zur Auswertung lesbar bleiben muss.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Das Protokoll fasst standardmäßig 32 Einträge und verwirft bei voller Belegung neue Einträge. Wenn Sie DEBUG_TRACE_MAX überschreiben, verwenden Sie in allen Übersetzungseinheiten denselben Wert zwischen 1 und 255. Namen werden als Zeiger gespeichert, nicht kopiert; ihr Speicher muss bis zum Ende der Auswertung lesbar bleiben. Zugriffe aus Hauptprogramm und Interrupts müssen Sie selbst gegeneinander absichern.

Anwendungsbeispiel

debug_mark_frame("BEGIN");

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Die Markierung BEGIN speichert den Wert 65535 (0xFFFF) mit der Frame-Kennung 513.

Vollständiges Beispielprogramm

Build-Befehl

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

Legt die Frame-Kennung fest, die in nachfolgende Protokolleinträge kopiert wird.

Syntax

void debug_set_frame(u16 frame);

Parameter

frame

16-Bit-Frame-Nummer für nachfolgende Einträge.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Die Funktion wartet weder auf einen Frame noch erhöht sie die Kennung automatisch. Übergeben Sie ausdrücklich den Frame-Zähler des Spiels. Das Protokoll fasst standardmäßig 32 Einträge und verwirft bei voller Belegung neue Einträge. Wenn Sie DEBUG_TRACE_MAX überschreiben, verwenden Sie in allen Übersetzungseinheiten denselben Wert zwischen 1 und 255. Namen werden als Zeiger gespeichert, nicht kopiert; ihr Speicher muss bis zum Ende der Auswertung lesbar bleiben. Zugriffe aus Hauptprogramm und Interrupts müssen Sie selbst gegeneinander absichern.

Anwendungsbeispiel

debug_set_frame(513);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel setzt die Kennung auf 513, schreibt zehn Einträge und liest zur Kontrolle alle zehn Frame-Felder zurück.

Vollständiges Beispielprogramm

Build-Befehl

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

Protokolliert einen benannten 16-Bit-Punktestand oder Zähler.

Syntax

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

Parameter

name

Nullterminierte Bezeichnung in Speicher, der bis zur Auswertung lesbar bleiben muss.

value

Zu protokollierender Wert von 0 bis 65535.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Das Protokoll fasst standardmäßig 32 Einträge und verwirft bei voller Belegung neue Einträge. Wenn Sie DEBUG_TRACE_MAX überschreiben, verwenden Sie in allen Übersetzungseinheiten denselben Wert zwischen 1 und 255. Namen werden als Zeiger gespeichert, nicht kopiert; ihr Speicher muss bis zum Ende der Auswertung lesbar bleiben. Zugriffe aus Hauptprogramm und Interrupts müssen Sie selbst gegeneinander absichern.

Anwendungsbeispiel

debug_trace_u16("WORD",4660);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Der Eintrag WORD speichert 4660 (0x1234); das Beispiel liest ihn zur Prüfung beider Bytes zurück.

Vollständiges Beispielprogramm

Build-Befehl

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

Protokolliert einen 8-Bit-Zustandswert mit Namen und aktueller Frame-Kennung.

Syntax

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

Parameter

name

Nullterminierte Bezeichnung in Speicher, der bis zur Auswertung lesbar bleiben muss.

value

Wert von 0 bis 255, der mit Nullen auf das 16-Bit-Protokollfeld erweitert wird.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Das Protokoll fasst standardmäßig 32 Einträge und verwirft bei voller Belegung neue Einträge. Wenn Sie DEBUG_TRACE_MAX überschreiben, verwenden Sie in allen Übersetzungseinheiten denselben Wert zwischen 1 und 255. Namen werden als Zeiger gespeichert, nicht kopiert; ihr Speicher muss bis zum Ende der Auswertung lesbar bleiben. Zugriffe aus Hauptprogramm und Interrupts müssen Sie selbst gegeneinander absichern.

Anwendungsbeispiel

debug_trace_u8("BYTE",255);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Der Eintrag BYTE speichert 255 und prüft, dass das 16-Bit-Wertfeld im Protokoll ebenfalls 255 enthält.

Vollständiges Beispielprogramm

Build-Befehl

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

Als Anweisung verwendbares Makro, das bei falscher Bedingung Assertion-Code 1 protokolliert.

Syntax

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

Parameter

cond

Bedingung, die erfüllt sein soll; null bedeutet einen Fehler.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Die Bedingung wird einmal ausgewertet. Bei wahr wird nichts protokolliert, bei falsch der Fehler aufgezeichnet, ohne die Ausführung anzuhalten. Durch die Form do…while (0) lässt sich das Makro in einem if…else als einzelne Anweisung verwenden.

Anwendungsbeispiel

KITAQGB_ASSERT(1);KITAQGB_ASSERT(0);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Eine wahre und eine falsche Assertion erzeugen genau einen Eintrag mit Code 1.

Vollständiges Beispielprogramm

Build-Befehl

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)

Protokolliert den gewählten Assertion-Code nur bei falscher Bedingung.

Syntax

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

Parameter

cond

Bedingung, die erfüllt sein soll.

code

Code-Ausdruck, der im Fehlerfall ausgewertet und in 16 Bits umgewandelt wird.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Die Bedingung wird einmal ausgewertet, der Code-Ausdruck nur im Fehlerfall. Nach dem Protokollieren läuft die Ausführung weiter.

Anwendungsbeispiel

KITAQGB_ASSERT_CODE(1,++side_effect);KITAQGB_ASSERT_CODE(0,77);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Bei wahrer Bedingung wird der Code-Ausdruck ++side_effect nicht ausgewertet; die Variable bleibt null. Eine falsche Bedingung protokolliert Code 77.

Vollständiges Beispielprogramm

Build-Befehl

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)

Wandelt eine Bezeichnung in einen Zeichenkettenzeiger um und fügt eine Frame-Markierung mit dem Wert 0xFFFF hinzu.

Syntax

#define KITAQGB_MARK_FRAME(label) debug_mark_frame((const u8*)(label))

Parameter

label

Nullterminierte Bezeichnung in Speicher, der bis zur Auswertung lesbar bleiben muss.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Das Protokoll fasst standardmäßig 32 Einträge und verwirft bei voller Belegung neue Einträge. Wenn Sie DEBUG_TRACE_MAX überschreiben, verwenden Sie in allen Übersetzungseinheiten denselben Wert zwischen 1 und 255. Namen werden als Zeiger gespeichert, nicht kopiert; ihr Speicher muss bis zum Ende der Auswertung lesbar bleiben. Zugriffe aus Hauptprogramm und Interrupts müssen Sie selbst gegeneinander absichern.

Anwendungsbeispiel

KITAQGB_MARK_FRAME("END");

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Die Markierung END wird auf den Wert 65535 und die Frame-Kennung 513 geprüft.

Vollständiges Beispielprogramm

Build-Befehl

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))

Wandelt einen Wert ausdrücklich in 16 Bits um und protokolliert ihn mit Namen.

Syntax

#define KITAQGB_TRACE(name, value) debug_trace_u16((const u8*)(name), (u16)(value))

Parameter

name

Nullterminierte Bezeichnung in Speicher, der bis zur Auswertung lesbar bleiben muss.

value

Ausdruck, der vor dem Protokollieren in 16 Bits umgewandelt wird.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Das Makro ist immer aktiv; Build-Einstellungen deaktivieren es nicht automatisch. Es protokolliert 16-Bit-Werte genauso wie KITAQGB_TRACE_U16. Das Protokoll fasst standardmäßig 32 Einträge und verwirft bei voller Belegung neue Einträge. Wenn Sie DEBUG_TRACE_MAX überschreiben, verwenden Sie in allen Übersetzungseinheiten denselben Wert zwischen 1 und 255. Namen werden als Zeiger gespeichert, nicht kopiert; ihr Speicher muss bis zum Ende der Auswertung lesbar bleiben. Zugriffe aus Hauptprogramm und Interrupts müssen Sie selbst gegeneinander absichern.

Anwendungsbeispiel

KITAQGB_TRACE("SCORE",600);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel speichert 600 und liest den Wert zur Prüfung aus dem Protokoll zurück.

Vollständiges Beispielprogramm

Build-Befehl

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))

Wandelt einen Wert ausdrücklich in 16 Bits um und protokolliert ihn mit Namen.

Syntax

#define KITAQGB_TRACE_U16(name, value) debug_trace_u16((const u8*)(name), (u16)(value))

Parameter

name

Nullterminierte Bezeichnung in Speicher, der bis zur Auswertung lesbar bleiben muss.

value

Ausdruck, der vor dem Protokollieren in 16 Bits umgewandelt wird.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Das Makro ist immer aktiv; Build-Einstellungen deaktivieren es nicht automatisch. Das Protokoll fasst standardmäßig 32 Einträge und verwirft bei voller Belegung neue Einträge. Wenn Sie DEBUG_TRACE_MAX überschreiben, verwenden Sie in allen Übersetzungseinheiten denselben Wert zwischen 1 und 255. Namen werden als Zeiger gespeichert, nicht kopiert; ihr Speicher muss bis zum Ende der Auswertung lesbar bleiben. Zugriffe aus Hauptprogramm und Interrupts müssen Sie selbst gegeneinander absichern.

Anwendungsbeispiel

KITAQGB_TRACE_U16("WORD2",500);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel speichert 500 und liest den Wert zur Prüfung aus dem Protokoll zurück.

Vollständiges Beispielprogramm

Build-Befehl

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))

Wandelt einen Wert ausdrücklich in 8 Bits um und protokolliert ihn mit Namen.

Syntax

#define KITAQGB_TRACE_U8(name, value) debug_trace_u8((const u8*)(name), (u8)(value))

Parameter

name

Nullterminierte Bezeichnung in Speicher, der bis zur Auswertung lesbar bleiben muss.

value

Ausdruck, der vor dem Protokollieren in 8 Bits umgewandelt wird.

Rückgabewert

Kein Rückgabewert.

Bedingungen und Grenzen

Das Makro ist immer aktiv; Build-Einstellungen deaktivieren es nicht automatisch. Das Protokoll fasst standardmäßig 32 Einträge und verwirft bei voller Belegung neue Einträge. Wenn Sie DEBUG_TRACE_MAX überschreiben, verwenden Sie in allen Übersetzungseinheiten denselben Wert zwischen 1 und 255. Namen werden als Zeiger gespeichert, nicht kopiert; ihr Speicher muss bis zum Ende der Auswertung lesbar bleiben. Zugriffe aus Hauptprogramm und Interrupts müssen Sie selbst gegeneinander absichern.

Anwendungsbeispiel

KITAQGB_TRACE_U8("CAST",0x1234);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel speichert 52. Von 0x1234 bleibt nur das niederwertige Byte 0x34 erhalten.

Vollständiges Beispielprogramm

Build-Befehl

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))

Gibt alle Entities frei und setzt ihre Felder einschließlich der Markierung für fehlende Sprites zurück.

Syntax

void entity_clear_all(void);

Rückgabewert

Keiner (void).

Bedingungen und Grenzen

Der Pool ist ein festes Array ohne Heap-Allokation. ENTITY_MAX ist standardmäßig 16 und muss in allen Übersetzungseinheiten gleich mit einem Wert von 1 bis 255 definiert sein. IDs beginnen bei null; 0xFF kennzeichnet einen Fehlschlag.

Setzt in allen Plätzen active,type,x,y,vx,vy,state,timer auf null und sprite auf 0xFF. Hardware-Sprites werden dadurch weder verborgen noch freigegeben; ihre Ressourcen müssen separat aufgeräumt werden.

Anwendungsbeispiel

entity_clear_all();
after_clear = entity_count_active();
if (after_clear != 0 || entity_get(reused) != 0) { failures++; }

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das vollständige Programm zeigt den Lebenszyklus eines wiederverwendbaren Platzes. Lesen Sie Zahlen mit ihren Beschriftungen: CREATED 002 nach zwei Belegungen, AFTER FREE 001 nach Freigabe der ersten, REUSED ID 000 bei Wiederverwendung der kleinsten freien ID und AFTER CLEAR 000 nach Leeren des Pools. Geprüft werden auch null-Abfrage nach Freigabe und zurückgesetzte Felder nach Neubelegung. FAILED CHECKS 000 bestätigt die erwarteten Werte.

Der FC-Durchlauf ruft jeden Callback für beide aktiven Entities auf: UPDATE CALLS 002 und DRAW CALLS 002. Der Aktualisierungs-Callback verschiebt beide um ein Tile nach rechts. Der Zeichen-Callback setzt zur Darstellung der Objekte A auf Tile (3,12) und B auf (7,12). Das sind vom Callback gezeichnete Hintergrund-Schrift-Tiles, keine automatisch belegten Sprites.

Vollständiges Beispielprogramm

Build-Befehl

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

Zählt belegte Entity-Plätze, ohne ihren Zustand zu ändern.

Syntax

u8 entity_count_active(void);

Rückgabewert

Anzahl der Plätze mit einem von null verschiedenen active-Byte, von 0 bis ENTITY_MAX. Das ist die Belegung, nicht die höchste ID oder die Anzahl sichtbarer Sprites.

Bedingungen und Grenzen

Der Pool ist ein festes Array ohne Heap-Allokation. ENTITY_MAX ist standardmäßig 16 und muss in allen Übersetzungseinheiten gleich mit einem Wert von 1 bis 255 definiert sein. IDs beginnen bei null; 0xFF kennzeichnet einen Fehlschlag.

Anwendungsbeispiel

created = entity_count_active();
if (created != 2) { failures++; }

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das vollständige Programm zeigt den Lebenszyklus eines wiederverwendbaren Platzes. Lesen Sie Zahlen mit ihren Beschriftungen: CREATED 002 nach zwei Belegungen, AFTER FREE 001 nach Freigabe der ersten, REUSED ID 000 bei Wiederverwendung der kleinsten freien ID und AFTER CLEAR 000 nach Leeren des Pools. Geprüft werden auch null-Abfrage nach Freigabe und zurückgesetzte Felder nach Neubelegung. FAILED CHECKS 000 bestätigt die erwarteten Werte.

Der FC-Durchlauf ruft jeden Callback für beide aktiven Entities auf: UPDATE CALLS 002 und DRAW CALLS 002. Der Aktualisierungs-Callback verschiebt beide um ein Tile nach rechts. Der Zeichen-Callback setzt zur Darstellung der Objekte A auf Tile (3,12) und B auf (7,12). Das sind vom Callback gezeichnete Hintergrund-Schrift-Tiles, keine automatisch belegten Sprites.

Vollständiges Beispielprogramm

Build-Befehl

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

Reserviert eine Entity mit Typ und Position; liefert ihre wiederverwendbare ID oder bei vollem Pool 0xFF.

Syntax

u8 entity_create(u8 type, s16 x, s16 y);

Parameter

type

Vom Spiel definierte Typkennung von 0 bis 255. Der Pool speichert sie, wählt damit aber weder Verhalten noch Zeichenroutinen aus.

x, y

Vorzeichenbehaftete 16-Bit-Koordinaten (-32768–32767). Die Einheit bestimmt das Spiel, etwa Pixel oder Q8.8. Der Pool rechnet keine Einheiten um, begrenzt keine Positionen und wendet Geschwindigkeiten nicht automatisch an.

Rückgabewert

Die kleinste freie Platz-ID (0–ENTITY_MAX-1) oder 0xFF, falls keiner frei ist. Erfolgreiche Belegung setzt active=1, speichert Typ und Position, löscht Geschwindigkeit/Zustand/Timer und setzt sprite=0xFF.

Bedingungen und Grenzen

Der Pool ist ein festes Array ohne Heap-Allokation. ENTITY_MAX ist standardmäßig 16 und muss in allen Übersetzungseinheiten gleich mit einem Wert von 1 bis 255 definiert sein. IDs beginnen bei null; 0xFF kennzeichnet einen Fehlschlag.

Anwendungsbeispiel

first = entity_create(1, 2, 12);
second = entity_create(2, 6, 12);
if (first == 0xFF || second == 0xFF) { failures++; }

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das vollständige Programm zeigt den Lebenszyklus eines wiederverwendbaren Platzes. Lesen Sie Zahlen mit ihren Beschriftungen: CREATED 002 nach zwei Belegungen, AFTER FREE 001 nach Freigabe der ersten, REUSED ID 000 bei Wiederverwendung der kleinsten freien ID und AFTER CLEAR 000 nach Leeren des Pools. Geprüft werden auch null-Abfrage nach Freigabe und zurückgesetzte Felder nach Neubelegung. FAILED CHECKS 000 bestätigt die erwarteten Werte.

Der FC-Durchlauf ruft jeden Callback für beide aktiven Entities auf: UPDATE CALLS 002 und DRAW CALLS 002. Der Aktualisierungs-Callback verschiebt beide um ein Tile nach rechts. Der Zeichen-Callback setzt zur Darstellung der Objekte A auf Tile (3,12) und B auf (7,12). Das sind vom Callback gezeichnete Hintergrund-Schrift-Tiles, keine automatisch belegten Sprites.

Vollständiges Beispielprogramm

Build-Befehl

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

Gibt den Platz von Entity id frei; die Nutzdaten werden erst bei erneuter Belegung zurückgesetzt.

Syntax

void entity_destroy(u8 id);

Parameter

id

Wiederverwendbarer Platzindex von 0 bis ENTITY_MAX-1. Werte außerhalb dieses Bereichs sind ungültig. Das Freigeben einer ungültigen ID bewirkt nichts; die Abfrage liefert null.

Rückgabewert

Keiner (void).

Bedingungen und Grenzen

Der Pool ist ein festes Array ohne Heap-Allokation. ENTITY_MAX ist standardmäßig 16 und muss in allen Übersetzungseinheiten gleich mit einem Wert von 1 bis 255 definiert sein. IDs beginnen bei null; 0xFF kennzeichnet einen Fehlschlag.

Freigeben löscht nur active, nicht die übrigen Felder, Sprites oder Assets. Spätere Belegung kann dieselbe ID und Adresse für eine andere Entity verwenden. Das Spiel muss die zugehörigen Ressourcen selbst aufräumen.

Anwendungsbeispiel

entity_destroy(first);
after_free = entity_count_active();
if (entity_get(first) != 0 || after_free != 1) { failures++; }

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das vollständige Programm zeigt den Lebenszyklus eines wiederverwendbaren Platzes. Lesen Sie Zahlen mit ihren Beschriftungen: CREATED 002 nach zwei Belegungen, AFTER FREE 001 nach Freigabe der ersten, REUSED ID 000 bei Wiederverwendung der kleinsten freien ID und AFTER CLEAR 000 nach Leeren des Pools. Geprüft werden auch null-Abfrage nach Freigabe und zurückgesetzte Felder nach Neubelegung. FAILED CHECKS 000 bestätigt die erwarteten Werte.

Der FC-Durchlauf ruft jeden Callback für beide aktiven Entities auf: UPDATE CALLS 002 und DRAW CALLS 002. Der Aktualisierungs-Callback verschiebt beide um ein Tile nach rechts. Der Zeichen-Callback setzt zur Darstellung der Objekte A auf Tile (3,12) und B auf (7,12). Das sind vom Callback gezeichnete Hintergrund-Schrift-Tiles, keine automatisch belegten Sprites.

Vollständiges Beispielprogramm

Build-Befehl

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

Durchläuft aktive Entities und übergibt jede ID an den Zeichen-Callback. Der Durchlauf entspricht entity_update_all; ohne vom Callback eingereichte Zeichendaten werden keine Sprites oder Pixel gezeichnet.

Syntax

void entity_draw_all(EntityFn fn);

Parameter

fn

Funktionszeiger mit Signatur void fn(u8 id). Er erhält eine Platz-ID; auf Felder greifen Sie über entity_get(id) zu. Null ist zulässig und führt zu keinen Aufrufen.

Rückgabewert

Keiner (void).

Bedingungen und Grenzen

Der Pool ist ein festes Array ohne Heap-Allokation. ENTITY_MAX ist standardmäßig 16 und muss in allen Übersetzungseinheiten gleich mit einem Wert von 1 bis 255 definiert sein. IDs beginnen bei null; 0xFF kennzeichnet einen Fehlschlag.

Der Durchlauf prüft die Aktivität erst beim Erreichen eines Platzes. Ein Callback kann spätere Plätze deaktivieren und damit überspringen lassen oder aktivieren und noch im selben Durchlauf besuchen lassen. Es wird kein Schnappschuss der anfänglichen Belegung verwendet.

Lege den Callback in die gemeinsame PRG-Bank 0 oder halte seine Bank während des gesamten Aufrufs eingeblendet. Ein Funktionszeiger enthält eine 16-Bit-CPU-Adresse und schaltet keine Bank um. Parameter und lokale Variablen der FC-Funktionen belegen feste Speicherbereiche. Rufe den Entity-Durchlauf daher weder rekursiv auf noch erneut aus einem Interrupt, während er bereits läuft.

Anwendungsbeispiel

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++; }

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das vollständige Programm zeigt den Lebenszyklus eines wiederverwendbaren Platzes. Lesen Sie Zahlen mit ihren Beschriftungen: CREATED 002 nach zwei Belegungen, AFTER FREE 001 nach Freigabe der ersten, REUSED ID 000 bei Wiederverwendung der kleinsten freien ID und AFTER CLEAR 000 nach Leeren des Pools. Geprüft werden auch null-Abfrage nach Freigabe und zurückgesetzte Felder nach Neubelegung. FAILED CHECKS 000 bestätigt die erwarteten Werte.

Der FC-Durchlauf ruft jeden Callback für beide aktiven Entities auf: UPDATE CALLS 002 und DRAW CALLS 002. Der Aktualisierungs-Callback verschiebt beide um ein Tile nach rechts. Der Zeichen-Callback setzt zur Darstellung der Objekte A auf Tile (3,12) und B auf (7,12). Das sind vom Callback gezeichnete Hintergrund-Schrift-Tiles, keine automatisch belegten Sprites.

Vollständiges Beispielprogramm

Build-Befehl

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

Liefert einen Zeiger auf die aktive Entity oder null bei ungültiger bzw. freier ID. Der Speicherplatz wird wiederverwendet.

Syntax

Entity* entity_get(u8 id);

Parameter

id

Wiederverwendbarer Platzindex von 0 bis ENTITY_MAX-1. Werte außerhalb dieses Bereichs sind ungültig. Das Freigeben einer ungültigen ID bewirkt nichts; die Abfrage liefert null.

Rückgabewert

Schreibbarer Zeiger auf den aktiven Pool-Platz oder null bei ungültiger bzw. inaktiver ID. Der Speicher gehört dem Pool; geben Sie ihn nicht selbst frei und verwenden Sie den Zeiger nicht als dauerhafte Identität über Freigabe und Neubelegung hinweg.

Bedingungen und Grenzen

Der Pool ist ein festes Array ohne Heap-Allokation. ENTITY_MAX ist standardmäßig 16 und muss in allen Übersetzungseinheiten gleich mit einem Wert von 1 bis 255 definiert sein. IDs beginnen bei null; 0xFF kennzeichnet einen Fehlschlag.

Freigeben löscht nur active, nicht die übrigen Felder, Sprites oder Assets. Spätere Belegung kann dieselbe ID und Adresse für eine andere Entity verwenden. Das Spiel muss die zugehörigen Ressourcen selbst aufräumen.

Anwendungsbeispiel

current_entity = entity_get(first);
if (current_entity != 0) { current_entity->vx = 5; }
else { failures++; }

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das vollständige Programm zeigt den Lebenszyklus eines wiederverwendbaren Platzes. Lesen Sie Zahlen mit ihren Beschriftungen: CREATED 002 nach zwei Belegungen, AFTER FREE 001 nach Freigabe der ersten, REUSED ID 000 bei Wiederverwendung der kleinsten freien ID und AFTER CLEAR 000 nach Leeren des Pools. Geprüft werden auch null-Abfrage nach Freigabe und zurückgesetzte Felder nach Neubelegung. FAILED CHECKS 000 bestätigt die erwarteten Werte.

Der FC-Durchlauf ruft jeden Callback für beide aktiven Entities auf: UPDATE CALLS 002 und DRAW CALLS 002. Der Aktualisierungs-Callback verschiebt beide um ein Tile nach rechts. Der Zeichen-Callback setzt zur Darstellung der Objekte A auf Tile (3,12) und B auf (7,12). Das sind vom Callback gezeichnete Hintergrund-Schrift-Tiles, keine automatisch belegten Sprites.

Vollständiges Beispielprogramm

Build-Befehl

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];
}

Initialisiert alle Plätze im Entity-Pool.

Syntax

void entity_init(void);

Rückgabewert

Keiner (void).

Bedingungen und Grenzen

Der Pool ist ein festes Array ohne Heap-Allokation. ENTITY_MAX ist standardmäßig 16 und muss in allen Übersetzungseinheiten gleich mit einem Wert von 1 bis 255 definiert sein. IDs beginnen bei null; 0xFF kennzeichnet einen Fehlschlag.

Setzt in allen Plätzen active,type,x,y,vx,vy,state,timer auf null und sprite auf 0xFF. Hardware-Sprites werden dadurch weder verborgen noch freigegeben; ihre Ressourcen müssen separat aufgeräumt werden.

Anwendungsbeispiel

entity_init();
if (entity_count_active() != 0) { failures++; }

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das vollständige Programm zeigt den Lebenszyklus eines wiederverwendbaren Platzes. Lesen Sie Zahlen mit ihren Beschriftungen: CREATED 002 nach zwei Belegungen, AFTER FREE 001 nach Freigabe der ersten, REUSED ID 000 bei Wiederverwendung der kleinsten freien ID und AFTER CLEAR 000 nach Leeren des Pools. Geprüft werden auch null-Abfrage nach Freigabe und zurückgesetzte Felder nach Neubelegung. FAILED CHECKS 000 bestätigt die erwarteten Werte.

Der FC-Durchlauf ruft jeden Callback für beide aktiven Entities auf: UPDATE CALLS 002 und DRAW CALLS 002. Der Aktualisierungs-Callback verschiebt beide um ein Tile nach rechts. Der Zeichen-Callback setzt zur Darstellung der Objekte A auf Tile (3,12) und B auf (7,12). Das sind vom Callback gezeichnete Hintergrund-Schrift-Tiles, keine automatisch belegten Sprites.

Vollständiges Beispielprogramm

Build-Befehl

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

Durchläuft aktive Plätze nach aufsteigender ID und ruft für jeden einmal fn(id) auf. Bewegung, Kollisionen oder Timer implementiert der Callback; der Pool stellt diese Logik nicht bereit. Ein null-Callback bewirkt nichts.

Syntax

void entity_update_all(EntityFn fn);

Parameter

fn

Funktionszeiger mit Signatur void fn(u8 id). Er erhält eine Platz-ID; auf Felder greifen Sie über entity_get(id) zu. Null ist zulässig und führt zu keinen Aufrufen.

Rückgabewert

Keiner (void).

Bedingungen und Grenzen

Der Pool ist ein festes Array ohne Heap-Allokation. ENTITY_MAX ist standardmäßig 16 und muss in allen Übersetzungseinheiten gleich mit einem Wert von 1 bis 255 definiert sein. IDs beginnen bei null; 0xFF kennzeichnet einen Fehlschlag.

Der Durchlauf prüft die Aktivität erst beim Erreichen eines Platzes. Ein Callback kann spätere Plätze deaktivieren und damit überspringen lassen oder aktivieren und noch im selben Durchlauf besuchen lassen. Es wird kein Schnappschuss der anfänglichen Belegung verwendet.

Lege den Callback in die gemeinsame PRG-Bank 0 oder halte seine Bank während des gesamten Aufrufs eingeblendet. Ein Funktionszeiger enthält eine 16-Bit-CPU-Adresse und schaltet keine Bank um. Parameter und lokale Variablen der FC-Funktionen belegen feste Speicherbereiche. Rufe den Entity-Durchlauf daher weder rekursiv auf noch erneut aus einem Interrupt, während er bereits läuft.

Anwendungsbeispiel

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++; }

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das vollständige Programm zeigt den Lebenszyklus eines wiederverwendbaren Platzes. Lesen Sie Zahlen mit ihren Beschriftungen: CREATED 002 nach zwei Belegungen, AFTER FREE 001 nach Freigabe der ersten, REUSED ID 000 bei Wiederverwendung der kleinsten freien ID und AFTER CLEAR 000 nach Leeren des Pools. Geprüft werden auch null-Abfrage nach Freigabe und zurückgesetzte Felder nach Neubelegung. FAILED CHECKS 000 bestätigt die erwarteten Werte.

Der FC-Durchlauf ruft jeden Callback für beide aktiven Entities auf: UPDATE CALLS 002 und DRAW CALLS 002. Der Aktualisierungs-Callback verschiebt beide um ein Tile nach rechts. Der Zeichen-Callback setzt zur Darstellung der Objekte A auf Tile (3,12) und B auf (7,12). Das sind vom Callback gezeichnete Hintergrund-Schrift-Tiles, keine automatisch belegten Sprites.

Vollständiges Beispielprogramm

Build-Befehl

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

Dividiert Q8.8-Werte nach einer Verringerung der Operandengenauigkeit.

Syntax

fix8 fix_div(fix8 a, fix8 b);

Parameter

a

Linker Operand im Q8.8-Format.

b

Rechter Operand im Q8.8-Format.

Rückgabewert

Gibt einen Q8.8-Quotienten zurück, bei b == 0 hingegen null.

Bedingungen und Grenzen

Berechnet wird ((a >> 4) * 256) / (b >> 4). Ein von null verschiedener Divisor darf durch die Verschiebung nicht null werden; übergeben Sie daher keine positiven Rohwerte von 1 bis 15. Auch der skalierte Zähler muss in 16 Bits passen.

Anwendungsbeispiel

result[3]=fix_div(768,512);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

3,0 geteilt durch 2,0 ergibt 1,5 (Rohwert 384). Ein eigener Test prüft den ausdrücklich vorgesehenen Rückgabewert bei Divisor null.

Vollständiges Beispielprogramm

Build-Befehl

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

Wandelt eine ganzzahlige Koordinate oder Geschwindigkeit in Q8.8 um, damit nachfolgende Berechnungen Nachkommastellen erhalten können.

Syntax

fix8 fix_from_int(s16 n);

Parameter

n

Die umzuwandelnde ganze Zahl im Bereich −128 bis 127.

Rückgabewert

Gibt den Rohwert n × 256 zurück.

Bedingungen und Grenzen

fix8 ist ein vorzeichenbehaftetes Q8.8-Format: Der Rohwert 256 steht für 1,0. Zwischenwerte und Ergebnisse müssen im 16-Bit-Wertebereich bleiben.

Anwendungsbeispiel

result[0]=fix_from_int(-3);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel wandelt −3 um. Die Anzeige −00768 entspricht dem Q8.8-Rohwert −768.

Vollständiges Beispielprogramm

Build-Befehl

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

Interpoliert mit einem 8-Bit-Gewicht von einem Q8.8-Wert in Richtung eines anderen.

Syntax

fix8 fix_lerp(fix8 a, fix8 b, u8 t_q8);

Parameter

a

Linker Operand im Q8.8-Format.

b

Rechter Operand im Q8.8-Format.

t_q8

Interpolationsgewicht von 0 bis 255.

Rückgabewert

Gibt den näherungsweise interpolierten Q8.8-Wert zurück.

Bedingungen und Grenzen

Differenz und Gewicht werden jeweils um vier Bits nach rechts geschoben. Dadurch gibt es nur 16 Gewichtsstufen; selbst 255 muss den Endwert nicht erreichen. b - a und das Endergebnis müssen im 16-Bit-Bereich bleiben.

Anwendungsbeispiel

result[4]=fix_lerp(0,1024,128);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Zwischen 0 und 4,0 ergibt Gewicht 128 den Wert 2,0 (Rohwert 512). Gewicht 255 liefert 3,75 (Rohwert 960) und zeigt damit, dass der Endwert nicht erreicht wird.

Vollständiges Beispielprogramm

Build-Befehl

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

Multipliziert zwei Q8.8-Werte mit einem rechenarmen Näherungsverfahren.

Syntax

fix8 fix_mul(fix8 a, fix8 b);

Parameter

a

Linker Operand im Q8.8-Format.

b

Rechter Operand im Q8.8-Format.

Rückgabewert

Gibt das Produkt im Q8.8-Format zurück.

Bedingungen und Grenzen

Vor der Multiplikation wird jeder Operand um vier Bits nach rechts geschoben; seine vier niederwertigsten Bits gehen verloren. Das ist ungenauer als ein vollständiges 16-mal-16-Bit-Produkt. fix8 ist vorzeichenbehaftetes Q8.8, wobei der Rohwert 256 für 1,0 steht. Zwischenwerte und Ergebnisse müssen im 16-Bit-Bereich bleiben.

Anwendungsbeispiel

result[2]=fix_mul(384,512);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

1,5 mal 2,0 ergibt 3,0 (Rohwert 768). Das Programm prüft auch die Quantisierung: Rohwert 271 mal Rohwert 271 ergibt 256.

Vollständiges Beispielprogramm

Build-Befehl

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

Gewinnt eine ganzzahlige Koordinate aus Q8.8, indem die Nachkommabits verworfen werden. Negative Werte werden gegen minus unendlich abgerundet.

Syntax

s16 fix_to_int(fix8 x);

Parameter

x

Der in eine ganze Zahl umzuwandelnde Q8.8-Wert.

Rückgabewert

Gibt eine vorzeichenbehaftete ganze Zahl zurück.

Bedingungen und Grenzen

fix8 ist ein vorzeichenbehaftetes Q8.8-Format: Der Rohwert 256 steht für 1,0. Zwischenwerte und Ergebnisse müssen im 16-Bit-Wertebereich bleiben.

Anwendungsbeispiel

result[1]=fix_to_int(-384);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Der Rohwert −384 (−1,5) ergibt −2 und wird als −00002 angezeigt. Ein Grenzwerttest bestätigt außerdem, dass der Rohwert −1 zu −1 wird.

Vollständiges Beispielprogramm

Build-Befehl

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

Ermittelt den Betrag eines vorzeichenbehafteten 16-Bit-Werts.

Syntax

s16 kq_abs_s16(s16 v);

Parameter

v

Vorzeichenbehafteter 16-Bit-Wert, dessen Betrag benötigt wird.

Rückgabewert

Gibt einen nichtnegativen Betrag zurück, mit Ausnahme des nicht darstellbaren Betrags von −32768.

Bedingungen und Grenzen

Der positive Betrag 32768 passt nicht in s16. Schließen Sie −32768 aus, wenn das Ergebnis nichtnegativ sein muss.

Anwendungsbeispiel

result[0]=kq_abs_s16(-123);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Beispiel wandelt −123 in 123 um, etwa zur Bestimmung des Betrags einer Koordinatendifferenz.

Vollständiges Beispielprogramm

Build-Befehl

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

Begrenzt eine Koordinate oder Geschwindigkeit auf ein Intervall einschließlich seiner Grenzen.

Syntax

s16 kq_clamp_s16(s16 v, s16 lo, s16 hi);

Parameter

v

Zu begrenzender Wert mit Vorzeichen.

lo

Einschließlich geltende Untergrenze.

hi

Einschließlich geltende Obergrenze.

Rückgabewert

Gibt unterhalb des Intervalls lo, oberhalb hi und innerhalb v zurück.

Bedingungen und Grenzen

Geben Sie ein gültiges Intervall mit lo <= hi an.

Anwendungsbeispiel

result[3]=kq_clamp_s16(25,-10,10);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Das Begrenzen von 25 auf −10…10 ergibt 10. Geprüft werden auch −11→−10 an der unteren Grenze und 3→3 innerhalb des Intervalls.

Vollständiges Beispielprogramm

Build-Befehl

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

Wählt den größeren von zwei vorzeichenbehafteten 16-Bit-Werten.

Syntax

s16 kq_max_s16(s16 a, s16 b);

Parameter

a

Erster zu vergleichender Wert mit Vorzeichen.

b

Zweiter zu vergleichender Wert mit Vorzeichen.

Rückgabewert

Gibt den ausgewählten Operanden zurück.

Bedingungen und Grenzen

Der Vergleich berücksichtigt das Vorzeichen. Bei gleichen Operanden wird dieser gemeinsame Wert zurückgegeben; beide Eingaben bleiben unverändert.

Anwendungsbeispiel

result[2]=kq_max_s16(-7,4);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Der Vergleich von −7 und 4 ergibt 4. Negative Ergebnisse werden mit Minuszeichen angezeigt.

Vollständiges Beispielprogramm

Build-Befehl

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

Wählt den kleineren von zwei vorzeichenbehafteten 16-Bit-Werten.

Syntax

s16 kq_min_s16(s16 a, s16 b);

Parameter

a

Erster zu vergleichender Wert mit Vorzeichen.

b

Zweiter zu vergleichender Wert mit Vorzeichen.

Rückgabewert

Gibt den ausgewählten Operanden zurück.

Bedingungen und Grenzen

Der Vergleich berücksichtigt das Vorzeichen. Bei gleichen Operanden wird dieser gemeinsame Wert zurückgegeben; beide Eingaben bleiben unverändert.

Anwendungsbeispiel

result[1]=kq_min_s16(-7,4);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Der Vergleich von −7 und 4 ergibt -7. Negative Ergebnisse werden mit Minuszeichen angezeigt.

Vollständiges Beispielprogramm

Build-Befehl

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

Prüft, ob ein Punkt im Rechteck liegt; linke und obere Kante sind eingeschlossen.

Syntax

u8 kq_point_in_rect(s16 x, s16 y, KQRect r);

Parameter

x

X-Koordinate des Punkts im Koordinatensystem des Rechtecks.

y

Y-Koordinate des Punkts.

r

Zu prüfendes Rechteck, als Wert übergeben.

Rückgabewert

Gibt innen 1 und außen 0 zurück.

Bedingungen und Grenzen

Verwenden Sie positive Abmessungen; Koordinate plus Größe muss als s16 darstellbar bleiben. Rechte und untere Kante sind ausgeschlossen. Rechtecke mit Fläche null werden nicht ausdrücklich abgewiesen.

Anwendungsbeispiel

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

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Jede Koordinateneinheit entspricht einer Kachel. Rechteck A bei (1,1) und B bei (5,4) sind jeweils 8×6 groß. Nur von A belegte Zellen zeigen A, nur von B belegte zeigen B, und die 4×3 große Überlappung zeigt zwölf O-Zellen. Die rechte Kante von A bei x=9 zählt nicht dazu. Auf dem CGB ist A rot, B blau und O grün.

Vollständiges Beispielprogramm

Build-Befehl

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

Prüft, ob sich zwei achsenparallele Rechtecke mit positiver Fläche überschneiden.

Syntax

u8 kq_rect_intersect(KQRect a, KQRect b);

Parameter

a

Erstes Rechteck, als Wert übergeben: x, y geben die linke obere Ecke an, w, h seine Breite und Höhe.

b

Zweites Rechteck im selben Koordinatensystem wie A.

Rückgabewert

Gibt bei Überschneidung 1 zurück, bei Trennung oder bloßer Kantenberührung 0.

Bedingungen und Grenzen

Verwenden Sie positive Abmessungen; Koordinate plus Größe muss als s16 darstellbar bleiben. Rechte und untere Kante sind ausgeschlossen. Rechtecke mit Fläche null werden nicht ausdrücklich abgewiesen.

Anwendungsbeispiel

result[0]=kq_rect_intersect(a,b);result[2]=kq_rect_intersect(a,touch);

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Jede Koordinateneinheit entspricht einer Kachel. Rechteck A bei (1,1) und B bei (5,4) sind jeweils 8×6 groß. Nur von A belegte Zellen zeigen A, nur von B belegte zeigen B, und die 4×3 große Überlappung zeigt zwölf O-Zellen. Die rechte Kante von A bei x=9 zählt nicht dazu. Auf dem CGB ist A rot, B blau und O grün.

Vollständiges Beispielprogramm

Build-Befehl

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 ist ein Alias für input_down. Prüft, ob mindestens eine der ausgewählten Tasten gerade gehalten wird.

Prüft, ob eine durch mask gewählte Taste gerade gehalten wird.

Syntax

u8 btn_down(u8 mask);

Parameter

mask

Eine BTN_*-Maske oder mehrere mit | verknüpfte Masken. Eine einzige passende Taste genügt; BTN_A | BTN_B verlangt nicht beide zugleich. Maske 0 liefert immer 0. Alle gehaltenen Tasten prüfst du mit (input_current() & mask) == mask.

Rückgabewert

Genau 1, wenn mindestens eine gewählte Taste die abgefragte Bedingung erfüllt, sonst 0. Der Rückgabewert ist keine Tastenmaske.

Bedingungen und Grenzen

Der Header definiert ein objektartiges Makro, das zum Implementierungsnamen expandiert. Argumente, Rückgabewerte und Zustandszugriffe entsprechen dem Ziel; der Alias fügt keinen eigenen Zustand oder Verarbeitungsschritt hinzu. Verwenden Sie wie im vollständigen Beispiel und Buildbefehl input.h/input.c für Eingaben oder system.h/system.c für Framedienste.

Gemeinsame Masken: BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80. Ein gesetztes Bit bedeutet gedrückt. input_* verwendet dieses Format auf GB und FC; rohe FC-Pad-Abfragen verwenden eine andere Bitreihenfolge.

Abfragen lesen den letzten input_update()-Zustand, ohne erneut abzufragen, ein Ereignis zu verbrauchen oder einen Zähler weiterzuführen. Mehrfache Abfragen im selben Takt liefern dasselbe Ergebnis. Bei zweimaligem input_update() mit gehaltener Taste ist das neue Druckereignis im zweiten Aufruf gelöscht.

input_down

Anwendungsbeispiel

if (btn_down(BTN_A)!=0) held_ticks++;

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Dieses Programm zeigt den Unterschied zwischen einer gehaltenen Taste, einem neuen Tastendruck, dem Loslassen und der automatischen Wiederholung. Halten Sie A für 40 Aktualisierungen gedrückt und lassen Sie die Taste dann los. FIRST DOWN, FIRST PRESS und FIRST REPEAT sind 1; FIRST CURRENT ist 16. HELD TICKS ist 40, PRESS COUNT ist 1 und REPEAT COUNT ist 5. Beim Loslassen ist RELEASE 1, LAST CURRENT 0 und LAST PREVIOUS 16. FAILED CHECKS muss 0 sein. Eine andere Haltedauer verändert die Zähler; das Programm prüft die Wiederholungsabstände anhand der tatsächlich beobachteten Dauer.

Vollständiges Beispielprogramm

Build-Befehl

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 ist ein Alias für input_pressed. Prüft, ob bei der letzten Eingabeaktualisierung mindestens eine ausgewählte Taste neu gedrückt wurde.

Prüft, ob eine maskierte Taste bei der letzten Eingabeaktualisierung neu gedrückt wurde.

Syntax

u8 btn_pressed(u8 mask);

Parameter

mask

Eine BTN_*-Maske oder mehrere mit | verknüpfte Masken. Eine einzige passende Taste genügt; BTN_A | BTN_B verlangt nicht beide zugleich. Maske 0 liefert immer 0. Alle gehaltenen Tasten prüfst du mit (input_current() & mask) == mask.

Rückgabewert

Genau 1, wenn mindestens eine gewählte Taste die abgefragte Bedingung erfüllt, sonst 0. Der Rückgabewert ist keine Tastenmaske.

Bedingungen und Grenzen

Der Header definiert ein objektartiges Makro, das zum Implementierungsnamen expandiert. Argumente, Rückgabewerte und Zustandszugriffe entsprechen dem Ziel; der Alias fügt keinen eigenen Zustand oder Verarbeitungsschritt hinzu. Verwenden Sie wie im vollständigen Beispiel und Buildbefehl input.h/input.c für Eingaben oder system.h/system.c für Framedienste.

Gemeinsame Masken: BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80. Ein gesetztes Bit bedeutet gedrückt. input_* verwendet dieses Format auf GB und FC; rohe FC-Pad-Abfragen verwenden eine andere Bitreihenfolge.

Abfragen lesen den letzten input_update()-Zustand, ohne erneut abzufragen, ein Ereignis zu verbrauchen oder einen Zähler weiterzuführen. Mehrfache Abfragen im selben Takt liefern dasselbe Ergebnis. Bei zweimaligem input_update() mit gehaltener Taste ist das neue Druckereignis im zweiten Aufruf gelöscht.

input_pressed

Anwendungsbeispiel

if (btn_pressed(BTN_A)!=0) {
        press_count++; seen_press=1;
        first_down=btn_down(BTN_A); first_press=btn_pressed(BTN_A);
        first_repeat=btn_repeat(BTN_A);
        first_current=input_current(); // Only A held: BTN_A, or decimal 16.
        first_previous=input_previous(); // No buttons in the preceding sample: 0.
        if (first_down!=1 || first_press!=1 || first_repeat!=1) failures++;
        if (first_current!=BTN_A || first_previous!=0) failures++;
        if (btn_down(BTN_A|BTN_B)!=1 || btn_down(0)!=0) failures++;
    }

Dieser Ausschnitt zeigt den Aufruf. Beachten Sie beim Einbau in ein vollständiges Programm die angegebenen Anforderungen an Initialisierung und Puffer.

Erwartetes Ergebnis

Dieses Programm zeigt den Unterschied zwischen einer gehaltenen Taste, einem neuen Tastendruck, dem Loslassen und der automatischen Wiederholung. Halten Sie A für 40 Aktualisierungen gedrückt und lassen Sie die Taste dann los. FIRST DOWN, FIRST PRESS und FIRST REPEAT sind 1; FIRST CURRENT ist 16. HELD TICKS ist 40, PRESS COUNT ist 1 und REPEAT COUNT ist 5. Beim Loslassen ist RELEASE 1, LAST CURRENT 0 und LAST PREVIOUS 16. FAILED CHECKS muss 0 sein. Eine andere Haltedauer verändert die Zähler; das Programm prüft die Wiederholungsabstände anhand der tatsächlich beobachteten Dauer.

Vollständiges Beispielprogramm

Build-Befehl

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_pressed input_pressed