BIBLIOTHÈQUE KITAQFC

Teste le chevauchement des rectangles d’acteurs alignés sur les axes dans les coordonnées du monde.

Syntaxe

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

Paramètres

a

Premier acteur.

b

Second acteur.

Valeur renvoyée

Renvoie 1 en cas de chevauchement, 0 si les rectangles sont séparés ou si leurs bords se touchent seulement.

Conditions et limites

Utilisez des largeurs et hauteurs positives et gardez position+taille≤65535. Les coordonnées d’écran, attr et flags sont ignorés.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Projetez (300,95) du monde via la caméra (268,32) : les parties rouges et bleues de 8×8 apparaissent en (32,64) et (40,64). Cela montre que le Y OAM brut 63 apparaît à 64, et que la collision passe de zéro pour des bords jointifs à un pour un chevauchement d’un pixel.

Programme d’exemple complet

Commande de compilation

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

Écrit un métasprite dans le miroir OAM à l’aide des coordonnées d’écran mises en cache de l’acteur.

Syntaxe

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

Paramètres

actor

Pointeur vers un NesActor accessible en écriture.

oam_index

Premier emplacement, de 0 à 63 ; réservez de la place pour toutes les parties.

metasprite

Enregistrements de quatre octets dx,dy,tile,attr ; dx=255 termine la liste.

Valeur renvoyée

Renvoie l’indice du prochain emplacement OAM, avec rebouclage après les 64 emplacements.

Conditions et limites

Liez runtime.c. La file copie les données pour une NMI ultérieure ou une application sûre avec le rendu désactivé. Sérialisez la production et la consommation. Si une opération multiligne manque de place, les lignes déjà acceptées restent en file.

N’applique pas les champs attr/flags de l’acteur. Y est un octet OAM brut : le haut visible est donc un pixel plus bas. Un DMA OAM est nécessaire pour afficher le miroir.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Projetez (300,95) du monde via la caméra (268,32) : les parties rouges et bleues de 8×8 apparaissent en (32,64) et (40,64). Cela montre que le Y OAM brut 63 apparaît à 64, et que la collision passe de zéro pour des bords jointifs à un pour un chevauchement d’un pixel.

Programme d’exemple complet

Commande de compilation

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

Définit le X/Y d’un acteur dans le monde.

Syntaxe

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

Paramètres

actor

Pointeur vers un NesActor accessible en écriture.

x

X du monde, de 0 à 65535 pixels.

y

Y du monde, de 0 à 65535 pixels.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Ne met pas screen_x/screen_y à jour. Appelez update_screen pour projeter la position à travers la caméra.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Projetez (300,95) du monde via la caméra (268,32) : les parties rouges et bleues de 8×8 apparaissent en (32,64) et (40,64). Cela montre que le Y OAM brut 63 apparaît à 64, et que la collision passe de zéro pour des bords jointifs à un pour un chevauchement d’un pixel.

Programme d’exemple complet

Commande de compilation

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

Soustrait les coordonnées de la caméra à celles du monde et met en cache les octets faibles comme coordonnées d’écran.

Syntaxe

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

Paramètres

actor

Pointeur vers un NesActor accessible en écriture.

camera_x

X de la caméra dans le monde.

camera_y

Y de la caméra dans le monde.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Les résultats négatifs ou ≥256 rebouclent. Les acteurs hors écran ne sont pas masqués ; le jeu doit les écarter avant le dessin.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Projetez (300,95) du monde via la caméra (268,32) : les parties rouges et bleues de 8×8 apparaissent en (32,64) et (40,64). Cela montre que le Y OAM brut 63 apparaît à 64, et que la collision passe de zéro pour des bords jointifs à un pour un chevauchement d’un pixel.

Programme d’exemple complet

Commande de compilation

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

Copie un AssetDesc depuis la banque ROM de la table enregistrée vers l’espace fourni par l’appelant. Elle récupère les métadonnées de la ressource, pas son contenu.

Syntaxe

u8 asset_get(u8 asset_id, AssetDesc* out_desc);

Paramètres

asset_id

Indice de ressource à partir de zéro. Il doit vérifier asset_id < count dans la table enregistrée.

out_desc

Espace accessible en écriture pour un descripteur de 6 octets. Un pointeur nul est rejeté avant tout accès à la table.

Valeur renvoyée

1 après copie du descripteur ; 0 si la sortie est nulle ou l’identifiant hors limites. Dans ces deux cas, la sortie reste inchangée.

Conditions et limites

Enregistrez la table avant toute recherche. Cet enregistrement est un état global partagé : ne le modifiez pas pendant une recherche. La bibliothèque vérifie les identifiants et le pointeur de sortie de asset_get, mais pas la table enregistrée, les adresses des données ni le contenu de la cartouche.

Les exemples placent le code appelant dans la banque fixe 0 afin qu’un changement de banque source ne le rende pas inaccessible. Les transferts sont synchrones. N’interrompez pas un transfert par une autre copie changeant de banque ; cette fonction ne garantit pas à elle seule la sûreté des interruptions de toute l’application.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple lit le descripteur 0 et vérifie le type TILES, la banque 2, le pointeur et la longueur de 144 octets. Les identifiants invalides et sorties nulles doivent être refusés, sans modifier la valeur de sortie précédente.

Image attendue : une rangée rouge part de (16,32) et occupe 72×8 pixels. Elle répète trois fois un triangle de 8×8, un carré de 8×8 au contour d’un pixel et une tuile dont les quatre colonnes de gauche sont pleines. Le triangle s’élargit d’un pixel en haut à gauche à huit sur sa ligne inférieure.

Sur FC, la paire bleue en (16,64) montre __far_memcpy ; la verte en (16,96), asset_load_raw suivi d’un transfert en CHR. Chaque paire occupe 16×8 pixels sur fond noir. Ces rangées montrent les données graphiques copiées, pas seulement des valeurs d’état numériques.

L’état attendu est FAILED CHECKS 000 et FIRST FAILURE 00. La vérification exécute 300 images puis compare texte, formes et couleurs aux résultats attendus. Il s’agit d’une preuve sur émulateur, pas d’un essai sur matériel physique.

Programme d’exemple complet

Commande de compilation

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

Lit dans le descripteur le numéro de banque des données. Ce n’est pas la banque de la table, et la fonction ne laisse pas cette banque de données sélectionnée.

Syntaxe

u8 asset_get_bank(u8 asset_id);

Paramètres

asset_id

Indice de ressource à partir de zéro. Il doit vérifier asset_id < count dans la table enregistrée.

Valeur renvoyée

Le champ bank sur 8 bits, ou 0 si la recherche échoue. La banque zéro pouvant être valide, utilisez asset_get() pour distinguer succès et valeur nulle.

Conditions et limites

Enregistrez la table avant toute recherche. Cet enregistrement est un état global partagé : ne le modifiez pas pendant une recherche. La bibliothèque vérifie les identifiants et le pointeur de sortie de asset_get, mais pas la table enregistrée, les adresses des données ni le contenu de la cartouche.

Chaque accesseur rappelle asset_get et copie un descripteur. Pour obtenir banque, pointeur et longueur ensemble, appelez asset_get une seule fois et lisez ses champs.

Les exemples placent le code appelant dans la banque fixe 0 afin qu’un changement de banque source ne le rende pas inaccessible. Les transferts sont synchrones. N’interrompez pas un transfert par une autre copie changeant de banque ; cette fonction ne garantit pas à elle seule la sûreté des interruptions de toute l’application.

Exemple d’utilisation

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.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple attend la banque de données 2 alors que la table est dans la banque 3. Il vérifie aussi qu’un identifiant invalide renvoie zéro.

Image attendue : une rangée rouge part de (16,32) et occupe 72×8 pixels. Elle répète trois fois un triangle de 8×8, un carré de 8×8 au contour d’un pixel et une tuile dont les quatre colonnes de gauche sont pleines. Le triangle s’élargit d’un pixel en haut à gauche à huit sur sa ligne inférieure.

Sur FC, la paire bleue en (16,64) montre __far_memcpy ; la verte en (16,96), asset_load_raw suivi d’un transfert en CHR. Chaque paire occupe 16×8 pixels sur fond noir. Ces rangées montrent les données graphiques copiées, pas seulement des valeurs d’état numériques.

L’état attendu est FAILED CHECKS 000 et FIRST FAILURE 00. La vérification exécute 300 images puis compare texte, formes et couleurs aux résultats attendus. Il s’agit d’une preuve sur émulateur, pas d’un essai sur matériel physique.

Programme d’exemple complet

Commande de compilation

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

Lit dans le descripteur la longueur de la ressource en octets. Il s’agit d’une métadonnée : la fonction n’examine pas le contenu et ne calcule aucun nombre de tuiles, d’éléments ou d’images.

Syntaxe

u16 asset_get_len(u8 asset_id);

Paramètres

asset_id

Indice de ressource à partir de zéro. Il doit vérifier asset_id < count dans la table enregistrée.

Valeur renvoyée

Le champ len sur 16 bits, en octets, ou 0 si la recherche échoue. Une ressource vide a aussi une longueur nulle ; asset_get() permet de faire la distinction.

Conditions et limites

Enregistrez la table avant toute recherche. Cet enregistrement est un état global partagé : ne le modifiez pas pendant une recherche. La bibliothèque vérifie les identifiants et le pointeur de sortie de asset_get, mais pas la table enregistrée, les adresses des données ni le contenu de la cartouche.

Chaque accesseur rappelle asset_get et copie un descripteur. Pour obtenir banque, pointeur et longueur ensemble, appelez asset_get une seule fois et lisez ses champs.

Les exemples placent le code appelant dans la banque fixe 0 afin qu’un changement de banque source ne le rende pas inaccessible. Les transferts sont synchrones. N’interrompez pas un transfert par une autre copie changeant de banque ; cette fonction ne garantit pas à elle seule la sûreté des interruptions de toute l’application.

Exemple d’utilisation

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.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

La ressource de neuf tuiles doit indiquer 144 octets, et non neuf tuiles. Une ressource vide comme un identifiant invalide doivent renvoyer zéro.

Image attendue : une rangée rouge part de (16,32) et occupe 72×8 pixels. Elle répète trois fois un triangle de 8×8, un carré de 8×8 au contour d’un pixel et une tuile dont les quatre colonnes de gauche sont pleines. Le triangle s’élargit d’un pixel en haut à gauche à huit sur sa ligne inférieure.

Sur FC, la paire bleue en (16,64) montre __far_memcpy ; la verte en (16,96), asset_load_raw suivi d’un transfert en CHR. Chaque paire occupe 16×8 pixels sur fond noir. Ces rangées montrent les données graphiques copiées, pas seulement des valeurs d’état numériques.

L’état attendu est FAILED CHECKS 000 et FIRST FAILURE 00. La vérification exécute 300 images puis compare texte, formes et couleurs aux résultats attendus. Il s’agit d’une preuve sur émulateur, pas d’un essai sur matériel physique.

Programme d’exemple complet

Commande de compilation

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

Lit l’adresse sur 16 bits conservée dans le descripteur. Le pointeur proche renvoyé ne contient aucun numéro de banque. Pour lire une autre banque ROM, associez-le à asset_get_bank() et à une fonction de copie interbanques.

Syntaxe

const u8* asset_get_ptr(u8 asset_id);

Paramètres

asset_id

Indice de ressource à partir de zéro. Il doit vérifier asset_id < count dans la table enregistrée.

Valeur renvoyée

Le const u8* enregistré, ou un pointeur nul si la recherche échoue. Le pointeur du descripteur n’étant pas validé, utilisez asset_get() pour reconnaître un échec de recherche.

Conditions et limites

Enregistrez la table avant toute recherche. Cet enregistrement est un état global partagé : ne le modifiez pas pendant une recherche. La bibliothèque vérifie les identifiants et le pointeur de sortie de asset_get, mais pas la table enregistrée, les adresses des données ni le contenu de la cartouche.

Chaque accesseur rappelle asset_get et copie un descripteur. Pour obtenir banque, pointeur et longueur ensemble, appelez asset_get une seule fois et lisez ses champs.

Les exemples placent le code appelant dans la banque fixe 0 afin qu’un changement de banque source ne le rende pas inaccessible. Les transferts sont synchrones. N’interrompez pas un transfert par une autre copie changeant de banque ; cette fonction ne garantit pas à elle seule la sûreté des interruptions de toute l’application.

Exemple d’utilisation

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.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le pointeur doit correspondre à l’adresse ROM de la ressource après placement, tandis qu’un marqueur de la banque 1 reste lisible. L’exemple passe ensuite ce pointeur et la banque 2 à une copie interbanques.

Image attendue : une rangée rouge part de (16,32) et occupe 72×8 pixels. Elle répète trois fois un triangle de 8×8, un carré de 8×8 au contour d’un pixel et une tuile dont les quatre colonnes de gauche sont pleines. Le triangle s’élargit d’un pixel en haut à gauche à huit sur sa ligne inférieure.

Sur FC, la paire bleue en (16,64) montre __far_memcpy ; la verte en (16,96), asset_load_raw suivi d’un transfert en CHR. Chaque paire occupe 16×8 pixels sur fond noir. Ces rangées montrent les données graphiques copiées, pas seulement des valeurs d’état numériques.

L’état attendu est FAILED CHECKS 000 et FIRST FAILURE 00. La vérification exécute 300 images puis compare texte, formes et couleurs aux résultats attendus. Il s’agit d’une preuve sur émulateur, pas d’un essai sur matériel physique.

Programme d’exemple complet

Commande de compilation

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

Recherche la ressource et copie min(desc.len, max_len) octets de sa banque ROM vers une mémoire accessible en écriture. Le type est ignoré : graphismes, cartes et morceaux sont copiés tels quels, sans décodage ni décompression.

Syntaxe

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

Paramètres

asset_id

Indice de ressource à partir de zéro. Il doit vérifier asset_id < count dans la table enregistrée.

dst

Destination en mémoire accessible en écriture, assez grande pour tous les octets copiés. Hors transfert de zéro octet, les adresses nulles ou invalides ne sont pas vérifiées.

max_len

Nombre maximal d’octets à copier, de 0 à 65535. Une limite plus petite tronque la copie ; zéro ne copie aucun octet du contenu.

Valeur renvoyée

0 si la recherche échoue ; sinon 1, même pour une copie tronquée, une limite nulle ou une ressource vide. Ce n’est ni un nombre d’octets ni la garantie que toute la ressource tenait dans le tampon.

Conditions et limites

Enregistrez la table avant toute recherche. Cet enregistrement est un état global partagé : ne le modifiez pas pendant une recherche. La bibliothèque vérifie les identifiants et le pointeur de sortie de asset_get, mais pas la table enregistrée, les adresses des données ni le contenu de la cartouche.

Toute la source doit être lisible dans le mappage ROM prévu, et toute la destination accessible en écriture. La copie ne passe pas automatiquement à la banque suivante, ne gère pas les chevauchements comme memmove et ne synchronise pas les écritures VRAM. Utilisez les API graphiques pour la VRAM.

Les exemples placent le code appelant dans la banque fixe 0 afin qu’un changement de banque source ne le rende pas inaccessible. Les transferts sont synchrones. N’interrompez pas un transfert par une autre copie changeant de banque ; cette fonction ne garantit pas à elle seule la sûreté des interruptions de toute l’application.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Une limite de sept copie seulement sept octets d’une ressource de 144, laisse le suivant à 0x55 et renvoie pourtant un succès. Le programme teste aussi la copie complète, une limite nulle, une ressource vide et la copie brute de données MAP.

Image attendue : une rangée rouge part de (16,32) et occupe 72×8 pixels. Elle répète trois fois un triangle de 8×8, un carré de 8×8 au contour d’un pixel et une tuile dont les quatre colonnes de gauche sont pleines. Le triangle s’élargit d’un pixel en haut à gauche à huit sur sa ligne inférieure.

Sur FC, la paire bleue en (16,64) montre __far_memcpy ; la verte en (16,96), asset_load_raw suivi d’un transfert en CHR. Chaque paire occupe 16×8 pixels sur fond noir. Ces rangées montrent les données graphiques copiées, pas seulement des valeurs d’état numériques.

L’état attendu est FAILED CHECKS 000 et FIRST FAILURE 00. La vérification exécute 300 images puis compare texte, formes et couleurs aux résultats attendus. Il s’agit d’une preuve sur émulateur, pas d’un essai sur matériel physique.

Programme d’exemple complet

Commande de compilation

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

Recherche une ressource RAW ou TILES, sélectionne sa banque ROM et transfère toutes les données avec __vram_write, par blocs de 128 octets au maximum. Elle rétablit ensuite la banque mémorisée par bank_get_current(). Le découpage n’attend pas l’image suivante.

Syntaxe

u8 asset_load_tiles(u8 asset_id, u16 vram_dst);

Paramètres

asset_id

Indice de ressource à partir de zéro. Il doit vérifier asset_id < count dans la table enregistrée.

vram_dst

Adresse en octets du PPU, et non adresse CPU ou numéro de tuile. Les motifs sont chargés en CHR RAM accessible en écriture, entre $0000 et $1FFF, à raison de 16 octets par tuile. Le transfert doit rester dans la zone PPU prévue.

Valeur renvoyée

0 pour un identifiant invalide ou un type autre que RAW/TILES ; 1 après un transfert accepté, même de longueur nulle. Ce succès ne valide ni l’encodage des tuiles ni leur affichage.

Conditions et limites

Enregistrez la table avant toute recherche. Cet enregistrement est un état global partagé : ne le modifiez pas pendant une recherche. La bibliothèque vérifie les identifiants et le pointeur de sortie de asset_get, mais pas la table enregistrée, les adresses des données ni le contenu de la cartouche.

Les exemples placent le code appelant dans la banque fixe 0 afin qu’un changement de banque source ne le rende pas inaccessible. Les transferts sont synchrones. N’interrompez pas un transfert par une autre copie changeant de banque ; cette fonction ne garantit pas à elle seule la sûreté des interruptions de toute l’application.

Le transfert écrit uniquement des octets : il ne place pas les tuiles sur la carte, n’attribue pas de couleurs et n’alloue pas de VRAM. Configurez séparément la carte et les palettes. Les exemples effectuent le transfert avec le rendu désactivé, puis activent l’affichage.

asset_load_tiles rétablit la banque suivie par bank.c, sans relire le mapper. Initialisez et maintenez cet état avec bank_switch ; les écritures directes et les appels isolés à __bankswitch ne mettent pas à jour la bibliothèque. La copie intrinsèque rétablit séparément l’état du compilateur.

Utilisez de la CHR RAM accessible en écriture et désactivez le rendu pour les longs transferts. Pendant VBlank, toute l’opération doit tenir dans le temps disponible ; les blocs de 128 octets ne le garantissent pas. L’exemple utilise --mapper=mmc1 --board=surom512. Sur les cartes génériques, omettre --nes-chr produit une CHR ROM vide, pas de la CHR RAM.

Exemple d’utilisation

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.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple charge neuf motifs originaux de 8×8 pixels, soit 144 octets, et vérifie le rejet du type MAP et des identifiants invalides. Sur FC, cette longueur teste le bloc de 128 octets ainsi que les 16 octets restants.

Image attendue : une rangée rouge part de (16,32) et occupe 72×8 pixels. Elle répète trois fois un triangle de 8×8, un carré de 8×8 au contour d’un pixel et une tuile dont les quatre colonnes de gauche sont pleines. Le triangle s’élargit d’un pixel en haut à gauche à huit sur sa ligne inférieure.

Sur FC, la paire bleue en (16,64) montre __far_memcpy ; la verte en (16,96), asset_load_raw suivi d’un transfert en CHR. Chaque paire occupe 16×8 pixels sur fond noir. Ces rangées montrent les données graphiques copiées, pas seulement des valeurs d’état numériques.

L’état attendu est FAILED CHECKS 000 et FIRST FAILURE 00. La vérification exécute 300 images puis compare texte, formes et couleurs aux résultats attendus. Il s’agit d’une preuve sur émulateur, pas d’un essai sur matériel physique.

Programme d’exemple complet

Commande de compilation

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

Enregistre la banque, l’adresse et le nombre d’entrées de l’unique table active. La fonction conserve ces trois valeurs sans copier la table, charger de ressource ni allouer de mémoire.

Syntaxe

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

Paramètres

bank

Numéro sur 8 bits de la banque ROM de la table, et non de celle des données.

table

Pointeur proche vers count entrées AssetDesc consécutives. Les count * 6 octets doivent rester lisibles dans la banque de la table tant qu’elle est enregistrée.

count

Nombre d’entrées, de 0 à 255. Avec zéro, aucun identifiant n’est valide ; asset_set_table(0, 0, 0) permet d’enregistrer une table vide.

Valeur renvoyée

Aucune (void).

Conditions et limites

Enregistrez la table avant toute recherche. Cet enregistrement est un état global partagé : ne le modifiez pas pendant une recherche. La bibliothèque vérifie les identifiants et le pointeur de sortie de asset_get, mais pas la table enregistrée, les adresses des données ni le contenu de la cartouche.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple enregistre quatre descripteurs dans la banque 3, avec les contenus non vides dans la banque 2. Il vérifie aussi qu’une table vide fait échouer la recherche sans lire l’adresse zéro.

Image attendue : une rangée rouge part de (16,32) et occupe 72×8 pixels. Elle répète trois fois un triangle de 8×8, un carré de 8×8 au contour d’un pixel et une tuile dont les quatre colonnes de gauche sont pleines. Le triangle s’élargit d’un pixel en haut à gauche à huit sur sa ligne inférieure.

Sur FC, la paire bleue en (16,64) montre __far_memcpy ; la verte en (16,96), asset_load_raw suivi d’un transfert en CHR. Chaque paire occupe 16×8 pixels sur fond noir. Ces rangées montrent les données graphiques copiées, pas seulement des valeurs d’état numériques.

L’état attendu est FAILED CHECKS 000 et FIRST FAILURE 00. La vérification exécute 300 images puis compare texte, formes et couleurs aux résultats attendus. Il s’agit d’une preuve sur émulateur, pas d’un essai sur matériel physique.

Programme d’exemple complet

Commande de compilation

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

Copie dans la file les lignes d’octets d’attributs couvrant un rectangle de tuiles.

Syntaxe

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

Paramètres

nt_base

Base logique de table de noms $2000/$2400/$2800/$2C00 ; le miroir détermine leur indépendance physique.

tile_x

Colonne de tuile gauche, plage visible de 0 à 31.

tile_y

Ligne de tuile supérieure, plage visible de 0 à 29.

width

Largeur en tuiles.

height

Hauteur en tuiles.

Valeur renvoyée

Renvoie 1 si tout est accepté ou si le rectangle est vide, 0 si les limites sont invalides ou la capacité insuffisante. Des limites invalides ne mettent rien en file.

Conditions et limites

Le miroir d’attributs partagé de 64 octets occupe la RAM CPU $03E0..$041F ; réservez cette zone. Un octet d’attribut couvre 4×4 tuiles ; chaque champ de deux bits choisit la palette d’un quadrant de 2×2 tuiles.

Liez runtime.c. La file copie les données pour une NMI ultérieure ou une application sûre avec le rendu désactivé. Sérialisez la production et la consommation. Si une opération multiligne manque de place, les lignes déjà acceptées restent en file.

Un octet d’attribut couvre 4×4 tuiles. Les octets qui intersectent la zone sont transférés en entier ; conservez donc les bonnes valeurs des quadrants voisins dans le miroir.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Découvrez les transferts d’attributs rectangulaires : rouge 32×32 en (16,32), bleu 32×32 en (80,32), vert 16×16 en bas à droite (240,224). L’exemple préserve les quadrants voisins et atteint correctement le dernier octet d’attributs.

Programme d’exemple complet

Commande de compilation

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

Copie 64 octets d’attributs déjà compactés dans le miroir partagé.

Syntaxe

void nes_attr_shadow_build_from_palette_map(unsigned char* src64);

Paramètres

src64

Table d’attributs compactée de 64 octets lisibles, et non tableau d’identifiants de palette par tuile.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Le miroir d’attributs partagé de 64 octets occupe la RAM CPU $03E0..$041F ; réservez cette zone. Un octet d’attribut couvre 4×4 tuiles ; chaque champ de deux bits choisit la palette d’un quadrant de 2×2 tuiles.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Découvrez les transferts d’attributs rectangulaires : rouge 32×32 en (16,32), bleu 32×32 en (80,32), vert 16×16 en bas à droite (240,224). L’exemple préserve les quadrants voisins et atteint correctement le dernier octet d’attributs.

Programme d’exemple complet

Commande de compilation

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

Remplace les champs de palette de chaque quadrant de 2×2 tuiles touché par un rectangle.

Syntaxe

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

Paramètres

tile_x

Colonne de tuile gauche, plage visible de 0 à 31.

tile_y

Ligne de tuile supérieure, plage visible de 0 à 29.

width

Largeur en tuiles.

height

Hauteur en tuiles.

pal_index

Indice de palette ; seuls les deux bits de poids faible sont utilisés.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Le miroir d’attributs partagé de 64 octets occupe la RAM CPU $03E0..$041F ; réservez cette zone. Un octet d’attribut couvre 4×4 tuiles ; chaque champ de deux bits choisit la palette d’un quadrant de 2×2 tuiles.

Gardez tout le rectangle dans les 32×30 tuiles. Les rectangles vides ou invalides ne changent rien. Les limites impaires sont étendues aux limites des quadrants ; des tuiles voisines extérieures au rectangle peuvent donc recevoir la nouvelle palette.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Découvrez les transferts d’attributs rectangulaires : rouge 32×32 en (16,32), bleu 32×32 en (80,32), vert 16×16 en bas à droite (240,224). L’exemple préserve les quadrants voisins et atteint correctement le dernier octet d’attributs.

Programme d’exemple complet

Commande de compilation

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

Remplace l’état d’activation des cinq canaux APU par le masque fourni.

Syntaxe

void nes_apu_channel_enable(u8 mask);

Paramètres

mask

Masque d’activation APU_STATUS complet. Les bits 0..4 sélectionnent pulse1, pulse2, triangle, noise et DMC ; les bits supérieurs sont ignorés.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Exemple d’utilisation

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

Résultat attendu

Écoutez pulse1, pulse2, triangle, noise, tick puis move. En NTSC, un timer de 253 produit des impulsions d’environ 440 Hz et un triangle de 220 Hz. Tick est à environ 111 Hz ; move, à 174 Hz, finit plus tôt. Le dernier intervalle est silencieux.

Programme d’exemple complet

Commande de compilation

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

Désactive l’IRQ de trame, active quatre voix et installe des réglages silencieux. Le DMC reste désactivé.

Syntaxe

void nes_apu_init(void);

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Exemple d’utilisation

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

Résultat attendu

Écoutez pulse1, pulse2, triangle, noise, tick puis move. En NTSC, un timer de 253 produit des impulsions d’environ 440 Hz et un triangle de 220 Hz. Tick est à environ 111 Hz ; move, à 174 Hz, finit plus tôt. Le dernier intervalle est silencieux.

Programme d’exemple complet

Commande de compilation

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

Désactive tous les canaux et remet à zéro les volumes impulsion/bruit et la sortie DMC.

Syntaxe

void nes_apu_silence_all(void);

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Exemple d’utilisation

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

Résultat attendu

Écoutez pulse1, pulse2, triangle, noise, tick puis move. En NTSC, un timer de 253 produit des impulsions d’environ 440 Hz et un triangle de 220 Hz. Tick est à environ 111 Hz ; move, à 174 Hz, finit plus tôt. Le dernier intervalle est silencieux.

Programme d’exemple complet

Commande de compilation

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

Configure contrôle/sortie DMC et convertit l’adresse et la longueur de l’échantillon en unités de registre.

Syntaxe

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

Paramètres

flags_rate

DMC : bit 7 IRQ, bit 6 boucle, demi-octet bas indice de cadence. L’exemple n’active pas IRQ.

output_level

Compteur de sortie DMC initial, de 0 à 127 ; seuls les sept bits bas sont écrits.

sample_addr

Adresse CPU des données DMC, sur une frontière de 64 octets entre $C000 et $FFC0.

sample_len

Longueur de 16*n+1 octets, de 1 à 4081. Ne passez ni zéro ni une longueur non représentable.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Le DMC lit la ROM sur une frontière de 64 octets entre $C000 et $FFC0. La longueur est de 16*n+1 octets, de 1 à 4081. Ces fonctions ne vérifient ni alignement ni plages et ne changent pas de banque. L’exemple place des données originales dans la banque fixe 0 avec __aligned(64) et vérifie leur emplacement à l’exécution.

Exemple d’utilisation

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

Résultat attendu

Un motif delta original joue à la cadence 10, s’interrompt, puis reprend plus vite à 12. L’arrêt DMC conserve le compteur de sortie ; la pause peut donc contenir un transitoire. L’opération finale coupe toute l’APU.

Programme d’exemple complet

Commande de compilation

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

Configure l’échantillon DMC et lance immédiatement sa lecture.

Syntaxe

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

Paramètres

flags_rate

DMC : bit 7 IRQ, bit 6 boucle, demi-octet bas indice de cadence. L’exemple n’active pas IRQ.

output_level

Compteur de sortie DMC initial, de 0 à 127 ; seuls les sept bits bas sont écrits.

sample_addr

Adresse CPU des données DMC, sur une frontière de 64 octets entre $C000 et $FFC0.

sample_len

Longueur de 16*n+1 octets, de 1 à 4081. Ne passez ni zéro ni une longueur non représentable.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Le DMC lit la ROM sur une frontière de 64 octets entre $C000 et $FFC0. La longueur est de 16*n+1 octets, de 1 à 4081. Ces fonctions ne vérifient ni alignement ni plages et ne changent pas de banque. L’exemple place des données originales dans la banque fixe 0 avec __aligned(64) et vérifie leur emplacement à l’exécution.

Exemple d’utilisation

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

Résultat attendu

Un motif delta original joue à la cadence 10, s’interrompt, puis reprend plus vite à 12. L’arrêt DMC conserve le compteur de sortie ; la pause peut donc contenir un transitoire. L’opération finale coupe toute l’APU.

Programme d’exemple complet

Commande de compilation

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

Écrit APU_STATUS=0x1F pour activer le DMC et les quatre autres voix.

Syntaxe

void nes_dmc_start(void);

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Le DMC lit la ROM sur une frontière de 64 octets entre $C000 et $FFC0. La longueur est de 16*n+1 octets, de 1 à 4081. Ces fonctions ne vérifient ni alignement ni plages et ne changent pas de banque. L’exemple place des données originales dans la banque fixe 0 avec __aligned(64) et vérifie leur emplacement à l’exécution.

Exemple d’utilisation

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

Résultat attendu

Un motif delta original joue à la cadence 10, s’interrompt, puis reprend plus vite à 12. L’arrêt DMC conserve le compteur de sortie ; la pause peut donc contenir un transitoire. L’opération finale coupe toute l’APU.

Programme d’exemple complet

Commande de compilation

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

Écrit APU_STATUS=0x0F pour arrêter le DMC tout en activant les bits des quatre autres voix.

Syntaxe

void nes_dmc_stop(void);

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Le DMC lit la ROM sur une frontière de 64 octets entre $C000 et $FFC0. La longueur est de 16*n+1 octets, de 1 à 4081. Ces fonctions ne vérifient ni alignement ni plages et ne changent pas de banque. L’exemple place des données originales dans la banque fixe 0 avec __aligned(64) et vérifie leur emplacement à l’exécution.

Exemple d’utilisation

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

Résultat attendu

Un motif delta original joue à la cadence 10, s’interrompt, puis reprend plus vite à 12. L’arrêt DMC conserve le compteur de sortie ; la pause peut donc contenir un transitoire. L’opération finale coupe toute l’APU.

Programme d’exemple complet

Commande de compilation

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

Déclenche l’impulsion 1 avec contrôle 0x5A, timer 0x0280 et indice de longueur 2 pour un bip de déplacement plus aigu et plus court.

Syntaxe

void nes_sfx_move_blip(void);

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Cette fonction écrit un masque APU_STATUS à un seul canal, désactivant les autres voix. Ce n’est pas un mélangeur multivoix. Pour les impulsions et le triangle, period est une valeur de minuterie : plus elle est petite, plus le son est aigu. Les hauteurs et durées de l’exemple ont été vérifiées en NTSC.

Exemple d’utilisation

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

Résultat attendu

Écoutez pulse1, pulse2, triangle, noise, tick puis move. En NTSC, un timer de 253 produit des impulsions d’environ 440 Hz et un triangle de 220 Hz. Tick est à environ 111 Hz ; move, à 174 Hz, finit plus tôt. Le dernier intervalle est silencieux.

Programme d’exemple complet

Commande de compilation

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

Active seulement le bruit et écrit enveloppe, période/mode et indice de longueur.

Syntaxe

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

Paramètres

volume

Contrôle de bruit brut : bit 5 arrêt du compteur de longueur, bit 4 volume constant, demi-octet bas volume ou période d’enveloppe.

period_mode

Registre de bruit : bit 7 pour le mode court, demi-octet bas pour l’indice de période.

length_index

Indice de table de longueur de 0 à 31, pas un nombre d’images. Seuls les cinq bits bas atteignent le registre.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Cette fonction écrit un masque APU_STATUS à un seul canal, désactivant les autres voix. Ce n’est pas un mélangeur multivoix. Pour les impulsions et le triangle, period est une valeur de minuterie : plus elle est petite, plus le son est aigu. Les hauteurs et durées de l’exemple ont été vérifiées en NTSC.

Exemple d’utilisation

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

Résultat attendu

Écoutez pulse1, pulse2, triangle, noise, tick puis move. En NTSC, un timer de 253 produit des impulsions d’environ 440 Hz et un triangle de 220 Hz. Tick est à environ 111 Hz ; move, à 174 Hz, finit plus tôt. Le dernier intervalle est silencieux.

Programme d’exemple complet

Commande de compilation

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

Active seulement l’impulsion 1, désactive le balayage et écrit contrôle, timer et indice de longueur.

Syntaxe

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

Paramètres

duty_volume

Contrôle d’impulsion brut : bits 7..6 pour le rapport cyclique, bit 5 pour l’arrêt du compteur de longueur, bit 4 pour le volume constant, demi-octet bas pour le volume ou la période d’enveloppe.

period

Timer sur 11 bits, de 0 à 2047. La fréquence d’impulsion vaut horloge CPU/[16*(period+1)] ; celle du triangle, horloge CPU/[32*(period+1)].

length_index

Indice de table de longueur de 0 à 31, pas un nombre d’images. Seuls les cinq bits bas atteignent le registre.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Cette fonction écrit un masque APU_STATUS à un seul canal, désactivant les autres voix. Ce n’est pas un mélangeur multivoix. Pour les impulsions et le triangle, period est une valeur de minuterie : plus elle est petite, plus le son est aigu. Les hauteurs et durées de l’exemple ont été vérifiées en NTSC.

Exemple d’utilisation

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

Résultat attendu

Écoutez pulse1, pulse2, triangle, noise, tick puis move. En NTSC, un timer de 253 produit des impulsions d’environ 440 Hz et un triangle de 220 Hz. Tick est à environ 111 Hz ; move, à 174 Hz, finit plus tôt. Le dernier intervalle est silencieux.

Programme d’exemple complet

Commande de compilation

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

Active seulement l’impulsion 2, désactive le balayage et écrit contrôle, timer et indice de longueur.

Syntaxe

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

Paramètres

duty_volume

Contrôle d’impulsion brut : bits 7..6 pour le rapport cyclique, bit 5 pour l’arrêt du compteur de longueur, bit 4 pour le volume constant, demi-octet bas pour le volume ou la période d’enveloppe.

period

Timer sur 11 bits, de 0 à 2047. La fréquence d’impulsion vaut horloge CPU/[16*(period+1)] ; celle du triangle, horloge CPU/[32*(period+1)].

length_index

Indice de table de longueur de 0 à 31, pas un nombre d’images. Seuls les cinq bits bas atteignent le registre.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Cette fonction écrit un masque APU_STATUS à un seul canal, désactivant les autres voix. Ce n’est pas un mélangeur multivoix. Pour les impulsions et le triangle, period est une valeur de minuterie : plus elle est petite, plus le son est aigu. Les hauteurs et durées de l’exemple ont été vérifiées en NTSC.

Exemple d’utilisation

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

Résultat attendu

Écoutez pulse1, pulse2, triangle, noise, tick puis move. En NTSC, un timer de 253 produit des impulsions d’environ 440 Hz et un triangle de 220 Hz. Tick est à environ 111 Hz ; move, à 174 Hz, finit plus tôt. Le dernier intervalle est silencieux.

Programme d’exemple complet

Commande de compilation

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

Déclenche l’impulsion 1 avec contrôle 0x9A, timer 0x03F0 et indice de longueur 4 pour un clic bref et grave.

Syntaxe

void nes_sfx_tick_blip(void);

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Cette fonction écrit un masque APU_STATUS à un seul canal, désactivant les autres voix. Ce n’est pas un mélangeur multivoix. Pour les impulsions et le triangle, period est une valeur de minuterie : plus elle est petite, plus le son est aigu. Les hauteurs et durées de l’exemple ont été vérifiées en NTSC.

Exemple d’utilisation

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

Résultat attendu

Écoutez pulse1, pulse2, triangle, noise, tick puis move. En NTSC, un timer de 253 produit des impulsions d’environ 440 Hz et un triangle de 220 Hz. Tick est à environ 111 Hz ; move, à 174 Hz, finit plus tôt. Le dernier intervalle est silencieux.

Programme d’exemple complet

Commande de compilation

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

Active seulement le triangle et écrit compteur linéaire, timer et indice de longueur.

Syntaxe

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

Paramètres

linear

Compteur linéaire du triangle : bit 7 pour le contrôle/arrêt de longueur, sept bits bas pour la valeur de rechargement.

period

Timer sur 11 bits, de 0 à 2047. La fréquence d’impulsion vaut horloge CPU/[16*(period+1)] ; celle du triangle, horloge CPU/[32*(period+1)].

length_index

Indice de table de longueur de 0 à 31, pas un nombre d’images. Seuls les cinq bits bas atteignent le registre.

Valeur renvoyée

Aucune valeur de retour. Modifie les registres audio ou l’état du pilote.

Conditions et limites

Cette fonction écrit un masque APU_STATUS à un seul canal, désactivant les autres voix. Ce n’est pas un mélangeur multivoix. Pour les impulsions et le triangle, period est une valeur de minuterie : plus elle est petite, plus le son est aigu. Les hauteurs et durées de l’exemple ont été vérifiées en NTSC.

Exemple d’utilisation

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

Résultat attendu

Écoutez pulse1, pulse2, triangle, noise, tick puis move. En NTSC, un timer de 253 produit des impulsions d’environ 440 Hz et un triangle de 220 Hz. Tick est à environ 111 Hz ; move, à 174 Hz, finit plus tôt. Le dernier intervalle est silencieux.

Programme d’exemple complet

Commande de compilation

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

Renvoie le dernier numéro de banque enregistré par bank_switch. Il s’agit d’un état logiciel, pas d’une lecture des registres de la cartouche.

Syntaxe

u8 bank_get_current(void);

Valeur renvoyée

La valeur u8 enregistrée par le dernier bank_switch ; zéro avant l’initialisation.

Conditions et limites

L’état de la bibliothèque commence à zéro et ne détecte pas le mappage initial de la cartouche. Initialisez-le avec bank_switch. Les intrinsèques et écritures directes dans le mapper n’actualisent pas cet état distinct ; bank_get_current ne vérifie donc pas le mappage matériel réel.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

bank_switch(2) enregistre et sélectionne d’abord la banque 2. Une commutation directe sélectionne ensuite la banque 1 et lit A1 dans home1, tandis que bank_get_current indique toujours 2 ; après restauration, home2 donne à nouveau B2.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

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

Enregistre la banque demandée dans la bibliothèque, puis la sélectionne avec la routine PRG du compilateur adaptée au mapper.

Syntaxe

void bank_switch(u8 bank);

Paramètres

bank

Numéro de banque ROM non signé sur 8 bits. Pour un appel, il doit correspondre au placement de la fonction ; pour une lecture, il sélectionne la source. Respectez la plage du type de cartouche.

Valeur renvoyée

Aucune (void).

Conditions et limites

Un changement persistant de banque ne doit pas rendre inaccessibles le code exécuté ou son adresse de retour. Placez cet appel, bank_switch elle-même si elle est utilisée, et le code qui suit dans la banque commune ou fixe 0, comme dans l’exemple.

L’état de la bibliothèque commence à zéro et ne détecte pas le mappage initial de la cartouche. Initialisez-le avec bank_switch. Les intrinsèques et écritures directes dans le mapper n’actualisent pas cet état distinct ; bank_get_current ne vérifie donc pas le mappage matériel réel.

Les banques FC sont des numéros logiques du compilateur. Zéro désigne la ROM commune, pas une cible de commutation ; la routine le ramène à la banque 1. SUROM512 accepte 1–30 : une constante hors plage transmise directement à l’intrinsèque de commutation provoque une erreur de compilation ; une valeur d’exécution invalide sélectionne 1 et active l’état de défaut du mapper. Lisez directement la ROM commune, sans demander la banque zéro.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

bank_switch(2) enregistre et sélectionne d’abord la banque 2. Une commutation directe sélectionne ensuite la banque 1 et lit A1 dans home1, tandis que bank_get_current indique toujours 2 ; après restauration, home2 donne à nouveau B2.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

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

Se développe en __farcall((bank), func). Cette macro conserve la cible sous forme de nom de fonction visible par le compilateur ; il ne s’agit pas d’un appel indirect par pointeur de rappel.

Syntaxe

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

Paramètres

bank

Numéro de banque ROM non signé sur 8 bits. Pour un appel, il doit correspondre au placement de la fonction ; pour une lecture, il sélectionne la source. Respectez la plage du type de cartouche.

func

Nom déclaré d’une fonction sans paramètre. Cet appel intrinsèque par nom n’accepte pas une variable contenant une adresse de fonction. L’argument bank n’est pas transmis au rappel.

Valeur renvoyée

Le résultat suit le type de la fonction appelée. Un rappel void ne renvoie rien ; les rappels u8 et u16 renvoient leur valeur scalaire. L’exemple affiché utilise des rappels void.

Conditions et limites

Ces appels ne transmettent pas d’arguments utilisateur et ne rendent pas le rappel réentrant face aux interruptions. Gérez correctement ses données, sa pile et ses interruptions. La restauration des banques est testée avec des appels imbriqués et répétés ; l’exemple ne couvre ni le matériel physique ni tous les entrelacements d’interruptions.

Les banques FC sont des numéros logiques du compilateur. Zéro désigne la ROM commune, pas une cible de commutation ; la routine le ramène à la banque 1. SUROM512 accepte 1–30 : une constante hors plage transmise directement à l’intrinsèque de commutation provoque une erreur de compilation ; une valeur d’exécution invalide sélectionne 1 et active l’état de défaut du mapper. Lisez directement la ROM commune, sans demander la banque zéro.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

À ce stade du programme complet, far_call porte callback_count à 1. Le rappel lit D3 dans la banque 3. Une lecture proche ultérieure de B2 dans home2 confirme le retour avec la banque 2 sélectionnée.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

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

Copie len octets de la banque ROM indiquée vers la RAM fournie par l’appelant via l’intrinsèque de copie distante. Rétablit la banque précédente avant le retour.

Syntaxe

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

Paramètres

bank

Numéro de banque ROM non signé sur 8 bits. Pour un appel, il doit correspondre au placement de la fonction ; pour une lecture, il sélectionne la source. Respectez la plage du type de cartouche.

addr

Pointeur proche vers des octets lisibles dans la banque ROM choisie. Il ne contient pas de numéro de banque.

dst

Destination en mémoire accessible en écriture, assez grande pour tous les octets copiés. Hors transfert de zéro octet, les adresses nulles ou invalides ne sont pas vérifiées.

len

Nombre d’octets, de 0 à 65535. Avec zéro, aucune mémoire n’est copiée, mais la sélection et le rétablissement de la banque ont bien lieu.

Valeur renvoyée

Aucune (void).

Conditions et limites

Toute la source doit être lisible dans le mappage ROM prévu, et toute la destination accessible en écriture. La copie ne passe pas automatiquement à la banque suivante, ne gère pas les chevauchements comme memmove et ne synchronise pas les écritures VRAM. Utilisez les API graphiques pour la VRAM.

Les lectures et copies distantes sont synchrones et utilisent un espace de travail partagé du compilateur. Une interruption ne doit pas y exécuter un autre transfert pendant son utilisation. Sur GB, la copie utilise aussi un emplacement HRAM partagé pour la banque sauvegardée. L’exemple exécute ces opérations depuis du code fixe, sans gestionnaire de transfert concurrent.

Les banques FC sont des numéros logiques du compilateur. Zéro désigne la ROM commune, pas une cible de commutation ; la routine le ramène à la banque 1. SUROM512 accepte 1–30 : une constante hors plage transmise directement à l’intrinsèque de commutation provoque une erreur de compilation ; une valeur d’exécution invalide sélectionne 1 et active l’état de défaut du mapper. Lisez directement la ROM commune, sans demander la banque zéro.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet extrait copie 4 octets via far_data_read et compare le tampon à D3 7A 5C 96. Le descripteur ou pointeur source de l’appelant est conservé ; le programme complet vérifie séparément une copie de longueur nulle et la restauration de la banque.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

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

Lit deux octets consécutifs via __farpeek16 et les assemble en un mot little-endian. Le premier octet fournit les huit bits de poids faible.

Syntaxe

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

Paramètres

bank

Numéro de banque ROM non signé sur 8 bits. Pour un appel, il doit correspondre au placement de la fonction ; pour une lecture, il sélectionne la source. Respectez la plage du type de cartouche.

addr

Pointeur proche vers des octets lisibles dans la banque ROM choisie. Il ne contient pas de numéro de banque.

Valeur renvoyée

Le mot little-endian lu, sous forme de u16 (0–65535).

Conditions et limites

L’octet ou le mot entier doit être lisible dans le mappage CPU sélectionné. Ces lectures ne valident pas les pointeurs, ne bornent pas les adresses et ne passent pas automatiquement à une autre banque à la limite d’une fenêtre. Un mot exige deux octets consécutifs valides.

Les lectures et copies distantes sont synchrones et utilisent un espace de travail partagé du compilateur. Une interruption ne doit pas y exécuter un autre transfert pendant son utilisation. Sur GB, la copie utilise aussi un emplacement HRAM partagé pour la banque sauvegardée. L’exemple exécute ces opérations depuis du code fixe, sans gestionnaire de transfert concurrent.

Les banques FC sont des numéros logiques du compilateur. Zéro désigne la ROM commune, pas une cible de commutation ; la routine le ramène à la banque 1. SUROM512 accepte 1–30 : une constante hors plage transmise directement à l’intrinsèque de commutation provoque une erreur de compilation ; une valeur d’exécution invalide sélectionne 1 et active l’état de défaut du mapper. Lisez directement la ROM commune, sans demander la banque zéro.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet extrait utilise far_data_read16 pour lire payload+1 dans la banque 3 et vérifie 5C7A. Le programme complet lit aussi home2 avec un pointeur proche pour confirmer la restauration de la banque 2.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

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

Lit un octet dans la banque ROM à l’adresse indiquée via __farpeek8, rétablit la banque précédente et renvoie la valeur.

Syntaxe

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

Paramètres

bank

Numéro de banque ROM non signé sur 8 bits. Pour un appel, il doit correspondre au placement de la fonction ; pour une lecture, il sélectionne la source. Respectez la plage du type de cartouche.

addr

Pointeur proche vers des octets lisibles dans la banque ROM choisie. Il ne contient pas de numéro de banque.

Valeur renvoyée

L’octet lu, sous forme de u8 (0–255).

Conditions et limites

L’octet ou le mot entier doit être lisible dans le mappage CPU sélectionné. Ces lectures ne valident pas les pointeurs, ne bornent pas les adresses et ne passent pas automatiquement à une autre banque à la limite d’une fenêtre. Un mot exige deux octets consécutifs valides.

Les lectures et copies distantes sont synchrones et utilisent un espace de travail partagé du compilateur. Une interruption ne doit pas y exécuter un autre transfert pendant son utilisation. Sur GB, la copie utilise aussi un emplacement HRAM partagé pour la banque sauvegardée. L’exemple exécute ces opérations depuis du code fixe, sans gestionnaire de transfert concurrent.

Les banques FC sont des numéros logiques du compilateur. Zéro désigne la ROM commune, pas une cible de commutation ; la routine le ramène à la banque 1. SUROM512 accepte 1–30 : une constante hors plage transmise directement à l’intrinsèque de commutation provoque une erreur de compilation ; une valeur d’exécution invalide sélectionne 1 et active l’état de défaut du mapper. Lisez directement la ROM commune, sans demander la banque zéro.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet extrait utilise far_data_read8 pour lire payload dans la banque 3 et vérifie D3. Le programme complet lit aussi home2 avec un pointeur proche pour confirmer la restauration de la banque 2.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

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

Enregistre un octet de banque et un pointeur visible par le CPU dans le BankPtr de l’appelant. Construit un descripteur, sans changer de banque ni lire les données pointées.

Syntaxe

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

Paramètres

out

Pointeur vers un espace accessible en écriture pour un BankPtr de trois octets. Si out est nul, aucune écriture n’a lieu.

bank

Numéro de banque ROM non signé sur 8 bits. Pour un appel, il doit correspondre au placement de la fonction ; pour une lecture, il sélectionne la source. Respectez la plage du type de cartouche.

ptr

Adresse de 16 bits visible par le CPU à stocker dans le descripteur. Elle est copiée telle quelle, sans vérifier sa validité dans la banque choisie.

Valeur renvoyée

Aucune (void).

Exemple d’utilisation

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.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le descripteur est réglé sur la banque 3 et payload+1. Ses lectures donnent 7A, 5C7A et les trois octets 7A 5C 96. L’appel avec une sortie nulle ne doit modifier aucun état.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

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

Copie len octets depuis un BankPtr vers une RAM accessible en écriture. Le descripteur étant passé par valeur, le pointeur de l’appelant reste au début de la source.

Syntaxe

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

Paramètres

ptr

Une valeur BankPtr contenant bank et ptr. Passez le descripteur lui-même, pas son adresse. Le descripteur de l’appelant n’est pas modifié.

dst

Destination en mémoire accessible en écriture, assez grande pour tous les octets copiés. Hors transfert de zéro octet, les adresses nulles ou invalides ne sont pas vérifiées.

len

Nombre d’octets, de 0 à 65535. Avec zéro, aucune mémoire n’est copiée, mais la sélection et le rétablissement de la banque ont bien lieu.

Valeur renvoyée

Aucune (void).

Conditions et limites

Toute la source doit être lisible dans le mappage ROM prévu, et toute la destination accessible en écriture. La copie ne passe pas automatiquement à la banque suivante, ne gère pas les chevauchements comme memmove et ne synchronise pas les écritures VRAM. Utilisez les API graphiques pour la VRAM.

Les lectures et copies distantes sont synchrones et utilisent un espace de travail partagé du compilateur. Une interruption ne doit pas y exécuter un autre transfert pendant son utilisation. Sur GB, la copie utilise aussi un emplacement HRAM partagé pour la banque sauvegardée. L’exemple exécute ces opérations depuis du code fixe, sans gestionnaire de transfert concurrent.

Les banques FC sont des numéros logiques du compilateur. Zéro désigne la ROM commune, pas une cible de commutation ; la routine le ramène à la banque 1. SUROM512 accepte 1–30 : une constante hors plage transmise directement à l’intrinsèque de commutation provoque une erreur de compilation ; une valeur d’exécution invalide sélectionne 1 et active l’état de défaut du mapper. Lisez directement la ROM commune, sans demander la banque zéro.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet extrait copie 3 octets via farptr_read et compare le tampon à 7A 5C 96. Le descripteur ou pointeur source de l’appelant est conservé ; le programme complet vérifie séparément une copie de longueur nulle et la restauration de la banque.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

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

Lit un mot little-endian dans la banque à l’adresse contenues dans un BankPtr. Le descripteur est passé par valeur et son pointeur n’avance pas.

Syntaxe

u16 farptr_read16(BankPtr ptr);

Paramètres

ptr

Une valeur BankPtr contenant bank et ptr. Passez le descripteur lui-même, pas son adresse. Le descripteur de l’appelant n’est pas modifié.

Valeur renvoyée

Le mot little-endian lu, sous forme de u16 (0–65535).

Conditions et limites

L’octet ou le mot entier doit être lisible dans le mappage CPU sélectionné. Ces lectures ne valident pas les pointeurs, ne bornent pas les adresses et ne passent pas automatiquement à une autre banque à la limite d’une fenêtre. Un mot exige deux octets consécutifs valides.

Les lectures et copies distantes sont synchrones et utilisent un espace de travail partagé du compilateur. Une interruption ne doit pas y exécuter un autre transfert pendant son utilisation. Sur GB, la copie utilise aussi un emplacement HRAM partagé pour la banque sauvegardée. L’exemple exécute ces opérations depuis du code fixe, sans gestionnaire de transfert concurrent.

Les banques FC sont des numéros logiques du compilateur. Zéro désigne la ROM commune, pas une cible de commutation ; la routine le ramène à la banque 1. SUROM512 accepte 1–30 : une constante hors plage transmise directement à l’intrinsèque de commutation provoque une erreur de compilation ; une valeur d’exécution invalide sélectionne 1 et active l’état de défaut du mapper. Lisez directement la ROM commune, sans demander la banque zéro.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet extrait utilise farptr_read16 pour lire pointer.ptr dans la banque 3 et vérifie 5C7A. Le programme complet lit aussi home2 avec un pointeur proche pour confirmer la restauration de la banque 2.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

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

Lit un octet à partir des deux champs d’un BankPtr passé par valeur. Le descripteur fournit la banque absente d’un pointeur proche ordinaire.

Syntaxe

u8 farptr_read8(BankPtr ptr);

Paramètres

ptr

Une valeur BankPtr contenant bank et ptr. Passez le descripteur lui-même, pas son adresse. Le descripteur de l’appelant n’est pas modifié.

Valeur renvoyée

L’octet lu, sous forme de u8 (0–255).

Conditions et limites

L’octet ou le mot entier doit être lisible dans le mappage CPU sélectionné. Ces lectures ne valident pas les pointeurs, ne bornent pas les adresses et ne passent pas automatiquement à une autre banque à la limite d’une fenêtre. Un mot exige deux octets consécutifs valides.

Les lectures et copies distantes sont synchrones et utilisent un espace de travail partagé du compilateur. Une interruption ne doit pas y exécuter un autre transfert pendant son utilisation. Sur GB, la copie utilise aussi un emplacement HRAM partagé pour la banque sauvegardée. L’exemple exécute ces opérations depuis du code fixe, sans gestionnaire de transfert concurrent.

Les banques FC sont des numéros logiques du compilateur. Zéro désigne la ROM commune, pas une cible de commutation ; la routine le ramène à la banque 1. SUROM512 accepte 1–30 : une constante hors plage transmise directement à l’intrinsèque de commutation provoque une erreur de compilation ; une valeur d’exécution invalide sélectionne 1 et active l’état de défaut du mapper. Lisez directement la ROM commune, sans demander la banque zéro.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet extrait utilise farptr_read8 pour lire pointer.ptr dans la banque 3 et vérifie 7A. Le programme complet lit aussi home2 avec un pointeur proche pour confirmer la restauration de la banque 2.

Le programme complet montre comment identifier des données par une banque et une adresse proche, appeler des rappels entre banques et distinguer l’état de la bibliothèque du mappage réel. Tous les nombres sont hexadécimaux. BANK IN et BANK OUT doivent valoir 02 ; BYTE HEX, D3 ; WORD HEX, 5C7A ; FAILED CHECKS et FIRST FAILURE, 00. Le texte est bleu sur CGB et FC, noir sur DMG.

CALL COUNT vaut 02 : la macro far_call et __farcall invoquent chacun le rappel une fois.

Programme d’exemple complet

Commande de compilation

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

Calcule le plus court déplacement signé de la position courante vers une cible sur un axe dont les extrémités se rejoignent. Utilisez-le pour le suivi ou la comparaison de distances à travers un bord du terrain.

Syntaxe

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

Paramètres

target

Coordonnée cible, de 0 à size−1.

current

Coordonnée courante, de 0 à size−1.

size

Longueur de l’axe à rebouclage, de 1 à 256 : largeur pour X, hauteur pour Y. L’argument est sur 16 bits pour représenter 256.

Valeur renvoyée

Renvoie le plus court déplacement en s16 : positif vers les coordonnées croissantes, négatif vers les décroissantes, zéro à la même position. Les entrées valides donnent −128..+128. À l’écran, droite et bas sont positifs.

Conditions et limites

Incluez chain.h et compilez chain.c exactement une fois. Aucune initialisation de Chain ou ChainBody n’est nécessaire. La fonction calcule seulement un déplacement, sans modifier tableaux de coordonnées, nombre d’articulations ni écran.

La fonction ne valide ni ne normalise les entrées. Ne passez pas size=0, size>256 ou des coordonnées supérieures ou égales à size. Ramenez les coordonnées d’un système plus grand dans 0..size−1 par rebouclage avant l’appel.

Si les deux chemins ont la même longueur, conserve le signe du déplacement direct target−current. Avec size=160, 0→80 renvoie +80 et 80→0 renvoie −80. Avec size=1, zéro est la seule coordonnée valide et le résultat vaut zéro.

Exemple d’utilisation

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.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Cet exemple présente les coordonnées à rebouclage. Chaque flèche va de la position courante à la cible. Il affiche +02/−02 pour traverser un bord de largeur 160, +80/−80 pour un demi-terrain et +00 pour la largeur 1. Le zéro initial est un remplissage décimal. L’exemple ne dessine ni ne déplace d’objet.

Programme d’exemple complet

Commande de compilation

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

Associe trois tableaux d’articulations fournis par l’appelant et met leur nombre à zéro, sans allouer de mémoire.

Syntaxe

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

Paramètres

body

ChainBody cible ; null est ignoré. Sauf pour l’initialisation, passez un état déjà initialisé.

x

Tableau des coordonnées X des articulations.

y

Tableau des coordonnées Y des articulations.

heading

Tableau des orientations des articulations.

capacity

Longueur allouée du tableau, de 1 à 255.

width

Largeur du terrain à rebouclage, de 1 à 256.

height

Hauteur du terrain à rebouclage, de 1 à 256.

Valeur renvoyée

Renvoie 1 en cas de succès, 0 pour des arguments invalides. Un échec avec un corps non nul met capacity et count à zéro, désactivant les mises à jour.

Conditions et limites

Incluez chain.h et compilez chain.c exactement une fois. ChainBody contient la position et l’orientation courantes de chaque articulation. Ce type d’état est distinct de l’historique circulaire de positions Chain.

Fournissez trois tableaux distincts accessibles en écriture, x, y et heading, de capacity octets chacun. Conservez-les pendant l’utilisation du corps. L’indice zéro est la tête, comprise dans count. Ne modifiez pas les pointeurs, la capacité ou les dimensions du terrain après l’initialisation.

Les orientations suivent 16 secteurs horaires : 0=droite, 4=bas, 8=gauche, 12=haut. Seuls les quatre bits de poids faible sont utilisés. Les coordonnées d’écran augmentent vers la droite et le bas ; chaque dimension va de 1 à 256 pixels.

Exemple d’utilisation

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.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’image montre en haut un corps droit, au milieu une mise à jour après un virage vers le bas et en bas quatre mises à jour après ce virage. Les coordonnées sont dessinées au double de leur taille logique. La courbure se propage depuis la tête à droite vers l’arrière. CGB et FC utilisent rouge pour la tête, bleu pour le corps et vert pour la queue ; DMG utilise noir. Quatre mises à jour de stabilisation séparent la queue dupliquée après croissance. Ce sont trois vues des mêmes huit articulations, pas un corps de 24 articulations.

Programme d’exemple complet

Commande de compilation

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

Construit une pose initiale droite en plaçant les articulations derrière la tête indiquée.

Syntaxe

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

Paramètres

body

ChainBody cible ; null est ignoré. Sauf pour l’initialisation, passez un état déjà initialisé.

count

Nombre d’articulations, tête comprise, de 1 à capacity.

head_x

Coordonnée X de la tête, ramenée par rebouclage à la largeur du terrain.

head_y

Coordonnée Y de la tête, ramenée par rebouclage à la hauteur du terrain.

heading

Orientation de la tête dans le système à 16 secteurs.

Valeur renvoyée

Renvoie 1 en cas de succès. Un nombre nul ou excessif, ou un corps nul, renvoie 0 sans modifier la pose.

Conditions et limites

Incluez chain.h et compilez chain.c exactement une fois. ChainBody contient la position et l’orientation courantes de chaque articulation. Ce type d’état est distinct de l’historique circulaire de positions Chain.

Fournissez trois tableaux distincts accessibles en écriture, x, y et heading, de capacity octets chacun. Conservez-les pendant l’utilisation du corps. L’indice zéro est la tête, comprise dans count. Ne modifiez pas les pointeurs, la capacité ou les dimensions du terrain après l’initialisation.

Les orientations suivent 16 secteurs horaires : 0=droite, 4=bas, 8=gauche, 12=haut. Seuls les quatre bits de poids faible sont utilisés. Les coordonnées d’écran augmentent vers la droite et le bas ; chaque dimension va de 1 à 256 pixels.

L’espacement cardinal est de quatre pixels. Les orientations intermédiaires utilisent des vecteurs entiers comme (4,1), (3,3) et (1,4) ; la distance euclidienne n’est donc pas exactement quatre pixels. La pose initiale peut franchir un bord du terrain.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’image montre en haut un corps droit, au milieu une mise à jour après un virage vers le bas et en bas quatre mises à jour après ce virage. Les coordonnées sont dessinées au double de leur taille logique. La courbure se propage depuis la tête à droite vers l’arrière. CGB et FC utilisent rouge pour la tête, bleu pour le corps et vert pour la queue ; DMG utilise noir. Quatre mises à jour de stabilisation séparent la queue dupliquée après croissance. Ce sont trois vues des mêmes huit articulations, pas un corps de 24 articulations.

Programme d’exemple complet

Commande de compilation

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

Définit la pose de la tête et attire progressivement chaque articulation vers un point d’attache derrière la précédente. Les changements d’orientation se propagent d’une articulation par mise à jour.

Syntaxe

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

Paramètres

body

ChainBody cible ; null est ignoré. Sauf pour l’initialisation, passez un état déjà initialisé.

head_x

Coordonnée X de la tête, ramenée par rebouclage à la largeur du terrain.

head_y

Coordonnée Y de la tête, ramenée par rebouclage à la hauteur du terrain.

heading

Orientation de la tête dans le système à 16 secteurs.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Incluez chain.h et compilez chain.c exactement une fois. ChainBody contient la position et l’orientation courantes de chaque articulation. Ce type d’état est distinct de l’historique circulaire de positions Chain.

Fournissez trois tableaux distincts accessibles en écriture, x, y et heading, de capacity octets chacun. Conservez-les pendant l’utilisation du corps. L’indice zéro est la tête, comprise dans count. Ne modifiez pas les pointeurs, la capacité ou les dimensions du terrain après l’initialisation.

Les orientations suivent 16 secteurs horaires : 0=droite, 4=bas, 8=gauche, 12=haut. Seuls les quatre bits de poids faible sont utilisés. Les coordonnées d’écran augmentent vers la droite et le bas ; chaque dimension va de 1 à 256 pixels.

Utilise la position mise à jour du prédécesseur pour trouver le point d’attache cible, puis calcule le plus court déplacement avec rebouclage sur chaque axe. Un déplacement nul ne bouge pas ; une amplitude de 1 à 4 avance d’un pixel, 5 ou plus de deux. À exactement un demi-terrain, conserve le signe initial.

Transmet à l’articulation suivante l’orientation sauvegardée avant la mise à jour de chacune, pour propager la courbure dans le corps. Un corps vide reste inchangé.

L’appelant gère vitesse et accélération de la tête, collisions, dessin et attente. Mettez normalement la tête à jour d’abord, puis appelez chain_body_step une fois par pas de simulation. Il s’agit de suivi d’articulations, pas d’un solveur de corps rigides ou de contraintes de longueur exactes.

Exemple d’utilisation

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.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’image montre en haut un corps droit, au milieu une mise à jour après un virage vers le bas et en bas quatre mises à jour après ce virage. Les coordonnées sont dessinées au double de leur taille logique. La courbure se propage depuis la tête à droite vers l’arrière. CGB et FC utilisent rouge pour la tête, bleu pour le corps et vert pour la queue ; DMG utilise noir. Quatre mises à jour de stabilisation séparent la queue dupliquée après croissance. Ce sont trois vues des mêmes huit articulations, pas un corps de 24 articulations.

Programme d’exemple complet

Commande de compilation

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

Copie la position et l’orientation actuelles de la queue dans le prochain emplacement libre et augmente le nombre d’un.

Syntaxe

u8 chain_body_grow(ChainBody* body);

Paramètres

body

ChainBody cible ; null est ignoré. Sauf pour l’initialisation, passez un état déjà initialisé.

Valeur renvoyée

Renvoie 1 si une articulation a été ajoutée ; 0 pour un corps vide, plein, désactivé ou nul.

Conditions et limites

Incluez chain.h et compilez chain.c exactement une fois. ChainBody contient la position et l’orientation courantes de chaque articulation. Ce type d’état est distinct de l’historique circulaire de positions Chain.

Fournissez trois tableaux distincts accessibles en écriture, x, y et heading, de capacity octets chacun. Conservez-les pendant l’utilisation du corps. L’indice zéro est la tête, comprise dans count. Ne modifiez pas les pointeurs, la capacité ou les dimensions du terrain après l’initialisation.

Les orientations suivent 16 secteurs horaires : 0=droite, 4=bas, 8=gauche, 12=haut. Seuls les quatre bits de poids faible sont utilisés. Les coordonnées d’écran augmentent vers la droite et le bas ; chaque dimension va de 1 à 256 pixels.

La nouvelle queue chevauche d’abord l’ancienne, puis s’en sépare lors des appels suivants à chain_body_step. La croissance seule ne déplace ni la tête ni les autres articulations.

Exemple d’utilisation

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.

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’image montre en haut un corps droit, au milieu une mise à jour après un virage vers le bas et en bas quatre mises à jour après ce virage. Les coordonnées sont dessinées au double de leur taille logique. La courbure se propage depuis la tête à droite vers l’arrière. CGB et FC utilisent rouge pour la tête, bleu pour le corps et vert pour la queue ; DMG utilise noir. Quatre mises à jour de stabilisation séparent la queue dupliquée après croissance. Ce sont trois vues des mêmes huit articulations, pas un corps de 24 articulations.

Programme d’exemple complet

Commande de compilation

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

Met le nombre d’articulations à zéro en conservant les tableaux et les réglages du terrain.

Syntaxe

void chain_body_clear(ChainBody* body);

Paramètres

body

ChainBody cible ; null est ignoré. Sauf pour l’initialisation, passez un état déjà initialisé.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Incluez chain.h et compilez chain.c exactement une fois. ChainBody contient la position et l’orientation courantes de chaque articulation. Ce type d’état est distinct de l’historique circulaire de positions Chain.

Fournissez trois tableaux distincts accessibles en écriture, x, y et heading, de capacity octets chacun. Conservez-les pendant l’utilisation du corps. L’indice zéro est la tête, comprise dans count. Ne modifiez pas les pointeurs, la capacité ou les dimensions du terrain après l’initialisation.

Les orientations suivent 16 secteurs horaires : 0=droite, 4=bas, 8=gauche, 12=haut. Seuls les quatre bits de poids faible sont utilisés. Les coordonnées d’écran augmentent vers la droite et le bas ; chaque dimension va de 1 à 256 pixels.

Les octets des tableaux ne sont pas effacés. Utilisez chain_body_reset pour recommencer ; appeler chain_body_grow juste après le vidage n’ajoute pas d’articulation.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’image montre en haut un corps droit, au milieu une mise à jour après un virage vers le bas et en bas quatre mises à jour après ce virage. Les coordonnées sont dessinées au double de leur taille logique. La courbure se propage depuis la tête à droite vers l’arrière. CGB et FC utilisent rouge pour la tête, bleu pour le corps et vert pour la queue ; DMG utilise noir. Quatre mises à jour de stabilisation séparent la queue dupliquée après croissance. Ce sont trois vues des mêmes huit articulations, pas un corps de 24 articulations.

Programme d’exemple complet

Commande de compilation

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

Oublie l’historique enregistré pour réutiliser le même tableau de stockage.

Syntaxe

void chain_clear(Chain* chain);

Paramètres

chain

Pointeur vers le Chain initialisé.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Remet le nombre d’éléments et head à zéro sans effacer ni libérer le tableau. L’appelant possède Chain et son tableau de points et doit les maintenir valides. Limitez la capacité à 128 pour éviter un débordement de l’addition des indices sur huit bits lors de la lecture.

La version FC ne fait rien si chain == 0.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple vide un historique de quatre points et vérifie que son nombre d’éléments devient nul.

Programme d’exemple complet

Commande de compilation

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

Lit le nombre de positions actuellement disponibles dans l’historique.

Syntaxe

u8 chain_get_count(const Chain* chain);

Paramètres

chain

Pointeur vers le Chain initialisé.

Valeur renvoyée

Renvoie un nombre compris entre zéro et la capacité, ou zéro si la chaîne est nulle.

Conditions et limites

L’appelant possède à la fois Chain et son tableau de points, et doit les maintenir valides. Limitez la capacité à 128 pour éviter un débordement lors de l’addition des indices sur huit bits dans la fonction de lecture.

Exemple d’utilisation

result[4]=chain_get_count(&trail);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Après cinq insertions dans quatre emplacements, le nombre reste quatre. Il passe à zéro après effacement et reste nul pour un historique de capacité nulle.

Programme d’exemple complet

Commande de compilation

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

Lit une position stockée en indiquant son ancienneté dans l’historique.

Syntaxe

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

Paramètres

chain

Pointeur vers le Chain initialisé.

index

Ancienneté du point : 0 désigne le plus récent et count - 1 le plus ancien conservé.

out

Objet ChainPoint modifiable et distinct pour recevoir le résultat ; un pointeur nul provoque un échec.

Valeur renvoyée

Renvoie 1 en cas de succès, ou 0 si la demande est invalide. Si out n’est pas nul, il est mis à (0,0) avant la validation.

Conditions et limites

out ne doit pas partager sa mémoire avec le tableau de stockage ou avec Chain : la remise à zéro de la sortie détruirait les données sources. L’appelant possède Chain et son tableau de points et doit les maintenir valides. Limitez la capacité à 128 pour éviter un débordement de l’addition des indices sur huit bits lors de la lecture.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’indice 0 lit le point le plus récent (40,24), l’indice 3 le plus ancien (16,8), et l’indice invalide 4 renvoie un échec avec une sortie (0,0).

Programme d’exemple complet

Commande de compilation

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

Associe une zone de stockage à un historique circulaire de positions, initialement vide.

Syntaxe

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

Paramètres

chain

Objet Chain modifiable à initialiser.

storage

Tableau pouvant contenir capacity éléments ChainPoint.

capacity

Nombre d’emplacements de points. Utilisez 1 à 128 pour un historique exploitable ; zéro désactive l’enregistrement.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

L’appelant possède à la fois Chain et son tableau de points, et doit les maintenir valides. Limitez la capacité à 128 pour éviter un débordement lors de l’addition des indices sur huit bits dans la fonction de lecture.

La version FC ne fait rien si chain == 0.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple associe quatre emplacements de points et vérifie que le nombre initial est nul.

Programme d’exemple complet

Commande de compilation

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

Ajoute la position la plus récente en tête de l’historique et remplace le point le plus ancien lorsque le tableau est plein.

Syntaxe

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

Paramètres

chain

Pointeur vers le Chain initialisé.

x

Coordonnée X signée du nouveau point.

y

Coordonnée Y signée du nouveau point.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Un pointeur de chaîne nul ou une capacité nulle ne produit aucun effet. L’appelant possède Chain et son tableau de points et doit les maintenir valides. Limitez la capacité à 128 pour éviter un débordement de l’addition des indices sur huit bits lors de la lecture.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Après cinq insertions dans quatre emplacements, (40,24) est le point le plus récent et (16,8) le plus ancien conservé ; le point initial (8,8) a été remplacé.

Programme d’exemple complet

Commande de compilation

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

Teste si un point appartient à un rectangle FC, bords gauche et supérieur inclus, bords droit et inférieur exclus.

Syntaxe

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

Paramètres

box

NesBox16 accessible en lecture ; ne passez pas de pointeur nul.

px

Coordonnée X du point, sur 16 bits non signés.

py

Coordonnée Y du point, sur 16 bits non signés.

Valeur renvoyée

Renvoie 1 à l’intérieur, 0 à l’extérieur.

Conditions et limites

x, y sont des coordonnées non signées sur 16 bits ; la largeur et la hauteur tiennent chacune sur un octet. Utilisez des dimensions positives et limitez à 65535 la somme de chaque coordonnée et de sa dimension. Les rectangles franchissant le rebouclage des coordonnées ne sont pas pris en charge.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Chaque unité de coordonnée correspond à une tuile. Les rectangles A en (1,1) et B en (5,4) mesurent tous deux 8×6. Les cases propres à A affichent A, celles propres à B affichent B, et le chevauchement de 4×3 affiche 12 cases O. Le bord droit de A, x=9, est exclu. Sur CGB, A est rouge, B bleu et O vert.

Programme d’exemple complet

Commande de compilation

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

Teste si deux rectangles FC passés par pointeur se chevauchent sur une surface non nulle.

Syntaxe

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

Paramètres

a

Premier NesBox16 accessible en lecture ; ne passez pas de pointeur nul.

b

Second NesBox16 accessible en lecture.

Valeur renvoyée

Renvoie 1 en cas de chevauchement, 0 si les rectangles sont séparés ou ne se touchent que par les bords.

Conditions et limites

x, y sont des coordonnées non signées sur 16 bits ; la largeur et la hauteur tiennent chacune sur un octet. Utilisez des dimensions positives et limitez à 65535 la somme de chaque coordonnée et de sa dimension. Les rectangles franchissant le rebouclage des coordonnées ne sont pas pris en charge.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Chaque unité de coordonnée correspond à une tuile. Les rectangles A en (1,1) et B en (5,4) mesurent tous deux 8×6. Les cases propres à A affichent A, celles propres à B affichent B, et le chevauchement de 4×3 affiche 12 cases O. Le bord droit de A, x=9, est exclu. Sur CGB, A est rouge, B bleu et O vert.

Programme d’exemple complet

Commande de compilation

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

Conserve un code d’échec d’assertion et tente d’ajouter une entrée ASSERT.

Syntaxe

void debug_assert_fail(u16 code);

Paramètres

code

Identifiant d’erreur sur 16 bits à conserver.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

L’exécution continue. Le dernier code d’assertion est mis à jour même si le journal est plein. Le journal contient par défaut 32 entrées et abandonne les nouvelles lorsqu’il est plein. Si vous redéfinissez DEBUG_TRACE_MAX, utilisez partout la même valeur, entre 1 et 255, dans chaque unité de traduction. Les noms sont conservés sous forme de pointeurs, sans copie ; leur mémoire doit rester lisible jusqu’à la fin de l’inspection. Vous devez coordonner vous-même les écritures du code principal et des interruptions.

Exemple d’utilisation

debug_assert_fail(42);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple enregistre le code 42, remplit le journal, puis enregistre le code 999. Le nombre d’entrées reste 32, mais le dernier code devient 999.

Programme d’exemple complet

Commande de compilation

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

Lit le dernier code d’assertion, indépendamment de la place disponible dans le journal.

Syntaxe

u16 debug_get_last_assert(void);

Valeur renvoyée

Renvoie le dernier code sur 16 bits ; sa valeur initiale après initialisation est zéro.

Conditions et limites

Zéro est aussi la valeur initiale : il ne permet pas de distinguer un échec enregistré avec le code zéro. La lecture n’efface pas le code.

Exemple d’utilisation

result[22]=debug_get_last_assert();

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple vérifie 77 après la macro d’assertion, 999 une fois le journal plein et zéro après réinitialisation.

Programme d’exemple complet

Commande de compilation

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

Lit le nombre d’entrées valides dans le tableau de trace.

Syntaxe

u8 debug_get_trace_count(void);

Valeur renvoyée

Renvoie un nombre compris entre zéro et DEBUG_TRACE_MAX.

Conditions et limites

Le journal contient par défaut 32 entrées et abandonne les nouvelles lorsqu’il est plein. Si vous redéfinissez DEBUG_TRACE_MAX, utilisez partout la même valeur, entre 1 et 255, dans chaque unité de traduction. Les noms sont conservés sous forme de pointeurs, sans copie ; leur mémoire doit rester lisible jusqu’à la fin de l’inspection. Vous devez coordonner vous-même les écritures du code principal et des interruptions.

Exemple d’utilisation

result[1]=debug_get_trace_count();

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple vérifie les dix premières entrées, puis la limite de 32 après d’autres écritures. Le compteur ne revient pas à zéro lorsque le journal est plein.

Programme d’exemple complet

Commande de compilation

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

Fournit une référence au tableau interne pour examiner les noms, valeurs et numéros de trame enregistrés.

Syntaxe

const DebugTraceEntry* debug_get_trace_log(void);

Valeur renvoyée

Renvoie un pointeur en lecture seule vers le tableau interne DebugTraceEntry.

Conditions et limites

Il ne s’agit pas d’une copie. Ne lisez que le nombre d’entrées indiqué par debug_get_trace_count(). Les anciens octets restants après initialisation ne sont pas des enregistrements valides. Le journal contient par défaut 32 entrées et abandonne les nouvelles lorsqu’il est plein. Si vous redéfinissez DEBUG_TRACE_MAX, utilisez partout la même valeur, entre 1 et 255, dans chaque unité de traduction. Les noms sont conservés sous forme de pointeurs, sans copie ; leur mémoire doit rester lisible jusqu’à la fin de l’inspection. Vous devez coordonner vous-même les écritures du code principal et des interruptions.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple lit les dix champs de valeur et de trame, et vérifie le B initial du libellé BEGIN.

Programme d’exemple complet

Commande de compilation

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

Initialise la longueur valide du journal, le numéro de trame associé et le dernier code d’assertion.

Syntaxe

void debug_init(void);

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Les octets des entrées existantes ne sont pas effacés. Appelez cette fonction avant d’enregistrer la première entrée. Le journal contient par défaut 32 entrées et abandonne les nouvelles lorsqu’il est plein. Si vous redéfinissez DEBUG_TRACE_MAX, utilisez partout la même valeur, entre 1 et 255, dans chaque unité de traduction. Les noms sont conservés sous forme de pointeurs, sans copie ; leur mémoire doit rester lisible jusqu’à la fin de l’inspection. Vous devez coordonner vous-même les écritures du code principal et des interruptions.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple vérifie que le nombre initial est nul, puis réinitialise un journal rempli. Il contrôle que le nombre d’entrées et le code d’assertion sont effacés, alors que les anciennes valeurs du tableau subsistent.

Programme d’exemple complet

Commande de compilation

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

Enregistre un marqueur de trame nommé pour repérer une étape du traitement.

Syntaxe

void debug_mark_frame(const u8* label);

Paramètres

label

Libellé terminé par zéro, dans une mémoire qui doit rester lisible jusqu’à l’inspection.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Le journal contient par défaut 32 entrées et abandonne les nouvelles lorsqu’il est plein. Si vous redéfinissez DEBUG_TRACE_MAX, utilisez partout la même valeur, entre 1 et 255, dans chaque unité de traduction. Les noms sont conservés sous forme de pointeurs, sans copie ; leur mémoire doit rester lisible jusqu’à la fin de l’inspection. Vous devez coordonner vous-même les écritures du code principal et des interruptions.

Exemple d’utilisation

debug_mark_frame("BEGIN");

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’ajout du marqueur BEGIN enregistre la valeur 65535 (0xFFFF) avec le numéro de trame 513.

Programme d’exemple complet

Commande de compilation

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

Définit le numéro de trame qui sera copié dans les entrées suivantes du journal.

Syntaxe

void debug_set_frame(u16 frame);

Paramètres

frame

Numéro de trame sur 16 bits pour les entrées suivantes.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Cette fonction n’attend pas de trame et n’incrémente pas automatiquement le numéro. Passez explicitement le compteur de trames du jeu. Le journal contient par défaut 32 entrées et abandonne les nouvelles lorsqu’il est plein. Si vous redéfinissez DEBUG_TRACE_MAX, utilisez partout la même valeur, entre 1 et 255, dans chaque unité de traduction. Les noms sont conservés sous forme de pointeurs, sans copie ; leur mémoire doit rester lisible jusqu’à la fin de l’inspection. Vous devez coordonner vous-même les écritures du code principal et des interruptions.

Exemple d’utilisation

debug_set_frame(513);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple définit 513, écrit dix entrées, puis relit leurs dix champs de trame pour vérifier ce numéro.

Programme d’exemple complet

Commande de compilation

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

Enregistre un score ou un compteur sur 16 bits avec son nom.

Syntaxe

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

Paramètres

name

Libellé terminé par zéro, dans une mémoire qui doit rester lisible jusqu’à l’inspection.

value

Valeur de 0 à 65535 à enregistrer.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Le journal contient par défaut 32 entrées et abandonne les nouvelles lorsqu’il est plein. Si vous redéfinissez DEBUG_TRACE_MAX, utilisez partout la même valeur, entre 1 et 255, dans chaque unité de traduction. Les noms sont conservés sous forme de pointeurs, sans copie ; leur mémoire doit rester lisible jusqu’à la fin de l’inspection. Vous devez coordonner vous-même les écritures du code principal et des interruptions.

Exemple d’utilisation

debug_trace_u16("WORD",4660);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’entrée WORD stocke 4660 (0x1234), puis l’exemple la relit pour vérifier les deux octets.

Programme d’exemple complet

Commande de compilation

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

Enregistre une valeur d’état sur huit bits avec son nom et le numéro de trame courant.

Syntaxe

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

Paramètres

name

Libellé terminé par zéro, dans une mémoire qui doit rester lisible jusqu’à l’inspection.

value

Valeur de 0 à 255, étendue par des zéros dans le champ de 16 bits du journal.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Le journal contient par défaut 32 entrées et abandonne les nouvelles lorsqu’il est plein. Si vous redéfinissez DEBUG_TRACE_MAX, utilisez partout la même valeur, entre 1 et 255, dans chaque unité de traduction. Les noms sont conservés sous forme de pointeurs, sans copie ; leur mémoire doit rester lisible jusqu’à la fin de l’inspection. Vous devez coordonner vous-même les écritures du code principal et des interruptions.

Exemple d’utilisation

debug_trace_u8("BYTE",255);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’entrée BYTE enregistre 255 et vérifie que le champ de valeur sur 16 bits du journal contient bien 255.

Programme d’exemple complet

Commande de compilation

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

Macro utilisable comme une instruction, qui enregistre le code d’assertion 1 si sa condition est fausse.

Syntaxe

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

Paramètres

cond

Condition qui doit être vraie ; zéro signifie un échec.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

La condition est évaluée une seule fois. Si elle est vraie, rien n’est enregistré ; sinon, l’échec est consigné sans arrêter l’exécution. La forme do…while (0) permet d’utiliser la macro comme une seule instruction dans un if…else.

Exemple d’utilisation

KITAQGB_ASSERT(1);KITAQGB_ASSERT(0);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Une assertion vraie et une assertion fausse produisent exactement une entrée de code 1.

Programme d’exemple complet

Commande de compilation

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)

Enregistre le code d’assertion choisi uniquement si la condition est fausse.

Syntaxe

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

Paramètres

cond

Condition censée être vraie.

code

Expression du code, évaluée en cas d’échec et convertie sur 16 bits.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

La condition est évaluée une seule fois ; l’expression du code ne l’est qu’en cas d’échec. L’exécution continue après l’enregistrement.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Si la condition est vraie, l’expression de code ++side_effect n’est pas évaluée et la variable reste à zéro. Une condition fausse enregistre le code 77.

Programme d’exemple complet

Commande de compilation

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)

Convertit un libellé en pointeur de chaîne et ajoute un marqueur de trame de valeur 0xFFFF.

Syntaxe

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

Paramètres

label

Libellé terminé par zéro, dans une mémoire qui doit rester lisible jusqu’à l’inspection.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

Le journal contient par défaut 32 entrées et abandonne les nouvelles lorsqu’il est plein. Si vous redéfinissez DEBUG_TRACE_MAX, utilisez partout la même valeur, entre 1 et 255, dans chaque unité de traduction. Les noms sont conservés sous forme de pointeurs, sans copie ; leur mémoire doit rester lisible jusqu’à la fin de l’inspection. Vous devez coordonner vous-même les écritures du code principal et des interruptions.

Exemple d’utilisation

KITAQGB_MARK_FRAME("END");

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le marqueur END est vérifié avec la valeur 65535 et le numéro de trame 513.

Programme d’exemple complet

Commande de compilation

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

Convertit explicitement une valeur sur 16 bits, puis l’enregistre avec son nom.

Syntaxe

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

Paramètres

name

Libellé terminé par zéro, dans une mémoire qui doit rester lisible jusqu’à l’inspection.

value

Expression convertie sur 16 bits avant enregistrement.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

La macro reste toujours active ; les paramètres de compilation ne la désactivent pas automatiquement. Elle enregistre les valeurs sur 16 bits comme KITAQGB_TRACE_U16. Le journal contient par défaut 32 entrées et abandonne les nouvelles lorsqu’il est plein. Si vous redéfinissez DEBUG_TRACE_MAX, utilisez partout la même valeur, entre 1 et 255, dans chaque unité de traduction. Les noms sont conservés sous forme de pointeurs, sans copie ; leur mémoire doit rester lisible jusqu’à la fin de l’inspection. Vous devez coordonner vous-même les écritures du code principal et des interruptions.

Exemple d’utilisation

KITAQGB_TRACE("SCORE",600);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple enregistre 600, puis relit cette valeur dans le journal pour la vérifier.

Programme d’exemple complet

Commande de compilation

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

Convertit explicitement une valeur sur 16 bits, puis l’enregistre avec son nom.

Syntaxe

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

Paramètres

name

Libellé terminé par zéro, dans une mémoire qui doit rester lisible jusqu’à l’inspection.

value

Expression convertie sur 16 bits avant enregistrement.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

La macro reste toujours active ; les paramètres de compilation ne la désactivent pas automatiquement. Le journal contient par défaut 32 entrées et abandonne les nouvelles lorsqu’il est plein. Si vous redéfinissez DEBUG_TRACE_MAX, utilisez partout la même valeur, entre 1 et 255, dans chaque unité de traduction. Les noms sont conservés sous forme de pointeurs, sans copie ; leur mémoire doit rester lisible jusqu’à la fin de l’inspection. Vous devez coordonner vous-même les écritures du code principal et des interruptions.

Exemple d’utilisation

KITAQGB_TRACE_U16("WORD2",500);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple enregistre 500, puis relit cette valeur dans le journal pour la vérifier.

Programme d’exemple complet

Commande de compilation

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

Convertit explicitement une valeur sur huit bits, puis l’enregistre avec son nom.

Syntaxe

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

Paramètres

name

Libellé terminé par zéro, dans une mémoire qui doit rester lisible jusqu’à l’inspection.

value

Expression convertie sur huit bits avant enregistrement.

Valeur renvoyée

Aucune valeur de retour.

Conditions et limites

La macro reste toujours active ; les paramètres de compilation ne la désactivent pas automatiquement. Le journal contient par défaut 32 entrées et abandonne les nouvelles lorsqu’il est plein. Si vous redéfinissez DEBUG_TRACE_MAX, utilisez partout la même valeur, entre 1 et 255, dans chaque unité de traduction. Les noms sont conservés sous forme de pointeurs, sans copie ; leur mémoire doit rester lisible jusqu’à la fin de l’inspection. Vous devez coordonner vous-même les écritures du code principal et des interruptions.

Exemple d’utilisation

KITAQGB_TRACE_U8("CAST",0x1234);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple enregistre 52. Seul l’octet de poids faible 0x34 de 0x1234 est conservé.

Programme d’exemple complet

Commande de compilation

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

Libère toutes les entités et réinitialise leurs champs, y compris le marqueur d’absence de sprite.

Syntaxe

void entity_clear_all(void);

Valeur renvoyée

Aucune (void).

Conditions et limites

Le pool est un tableau fixe, sans allocation sur le tas. ENTITY_MAX vaut 16 par défaut et doit être compris entre 1 et 255, avec la même définition dans chaque unité de compilation. Les ID commencent à zéro ; 0xFF indique un échec.

Met à zéro active,type,x,y,vx,vy,state,timer et place sprite à 0xFF dans chaque emplacement. Ne masque ni ne libère les sprites matériels ; gérez séparément ces ressources.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme complet illustre le cycle de vie d’un emplacement réutilisable. Lisez les nombres avec leurs libellés : CREATED 002 après deux allocations ; AFTER FREE 001 après libération de la première ; REUSED ID 000 quand le plus petit ID libre est réutilisé ; AFTER CLEAR 000 après vidage du pool. Il vérifie aussi la recherche null après libération et la remise à zéro après réallocation. FAILED CHECKS 000 indique que les valeurs concordent.

Le parcours FC appelle chaque rappel pour les deux entités actives : UPDATE CALLS 002 et DRAW CALLS 002. Le rappel de mise à jour déplace les deux objets d’une tuile vers la droite. Celui de dessin place A en (3,12) et B en (7,12) pour les représenter. Ce sont des tuiles de police du fond dessinées par le rappel, pas des sprites alloués automatiquement.

Programme d’exemple complet

Commande de compilation

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

Compte les emplacements d’entités occupés sans les modifier.

Syntaxe

u8 entity_count_active(void);

Valeur renvoyée

Nombre d’emplacements dont active est non nul, de 0 à ENTITY_MAX. C’est l’occupation, pas le plus grand ID ni le nombre de sprites à l’écran.

Conditions et limites

Le pool est un tableau fixe, sans allocation sur le tas. ENTITY_MAX vaut 16 par défaut et doit être compris entre 1 et 255, avec la même définition dans chaque unité de compilation. Les ID commencent à zéro ; 0xFF indique un échec.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme complet illustre le cycle de vie d’un emplacement réutilisable. Lisez les nombres avec leurs libellés : CREATED 002 après deux allocations ; AFTER FREE 001 après libération de la première ; REUSED ID 000 quand le plus petit ID libre est réutilisé ; AFTER CLEAR 000 après vidage du pool. Il vérifie aussi la recherche null après libération et la remise à zéro après réallocation. FAILED CHECKS 000 indique que les valeurs concordent.

Le parcours FC appelle chaque rappel pour les deux entités actives : UPDATE CALLS 002 et DRAW CALLS 002. Le rappel de mise à jour déplace les deux objets d’une tuile vers la droite. Celui de dessin place A en (3,12) et B en (7,12) pour les représenter. Ce sont des tuiles de police du fond dessinées par le rappel, pas des sprites alloués automatiquement.

Programme d’exemple complet

Commande de compilation

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

Alloue une entité du type et à la position indiqués ; renvoie son ID réutilisable ou 0xFF si le pool est plein.

Syntaxe

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

Paramètres

type

Étiquette de type définie par le jeu, de 0 à 255. Le pool la conserve sans sélectionner de comportement ni de routine de dessin.

x, y

Coordonnées signées sur 16 bits (-32768–32767). Le jeu choisit l’unité, par exemple pixels ou Q8.8 ; le pool ne convertit pas les unités, ne borne pas les positions et n’applique pas automatiquement les vitesses.

Valeur renvoyée

L’ID du premier emplacement libre (0–ENTITY_MAX-1), ou 0xFF si aucun n’est libre. L’allocation fixe active=1, conserve type et position, efface vitesse/état/temporisateur et place sprite=0xFF.

Conditions et limites

Le pool est un tableau fixe, sans allocation sur le tas. ENTITY_MAX vaut 16 par défaut et doit être compris entre 1 et 255, avec la même définition dans chaque unité de compilation. Les ID commencent à zéro ; 0xFF indique un échec.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme complet illustre le cycle de vie d’un emplacement réutilisable. Lisez les nombres avec leurs libellés : CREATED 002 après deux allocations ; AFTER FREE 001 après libération de la première ; REUSED ID 000 quand le plus petit ID libre est réutilisé ; AFTER CLEAR 000 après vidage du pool. Il vérifie aussi la recherche null après libération et la remise à zéro après réallocation. FAILED CHECKS 000 indique que les valeurs concordent.

Le parcours FC appelle chaque rappel pour les deux entités actives : UPDATE CALLS 002 et DRAW CALLS 002. Le rappel de mise à jour déplace les deux objets d’une tuile vers la droite. Celui de dessin place A en (3,12) et B en (7,12) pour les représenter. Ce sont des tuiles de police du fond dessinées par le rappel, pas des sprites alloués automatiquement.

Programme d’exemple complet

Commande de compilation

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

Libère l’entité id ; ses données restent en place jusqu’à la prochaine allocation.

Syntaxe

void entity_destroy(u8 id);

Paramètres

id

Indice d’emplacement réutilisable, de 0 à ENTITY_MAX-1. Au-delà, l’ID est invalide. Sa destruction n’a aucun effet et sa recherche renvoie null.

Valeur renvoyée

Aucune (void).

Conditions et limites

Le pool est un tableau fixe, sans allocation sur le tas. ENTITY_MAX vaut 16 par défaut et doit être compris entre 1 et 255, avec la même définition dans chaque unité de compilation. Les ID commencent à zéro ; 0xFF indique un échec.

La destruction efface seulement active : elle n’efface pas les autres champs et ne libère ni sprite ni ressource. Une allocation ultérieure peut réutiliser le même ID et la même adresse pour une autre entité. Le jeu doit gérer les ressources associées.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme complet illustre le cycle de vie d’un emplacement réutilisable. Lisez les nombres avec leurs libellés : CREATED 002 après deux allocations ; AFTER FREE 001 après libération de la première ; REUSED ID 000 quand le plus petit ID libre est réutilisé ; AFTER CLEAR 000 après vidage du pool. Il vérifie aussi la recherche null après libération et la remise à zéro après réallocation. FAILED CHECKS 000 indique que les valeurs concordent.

Le parcours FC appelle chaque rappel pour les deux entités actives : UPDATE CALLS 002 et DRAW CALLS 002. Le rappel de mise à jour déplace les deux objets d’une tuile vers la droite. Celui de dessin place A en (3,12) et B en (7,12) pour les représenter. Ce sont des tuiles de police du fond dessinées par le rappel, pas des sprites alloués automatiquement.

Programme d’exemple complet

Commande de compilation

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

Parcourt les entités actives et transmet chaque ID au rappel de dessin. Le parcours est celui de entity_update_all ; aucun sprite ni pixel n’est dessiné si le rappel ne soumet pas de données de dessin.

Syntaxe

void entity_draw_all(EntityFn fn);

Paramètres

fn

Pointeur de fonction de signature void fn(u8 id). Reçoit un ID ; utilisez entity_get(id) pour accéder aux champs. Null est accepté et n’entraîne aucun appel.

Valeur renvoyée

Aucune (void).

Conditions et limites

Le pool est un tableau fixe, sans allocation sur le tas. ENTITY_MAX vaut 16 par défaut et doit être compris entre 1 et 255, avec la même définition dans chaque unité de compilation. Les ID commencent à zéro ; 0xFF indique un échec.

L’activité est testée au moment d’atteindre l’emplacement. Un rappel peut désactiver un emplacement suivant pour le sauter, ou l’activer pour le visiter dans cette passe. Ce n’est pas un instantané de l’ensemble actif initial.

Placez le rappel dans la banque PRG commune 0, ou maintenez sa banque mappée pendant tout l’appel. Le pointeur contient une adresse CPU sur 16 bits et ne sélectionne pas de banque. Les paramètres et variables locales des fonctions FC occupent des emplacements fixes : n’appelez pas le parcours des entités récursivement et n’y entrez pas à nouveau depuis une interruption.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme complet illustre le cycle de vie d’un emplacement réutilisable. Lisez les nombres avec leurs libellés : CREATED 002 après deux allocations ; AFTER FREE 001 après libération de la première ; REUSED ID 000 quand le plus petit ID libre est réutilisé ; AFTER CLEAR 000 après vidage du pool. Il vérifie aussi la recherche null après libération et la remise à zéro après réallocation. FAILED CHECKS 000 indique que les valeurs concordent.

Le parcours FC appelle chaque rappel pour les deux entités actives : UPDATE CALLS 002 et DRAW CALLS 002. Le rappel de mise à jour déplace les deux objets d’une tuile vers la droite. Celui de dessin place A en (3,12) et B en (7,12) pour les représenter. Ce sont des tuiles de police du fond dessinées par le rappel, pas des sprites alloués automatiquement.

Programme d’exemple complet

Commande de compilation

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

Renvoie un pointeur vers l’entité active, ou null pour un ID invalide ou libre. Cet espace peut être réutilisé.

Syntaxe

Entity* entity_get(u8 id);

Paramètres

id

Indice d’emplacement réutilisable, de 0 à ENTITY_MAX-1. Au-delà, l’ID est invalide. Sa destruction n’a aucun effet et sa recherche renvoie null.

Valeur renvoyée

Pointeur modifiable vers l’emplacement actif, ou null pour un ID invalide ou libre. La mémoire appartient au pool ; ne la libérez pas et ne traitez pas le pointeur comme une identité permanente après destruction et réallocation.

Conditions et limites

Le pool est un tableau fixe, sans allocation sur le tas. ENTITY_MAX vaut 16 par défaut et doit être compris entre 1 et 255, avec la même définition dans chaque unité de compilation. Les ID commencent à zéro ; 0xFF indique un échec.

La destruction efface seulement active : elle n’efface pas les autres champs et ne libère ni sprite ni ressource. Une allocation ultérieure peut réutiliser le même ID et la même adresse pour une autre entité. Le jeu doit gérer les ressources associées.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme complet illustre le cycle de vie d’un emplacement réutilisable. Lisez les nombres avec leurs libellés : CREATED 002 après deux allocations ; AFTER FREE 001 après libération de la première ; REUSED ID 000 quand le plus petit ID libre est réutilisé ; AFTER CLEAR 000 après vidage du pool. Il vérifie aussi la recherche null après libération et la remise à zéro après réallocation. FAILED CHECKS 000 indique que les valeurs concordent.

Le parcours FC appelle chaque rappel pour les deux entités actives : UPDATE CALLS 002 et DRAW CALLS 002. Le rappel de mise à jour déplace les deux objets d’une tuile vers la droite. Celui de dessin place A en (3,12) et B en (7,12) pour les représenter. Ce sont des tuiles de police du fond dessinées par le rappel, pas des sprites alloués automatiquement.

Programme d’exemple complet

Commande de compilation

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

Initialise tous les emplacements du pool d’entités.

Syntaxe

void entity_init(void);

Valeur renvoyée

Aucune (void).

Conditions et limites

Le pool est un tableau fixe, sans allocation sur le tas. ENTITY_MAX vaut 16 par défaut et doit être compris entre 1 et 255, avec la même définition dans chaque unité de compilation. Les ID commencent à zéro ; 0xFF indique un échec.

Met à zéro active,type,x,y,vx,vy,state,timer et place sprite à 0xFF dans chaque emplacement. Ne masque ni ne libère les sprites matériels ; gérez séparément ces ressources.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme complet illustre le cycle de vie d’un emplacement réutilisable. Lisez les nombres avec leurs libellés : CREATED 002 après deux allocations ; AFTER FREE 001 après libération de la première ; REUSED ID 000 quand le plus petit ID libre est réutilisé ; AFTER CLEAR 000 après vidage du pool. Il vérifie aussi la recherche null après libération et la remise à zéro après réallocation. FAILED CHECKS 000 indique que les valeurs concordent.

Le parcours FC appelle chaque rappel pour les deux entités actives : UPDATE CALLS 002 et DRAW CALLS 002. Le rappel de mise à jour déplace les deux objets d’une tuile vers la droite. Celui de dessin place A en (3,12) et B en (7,12) pour les représenter. Ce sont des tuiles de police du fond dessinées par le rappel, pas des sprites alloués automatiquement.

Programme d’exemple complet

Commande de compilation

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

Parcourt les emplacements actifs par ID croissant et appelle fn(id) une fois pour chacun. Le rappel implémente déplacements, collisions ou temporisateurs ; le pool ne fournit pas cette logique. Un rappel null ne fait rien.

Syntaxe

void entity_update_all(EntityFn fn);

Paramètres

fn

Pointeur de fonction de signature void fn(u8 id). Reçoit un ID ; utilisez entity_get(id) pour accéder aux champs. Null est accepté et n’entraîne aucun appel.

Valeur renvoyée

Aucune (void).

Conditions et limites

Le pool est un tableau fixe, sans allocation sur le tas. ENTITY_MAX vaut 16 par défaut et doit être compris entre 1 et 255, avec la même définition dans chaque unité de compilation. Les ID commencent à zéro ; 0xFF indique un échec.

L’activité est testée au moment d’atteindre l’emplacement. Un rappel peut désactiver un emplacement suivant pour le sauter, ou l’activer pour le visiter dans cette passe. Ce n’est pas un instantané de l’ensemble actif initial.

Placez le rappel dans la banque PRG commune 0, ou maintenez sa banque mappée pendant tout l’appel. Le pointeur contient une adresse CPU sur 16 bits et ne sélectionne pas de banque. Les paramètres et variables locales des fonctions FC occupent des emplacements fixes : n’appelez pas le parcours des entités récursivement et n’y entrez pas à nouveau depuis une interruption.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Le programme complet illustre le cycle de vie d’un emplacement réutilisable. Lisez les nombres avec leurs libellés : CREATED 002 après deux allocations ; AFTER FREE 001 après libération de la première ; REUSED ID 000 quand le plus petit ID libre est réutilisé ; AFTER CLEAR 000 après vidage du pool. Il vérifie aussi la recherche null après libération et la remise à zéro après réallocation. FAILED CHECKS 000 indique que les valeurs concordent.

Le parcours FC appelle chaque rappel pour les deux entités actives : UPDATE CALLS 002 et DRAW CALLS 002. Le rappel de mise à jour déplace les deux objets d’une tuile vers la droite. Celui de dessin place A en (3,12) et B en (7,12) pour les représenter. Ce sont des tuiles de police du fond dessinées par le rappel, pas des sprites alloués automatiquement.

Programme d’exemple complet

Commande de compilation

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

Divise des valeurs Q8.8 après avoir réduit la précision des opérandes.

Syntaxe

fix8 fix_div(fix8 a, fix8 b);

Paramètres

a

Opérande de gauche au format Q8.8.

b

Opérande de droite au format Q8.8.

Valeur renvoyée

Renvoie un quotient Q8.8, ou zéro si b == 0.

Conditions et limites

L’expression calculée est ((a >> 4) * 256) / (b >> 4). Un diviseur non nul doit le rester après le décalage : n’utilisez pas de valeur brute positive de 1 à 15. Le numérateur mis à l’échelle doit lui aussi tenir sur 16 bits.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Diviser 3,0 par 2,0 donne 1,5 (valeur brute 384). Une vérification distincte contrôle le retour prévu lorsque le diviseur est exactement nul.

Programme d’exemple complet

Commande de compilation

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

Convertit une coordonnée ou une vitesse entière en Q8.8 pour conserver les parties fractionnaires dans les calculs suivants.

Syntaxe

fix8 fix_from_int(s16 n);

Paramètres

n

Entier à convertir, de −128 à 127.

Valeur renvoyée

Renvoie la valeur brute n × 256.

Conditions et limites

fix8 est un format Q8.8 signé : la valeur brute 256 représente 1,0. Les valeurs intermédiaires et les résultats doivent tenir sur 16 bits.

Exemple d’utilisation

result[0]=fix_from_int(-3);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple convertit −3. L’affichage −00768 correspond au résultat brut Q8.8, soit −768.

Programme d’exemple complet

Commande de compilation

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

Interpole entre deux valeurs Q8.8 à l’aide d’un poids sur huit bits.

Syntaxe

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

Paramètres

a

Opérande de gauche au format Q8.8.

b

Opérande de droite au format Q8.8.

t_q8

Poids d’interpolation, de 0 à 255.

Valeur renvoyée

Renvoie la valeur Q8.8 interpolée approximativement.

Conditions et limites

La différence et le poids sont chacun décalés de quatre bits vers la droite. Le poids n’a donc que 16 niveaux, et même 255 ne permet pas nécessairement d’atteindre la valeur finale. b - a et le résultat doivent tenir sur 16 bits.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Entre 0 et 4,0, un poids de 128 donne 2,0 (valeur brute 512). Un poids de 255 donne 3,75 (valeur brute 960), ce qui montre que la valeur finale n’est pas atteinte.

Programme d’exemple complet

Commande de compilation

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

Multiplie deux valeurs Q8.8 par une approximation peu coûteuse en calcul.

Syntaxe

fix8 fix_mul(fix8 a, fix8 b);

Paramètres

a

Opérande de gauche au format Q8.8.

b

Opérande de droite au format Q8.8.

Valeur renvoyée

Renvoie le produit au format Q8.8.

Conditions et limites

Chaque opérande est décalé de quatre bits vers la droite avant la multiplication, ce qui supprime ses quatre bits de poids faible. La précision est donc inférieure à celle d’un produit complet de deux valeurs de 16 bits. fix8 est un format Q8.8 signé où la valeur brute 256 représente 1,0. Les valeurs intermédiaires et les résultats doivent tenir sur 16 bits.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Multiplier 1,5 par 2,0 donne 3,0 (valeur brute 768). Le programme vérifie aussi un cas de quantification : le produit des valeurs brutes 271 et 271 donne 256.

Programme d’exemple complet

Commande de compilation

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

Extrait une coordonnée entière d’une valeur Q8.8 en supprimant les bits fractionnaires. Les valeurs négatives sont arrondies vers moins l’infini.

Syntaxe

s16 fix_to_int(fix8 x);

Paramètres

x

Valeur Q8.8 à convertir en entier.

Valeur renvoyée

Renvoie un entier signé.

Conditions et limites

fix8 est un format Q8.8 signé : la valeur brute 256 représente 1,0. Les valeurs intermédiaires et les résultats doivent tenir sur 16 bits.

Exemple d’utilisation

result[1]=fix_to_int(-384);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

La valeur brute −384 (−1,5) donne −2, affiché sous la forme −00002. Un test de limite vérifie aussi que la valeur brute −1 devient −1.

Programme d’exemple complet

Commande de compilation

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

Calcule la valeur absolue d’un entier signé sur 16 bits.

Syntaxe

s16 kq_abs_s16(s16 v);

Paramètres

v

Valeur signée sur 16 bits dont on cherche la valeur absolue.

Valeur renvoyée

Renvoie une valeur absolue non négative, sauf pour −32768, dont la valeur absolue n’est pas représentable.

Conditions et limites

La valeur positive 32768 ne tient pas dans un s16. Excluez −32768 si vous avez besoin d’un résultat non négatif.

Exemple d’utilisation

result[0]=kq_abs_s16(-123);

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

L’exemple transforme −123 en 123, comme pour mesurer l’amplitude d’un écart entre deux coordonnées.

Programme d’exemple complet

Commande de compilation

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

Limite une coordonnée ou une vitesse à un intervalle dont les bornes sont incluses.

Syntaxe

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

Paramètres

v

Valeur signée à limiter.

lo

Borne inférieure incluse.

hi

Borne supérieure incluse.

Valeur renvoyée

Renvoie lo en dessous de l’intervalle, hi au-dessus, ou v si la valeur est dans l’intervalle.

Conditions et limites

Fournissez un intervalle valide tel que lo <= hi.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Limiter 25 à l’intervalle −10…10 donne 10. Les tests couvrent aussi −11→−10 à la borne inférieure et 3→3 à l’intérieur de l’intervalle.

Programme d’exemple complet

Commande de compilation

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

Sélectionne le plus grand de deux entiers signés sur 16 bits.

Syntaxe

s16 kq_max_s16(s16 a, s16 b);

Paramètres

a

Première valeur signée à comparer.

b

Seconde valeur signée à comparer.

Valeur renvoyée

Renvoie l’opérande sélectionné.

Conditions et limites

La comparaison tient compte du signe. Si les opérandes sont égaux, leur valeur commune est renvoyée. Aucun des deux n’est modifié.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Comparer −7 et 4 donne 4. Les résultats négatifs sont affichés avec un signe moins.

Programme d’exemple complet

Commande de compilation

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

Sélectionne le plus petit de deux entiers signés sur 16 bits.

Syntaxe

s16 kq_min_s16(s16 a, s16 b);

Paramètres

a

Première valeur signée à comparer.

b

Seconde valeur signée à comparer.

Valeur renvoyée

Renvoie l’opérande sélectionné.

Conditions et limites

La comparaison tient compte du signe. Si les opérandes sont égaux, leur valeur commune est renvoyée. Aucun des deux n’est modifié.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Comparer −7 et 4 donne -7. Les résultats négatifs sont affichés avec un signe moins.

Programme d’exemple complet

Commande de compilation

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

Teste si un point se trouve dans un rectangle, bords gauche et supérieur inclus.

Syntaxe

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

Paramètres

x

Coordonnée X du point, dans le repère du rectangle.

y

Coordonnée Y du point.

r

Rectangle à tester, passé par valeur.

Valeur renvoyée

Renvoie 1 à l’intérieur et 0 à l’extérieur.

Conditions et limites

Utilisez des dimensions positives et veillez à ce que les sommes coordonnée + dimension soient représentables en s16. Les bords droit et inférieur sont exclus. Les rectangles d’aire nulle ne sont pas explicitement rejetés.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Chaque unité de coordonnée correspond à une tuile. Les rectangles A en (1,1) et B en (5,4) mesurent tous deux 8×6. Les cases propres à A affichent A, celles propres à B affichent B, et le chevauchement de 4×3 affiche 12 cases O. Le bord droit de A, x=9, est exclu. Sur CGB, A est rouge, B bleu et O vert.

Programme d’exemple complet

Commande de compilation

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

Teste si deux rectangles alignés sur les axes se recouvrent sur une aire strictement positive.

Syntaxe

u8 kq_rect_intersect(KQRect a, KQRect b);

Paramètres

a

Premier rectangle, passé par valeur : x, y indiquent son coin supérieur gauche ; w, h sont sa largeur et sa hauteur.

b

Second rectangle, dans le même repère que A.

Valeur renvoyée

Renvoie 1 en cas de recouvrement, et 0 en cas de séparation ou de simple contact des bords.

Conditions et limites

Utilisez des dimensions positives et veillez à ce que les sommes coordonnée + dimension soient représentables en s16. Les bords droit et inférieur sont exclus. Les rectangles d’aire nulle ne sont pas explicitement rejetés.

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Chaque unité de coordonnée correspond à une tuile. Les rectangles A en (1,1) et B en (5,4) mesurent tous deux 8×6. Les cases propres à A affichent A, celles propres à B affichent B, et le chevauchement de 4×3 affiche 12 cases O. Le bord droit de A, x=9, est exclu. Sur CGB, A est rouge, B bleu et O vert.

Programme d’exemple complet

Commande de compilation

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 est un alias de input_down. Vérifie si au moins un des boutons sélectionnés est actuellement maintenu.

Indique si au moins un bouton sélectionné par mask est maintenu.

Syntaxe

u8 btn_down(u8 mask);

Paramètres

mask

Un masque BTN_*, ou plusieurs combinés avec |. Un seul bouton correspondant suffit ; BTN_A | BTN_B n’exige pas les deux. Le masque 0 renvoie toujours 0. Pour vérifier que tous sont maintenus, comparez (input_current() & mask) == mask.

Valeur renvoyée

Renvoie exactement 1 si un bouton sélectionné remplit la condition, sinon 0. Le résultat n’est pas un masque de boutons.

Conditions et limites

L’en-tête définit une macro objet qui se développe en nom d’implémentation. Arguments, résultats et accès à l’état sont identiques à ceux de la cible ; l’alias n’ajoute aucun état ni traitement distinct. Utilisez input.h/input.c pour les entrées ou system.h/system.c pour les services d’images, comme dans l’exemple complet et sa commande de compilation.

Masques communs : BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80. Un bit à 1 indique un bouton maintenu. Ce format s’applique à input_* sur GB et FC ; les lectures brutes FC utilisent un autre ordre.

Les fonctions de consultation lisent le dernier input_update() sans relire le contrôleur, consommer d’événement ni avancer les compteurs. Plusieurs consultations dans un même cycle donnent le même résultat. Deux appels à input_update() avec un bouton maintenu effacent son événement de nouvel appui au second appel.

input_down

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme distingue le maintien d’un bouton, un nouvel appui, le relâchement et la répétition automatique. Maintenez A pendant 40 mises à jour, puis relâchez-le. FIRST DOWN, FIRST PRESS et FIRST REPEAT valent 1 ; FIRST CURRENT vaut 16. HELD TICKS vaut 40, PRESS COUNT vaut 1 et REPEAT COUNT vaut 5. Au relâchement, RELEASE vaut 1, LAST CURRENT vaut 0 et LAST PREVIOUS vaut 16. FAILED CHECKS doit valoir 0. Une autre durée modifie les compteurs ; le programme vérifie les intervalles de répétition selon la durée réellement observée.

Programme d’exemple complet

Commande de compilation

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 est un alias de input_pressed. Vérifie si au moins un des boutons sélectionnés vient d’être enfoncé lors de la dernière mise à jour des entrées.

Détecte un passage de relâché à appuyé pour un bouton du masque lors de la dernière mise à jour.

Syntaxe

u8 btn_pressed(u8 mask);

Paramètres

mask

Un masque BTN_*, ou plusieurs combinés avec |. Un seul bouton correspondant suffit ; BTN_A | BTN_B n’exige pas les deux. Le masque 0 renvoie toujours 0. Pour vérifier que tous sont maintenus, comparez (input_current() & mask) == mask.

Valeur renvoyée

Renvoie exactement 1 si un bouton sélectionné remplit la condition, sinon 0. Le résultat n’est pas un masque de boutons.

Conditions et limites

L’en-tête définit une macro objet qui se développe en nom d’implémentation. Arguments, résultats et accès à l’état sont identiques à ceux de la cible ; l’alias n’ajoute aucun état ni traitement distinct. Utilisez input.h/input.c pour les entrées ou system.h/system.c pour les services d’images, comme dans l’exemple complet et sa commande de compilation.

Masques communs : BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80. Un bit à 1 indique un bouton maintenu. Ce format s’applique à input_* sur GB et FC ; les lectures brutes FC utilisent un autre ordre.

Les fonctions de consultation lisent le dernier input_update() sans relire le contrôleur, consommer d’événement ni avancer les compteurs. Plusieurs consultations dans un même cycle donnent le même résultat. Deux appels à input_update() avec un bouton maintenu effacent son événement de nouvel appui au second appel.

input_pressed

Exemple d’utilisation

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

Cet extrait montre l’appel. Avant de l’intégrer à un programme complet, respectez les conditions d’initialisation et de dimensionnement des tampons indiquées.

Résultat attendu

Ce programme distingue le maintien d’un bouton, un nouvel appui, le relâchement et la répétition automatique. Maintenez A pendant 40 mises à jour, puis relâchez-le. FIRST DOWN, FIRST PRESS et FIRST REPEAT valent 1 ; FIRST CURRENT vaut 16. HELD TICKS vaut 40, PRESS COUNT vaut 1 et REPEAT COUNT vaut 5. Au relâchement, RELEASE vaut 1, LAST CURRENT vaut 0 et LAST PREVIOUS vaut 16. FAILED CHECKS doit valoir 0. Une autre durée modifie les compteurs ; le programme vérifie les intervalles de répétition selon la durée réellement observée.

Programme d’exemple complet

Commande de compilation

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