BIBLIOTECA KITAQGB

Copia un AssetDesc desde el banco de ROM de la tabla registrada al espacio proporcionado por el programa. Obtiene los metadatos del recurso, no sus datos.

Sintaxis

u8 asset_get(u8 asset_id, AssetDesc* out_desc);

Parámetros

asset_id

Índice del recurso, empezando por cero. Debe cumplir asset_id < count en la tabla registrada.

out_desc

Espacio escribible para un descriptor de 6 bytes. Un puntero nulo se rechaza antes de acceder a la tabla.

Valor devuelto

1 si se copia el descriptor; 0 si el destino es nulo o el ID queda fuera del rango. Esos fallos no modifican el destino.

Condiciones y límites

Registre la tabla antes de buscar recursos. El registro es un estado global compartido: no lo cambie durante una búsqueda. La biblioteca comprueba los ID y el puntero de salida de asset_get, pero no valida la tabla, las direcciones de los datos ni el contenido del cartucho.

Los ejemplos sitúan el código llamante en el banco fijo 0 para que cambiar el banco de origen no retire el código en ejecución. Las transferencias son síncronas. No las interrumpa con otra copia que cambie bancos ni suponga que la función garantiza por sí sola la seguridad de todas las interrupciones.

Ejemplo de uso

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

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Lee el descriptor 0 y comprueba tipo TILES, banco 2, puntero y longitud de 144 bytes. Los ID inválidos y el destino nulo deben fallar; una búsqueda fallida conserva el valor previo de salida.

Imagen esperada: una fila roja empieza en (16,32) y ocupa 72×8 píxeles. Repite tres veces un triángulo de 8×8, un cuadrado de 8×8 con borde de un píxel y un tile con sus cuatro columnas izquierdas rellenas. El triángulo crece desde un píxel arriba a la izquierda hasta ocho en la fila inferior.

En GB, el triángulo y contorno azules de (16,64) muestran __farmemcpy; la pareja verde de (16,96), __far_memcpy. Cada pareja ocupa 16×8 píxeles. CGB usa esos colores; DMG muestra las mismas formas en negro sobre blanco.

El estado esperado es FAILED CHECKS 000 y FIRST FAILURE 00. La verificación ejecuta 300 fotogramas y compara texto, formas y colores con lo esperado. Es una prueba en emulador, no en hardware físico.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\asset_banks.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\asset_banks.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Copy one descriptor from its ROM bank into caller storage. Return zero for a
null destination or an out-of-range ID; table validity is the caller's responsibility.

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

Lee del descriptor el banco de los datos del recurso. No es el banco de la tabla, y la función no deja seleccionado el banco del recurso.

Sintaxis

u8 asset_get_bank(u8 asset_id);

Parámetros

asset_id

Índice del recurso, empezando por cero. Debe cumplir asset_id < count en la tabla registrada.

Valor devuelto

El campo bank de 8 bits, o 0 si falla la búsqueda. El banco cero también puede ser válido; use asset_get() para distinguir éxito y valor cero.

Condiciones y límites

Registre la tabla antes de buscar recursos. El registro es un estado global compartido: no lo cambie durante una búsqueda. La biblioteca comprueba los ID y el puntero de salida de asset_get, pero no valida la tabla, las direcciones de los datos ni el contenido del cartucho.

Cada consulta llama de nuevo a asset_get y copia un descriptor. Si necesita banco, puntero y longitud, llame una sola vez a asset_get y lea sus campos.

Los ejemplos sitúan el código llamante en el banco fijo 0 para que cambiar el banco de origen no retire el código en ejecución. Las transferencias son síncronas. No las interrumpa con otra copia que cambie bancos ni suponga que la función garantiza por sí sola la seguridad de todas las interrupciones.

Ejemplo de uso

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.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Se espera el banco 2 de los datos aunque la tabla esté en el banco 3. También se comprueba que un ID inválido devuelve cero.

Imagen esperada: una fila roja empieza en (16,32) y ocupa 72×8 píxeles. Repite tres veces un triángulo de 8×8, un cuadrado de 8×8 con borde de un píxel y un tile con sus cuatro columnas izquierdas rellenas. El triángulo crece desde un píxel arriba a la izquierda hasta ocho en la fila inferior.

En GB, el triángulo y contorno azules de (16,64) muestran __farmemcpy; la pareja verde de (16,96), __far_memcpy. Cada pareja ocupa 16×8 píxeles. CGB usa esos colores; DMG muestra las mismas formas en negro sobre blanco.

El estado esperado es FAILED CHECKS 000 y FIRST FAILURE 00. La verificación ejecuta 300 fotogramas y compara texto, formas y colores con lo esperado. Es una prueba en emulador, no en hardware físico.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\asset_banks.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\asset_banks.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Return the descriptor bank, or zero on lookup failure; zero can also be a valid bank.

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

Lee la longitud del recurso en bytes desde su descriptor. Devuelve metadatos; no examina los datos ni convierte la longitud en cantidad de tiles, elementos o fotogramas.

Sintaxis

u16 asset_get_len(u8 asset_id);

Parámetros

asset_id

Índice del recurso, empezando por cero. Debe cumplir asset_id < count en la tabla registrada.

Valor devuelto

El campo len de 16 bits, en bytes, o 0 si falla la búsqueda. Un recurso vacío también mide cero; use asset_get() para distinguirlos.

Condiciones y límites

Registre la tabla antes de buscar recursos. El registro es un estado global compartido: no lo cambie durante una búsqueda. La biblioteca comprueba los ID y el puntero de salida de asset_get, pero no valida la tabla, las direcciones de los datos ni el contenido del cartucho.

Cada consulta llama de nuevo a asset_get y copia un descriptor. Si necesita banco, puntero y longitud, llame una sola vez a asset_get y lea sus campos.

Los ejemplos sitúan el código llamante en el banco fijo 0 para que cambiar el banco de origen no retire el código en ejecución. Las transferencias son síncronas. No las interrumpa con otra copia que cambie bancos ni suponga que la función garantiza por sí sola la seguridad de todas las interrupciones.

Ejemplo de uso

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.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El recurso de nueve tiles debe indicar 144 bytes, no nueve tiles. Un recurso vacío y un ID inválido deben devolver cero.

Imagen esperada: una fila roja empieza en (16,32) y ocupa 72×8 píxeles. Repite tres veces un triángulo de 8×8, un cuadrado de 8×8 con borde de un píxel y un tile con sus cuatro columnas izquierdas rellenas. El triángulo crece desde un píxel arriba a la izquierda hasta ocho en la fila inferior.

En GB, el triángulo y contorno azules de (16,64) muestran __farmemcpy; la pareja verde de (16,96), __far_memcpy. Cada pareja ocupa 16×8 píxeles. CGB usa esos colores; DMG muestra las mismas formas en negro sobre blanco.

El estado esperado es FAILED CHECKS 000 y FIRST FAILURE 00. La verificación ejecuta 300 fotogramas y compara texto, formas y colores con lo esperado. Es una prueba en emulador, no en hardware físico.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\asset_banks.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\asset_banks.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Return the descriptor byte length, or zero if its ID cannot be resolved.

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

Lee la dirección de 16 bits guardada en el descriptor. El puntero cercano devuelto no incluye el banco. Para leer otro banco de ROM, combínelo con asset_get_bank() y una función de copia entre bancos.

Sintaxis

const u8* asset_get_ptr(u8 asset_id);

Parámetros

asset_id

Índice del recurso, empezando por cero. Debe cumplir asset_id < count en la tabla registrada.

Valor devuelto

El const u8* guardado, o un puntero nulo si falla la búsqueda. El puntero del descriptor no se valida; use asset_get() para identificar un fallo de búsqueda.

Condiciones y límites

Registre la tabla antes de buscar recursos. El registro es un estado global compartido: no lo cambie durante una búsqueda. La biblioteca comprueba los ID y el puntero de salida de asset_get, pero no valida la tabla, las direcciones de los datos ni el contenido del cartucho.

Cada consulta llama de nuevo a asset_get y copia un descriptor. Si necesita banco, puntero y longitud, llame una sola vez a asset_get y lea sus campos.

Los ejemplos sitúan el código llamante en el banco fijo 0 para que cambiar el banco de origen no retire el código en ejecución. Las transferencias son síncronas. No las interrumpa con otra copia que cambie bancos ni suponga que la función garantiza por sí sola la seguridad de todas las interrupciones.

Ejemplo de uso

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.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El puntero debe coincidir con la dirección enlazada del recurso, mientras sigue siendo legible un marcador del banco 1. Después se pasa ese puntero junto con el banco 2 a una copia entre bancos.

Imagen esperada: una fila roja empieza en (16,32) y ocupa 72×8 píxeles. Repite tres veces un triángulo de 8×8, un cuadrado de 8×8 con borde de un píxel y un tile con sus cuatro columnas izquierdas rellenas. El triángulo crece desde un píxel arriba a la izquierda hasta ocho en la fila inferior.

En GB, el triángulo y contorno azules de (16,64) muestran __farmemcpy; la pareja verde de (16,96), __far_memcpy. Cada pareja ocupa 16×8 píxeles. CGB usa esos colores; DMG muestra las mismas formas en negro sobre blanco.

El estado esperado es FAILED CHECKS 000 y FIRST FAILURE 00. La verificación ejecuta 300 fotogramas y compara texto, formas y colores con lo esperado. Es una prueba en emulador, no en hardware físico.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\asset_banks.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\asset_banks.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Return the stored address without switching banks. Use the descriptor bank
with far-data helpers before dereferencing banked assets; failure returns null.

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

Busca el recurso y copia min(desc.len, max_len) bytes desde su banco de ROM a memoria escribible. Ignora el tipo: los gráficos, mapas y canciones se copian como bytes, sin interpretar el formato ni descomprimirlos.

Sintaxis

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

Parámetros

asset_id

Índice del recurso, empezando por cero. Debe cumplir asset_id < count en la tabla registrada.

dst

Destino en memoria escribible, con espacio para todos los bytes copiados. Salvo en una transferencia de cero bytes, no se comprueba si el destino es nulo o inválido.

max_len

Máximo de bytes que se copiarán, de 0 a 65535. Un límite menor trunca la copia; cero no copia ningún byte de los datos.

Valor devuelto

0 si falla la búsqueda; en caso contrario, 1, incluso si la copia se trunca, el límite es cero o el recurso está vacío. No devuelve una cantidad de bytes ni garantiza que haya cabido todo el recurso.

Condiciones y límites

Registre la tabla antes de buscar recursos. El registro es un estado global compartido: no lo cambie durante una búsqueda. La biblioteca comprueba los ID y el puntero de salida de asset_get, pero no valida la tabla, las direcciones de los datos ni el contenido del cartucho.

Mantenga todo el origen en el mapeo de ROM previsto y todo el destino en memoria escribible. La copia no cambia automáticamente de banco al cruzar una ventana, no trata solapamientos como memmove ni sincroniza escrituras en VRAM. Para VRAM, use las API de transferencia gráfica.

Los ejemplos sitúan el código llamante en el banco fijo 0 para que cambiar el banco de origen no retire el código en ejecución. Las transferencias son síncronas. No las interrumpa con otra copia que cambie bancos ni suponga que la función garantiza por sí sola la seguridad de todas las interrupciones.

Ejemplo de uso

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

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Un límite de siete copia solo siete bytes de un recurso de 144, deja el siguiente en 0x55 y aun así devuelve éxito. También se prueban la copia completa, el límite cero, un recurso vacío y la copia de datos MAP.

Imagen esperada: una fila roja empieza en (16,32) y ocupa 72×8 píxeles. Repite tres veces un triángulo de 8×8, un cuadrado de 8×8 con borde de un píxel y un tile con sus cuatro columnas izquierdas rellenas. El triángulo crece desde un píxel arriba a la izquierda hasta ocho en la fila inferior.

En GB, el triángulo y contorno azules de (16,64) muestran __farmemcpy; la pareja verde de (16,96), __far_memcpy. Cada pareja ocupa 16×8 píxeles. CGB usa esos colores; DMG muestra las mismas formas en negro sobre blanco.

El estado esperado es FAILED CHECKS 000 y FIRST FAILURE 00. La verificación ejecuta 300 fotogramas y compara texto, formas y colores con lo esperado. Es una prueba en emulador, no en hardware físico.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\asset_banks.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\asset_banks.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Copy at most max_len bytes using the asset's bank. Success means the ID was
valid, even when the payload was truncated to fit the supplied limit.

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;
    __farmemcpy(dst, desc.bank, desc.ptr, len);
    return 1;
}

Busca un recurso RAW o TILES y transfiere sus desc.len bytes mediante __vram_copy. Seleccione antes el banco de ROM de los datos: esta función de GB usa desc.ptr directamente y no selecciona desc.bank para la transferencia.

Sintaxis

u8 asset_load_tiles(u8 asset_id, u16 vram_dst);

Parámetros

asset_id

Índice del recurso, empezando por cero. Debe cumplir asset_id < count en la tabla registrada.

vram_dst

Dirección de byte en VRAM, entre $8000 y $9FFF, no un número de tile. Para patrones, use una dirección alineada a 16 bytes y una longitud múltiplo de 16; la biblioteca no comprueba estas condiciones.

Valor devuelto

0 si el ID es inválido o el tipo no es RAW/TILES; 1 tras una transferencia aceptada, incluso con longitud cero. El éxito no valida el formato gráfico ni su visualización en VRAM.

Condiciones y límites

Registre la tabla antes de buscar recursos. El registro es un estado global compartido: no lo cambie durante una búsqueda. La biblioteca comprueba los ID y el puntero de salida de asset_get, pero no valida la tabla, las direcciones de los datos ni el contenido del cartucho.

Los ejemplos sitúan el código llamante en el banco fijo 0 para que cambiar el banco de origen no retire el código en ejecución. Las transferencias son síncronas. No las interrumpa con otra copia que cambie bancos ni suponga que la función garantiza por sí sola la seguridad de todas las interrupciones.

La transferencia solo escribe bytes: no coloca tiles en el mapa, asigna colores ni reserva VRAM. Configure el mapa y las paletas por separado. Los ejemplos transfieren con el renderizado desactivado y activan la imagen cuando está lista.

La rutina de GB restaura el banco registrado por el compilador. Manténgalo actualizado con __bankswitch; escribir directamente en el mapper no lo actualiza. La posición de HRAM que guarda el banco de retorno es compartida, por lo que no admite transferencias anidadas que la sobrescriban.

Ejemplo de uso

__bankswitch(payload_bank); // GB tile upload expects the payload bank already visible.
loaded=asset_load_tiles(0,0x8010); // Nine tiles = 144 bytes, LCD off.
expect(loaded==1,24);
__bankswitch(1);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

La carga usa nueve patrones originales de 8×8 píxeles, 144 bytes en total, y comprueba el rechazo de MAP e ID inválidos. En FC, la longitud prueba tanto el bloque de 128 bytes como los 16 restantes.

Imagen esperada: una fila roja empieza en (16,32) y ocupa 72×8 píxeles. Repite tres veces un triángulo de 8×8, un cuadrado de 8×8 con borde de un píxel y un tile con sus cuatro columnas izquierdas rellenas. El triángulo crece desde un píxel arriba a la izquierda hasta ocho en la fila inferior.

En GB, el triángulo y contorno azules de (16,64) muestran __farmemcpy; la pareja verde de (16,96), __far_memcpy. Cada pareja ocupa 16×8 píxeles. CGB usa esos colores; DMG muestra las mismas formas en negro sobre blanco.

El estado esperado es FAILED CHECKS 000 y FIRST FAILURE 00. La verificación ejecuta 300 fotogramas y compara texto, formas y colores con lo esperado. Es una prueba en emulador, no en hardware físico.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\asset_banks.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\asset_banks.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Accept tile/raw descriptors and transfer their bytes to VRAM. This path passes
the descriptor pointer directly; callers must arrange the correct visible ROM bank.

u8 asset_load_tiles(u8 asset_id, u16 vram_dst)
{
    AssetDesc desc;
    if (asset_get(asset_id, &desc) == 0) return 0;
    if (desc.type != ASSET_TYPE_TILES && desc.type != ASSET_TYPE_RAW) return 0;
    __vram_copy(vram_dst, desc.ptr, desc.len);
    return 1;
}

Registra el banco, la dirección y el número de entradas de la única tabla activa. Guarda esos tres valores; no copia la tabla, carga recursos ni reserva memoria.

Sintaxis

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

Parámetros

bank

Banco de ROM de la tabla de descriptores, expresado en 8 bits; no es el banco de los datos.

table

Puntero cercano a count entradas AssetDesc consecutivas. Los count * 6 bytes deben seguir siendo legibles en el banco de la tabla mientras esté registrada.

count

Número de entradas, de 0 a 255. Con cero no hay ningún ID válido; asset_set_table(0, 0, 0) registra una tabla vacía de forma segura.

Valor devuelto

Ninguno (void).

Condiciones y límites

Registre la tabla antes de buscar recursos. El registro es un estado global compartido: no lo cambie durante una búsqueda. La biblioteca comprueba los ID y el puntero de salida de asset_get, pero no valida la tabla, las direcciones de los datos ni el contenido del cartucho.

Ejemplo de uso

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

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo registra cuatro descriptores en el banco 3, con los datos no vacíos en el banco 2. También registra una tabla vacía y comprueba que la búsqueda falla sin leer la dirección cero.

Imagen esperada: una fila roja empieza en (16,32) y ocupa 72×8 píxeles. Repite tres veces un triángulo de 8×8, un cuadrado de 8×8 con borde de un píxel y un tile con sus cuatro columnas izquierdas rellenas. El triángulo crece desde un píxel arriba a la izquierda hasta ocho en la fila inferior.

En GB, el triángulo y contorno azules de (16,64) muestran __farmemcpy; la pareja verde de (16,96), __far_memcpy. Cada pareja ocupa 16×8 píxeles. CGB usa esos colores; DMG muestra las mismas formas en negro sobre blanco.

El estado esperado es FAILED CHECKS 000 y FIRST FAILURE 00. La verificación ejecuta 300 fotogramas y compara texto, formas y colores con lo esperado. Es una prueba en emulador, no en hardware físico.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\asset_banks.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\asset_banks.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Retain the descriptor table address, bank and count; the table is not copied.

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

Detiene los pasos siguientes del fundido conservando niveles y registros actuales.

Sintaxis

void Audio_CancelMasterVolumeFade();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Ejemplo de uso

// A sustained pulse moves left, right and center, then fades to a quieter level.
#include "gb_sound_example.h"
void main() {
    sound_begin("PAN AND VOLUME");
    Audio_SetMasterVolume(7,7);
    Audio_Ch1NoteOn(33,0xC0,2);
    Audio_SetPan(AUDIO_CHANNEL_CH1,AUDIO_PAN_LEFT);
    sound_result[0]=NR51;
    sound_wait(30);
    // Packed low two bits are CH1: 2 means right. Other channels remain centered.
    Audio_SetPanPacked(2);
    sound_result[1]=NR51;
    sound_wait(30);
    Audio_SetPanPacked(0);
    sound_result[2]=NR51;
    Audio_FadeToMasterVolume(1,1,5);
    sound_wait(30);
    sound_result[3]=NR50;
    sound_result[4]=Audio_FadeActive;
    sound_wait(30);
    // Cancel halfway through a rise: retain volume 4 instead of reaching 7.
    Audio_FadeToMasterVolume(7,7,5);
    sound_wait(15);
    Audio_CancelMasterVolumeFade();
    sound_result[5]=NR50;
    sound_wait(30);
    sound_result[6]=NR50;
    // A zero fade interval sets the target immediately. Level zero is not mute.
    Audio_FadeToMasterVolume(0,0,0);
    sound_result[7]=NR50;
    sound_wait(30);
    Audio_StopChannel(AUDIO_CHANNEL_CH1);
    sound_wait(15);
    sound_end();
}

Resultado esperado

A4 pasa a izquierda, derecha y centro. En el centro baja del nivel 7 al 1, sube al 4 y permanece ahí. El nivel 0 aún se oye débilmente; detener el canal produce silencio. Cambiar el enrutamiento puede dejar un transitorio de filtro que se desvanece.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_mix.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-mix.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Cancel further volume steps, retaining the current cached levels and hardware output.

void Audio_CancelMasterVolumeFade() {
    Audio_FadeTargetLeft = Audio_MasterLeft;
    Audio_FadeTargetRight = Audio_MasterRight;
    Audio_FadeStepFrames = 0;
    Audio_FadeCounter = 0;
    Audio_FadeActive = 0;
}

Configura barrido, ciclo de trabajo, envolvente y altura de CH1, y dispara el pulso.

Sintaxis

void __stackcall Audio_Ch1NoteOn(u8 note, u8 vol_env, u8 duty2);

Parámetros

note

Índice de tabla de alturas de 0 a 67. Consulta las notas sobre la reutilización de frecuencias y la diferencia de octava de CH3.

vol_env

Codificación NR12/NR22/NR42: nibble alto para volumen inicial, bit 3 para envolvente creciente y tres bits bajos para su período. 0xC0 mantiene el volumen en 12.

duty2

Ciclo de trabajo: 0=12,5 %, 1=25 %, 3=75 %; los demás valores seleccionan 50 %.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

note indexa una tabla de alturas de 0 a 67: 0 es C2 y 33 es A4. Los valores superiores a 67 se limitan a 67; 60..67 usan las frecuencias de 48..55. Con el mismo índice, CH3 suena una octava por debajo de un canal de pulsos. Las funciones de inicio de nota disparan el hardware directamente sin comprobar activación ni pausa.

Ejemplo de uso

// Four isolated voices, each lasting 30 frames, separated by 15 silent frames.
#include "gb_sound_example.h"
void main() {
    sound_begin("FOUR SOUND CHANNELS");
    Audio_SetMasterVolume(3,3);
    // CH1: A4, 50% duty, fixed envelope volume 12.
    Audio_SetCh1Duty(2);
    sound_result[0]=Audio_Ch1Duty;
    Audio_Ch1NoteOn(33,0xC0,Audio_Ch1Duty);
    sound_result[1]=NR12;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH1); sound_wait(15);
    // CH2: A4, 25% duty. Changing the cached duty takes effect on this trigger.
    Audio_SetCh2Duty(1);
    sound_result[2]=Audio_Ch2Duty;
    Audio_Ch2NoteOn(33,0xC0,Audio_Ch2Duty);
    sound_result[3]=NR22;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH2); sound_wait(15);
    // CH3: the initialized triangle wave, at 50% digital output level.
    Audio_SetCh3Level(AUDIO_CH3_LEVEL_50);
    sound_result[4]=Audio_Ch3Level;
    Audio_Ch3NoteOn(33,Audio_Ch3Level);
    sound_result[5]=NR32;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // CH4: a sustained noise burst; param is NR43, not a pitched note number.
    Audio_SetCh4Param(0x35);
    sound_result[6]=Audio_Ch4Param;
    Audio_Ch4NoteOn(Audio_Ch4Param,0xC0);
    sound_result[7]=NR43;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH4); sound_wait(15);
    sound_end();
}

Resultado esperado

Tras aproximadamente medio segundo de silencio, se oyen CH1 A4, CH2 A4, CH3 A3 y ruido. Cada voz dura 30 fotogramas, con pausas de 15. SEQUENCE COMPLETE indica el final del programa; usa la grabación para valorar el sonido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_channels.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-channels.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Trigger CH1 with the cached sweep and the supplied raw envelope. Clamp the
note index; duty values 0, 1 and 3 select their encodings, and all others use 2.

void __stackcall Audio_Ch1NoteOn(u8 note, u8 vol_env, u8 duty2) {
    u16 freq;
    u8 duty_reg;
    u8 hi;

    if (note > AUDIO_NOTE_MAX) note = AUDIO_NOTE_MAX;
    freq = GB_FREQ_TABLE[note];

    duty_reg = 128;
    if (duty2 == 0) duty_reg = 0;
    else if (duty2 == 1) duty_reg = 64;
    else if (duty2 == 3) duty_reg = 192;

    NR10 = Audio_Ch1Sweep;
    NR11 = duty_reg;
    NR12 = vol_env;
    NR13 = (u8)(freq & 0xFF);
    hi = (u8)((u16)freq >> 8);
    NR14 = (u8)(hi | 0x80);
}

Configura ciclo de trabajo, envolvente y altura de CH2, y dispara el pulso.

Sintaxis

void __stackcall Audio_Ch2NoteOn(u8 note, u8 vol_env, u8 duty2);

Parámetros

note

Índice de tabla de alturas de 0 a 67. Consulta las notas sobre la reutilización de frecuencias y la diferencia de octava de CH3.

vol_env

Codificación NR12/NR22/NR42: nibble alto para volumen inicial, bit 3 para envolvente creciente y tres bits bajos para su período. 0xC0 mantiene el volumen en 12.

duty2

Ciclo de trabajo: 0=12,5 %, 1=25 %, 3=75 %; los demás valores seleccionan 50 %.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

note indexa una tabla de alturas de 0 a 67: 0 es C2 y 33 es A4. Los valores superiores a 67 se limitan a 67; 60..67 usan las frecuencias de 48..55. Con el mismo índice, CH3 suena una octava por debajo de un canal de pulsos. Las funciones de inicio de nota disparan el hardware directamente sin comprobar activación ni pausa.

Ejemplo de uso

// Four isolated voices, each lasting 30 frames, separated by 15 silent frames.
#include "gb_sound_example.h"
void main() {
    sound_begin("FOUR SOUND CHANNELS");
    Audio_SetMasterVolume(3,3);
    // CH1: A4, 50% duty, fixed envelope volume 12.
    Audio_SetCh1Duty(2);
    sound_result[0]=Audio_Ch1Duty;
    Audio_Ch1NoteOn(33,0xC0,Audio_Ch1Duty);
    sound_result[1]=NR12;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH1); sound_wait(15);
    // CH2: A4, 25% duty. Changing the cached duty takes effect on this trigger.
    Audio_SetCh2Duty(1);
    sound_result[2]=Audio_Ch2Duty;
    Audio_Ch2NoteOn(33,0xC0,Audio_Ch2Duty);
    sound_result[3]=NR22;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH2); sound_wait(15);
    // CH3: the initialized triangle wave, at 50% digital output level.
    Audio_SetCh3Level(AUDIO_CH3_LEVEL_50);
    sound_result[4]=Audio_Ch3Level;
    Audio_Ch3NoteOn(33,Audio_Ch3Level);
    sound_result[5]=NR32;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // CH4: a sustained noise burst; param is NR43, not a pitched note number.
    Audio_SetCh4Param(0x35);
    sound_result[6]=Audio_Ch4Param;
    Audio_Ch4NoteOn(Audio_Ch4Param,0xC0);
    sound_result[7]=NR43;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH4); sound_wait(15);
    sound_end();
}

Resultado esperado

Tras aproximadamente medio segundo de silencio, se oyen CH1 A4, CH2 A4, CH3 A3 y ruido. Cada voz dura 30 fotogramas, con pausas de 15. SEQUENCE COMPLETE indica el final del programa; usa la grabación para valorar el sonido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_channels.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-channels.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Trigger CH2 with the supplied raw envelope and a clamped note index. Duty
values 0, 1 and 3 select their encodings; all other values use duty 2.

void __stackcall Audio_Ch2NoteOn(u8 note, u8 vol_env, u8 duty2) {
    u16 freq;
    u8 duty_reg;
    u8 hi;

    if (note > AUDIO_NOTE_MAX) note = AUDIO_NOTE_MAX;
    freq = GB_FREQ_TABLE[note];

    duty_reg = 128;
    if (duty2 == 0) duty_reg = 0;
    else if (duty2 == 1) duty_reg = 64;
    else if (duty2 == 3) duty_reg = 192;

    NR21 = duty_reg;
    NR22 = vol_env;
    NR23 = (u8)(freq & 0xFF);
    hi = (u8)((u16)freq >> 8);
    NR24 = (u8)(hi | 0x80);
}

Dispara la onda CH3 cargada con la altura y el nivel NR32 solicitados.

Sintaxis

void __stackcall Audio_Ch3NoteOn(u8 note, u8 level);

Parámetros

note

Índice de tabla de alturas de 0 a 67. Consulta las notas sobre la reutilización de frecuencias y la diferencia de octava de CH3.

level

Codificación NR32: 0x00=silencio, 0x20=100 %, 0x40=50 %, 0x60=25 %.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

note indexa una tabla de alturas de 0 a 67: 0 es C2 y 33 es A4. Los valores superiores a 67 se limitan a 67; 60..67 usan las frecuencias de 48..55. Con el mismo índice, CH3 suena una octava por debajo de un canal de pulsos. Las funciones de inicio de nota disparan el hardware directamente sin comprobar activación ni pausa.

Ejemplo de uso

// Four isolated voices, each lasting 30 frames, separated by 15 silent frames.
#include "gb_sound_example.h"
void main() {
    sound_begin("FOUR SOUND CHANNELS");
    Audio_SetMasterVolume(3,3);
    // CH1: A4, 50% duty, fixed envelope volume 12.
    Audio_SetCh1Duty(2);
    sound_result[0]=Audio_Ch1Duty;
    Audio_Ch1NoteOn(33,0xC0,Audio_Ch1Duty);
    sound_result[1]=NR12;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH1); sound_wait(15);
    // CH2: A4, 25% duty. Changing the cached duty takes effect on this trigger.
    Audio_SetCh2Duty(1);
    sound_result[2]=Audio_Ch2Duty;
    Audio_Ch2NoteOn(33,0xC0,Audio_Ch2Duty);
    sound_result[3]=NR22;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH2); sound_wait(15);
    // CH3: the initialized triangle wave, at 50% digital output level.
    Audio_SetCh3Level(AUDIO_CH3_LEVEL_50);
    sound_result[4]=Audio_Ch3Level;
    Audio_Ch3NoteOn(33,Audio_Ch3Level);
    sound_result[5]=NR32;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // CH4: a sustained noise burst; param is NR43, not a pitched note number.
    Audio_SetCh4Param(0x35);
    sound_result[6]=Audio_Ch4Param;
    Audio_Ch4NoteOn(Audio_Ch4Param,0xC0);
    sound_result[7]=NR43;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH4); sound_wait(15);
    sound_end();
}

Resultado esperado

Tras aproximadamente medio segundo de silencio, se oyen CH1 A4, CH2 A4, CH3 A3 y ruido. Cada voz dura 30 fotogramas, con pausas de 15. SEQUENCE COMPLETE indica el final del programa; usa la grabación para valorar el sonido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_channels.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-channels.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Clamp the note index, program the raw NR32 output level, and trigger CH3.
Wave RAM must already contain the desired waveform; this does not load one.

void __stackcall Audio_Ch3NoteOn(u8 note, u8 level) {
    u16 freq;
    u8 hi;

    if (note > AUDIO_NOTE_MAX) note = AUDIO_NOTE_MAX;
    freq = GB_FREQ_TABLE[note];

    NR30 = 128;
    NR31 = 0;
    NR32 = level;
    NR33 = (u8)(freq & 255);
    hi = (u8)((u16)freq >> 8);
    NR34 = (u8)(hi | 128);
}

Guarda los parámetros de ruido, configura los registros de envolvente y contador polinómico, y dispara CH4.

Sintaxis

void __stackcall Audio_Ch4NoteOn(u8 param, u8 vol_env);

Parámetros

param

NR43 bruto: bits 7..4 para desplazamiento del reloj, bit 3 para LFSR corto y bits 2..0 para código divisor.

vol_env

Codificación NR12/NR22/NR42: nibble alto para volumen inicial, bit 3 para envolvente creciente y tres bits bajos para su período. 0xC0 mantiene el volumen en 12.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

No se habilita la parada automática por longitud. Termina el sonido mediante la envolvente o una parada explícita.

Ejemplo de uso

// Four isolated voices, each lasting 30 frames, separated by 15 silent frames.
#include "gb_sound_example.h"
void main() {
    sound_begin("FOUR SOUND CHANNELS");
    Audio_SetMasterVolume(3,3);
    // CH1: A4, 50% duty, fixed envelope volume 12.
    Audio_SetCh1Duty(2);
    sound_result[0]=Audio_Ch1Duty;
    Audio_Ch1NoteOn(33,0xC0,Audio_Ch1Duty);
    sound_result[1]=NR12;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH1); sound_wait(15);
    // CH2: A4, 25% duty. Changing the cached duty takes effect on this trigger.
    Audio_SetCh2Duty(1);
    sound_result[2]=Audio_Ch2Duty;
    Audio_Ch2NoteOn(33,0xC0,Audio_Ch2Duty);
    sound_result[3]=NR22;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH2); sound_wait(15);
    // CH3: the initialized triangle wave, at 50% digital output level.
    Audio_SetCh3Level(AUDIO_CH3_LEVEL_50);
    sound_result[4]=Audio_Ch3Level;
    Audio_Ch3NoteOn(33,Audio_Ch3Level);
    sound_result[5]=NR32;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // CH4: a sustained noise burst; param is NR43, not a pitched note number.
    Audio_SetCh4Param(0x35);
    sound_result[6]=Audio_Ch4Param;
    Audio_Ch4NoteOn(Audio_Ch4Param,0xC0);
    sound_result[7]=NR43;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH4); sound_wait(15);
    sound_end();
}

Resultado esperado

Tras aproximadamente medio segundo de silencio, se oyen CH1 A4, CH2 A4, CH3 A3 y ruido. Cada voz dura 30 fotogramas, con pausas de 15. SEQUENCE COMPLETE indica el final del programa; usa la grabación para valorar el sonido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_channels.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-channels.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Cache the supplied noise parameter, program the raw envelope and polynomial
registers, then trigger CH4 with the length-enable bit clear.

void __stackcall Audio_Ch4NoteOn(u8 param, u8 vol_env) {
    Audio_SetCh4Param(param);
    NR41 = 0x20;
    NR42 = vol_env;
    NR43 = Audio_Ch4Param;
    NR44 = 0x80;
}

Mueve cada nivel de salida un paso hacia el objetivo al intervalo solicitado.

Sintaxis

void __stackcall Audio_FadeToMasterVolume(u8 left, u8 right, u8 step_frames);

Parámetros

left

Nivel maestro izquierdo, de 0 a 7; los valores mayores se limitan a 7. Cero no es silencio total.

right

Nivel maestro derecho, de 0 a 7; los valores mayores se limitan a 7.

step_frames

Número de llamadas Audio_Update por cambio de un nivel. Cero aplica el objetivo inmediatamente.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Incluye audio_hwregs_gb.c antes de audio.c y llama a Audio_Init al arrancar. Llama a Audio_Update exactamente una vez por fotograma, unos 59,7 Hz. Las lecturas del flujo cambian temporalmente el mapeo ROM; no vuelvas a entrar en este controlador desde una interrupción.

Ejemplo de uso

// A sustained pulse moves left, right and center, then fades to a quieter level.
#include "gb_sound_example.h"
void main() {
    sound_begin("PAN AND VOLUME");
    Audio_SetMasterVolume(7,7);
    Audio_Ch1NoteOn(33,0xC0,2);
    Audio_SetPan(AUDIO_CHANNEL_CH1,AUDIO_PAN_LEFT);
    sound_result[0]=NR51;
    sound_wait(30);
    // Packed low two bits are CH1: 2 means right. Other channels remain centered.
    Audio_SetPanPacked(2);
    sound_result[1]=NR51;
    sound_wait(30);
    Audio_SetPanPacked(0);
    sound_result[2]=NR51;
    Audio_FadeToMasterVolume(1,1,5);
    sound_wait(30);
    sound_result[3]=NR50;
    sound_result[4]=Audio_FadeActive;
    sound_wait(30);
    // Cancel halfway through a rise: retain volume 4 instead of reaching 7.
    Audio_FadeToMasterVolume(7,7,5);
    sound_wait(15);
    Audio_CancelMasterVolumeFade();
    sound_result[5]=NR50;
    sound_wait(30);
    sound_result[6]=NR50;
    // A zero fade interval sets the target immediately. Level zero is not mute.
    Audio_FadeToMasterVolume(0,0,0);
    sound_result[7]=NR50;
    sound_wait(30);
    Audio_StopChannel(AUDIO_CHANNEL_CH1);
    sound_wait(15);
    sound_end();
}

Resultado esperado

A4 pasa a izquierda, derecha y centro. En el centro baja del nivel 7 al 1, sube al 4 y permanece ahí. El nivel 0 aún se oye débilmente; detener el canal produce silencio. Cambiar el enrutamiento puede dejar un transitorio de filtro que se desvanece.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_mix.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-mix.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Move left/right volume toward clamped targets at the requested Audio_Update
call interval. An interval of zero applies the levels immediately.

void __stackcall Audio_FadeToMasterVolume(u8 left, u8 right, u8 step_frames) {
    Audio_FadeTargetLeft = Audio_ClampVolume(left);
    Audio_FadeTargetRight = Audio_ClampVolume(right);

    if (step_frames == 0) {
        Audio_SetMasterVolume(Audio_FadeTargetLeft, Audio_FadeTargetRight);
        return;
    }

    Audio_FadeStepFrames = step_frames;
    Audio_FadeCounter = step_frames;
    if (Audio_MasterLeft == Audio_FadeTargetLeft && Audio_MasterRight == Audio_FadeTargetRight) {
        Audio_FadeActive = 0;
        Audio_FadeCounter = 0;
    } else {
        Audio_FadeActive = 1;
    }
}

Activa la APU, inicializa música, efectos, pausa, mezcla y onda, y deja todos los canales en silencio.

Sintaxis

void Audio_Init();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Incluye audio_hwregs_gb.c antes de audio.c y llama a Audio_Init al arrancar. Llama a Audio_Update exactamente una vez por fotograma, unos 59,7 Hz. Las lecturas del flujo cambian temporalmente el mapeo ROM; no vuelvas a entrar en este controlador desde una interrupción.

Ejemplo de uso

// Four isolated voices, each lasting 30 frames, separated by 15 silent frames.
#include "gb_sound_example.h"
void main() {
    sound_begin("FOUR SOUND CHANNELS");
    Audio_SetMasterVolume(3,3);
    // CH1: A4, 50% duty, fixed envelope volume 12.
    Audio_SetCh1Duty(2);
    sound_result[0]=Audio_Ch1Duty;
    Audio_Ch1NoteOn(33,0xC0,Audio_Ch1Duty);
    sound_result[1]=NR12;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH1); sound_wait(15);
    // CH2: A4, 25% duty. Changing the cached duty takes effect on this trigger.
    Audio_SetCh2Duty(1);
    sound_result[2]=Audio_Ch2Duty;
    Audio_Ch2NoteOn(33,0xC0,Audio_Ch2Duty);
    sound_result[3]=NR22;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH2); sound_wait(15);
    // CH3: the initialized triangle wave, at 50% digital output level.
    Audio_SetCh3Level(AUDIO_CH3_LEVEL_50);
    sound_result[4]=Audio_Ch3Level;
    Audio_Ch3NoteOn(33,Audio_Ch3Level);
    sound_result[5]=NR32;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // CH4: a sustained noise burst; param is NR43, not a pitched note number.
    Audio_SetCh4Param(0x35);
    sound_result[6]=Audio_Ch4Param;
    Audio_Ch4NoteOn(Audio_Ch4Param,0xC0);
    sound_result[7]=NR43;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH4); sound_wait(15);
    sound_end();
}

Resultado esperado

Tras aproximadamente medio segundo de silencio, se oyen CH1 A4, CH2 A4, CH3 A3 y ruido. Cada voz dura 30 fotogramas, con pausas de 15. SEQUENCE COMPLETE indica el final del programa; usa la grabación para valorar el sonido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_channels.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-channels.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Enable the APU and reset software streams, instruments, mix and fade state.
Load the initial triangle wave, then leave every channel silent. Call at startup
before concurrent interrupt-driven audio service can access these shared fields.

void Audio_Init() {
    NR52 = 0x80;
    NR51 = 0xFF;
    Audio_Pan = 0xFF;
    Audio_EffectPan = AUDIO_PAN_INHERIT;
    Audio_EffectPan3 = AUDIO_PAN_INHERIT;
    Audio_UpdateNR51();

    Audio_SetMasterVolume(AUDIO_VOLUME_MAX, AUDIO_VOLUME_MAX);
    Audio_SilenceAll();

    Audio_PlayingMusic = 0;
    Audio_Paused = 0;
    Audio_MusicEnabled = 1;
    Audio_SfxEnabled = 1;
    Audio_Delay = 0;
    Audio_MusicBank = 0;
    Audio_MusicPointer = 0;
    Audio_MusicLoopPoint = 0;

    Audio_EffectPointer = 0;
    Audio_EffectPriority = 0;
    Audio_EffectBank = 0;
    Audio_EffectPointer3 = 0;
    Audio_EffectPriority3 = 0;
    Audio_EffectBank3 = 0;
    Audio_EffectUsesCh2 = 0;
    Audio_EffectPan = AUDIO_PAN_INHERIT;
    Audio_EffectPan3 = AUDIO_PAN_INHERIT;

    Audio_LastChMask = 0;
    Audio_LastCh1Note = 0;
    Audio_LastCh2Note = 0;
    Audio_LastCh3Note = 0;
    Audio_LastCh4Param = 0;

    Audio_Ch1Duty = 2;
    Audio_Ch2Duty = 2;
    Audio_Ch1Env = 0xF1;
    Audio_Ch2Env = 0xF2;
    Audio_Ch4Env = 0xF1;
    Audio_Ch4Param = 0x00;
    Audio_Ch3Level = AUDIO_CH3_LEVEL_100;
    Audio_Ch3Wave = AUDIO_WAVE_TRIANGLE;
    Audio_Ch1Sweep = 0x00;

    Audio_SetCustomWaveTriangle();
#ifdef AUDIO_EXCLUDE_WAVE_LOAD_API
    Audio_ApplyWaveBytes(Audio_CustomWave);
#else
    Audio_LoadWave(Audio_Ch3Wave);
#endif
    Audio_Ch3Off();
}

Copia dieciséis bytes a la caché de onda personalizada y a la RAM de onda CH3.

Sintaxis

void __stackcall Audio_LoadCustomWave(const u8 *wave16);

Parámetros

wave16

Dieciséis bytes legibles; los nibbles alto y bajo codifican muestras sucesivas. Ignora NULL.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

El código que llama puede reutilizar el origen tras copiarlo. La función deshabilita el DAC para escribir; quien llama debe volver a disparar la nota.

Ejemplo de uso

// Compare a triangle preset with an original packed 32-sample pulse waveform.
#include "gb_sound_example.h"
__prg_rom u8 custom_wave[16]={0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0,0,0,0,0,0,0,0};
void main() {
    sound_begin("WAVE PRESET CUSTOM");
    Audio_SetMasterVolume(3,3);
    Audio_LoadWave(AUDIO_WAVE_TRIANGLE);
    Audio_Ch3NoteOn(33,AUDIO_CH3_LEVEL_100);
    sound_wait(45); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // Loading copies all sixteen bytes and enables the DAC without triggering a note.
    Audio_LoadCustomWave(custom_wave);
    sound_result[0]=Audio_CustomWave[0]; sound_result[1]=Audio_CustomWave[8];
    Audio_Ch3NoteOn(33,AUDIO_CH3_LEVEL_100);
    sound_wait(45); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // The cache survives another preset load; select CUSTOM to reuse it.
    Audio_LoadWave(AUDIO_WAVE_SAW);
    Audio_LoadWave(AUDIO_WAVE_CUSTOM);
    sound_result[2]=WAVE0; sound_result[3]=WAVE8;
    Audio_Ch3NoteOn(33,AUDIO_CH3_LEVEL_100);
    sound_wait(45); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    sound_end();
}

Resultado esperado

Se oyen el preajuste triangular, una onda de pulsos original y esa misma onda recargada desde la caché. Cada una dura 45 fotogramas con pausas de 15. Las tres están en unos 220 Hz; solo la primera tiene otro timbre.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_wave.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-wave.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Copy 16 packed sample bytes into the persistent custom cache and wave RAM.
A null pointer is ignored; the source is needed only for this call.

void __stackcall Audio_LoadCustomWave(const u8 *wave16) {
    if (wave16 == 0) return;

    Audio_CustomWave[0] = wave16[0];   Audio_CustomWave[1] = wave16[1];
    Audio_CustomWave[2] = wave16[2];   Audio_CustomWave[3] = wave16[3];
    Audio_CustomWave[4] = wave16[4];   Audio_CustomWave[5] = wave16[5];
    Audio_CustomWave[6] = wave16[6];   Audio_CustomWave[7] = wave16[7];
    Audio_CustomWave[8] = wave16[8];   Audio_CustomWave[9] = wave16[9];
    Audio_CustomWave[10] = wave16[10]; Audio_CustomWave[11] = wave16[11];
    Audio_CustomWave[12] = wave16[12]; Audio_CustomWave[13] = wave16[13];
    Audio_CustomWave[14] = wave16[14]; Audio_CustomWave[15] = wave16[15];

    Audio_ApplyWaveBytes(Audio_CustomWave);
}

Instala una onda predefinida o personalizada en caché en la RAM de onda CH3.

Sintaxis

void __stackcall Audio_LoadWave(u8 wave_id);

Parámetros

wave_id

ID AUDIO_WAVE_* de 0 a 7; 7 selecciona la onda personalizada en caché. Los valores mayores que 7 no hacen nada.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Cargar no inicia una nota ni cambia Audio_Ch3Wave. El preajuste triangular también reinicia la caché personalizada como triángulo. Llama a Audio_Ch3NoteOn para hacer sonar la voz.

Ejemplo de uso

// Compare a triangle preset with an original packed 32-sample pulse waveform.
#include "gb_sound_example.h"
__prg_rom u8 custom_wave[16]={0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0,0,0,0,0,0,0,0};
void main() {
    sound_begin("WAVE PRESET CUSTOM");
    Audio_SetMasterVolume(3,3);
    Audio_LoadWave(AUDIO_WAVE_TRIANGLE);
    Audio_Ch3NoteOn(33,AUDIO_CH3_LEVEL_100);
    sound_wait(45); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // Loading copies all sixteen bytes and enables the DAC without triggering a note.
    Audio_LoadCustomWave(custom_wave);
    sound_result[0]=Audio_CustomWave[0]; sound_result[1]=Audio_CustomWave[8];
    Audio_Ch3NoteOn(33,AUDIO_CH3_LEVEL_100);
    sound_wait(45); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // The cache survives another preset load; select CUSTOM to reuse it.
    Audio_LoadWave(AUDIO_WAVE_SAW);
    Audio_LoadWave(AUDIO_WAVE_CUSTOM);
    sound_result[2]=WAVE0; sound_result[3]=WAVE8;
    Audio_Ch3NoteOn(33,AUDIO_CH3_LEVEL_100);
    sound_wait(45); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    sound_end();
}

Resultado esperado

Se oyen el preajuste triangular, una onda de pulsos original y esa misma onda recargada desde la caché. Cada una dura 45 fotogramas con pausas de 15. Las tres están en unos 220 Hz; solo la primera tiene otro timbre.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_wave.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-wave.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Install a named preset or the cached custom wave. Unknown IDs are ignored.
This does not update Audio_Ch3Wave or trigger a new note.

void __stackcall Audio_LoadWave(u8 wave_id) {
    if (wave_id == AUDIO_WAVE_TRIANGLE) Audio_LoadWave0();
    else if (wave_id == AUDIO_WAVE_SAW) Audio_LoadWave1();
    else if (wave_id == AUDIO_WAVE_VOWEL_A) Audio_LoadWave2();
    else if (wave_id == AUDIO_WAVE_VOWEL_I) Audio_LoadWave3();
    else if (wave_id == AUDIO_WAVE_VOWEL_U) Audio_LoadWave4();
    else if (wave_id == AUDIO_WAVE_VOWEL_E) Audio_LoadWave5();
    else if (wave_id == AUDIO_WAVE_VOWEL_O) Audio_LoadWave6();
    else if (wave_id == AUDIO_WAVE_CUSTOM) Audio_ApplyWaveBytes(Audio_CustomWave);
}

Prepara la canción del banco indicado desde el principio y reinicia instrumentos, panorama y delay.

Sintaxis

void __stackcall Audio_PlayMusic(u8 bank, u8 *song);

Parámetros

bank

Banco ROM que contiene el flujo; debe coincidir con su ubicación.

song

Dirección inicial de la canción. El controlador usa el array prestado, que debe seguir siendo legible durante toda la reproducción.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Incluye audio_hwregs_gb.c antes de audio.c y llama a Audio_Init al arrancar. Llama a Audio_Update exactamente una vez por fotograma, unos 59,7 Hz. Las lecturas del flujo cambian temporalmente el mapeo ROM; no vuelvas a entrar en este controlador desde una interrupción.

El siguiente Audio_Update lee los datos. No se comprueba NULL. Los efectos existentes siguen activos.

Ejemplo de uso

// Original two-note phrase: pause preserves the cursor; the enable gate does not.
#include "gb_sound_example.h"
__prg_rom u8 song[]={
    AUDIO_CMD_SET_INST,AUDIO_STREAM_CHANNEL_CH1,2,0xC0,
    AUDIO_CMD_NOTE,AUDIO_STREAM_CHANNEL_CH1,33,AUDIO_CMD_WAIT,59,
    AUDIO_CMD_NOTE,AUDIO_STREAM_CHANNEL_CH1,40,AUDIO_CMD_WAIT,59,
    AUDIO_CMD_LOOP
};
void main() {
    u8 delay;
    sound_begin("MUSIC PAUSE GATE");
    Audio_SetMasterVolume(3,3);
    Audio_PlayMusic(0,song);
    sound_wait(30);
    delay=Audio_Delay;
    Audio_SetPaused(1);
    sound_wait(30);
    sound_result[0]=(u8)(Audio_Delay==delay);
    sound_result[1]=Audio_Paused;
    Audio_SetPaused(0);
    sound_wait(30);
    sound_result[2]=Audio_Paused;
    // Disabling suppresses note writes; the next 30 updates still consume data.
    Audio_SetMusicEnabled(0);
    sound_wait(30);
    sound_result[3]=Audio_Delay;
    sound_result[4]=Audio_MusicEnabled;
    // Explicitly stop the sounding channel while leaving the stream running.
    Audio_StopChannel(AUDIO_CHANNEL_CH1);
    sound_wait(30);
    Audio_SetMusicEnabled(1);
    sound_wait(30);
    Audio_StopMusic();
    sound_result[5]=Audio_PlayingMusic;
    sound_wait(30);
    sound_end();
}

Resultado esperado

Se oyen una nota, silencio en pausa, reanudación, una nota retenida al deshabilitar la música, silencio explícito del canal, la siguiente nota tras habilitar y, al final, parada. La RAM también verifica que 30 actualizaciones en pausa conservan delay, mientras que deshabilitar la música deja que avance hasta 30.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_music.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-music.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Retain the bank and song pointer, reset legacy instruments/cursors, and arm
playback from the beginning. Supply a valid, persistent song; no bytes are copied
and null is not checked. Existing effect streams remain active.

void __stackcall Audio_PlayMusic(u8 bank, u8 *song) {
    Audio_PlayingMusic = 0;
    Audio_MusicBank = bank;
    Audio_MusicPointer = song;
    Audio_MusicLoopPoint = song;
    Audio_Delay = 0;
    Audio_LastChMask = 0;

    Audio_Ch1Duty = 2;
    Audio_Ch2Duty = 2;
    Audio_Ch1Env = 0xF1;
    Audio_Ch2Env = 0xF2;
    Audio_Ch4Env = 0xF1;
    Audio_Ch4Param = 0x00;
    Audio_Ch3Level = AUDIO_CH3_LEVEL_100;
    Audio_Ch3Wave = AUDIO_WAVE_TRIANGLE;
    Audio_Ch1Sweep = 0x00;
    Audio_Pan = 0xFF;
    Audio_UpdateNR51();
    Audio_LoadWave(Audio_Ch3Wave);

    Audio_PlayingMusic = 1;
}

Captura el banco ROM actual y solicita un efecto que hereda el panorama base.

Sintaxis

void __stackcall Audio_PlaySFX(u8 *sfx, u8 priority);

Parámetros

sfx

Inicio del flujo de bytes del efecto. Consulta las notas para los formatos de pulsos y CH3.

priority

Prioridad de 0 a 255. Gana el valor mayor; uno igual también puede sustituir al efecto actual.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Un efecto consume un par (note,value) por actualización y termina en note=0. value es NR12 para efectos de pulsos y NR32 para CH3. Antepon 0xFF a los datos CH3 y conserva la memoria hasta que termine. Las prioridades compiten dentro de una ranura; una prioridad igual también puede sustituir al efecto actual.

En la configuración normal, liberar un efecto apaga CH3. Silencia CH1 si la música está detenida, pero no vuelve a tocar automáticamente una nota anterior mientras la música sigue activa. Con AUDIO_VBLANK_SFX_RESTORE, la liberación solicita la recuperación a la ISR.

Ejemplo de uso

// Each pair lasts one update. Priority controls replacement within each slot.
#include "gb_sound_example.h"
#pragma bank 2
__prg_rom u8 effect[]={33,0xC0,33,0xC0,33,0xC0,33,0xC0,33,0xC0,33,0xC0,
    40,0xC0,40,0xC0,40,0xC0,40,0xC0,40,0xC0,40,0xC0,0};
__prg_rom u8 wave_effect[]={AUDIO_SFX_CH3_MARKER,
    33,0x20,33,0x20,33,0x20,33,0x20,33,0x20,33,0x20,
    40,0x20,40,0x20,40,0x20,40,0x20,40,0x20,40,0x20,0};
#pragma bank 0
void main() {
    sound_begin("BANKED SOUND EFFECT");
    Audio_SetMasterVolume(3,3);
    // Read the marker in bank 2 while restoring the caller's original mapping.
    Audio_PlaySFXPannedBanked(2,effect,5,AUDIO_PAN_LEFT);
    sound_result[0]=Audio_EffectPriority;
    Audio_PlaySFXBanked(2,effect,4);
    sound_result[1]=Audio_EffectPriority;
    sound_wait(30);
    Audio_PlaySFXPannedBanked(2,wave_effect,5,AUDIO_PAN_RIGHT);
    sound_result[2]=Audio_EffectPriority3;
    sound_wait(30);
    // Implicit-bank entry points capture bank 2; the service restores bank 1.
    __bankswitch(2);
    Audio_PlaySFX(effect,5);
    __bankswitch(1);
    sound_result[3]=Audio_EffectBank;
    sound_wait(30);
    __bankswitch(2);
    Audio_PlaySFXPanned(effect,5,AUDIO_PAN_RIGHT);
    __bankswitch(1);
    sound_wait(6);
    Audio_StopSfx();
    sound_result[4]=(u8)(Audio_EffectPointer==0);
    sound_wait(24);
    // Disabling effects releases current owners; re-enable before the next request.
    Audio_PlaySFXBanked(2,effect,5);
    sound_wait(6);
    Audio_SetSfxEnabled(0);
    sound_result[5]=Audio_SfxEnabled;
    sound_result[6]=(u8)(Audio_EffectPointer==0);
    sound_wait(24);
    Audio_SetSfxEnabled(1);
    Audio_PlaySFXBanked(2,effect,5);
    sound_wait(30);
    sound_result[7]=Audio_SfxEnabled;
    sound_end();
}

Resultado esperado

Los datos del banco 2 reproducen un pulso ascendente corto a la izquierda, un efecto de onda a la derecha y un pulso centrado. Los ejemplos posteriores detienen antes un pulso derecho, deshabilitan un efecto y vuelven a habilitar la reproducción. Una solicitud de prioridad 4 no sustituye a la prioridad 5.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_sfx.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-sfx.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Capture the currently mapped ROM bank and start an effect with inherited pan.
Use the explicit-bank API when the pointer belongs to another bank.

void __stackcall Audio_PlaySFX(u8 *sfx, u8 priority) {
    Audio_PlaySFXBanked(__rom_bank, sfx, priority);
}

Identifica el tipo de efecto en el banco de origen explícito y solicita reproducirlo con el panorama base.

Sintaxis

void __stackcall Audio_PlaySFXBanked(u8 bank, u8 *sfx, u8 priority);

Parámetros

bank

Banco ROM que contiene el flujo; debe coincidir con su ubicación.

sfx

Inicio del flujo de bytes del efecto. Consulta las notas para los formatos de pulsos y CH3.

priority

Prioridad de 0 a 255. Gana el valor mayor; uno igual también puede sustituir al efecto actual.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Un efecto consume un par (note,value) por actualización y termina en note=0. value es NR12 para efectos de pulsos y NR32 para CH3. Antepon 0xFF a los datos CH3 y conserva la memoria hasta que termine. Las prioridades compiten dentro de una ranura; una prioridad igual también puede sustituir al efecto actual.

En la configuración normal, liberar un efecto apaga CH3. Silencia CH1 si la música está detenida, pero no vuelve a tocar automáticamente una nota anterior mientras la música sigue activa. Con AUDIO_VBLANK_SFX_RESTORE, la liberación solicita la recuperación a la ISR.

Ejemplo de uso

// Each pair lasts one update. Priority controls replacement within each slot.
#include "gb_sound_example.h"
#pragma bank 2
__prg_rom u8 effect[]={33,0xC0,33,0xC0,33,0xC0,33,0xC0,33,0xC0,33,0xC0,
    40,0xC0,40,0xC0,40,0xC0,40,0xC0,40,0xC0,40,0xC0,0};
__prg_rom u8 wave_effect[]={AUDIO_SFX_CH3_MARKER,
    33,0x20,33,0x20,33,0x20,33,0x20,33,0x20,33,0x20,
    40,0x20,40,0x20,40,0x20,40,0x20,40,0x20,40,0x20,0};
#pragma bank 0
void main() {
    sound_begin("BANKED SOUND EFFECT");
    Audio_SetMasterVolume(3,3);
    // Read the marker in bank 2 while restoring the caller's original mapping.
    Audio_PlaySFXPannedBanked(2,effect,5,AUDIO_PAN_LEFT);
    sound_result[0]=Audio_EffectPriority;
    Audio_PlaySFXBanked(2,effect,4);
    sound_result[1]=Audio_EffectPriority;
    sound_wait(30);
    Audio_PlaySFXPannedBanked(2,wave_effect,5,AUDIO_PAN_RIGHT);
    sound_result[2]=Audio_EffectPriority3;
    sound_wait(30);
    // Implicit-bank entry points capture bank 2; the service restores bank 1.
    __bankswitch(2);
    Audio_PlaySFX(effect,5);
    __bankswitch(1);
    sound_result[3]=Audio_EffectBank;
    sound_wait(30);
    __bankswitch(2);
    Audio_PlaySFXPanned(effect,5,AUDIO_PAN_RIGHT);
    __bankswitch(1);
    sound_wait(6);
    Audio_StopSfx();
    sound_result[4]=(u8)(Audio_EffectPointer==0);
    sound_wait(24);
    // Disabling effects releases current owners; re-enable before the next request.
    Audio_PlaySFXBanked(2,effect,5);
    sound_wait(6);
    Audio_SetSfxEnabled(0);
    sound_result[5]=Audio_SfxEnabled;
    sound_result[6]=(u8)(Audio_EffectPointer==0);
    sound_wait(24);
    Audio_SetSfxEnabled(1);
    Audio_PlaySFXBanked(2,effect,5);
    sound_wait(30);
    sound_result[7]=Audio_SfxEnabled;
    sound_end();
}

Resultado esperado

Los datos del banco 2 reproducen un pulso ascendente corto a la izquierda, un efecto de onda a la derecha y un pulso centrado. Los ejemplos posteriores detienen antes un pulso derecho, deshabilitan un efecto y vuelven a habilitar la reproducción. Una solicitud de prioridad 4 no sustituye a la prioridad 5.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_sfx.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-sfx.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Start a banked effect with the channel's base pan, subject to priority arbitration.

void __stackcall Audio_PlaySFXBanked(u8 bank, u8 *sfx, u8 priority) {
    Audio_PlaySFXPannedBanked(bank, sfx, priority, AUDIO_PAN_INHERIT);
}

Captura el banco ROM actual y solicita un efecto con panorama específico.

Sintaxis

void __stackcall Audio_PlaySFXPanned(u8 *sfx, u8 priority, u8 pan);

Parámetros

sfx

Inicio del flujo de bytes del efecto. Consulta las notas para los formatos de pulsos y CH3.

priority

Prioridad de 0 a 255. Gana el valor mayor; uno igual también puede sustituir al efecto actual.

pan

0=centro, 1=izquierda, 2=derecha, 3=silencio. Las API de efectos tratan valores mayores que 3, incluido 0xFF, como herencia del panorama base.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Un efecto consume un par (note,value) por actualización y termina en note=0. value es NR12 para efectos de pulsos y NR32 para CH3. Antepon 0xFF a los datos CH3 y conserva la memoria hasta que termine. Las prioridades compiten dentro de una ranura; una prioridad igual también puede sustituir al efecto actual.

En la configuración normal, liberar un efecto apaga CH3. Silencia CH1 si la música está detenida, pero no vuelve a tocar automáticamente una nota anterior mientras la música sigue activa. Con AUDIO_VBLANK_SFX_RESTORE, la liberación solicita la recuperación a la ISR.

Ejemplo de uso

// Each pair lasts one update. Priority controls replacement within each slot.
#include "gb_sound_example.h"
#pragma bank 2
__prg_rom u8 effect[]={33,0xC0,33,0xC0,33,0xC0,33,0xC0,33,0xC0,33,0xC0,
    40,0xC0,40,0xC0,40,0xC0,40,0xC0,40,0xC0,40,0xC0,0};
__prg_rom u8 wave_effect[]={AUDIO_SFX_CH3_MARKER,
    33,0x20,33,0x20,33,0x20,33,0x20,33,0x20,33,0x20,
    40,0x20,40,0x20,40,0x20,40,0x20,40,0x20,40,0x20,0};
#pragma bank 0
void main() {
    sound_begin("BANKED SOUND EFFECT");
    Audio_SetMasterVolume(3,3);
    // Read the marker in bank 2 while restoring the caller's original mapping.
    Audio_PlaySFXPannedBanked(2,effect,5,AUDIO_PAN_LEFT);
    sound_result[0]=Audio_EffectPriority;
    Audio_PlaySFXBanked(2,effect,4);
    sound_result[1]=Audio_EffectPriority;
    sound_wait(30);
    Audio_PlaySFXPannedBanked(2,wave_effect,5,AUDIO_PAN_RIGHT);
    sound_result[2]=Audio_EffectPriority3;
    sound_wait(30);
    // Implicit-bank entry points capture bank 2; the service restores bank 1.
    __bankswitch(2);
    Audio_PlaySFX(effect,5);
    __bankswitch(1);
    sound_result[3]=Audio_EffectBank;
    sound_wait(30);
    __bankswitch(2);
    Audio_PlaySFXPanned(effect,5,AUDIO_PAN_RIGHT);
    __bankswitch(1);
    sound_wait(6);
    Audio_StopSfx();
    sound_result[4]=(u8)(Audio_EffectPointer==0);
    sound_wait(24);
    // Disabling effects releases current owners; re-enable before the next request.
    Audio_PlaySFXBanked(2,effect,5);
    sound_wait(6);
    Audio_SetSfxEnabled(0);
    sound_result[5]=Audio_SfxEnabled;
    sound_result[6]=(u8)(Audio_EffectPointer==0);
    sound_wait(24);
    Audio_SetSfxEnabled(1);
    Audio_PlaySFXBanked(2,effect,5);
    sound_wait(30);
    sound_result[7]=Audio_SfxEnabled;
    sound_end();
}

Resultado esperado

Los datos del banco 2 reproducen un pulso ascendente corto a la izquierda, un efecto de onda a la derecha y un pulso centrado. Los ejemplos posteriores detienen antes un pulso derecho, deshabilitan un efecto y vuelven a habilitar la reproducción. Una solicitud de prioridad 4 no sustituye a la prioridad 5.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_sfx.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-sfx.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Capture the currently mapped ROM bank and request an effect with a pan override.
Use the explicit-bank API when the pointer belongs to another bank.

void __stackcall Audio_PlaySFXPanned(u8 *sfx, u8 priority, u8 pan) {
    Audio_PlaySFXPannedBanked(__rom_bank, sfx, priority, pan);
}

Adquiere una ranura de efecto de pulsos o CH3 con banco, prioridad y panorama explícitos.

Sintaxis

void __stackcall Audio_PlaySFXPannedBanked(u8 bank, u8 *sfx, u8 priority, u8 pan);

Parámetros

bank

Banco ROM que contiene el flujo; debe coincidir con su ubicación.

sfx

Inicio del flujo de bytes del efecto. Consulta las notas para los formatos de pulsos y CH3.

priority

Prioridad de 0 a 255. Gana el valor mayor; uno igual también puede sustituir al efecto actual.

pan

0=centro, 1=izquierda, 2=derecha, 3=silencio. Las API de efectos tratan valores mayores que 3, incluido 0xFF, como herencia del panorama base.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Un efecto consume un par (note,value) por actualización y termina en note=0. value es NR12 para efectos de pulsos y NR32 para CH3. Antepon 0xFF a los datos CH3 y conserva la memoria hasta que termine. Las prioridades compiten dentro de una ranura; una prioridad igual también puede sustituir al efecto actual.

En la configuración normal, liberar un efecto apaga CH3. Silencia CH1 si la música está detenida, pero no vuelve a tocar automáticamente una nota anterior mientras la música sigue activa. Con AUDIO_VBLANK_SFX_RESTORE, la liberación solicita la recuperación a la ISR.

Ejemplo de uso

// Each pair lasts one update. Priority controls replacement within each slot.
#include "gb_sound_example.h"
#pragma bank 2
__prg_rom u8 effect[]={33,0xC0,33,0xC0,33,0xC0,33,0xC0,33,0xC0,33,0xC0,
    40,0xC0,40,0xC0,40,0xC0,40,0xC0,40,0xC0,40,0xC0,0};
__prg_rom u8 wave_effect[]={AUDIO_SFX_CH3_MARKER,
    33,0x20,33,0x20,33,0x20,33,0x20,33,0x20,33,0x20,
    40,0x20,40,0x20,40,0x20,40,0x20,40,0x20,40,0x20,0};
#pragma bank 0
void main() {
    sound_begin("BANKED SOUND EFFECT");
    Audio_SetMasterVolume(3,3);
    // Read the marker in bank 2 while restoring the caller's original mapping.
    Audio_PlaySFXPannedBanked(2,effect,5,AUDIO_PAN_LEFT);
    sound_result[0]=Audio_EffectPriority;
    Audio_PlaySFXBanked(2,effect,4);
    sound_result[1]=Audio_EffectPriority;
    sound_wait(30);
    Audio_PlaySFXPannedBanked(2,wave_effect,5,AUDIO_PAN_RIGHT);
    sound_result[2]=Audio_EffectPriority3;
    sound_wait(30);
    // Implicit-bank entry points capture bank 2; the service restores bank 1.
    __bankswitch(2);
    Audio_PlaySFX(effect,5);
    __bankswitch(1);
    sound_result[3]=Audio_EffectBank;
    sound_wait(30);
    __bankswitch(2);
    Audio_PlaySFXPanned(effect,5,AUDIO_PAN_RIGHT);
    __bankswitch(1);
    sound_wait(6);
    Audio_StopSfx();
    sound_result[4]=(u8)(Audio_EffectPointer==0);
    sound_wait(24);
    // Disabling effects releases current owners; re-enable before the next request.
    Audio_PlaySFXBanked(2,effect,5);
    sound_wait(6);
    Audio_SetSfxEnabled(0);
    sound_result[5]=Audio_SfxEnabled;
    sound_result[6]=(u8)(Audio_EffectPointer==0);
    sound_wait(24);
    Audio_SetSfxEnabled(1);
    Audio_PlaySFXBanked(2,effect,5);
    sound_wait(30);
    sound_result[7]=Audio_SfxEnabled;
    sound_end();
}

Resultado esperado

Los datos del banco 2 reproducen un pulso ascendente corto a la izquierda, un efecto de onda a la derecha y un pulso centrado. Los ejemplos posteriores detienen antes un pulso derecho, deshabilitan un efecto y vuelven a habilitar la reproducción. Una solicitud de prioridad 4 no sustituye a la prioridad 5.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_sfx.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-sfx.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Retain a banked effect stream if its priority equals or exceeds the current
owner's priority, or that slot is empty. A leading CH3 marker selects the wave
slot and is skipped; other streams use the pulse slot. Paused requests are ignored.
Keep stream storage valid until completion; acceptance does not trigger a note.

void __stackcall Audio_PlaySFXPannedBanked(u8 bank, u8 *sfx, u8 priority, u8 pan) {
    u8 sfx_pan = pan;
    u8 use_ch3 = 0;
    if (sfx_pan > AUDIO_PAN_MUTE) sfx_pan = AUDIO_PAN_INHERIT;

    if (Audio_Paused != 0) return;
    if (sfx != 0) {
        use_ch3 = Audio_SfxStartsOnCh3Banked(bank, sfx);
        if (use_ch3 != 0) {
            if (Audio_EffectPointer3 == 0 || priority >= Audio_EffectPriority3) {
                Audio_EffectPointer3 = sfx + 1;
                Audio_EffectPriority3 = priority;
                Audio_EffectBank3 = bank;
                Audio_EffectPan3 = sfx_pan;
                Audio_UpdateNR51();
            }
            return;
        }
    }
    if (Audio_EffectPointer == 0 || priority >= Audio_EffectPriority) {
#ifdef AUDIO_VBLANK_SFX_AUTO_CH2
        // Choose pulse-channel ownership when accepting the effect, so its later
        // updates and deferred recovery agree on which physical channel was borrowed.
        Audio_EffectUsesCh2 = (u8)(AudioVBlank_MusicPlaying != 0 &&
                                   AudioVBlank_MusicEnabled != 0);
#else
        Audio_EffectUsesCh2 = 0;
#endif
        Audio_EffectPointer = sfx;
        Audio_EffectPriority = priority;
        Audio_EffectBank = bank;
        Audio_EffectPan = sfx_pan;
        Audio_UpdateNR51();
    }
}

Guarda el índice de ciclo de trabajo de la próxima nota CH1.

Sintaxis

void __stackcall Audio_SetCh1Duty(u8 duty);

Parámetros

duty

Índice de ciclo de trabajo; se guardan los dos bits bajos. 0=12,5 %, 1=25 %, 2=50 %, 3=75 %.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Esta llamada por sí sola no cambia los registros de sonido activos. Pasa el valor guardado al inicio de nota o usa el flujo correspondiente para aplicarlo.

Ejemplo de uso

// Four isolated voices, each lasting 30 frames, separated by 15 silent frames.
#include "gb_sound_example.h"
void main() {
    sound_begin("FOUR SOUND CHANNELS");
    Audio_SetMasterVolume(3,3);
    // CH1: A4, 50% duty, fixed envelope volume 12.
    Audio_SetCh1Duty(2);
    sound_result[0]=Audio_Ch1Duty;
    Audio_Ch1NoteOn(33,0xC0,Audio_Ch1Duty);
    sound_result[1]=NR12;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH1); sound_wait(15);
    // CH2: A4, 25% duty. Changing the cached duty takes effect on this trigger.
    Audio_SetCh2Duty(1);
    sound_result[2]=Audio_Ch2Duty;
    Audio_Ch2NoteOn(33,0xC0,Audio_Ch2Duty);
    sound_result[3]=NR22;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH2); sound_wait(15);
    // CH3: the initialized triangle wave, at 50% digital output level.
    Audio_SetCh3Level(AUDIO_CH3_LEVEL_50);
    sound_result[4]=Audio_Ch3Level;
    Audio_Ch3NoteOn(33,Audio_Ch3Level);
    sound_result[5]=NR32;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // CH4: a sustained noise burst; param is NR43, not a pitched note number.
    Audio_SetCh4Param(0x35);
    sound_result[6]=Audio_Ch4Param;
    Audio_Ch4NoteOn(Audio_Ch4Param,0xC0);
    sound_result[7]=NR43;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH4); sound_wait(15);
    sound_end();
}

Resultado esperado

Tras aproximadamente medio segundo de silencio, se oyen CH1 A4, CH2 A4, CH3 A3 y ruido. Cada voz dura 30 fotogramas, con pausas de 15. SEQUENCE COMPLETE indica el final del programa; usa la grabación para valorar el sonido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_channels.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-channels.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Cache the low two duty bits for the next CH1 note; do not change the active register.

void __stackcall Audio_SetCh1Duty(u8 duty) {
    Audio_Ch1Duty = (u8)(duty & 3);
}

Guarda el índice de ciclo de trabajo de la próxima nota CH2.

Sintaxis

void __stackcall Audio_SetCh2Duty(u8 duty);

Parámetros

duty

Índice de ciclo de trabajo; se guardan los dos bits bajos. 0=12,5 %, 1=25 %, 2=50 %, 3=75 %.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Esta llamada por sí sola no cambia los registros de sonido activos. Pasa el valor guardado al inicio de nota o usa el flujo correspondiente para aplicarlo.

Ejemplo de uso

// Four isolated voices, each lasting 30 frames, separated by 15 silent frames.
#include "gb_sound_example.h"
void main() {
    sound_begin("FOUR SOUND CHANNELS");
    Audio_SetMasterVolume(3,3);
    // CH1: A4, 50% duty, fixed envelope volume 12.
    Audio_SetCh1Duty(2);
    sound_result[0]=Audio_Ch1Duty;
    Audio_Ch1NoteOn(33,0xC0,Audio_Ch1Duty);
    sound_result[1]=NR12;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH1); sound_wait(15);
    // CH2: A4, 25% duty. Changing the cached duty takes effect on this trigger.
    Audio_SetCh2Duty(1);
    sound_result[2]=Audio_Ch2Duty;
    Audio_Ch2NoteOn(33,0xC0,Audio_Ch2Duty);
    sound_result[3]=NR22;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH2); sound_wait(15);
    // CH3: the initialized triangle wave, at 50% digital output level.
    Audio_SetCh3Level(AUDIO_CH3_LEVEL_50);
    sound_result[4]=Audio_Ch3Level;
    Audio_Ch3NoteOn(33,Audio_Ch3Level);
    sound_result[5]=NR32;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // CH4: a sustained noise burst; param is NR43, not a pitched note number.
    Audio_SetCh4Param(0x35);
    sound_result[6]=Audio_Ch4Param;
    Audio_Ch4NoteOn(Audio_Ch4Param,0xC0);
    sound_result[7]=NR43;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH4); sound_wait(15);
    sound_end();
}

Resultado esperado

Tras aproximadamente medio segundo de silencio, se oyen CH1 A4, CH2 A4, CH3 A3 y ruido. Cada voz dura 30 fotogramas, con pausas de 15. SEQUENCE COMPLETE indica el final del programa; usa la grabación para valorar el sonido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_channels.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-channels.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Cache the low two duty bits for the next CH2 note; do not change the active register.

void __stackcall Audio_SetCh2Duty(u8 duty) {
    Audio_Ch2Duty = (u8)(duty & 3);
}

Guarda el nivel de salida NR32 de la próxima nota CH3.

Sintaxis

void __stackcall Audio_SetCh3Level(u8 level);

Parámetros

level

Codificación NR32: 0x00=silencio, 0x20=100 %, 0x40=50 %, 0x60=25 %.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Esta llamada por sí sola no cambia los registros de sonido activos. Pasa el valor guardado al inicio de nota o usa el flujo correspondiente para aplicarlo.

Ejemplo de uso

// Four isolated voices, each lasting 30 frames, separated by 15 silent frames.
#include "gb_sound_example.h"
void main() {
    sound_begin("FOUR SOUND CHANNELS");
    Audio_SetMasterVolume(3,3);
    // CH1: A4, 50% duty, fixed envelope volume 12.
    Audio_SetCh1Duty(2);
    sound_result[0]=Audio_Ch1Duty;
    Audio_Ch1NoteOn(33,0xC0,Audio_Ch1Duty);
    sound_result[1]=NR12;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH1); sound_wait(15);
    // CH2: A4, 25% duty. Changing the cached duty takes effect on this trigger.
    Audio_SetCh2Duty(1);
    sound_result[2]=Audio_Ch2Duty;
    Audio_Ch2NoteOn(33,0xC0,Audio_Ch2Duty);
    sound_result[3]=NR22;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH2); sound_wait(15);
    // CH3: the initialized triangle wave, at 50% digital output level.
    Audio_SetCh3Level(AUDIO_CH3_LEVEL_50);
    sound_result[4]=Audio_Ch3Level;
    Audio_Ch3NoteOn(33,Audio_Ch3Level);
    sound_result[5]=NR32;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // CH4: a sustained noise burst; param is NR43, not a pitched note number.
    Audio_SetCh4Param(0x35);
    sound_result[6]=Audio_Ch4Param;
    Audio_Ch4NoteOn(Audio_Ch4Param,0xC0);
    sound_result[7]=NR43;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH4); sound_wait(15);
    sound_end();
}

Resultado esperado

Tras aproximadamente medio segundo de silencio, se oyen CH1 A4, CH2 A4, CH3 A3 y ruido. Cada voz dura 30 fotogramas, con pausas de 15. SEQUENCE COMPLETE indica el final del programa; usa la grabación para valorar el sonido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_channels.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-channels.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Cache the raw NR32 level encoding for the next CH3 note without writing hardware.

void __stackcall Audio_SetCh3Level(u8 level) {
    Audio_Ch3Level = level;
}

Guarda los parámetros de ruido NR43 de la próxima nota CH4.

Sintaxis

void __stackcall Audio_SetCh4Param(u8 param);

Parámetros

param

NR43 bruto: bits 7..4 para desplazamiento del reloj, bit 3 para LFSR corto y bits 2..0 para código divisor.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Esta llamada por sí sola no cambia los registros de sonido activos. Pasa el valor guardado al inicio de nota o usa el flujo correspondiente para aplicarlo.

Ejemplo de uso

// Four isolated voices, each lasting 30 frames, separated by 15 silent frames.
#include "gb_sound_example.h"
void main() {
    sound_begin("FOUR SOUND CHANNELS");
    Audio_SetMasterVolume(3,3);
    // CH1: A4, 50% duty, fixed envelope volume 12.
    Audio_SetCh1Duty(2);
    sound_result[0]=Audio_Ch1Duty;
    Audio_Ch1NoteOn(33,0xC0,Audio_Ch1Duty);
    sound_result[1]=NR12;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH1); sound_wait(15);
    // CH2: A4, 25% duty. Changing the cached duty takes effect on this trigger.
    Audio_SetCh2Duty(1);
    sound_result[2]=Audio_Ch2Duty;
    Audio_Ch2NoteOn(33,0xC0,Audio_Ch2Duty);
    sound_result[3]=NR22;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH2); sound_wait(15);
    // CH3: the initialized triangle wave, at 50% digital output level.
    Audio_SetCh3Level(AUDIO_CH3_LEVEL_50);
    sound_result[4]=Audio_Ch3Level;
    Audio_Ch3NoteOn(33,Audio_Ch3Level);
    sound_result[5]=NR32;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // CH4: a sustained noise burst; param is NR43, not a pitched note number.
    Audio_SetCh4Param(0x35);
    sound_result[6]=Audio_Ch4Param;
    Audio_Ch4NoteOn(Audio_Ch4Param,0xC0);
    sound_result[7]=NR43;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH4); sound_wait(15);
    sound_end();
}

Resultado esperado

Tras aproximadamente medio segundo de silencio, se oyen CH1 A4, CH2 A4, CH3 A3 y ruido. Cada voz dura 30 fotogramas, con pausas de 15. SEQUENCE COMPLETE indica el final del programa; usa la grabación para valorar el sonido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_channels.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-channels.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Cache the raw noise polynomial encoding for the next CH4 note without writing hardware.

void __stackcall Audio_SetCh4Param(u8 param) {
    Audio_Ch4Param = param;
}

Limita los niveles maestros izquierdo/derecho a 0..7, los escribe de inmediato y cancela el fundido activo.

Sintaxis

void __stackcall Audio_SetMasterVolume(u8 left, u8 right);

Parámetros

left

Nivel maestro izquierdo, de 0 a 7; los valores mayores se limitan a 7. Cero no es silencio total.

right

Nivel maestro derecho, de 0 a 7; los valores mayores se limitan a 7.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Ejemplo de uso

// A sustained pulse moves left, right and center, then fades to a quieter level.
#include "gb_sound_example.h"
void main() {
    sound_begin("PAN AND VOLUME");
    Audio_SetMasterVolume(7,7);
    Audio_Ch1NoteOn(33,0xC0,2);
    Audio_SetPan(AUDIO_CHANNEL_CH1,AUDIO_PAN_LEFT);
    sound_result[0]=NR51;
    sound_wait(30);
    // Packed low two bits are CH1: 2 means right. Other channels remain centered.
    Audio_SetPanPacked(2);
    sound_result[1]=NR51;
    sound_wait(30);
    Audio_SetPanPacked(0);
    sound_result[2]=NR51;
    Audio_FadeToMasterVolume(1,1,5);
    sound_wait(30);
    sound_result[3]=NR50;
    sound_result[4]=Audio_FadeActive;
    sound_wait(30);
    // Cancel halfway through a rise: retain volume 4 instead of reaching 7.
    Audio_FadeToMasterVolume(7,7,5);
    sound_wait(15);
    Audio_CancelMasterVolumeFade();
    sound_result[5]=NR50;
    sound_wait(30);
    sound_result[6]=NR50;
    // A zero fade interval sets the target immediately. Level zero is not mute.
    Audio_FadeToMasterVolume(0,0,0);
    sound_result[7]=NR50;
    sound_wait(30);
    Audio_StopChannel(AUDIO_CHANNEL_CH1);
    sound_wait(15);
    sound_end();
}

Resultado esperado

A4 pasa a izquierda, derecha y centro. En el centro baja del nivel 7 al 1, sube al 4 y permanece ahí. El nivel 0 aún se oye débilmente; detener el canal produce silencio. Cambiar el enrutamiento puede dejar un transitorio de filtro que se desvanece.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_mix.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-mix.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Clamp both output levels to 0..7, cancel any fade, and write NR50 immediately.

void __stackcall Audio_SetMasterVolume(u8 left, u8 right) {
    Audio_MasterLeft = Audio_ClampVolume(left);
    Audio_MasterRight = Audio_ClampVolume(right);
    Audio_FadeTargetLeft = Audio_MasterLeft;
    Audio_FadeTargetRight = Audio_MasterRight;
    Audio_FadeStepFrames = 0;
    Audio_FadeCounter = 0;
    Audio_FadeActive = 0;
    Audio_UpdateNR50();
}

Controla si el decodificador musical normal escribe notas nuevas.

Sintaxis

void __stackcall Audio_SetMusicEnabled(u8 on);

Parámetros

on

Cero deshabilita y un valor no nulo habilita. Consulta la descripción para distinguir entre silenciar y bloquear las actualizaciones.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Deshabilitar sigue avanzando el flujo y procesando instrumentos y panorama. No silencia la nota actual. Usa Audio_SetPaused para pausar la reproducción.

Ejemplo de uso

// Original two-note phrase: pause preserves the cursor; the enable gate does not.
#include "gb_sound_example.h"
__prg_rom u8 song[]={
    AUDIO_CMD_SET_INST,AUDIO_STREAM_CHANNEL_CH1,2,0xC0,
    AUDIO_CMD_NOTE,AUDIO_STREAM_CHANNEL_CH1,33,AUDIO_CMD_WAIT,59,
    AUDIO_CMD_NOTE,AUDIO_STREAM_CHANNEL_CH1,40,AUDIO_CMD_WAIT,59,
    AUDIO_CMD_LOOP
};
void main() {
    u8 delay;
    sound_begin("MUSIC PAUSE GATE");
    Audio_SetMasterVolume(3,3);
    Audio_PlayMusic(0,song);
    sound_wait(30);
    delay=Audio_Delay;
    Audio_SetPaused(1);
    sound_wait(30);
    sound_result[0]=(u8)(Audio_Delay==delay);
    sound_result[1]=Audio_Paused;
    Audio_SetPaused(0);
    sound_wait(30);
    sound_result[2]=Audio_Paused;
    // Disabling suppresses note writes; the next 30 updates still consume data.
    Audio_SetMusicEnabled(0);
    sound_wait(30);
    sound_result[3]=Audio_Delay;
    sound_result[4]=Audio_MusicEnabled;
    // Explicitly stop the sounding channel while leaving the stream running.
    Audio_StopChannel(AUDIO_CHANNEL_CH1);
    sound_wait(30);
    Audio_SetMusicEnabled(1);
    sound_wait(30);
    Audio_StopMusic();
    sound_result[5]=Audio_PlayingMusic;
    sound_wait(30);
    sound_end();
}

Resultado esperado

Se oyen una nota, silencio en pausa, reanudación, una nota retenida al deshabilitar la música, silencio explícito del canal, la siguiente nota tras habilitar y, al final, parada. La RAM también verifica que 30 actualizaciones en pausa conservan delay, mientras que deshabilitar la música deja que avance hasta 30.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_music.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-music.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Set the music-processing gate. This does not silence notes already playing
or stop the legacy stream cursor from consuming commands.

void __stackcall Audio_SetMusicEnabled(u8 on) {
    if (on != 0) Audio_MusicEnabled = 1;
    else Audio_MusicEnabled = 0;
}

Cambia el panorama base de una voz física y vuelve a aplicar los panoramas específicos de los efectos activos.

Sintaxis

void __stackcall Audio_SetPan(u8 ch, u8 pan);

Parámetros

ch

ID de canal: 0=CH1, 1=CH2, 2=CH3, 3=CH4. Las API directas y los flujos musicales usan los mismos ID.

pan

0=centro, 1=izquierda, 2=derecha, 3=silencio. Las API de efectos tratan valores mayores que 3, incluido 0xFF, como herencia del panorama base.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Un canal desconocido selecciona CH4. Aquí pan fuera de 0..3 silencia; no es la opción de heredar de las API de efectos.

Ejemplo de uso

// A sustained pulse moves left, right and center, then fades to a quieter level.
#include "gb_sound_example.h"
void main() {
    sound_begin("PAN AND VOLUME");
    Audio_SetMasterVolume(7,7);
    Audio_Ch1NoteOn(33,0xC0,2);
    Audio_SetPan(AUDIO_CHANNEL_CH1,AUDIO_PAN_LEFT);
    sound_result[0]=NR51;
    sound_wait(30);
    // Packed low two bits are CH1: 2 means right. Other channels remain centered.
    Audio_SetPanPacked(2);
    sound_result[1]=NR51;
    sound_wait(30);
    Audio_SetPanPacked(0);
    sound_result[2]=NR51;
    Audio_FadeToMasterVolume(1,1,5);
    sound_wait(30);
    sound_result[3]=NR50;
    sound_result[4]=Audio_FadeActive;
    sound_wait(30);
    // Cancel halfway through a rise: retain volume 4 instead of reaching 7.
    Audio_FadeToMasterVolume(7,7,5);
    sound_wait(15);
    Audio_CancelMasterVolumeFade();
    sound_result[5]=NR50;
    sound_wait(30);
    sound_result[6]=NR50;
    // A zero fade interval sets the target immediately. Level zero is not mute.
    Audio_FadeToMasterVolume(0,0,0);
    sound_result[7]=NR50;
    sound_wait(30);
    Audio_StopChannel(AUDIO_CHANNEL_CH1);
    sound_wait(15);
    sound_end();
}

Resultado esperado

A4 pasa a izquierda, derecha y centro. En el centro baja del nivel 7 al 1, sube al 4 y permanece ahí. El nivel 0 aún se oye débilmente; detener el canal produce silencio. Cambiar el enrutamiento puede dejar un transitorio de filtro que se desvanece.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_mix.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-mix.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Update the base pan for a physical channel and reapply active effect overrides.
Unknown channel IDs select CH4; unsupported pan values mute the selected channel.

void __stackcall Audio_SetPan(u8 ch, u8 pan) {
    u8 r_bit;
    u8 l_bit;
    u8 mask;

    if (ch == AUDIO_CHANNEL_CH1) {
        r_bit = 0x01;
        l_bit = 0x10;
    } else if (ch == AUDIO_CHANNEL_CH2) {
        r_bit = 0x02;
        l_bit = 0x20;
    } else if (ch == AUDIO_CHANNEL_CH3) {
        r_bit = 0x04;
        l_bit = 0x40;
    } else {
        r_bit = 0x08;
        l_bit = 0x80;
    }

    mask = (u8)(l_bit | r_bit);
    Audio_Pan = (u8)(Audio_Pan & (u8)~mask);

    if (pan == AUDIO_PAN_CENTER) Audio_Pan = (u8)(Audio_Pan | mask);
    else if (pan == AUDIO_PAN_LEFT) Audio_Pan = (u8)(Audio_Pan | l_bit);
    else if (pan == AUDIO_PAN_RIGHT) Audio_Pan = (u8)(Audio_Pan | r_bit);

    Audio_UpdateNR51();
}

Extrae cuatro panoramas base de un byte y actualiza NR51 una vez.

Sintaxis

void __stackcall Audio_SetPanPacked(u8 packed);

Parámetros

packed

Dos bits por canal físico: CH1 en 0..1, CH2 en 2..3, CH3 en 4..5 y CH4 en 6..7. Cada campo usa los valores de panorama.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Ejemplo de uso

// A sustained pulse moves left, right and center, then fades to a quieter level.
#include "gb_sound_example.h"
void main() {
    sound_begin("PAN AND VOLUME");
    Audio_SetMasterVolume(7,7);
    Audio_Ch1NoteOn(33,0xC0,2);
    Audio_SetPan(AUDIO_CHANNEL_CH1,AUDIO_PAN_LEFT);
    sound_result[0]=NR51;
    sound_wait(30);
    // Packed low two bits are CH1: 2 means right. Other channels remain centered.
    Audio_SetPanPacked(2);
    sound_result[1]=NR51;
    sound_wait(30);
    Audio_SetPanPacked(0);
    sound_result[2]=NR51;
    Audio_FadeToMasterVolume(1,1,5);
    sound_wait(30);
    sound_result[3]=NR50;
    sound_result[4]=Audio_FadeActive;
    sound_wait(30);
    // Cancel halfway through a rise: retain volume 4 instead of reaching 7.
    Audio_FadeToMasterVolume(7,7,5);
    sound_wait(15);
    Audio_CancelMasterVolumeFade();
    sound_result[5]=NR50;
    sound_wait(30);
    sound_result[6]=NR50;
    // A zero fade interval sets the target immediately. Level zero is not mute.
    Audio_FadeToMasterVolume(0,0,0);
    sound_result[7]=NR50;
    sound_wait(30);
    Audio_StopChannel(AUDIO_CHANNEL_CH1);
    sound_wait(15);
    sound_end();
}

Resultado esperado

A4 pasa a izquierda, derecha y centro. En el centro baja del nivel 7 al 1, sube al 4 y permanece ahí. El nivel 0 aún se oye débilmente; detener el canal produce silencio. Cambiar el enrutamiento puede dejar un transitorio de filtro que se desvanece.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_mix.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-mix.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Two bits per channel (CH1 in bits 0-1): center, left, right, mute.
Applies all four positions with one NR51 update for sequencer automation.

void __stackcall Audio_SetPanPacked(u8 packed) {
    u8 mix = 0;
    u8 pan = (u8)(packed & 3);
    if (pan == AUDIO_PAN_CENTER) mix = (u8)(mix | 0x11);
    else if (pan == AUDIO_PAN_LEFT) mix = (u8)(mix | 0x10);
    else if (pan == AUDIO_PAN_RIGHT) mix = (u8)(mix | 0x01);
    pan = (u8)((packed >> 2) & 3);
    if (pan == AUDIO_PAN_CENTER) mix = (u8)(mix | 0x22);
    else if (pan == AUDIO_PAN_LEFT) mix = (u8)(mix | 0x20);
    else if (pan == AUDIO_PAN_RIGHT) mix = (u8)(mix | 0x02);
    pan = (u8)((packed >> 4) & 3);
    if (pan == AUDIO_PAN_CENTER) mix = (u8)(mix | 0x44);
    else if (pan == AUDIO_PAN_LEFT) mix = (u8)(mix | 0x40);
    else if (pan == AUDIO_PAN_RIGHT) mix = (u8)(mix | 0x04);
    pan = (u8)((packed >> 6) & 3);
    if (pan == AUDIO_PAN_CENTER) mix = (u8)(mix | 0x88);
    else if (pan == AUDIO_PAN_LEFT) mix = (u8)(mix | 0x80);
    else if (pan == AUDIO_PAN_RIGHT) mix = (u8)(mix | 0x08);
    Audio_Pan = mix;
    Audio_UpdateNR51();
}

Silencia en pausa conservando las posiciones de música y efectos. Al reanudar vuelve a disparar las notas que correspondan de CH1, CH2 y CH4.

Sintaxis

void __stackcall Audio_SetPaused(u8 on);

Parámetros

on

Cero deshabilita y un valor no nulo habilita. Consulta la descripción para distinguir entre silenciar y bloquear las actualizaciones.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Incluye audio_hwregs_gb.c antes de audio.c y llama a Audio_Init al arrancar. Llama a Audio_Update exactamente una vez por fotograma, unos 59,7 Hz. Las lecturas del flujo cambian temporalmente el mapeo ROM; no vuelvas a entrar en este controlador desde una interrupción.

Esta rutina no vuelve a disparar CH3. Los efectos continúan en una actualización posterior. Las llamadas directas de inicio de nota pueden sonar incluso en pausa.

Ejemplo de uso

// Original two-note phrase: pause preserves the cursor; the enable gate does not.
#include "gb_sound_example.h"
__prg_rom u8 song[]={
    AUDIO_CMD_SET_INST,AUDIO_STREAM_CHANNEL_CH1,2,0xC0,
    AUDIO_CMD_NOTE,AUDIO_STREAM_CHANNEL_CH1,33,AUDIO_CMD_WAIT,59,
    AUDIO_CMD_NOTE,AUDIO_STREAM_CHANNEL_CH1,40,AUDIO_CMD_WAIT,59,
    AUDIO_CMD_LOOP
};
void main() {
    u8 delay;
    sound_begin("MUSIC PAUSE GATE");
    Audio_SetMasterVolume(3,3);
    Audio_PlayMusic(0,song);
    sound_wait(30);
    delay=Audio_Delay;
    Audio_SetPaused(1);
    sound_wait(30);
    sound_result[0]=(u8)(Audio_Delay==delay);
    sound_result[1]=Audio_Paused;
    Audio_SetPaused(0);
    sound_wait(30);
    sound_result[2]=Audio_Paused;
    // Disabling suppresses note writes; the next 30 updates still consume data.
    Audio_SetMusicEnabled(0);
    sound_wait(30);
    sound_result[3]=Audio_Delay;
    sound_result[4]=Audio_MusicEnabled;
    // Explicitly stop the sounding channel while leaving the stream running.
    Audio_StopChannel(AUDIO_CHANNEL_CH1);
    sound_wait(30);
    Audio_SetMusicEnabled(1);
    sound_wait(30);
    Audio_StopMusic();
    sound_result[5]=Audio_PlayingMusic;
    sound_wait(30);
    sound_end();
}

Resultado esperado

Se oyen una nota, silencio en pausa, reanudación, una nota retenida al deshabilitar la música, silencio explícito del canal, la siguiente nota tras habilitar y, al final, parada. La RAM también verifica que 30 actualizaciones en pausa conservan delay, mientras que deshabilitar la música deja que avance hasta 30.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_music.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-music.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

On pause entry, silence hardware while retaining cursors. On resume, retrigger
eligible legacy CH1, CH2 and CH4 notes; CH3 is not retriggered here. Updates still
advance master fades while paused, and effect playback resumes on a later update.

void __stackcall Audio_SetPaused(u8 on) {
    if (on != 0) {
        if (Audio_Paused == 0) {
            Audio_Paused = 1;
            Audio_SilenceAll();
        }
    } else {
        if (Audio_Paused != 0) {
            Audio_Paused = 0;
            if (Audio_PlayingMusic != 0 && Audio_MusicEnabled != 0) {
                if ((Audio_LastChMask & AUDIO_RESUME_CH1) != 0 && Audio_EffectPointer == 0) {
                    Audio_Ch1NoteOn(Audio_LastCh1Note, Audio_Ch1Env, Audio_Ch1Duty);
                }
                if ((Audio_LastChMask & AUDIO_RESUME_CH2) != 0) {
                    Audio_Ch2NoteOn(Audio_LastCh2Note, Audio_Ch2Env, Audio_Ch2Duty);
                }
                if ((Audio_LastChMask & AUDIO_RESUME_CH4) != 0) {
                    Audio_Ch4NoteOn(Audio_LastCh4Param, Audio_Ch4Env);
                }
            }
        }
    }
}

Permite o bloquea las escrituras de notas de efectos; deshabilitar también libera sus ranuras.

Sintaxis

void __stackcall Audio_SetSfxEnabled(u8 on);

Parámetros

on

Cero deshabilita y un valor no nulo habilita. Consulta la descripción para distinguir entre silenciar y bloquear las actualizaciones.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

En la configuración normal, liberar un efecto apaga CH3. Silencia CH1 si la música está detenida, pero no vuelve a tocar automáticamente una nota anterior mientras la música sigue activa. Con AUDIO_VBLANK_SFX_RESTORE, la liberación solicita la recuperación a la ISR.

Iniciar con efectos deshabilitados puede registrar un flujo, pero las actualizaciones suprimen sus escrituras de notas. Habilita los efectos antes de pedir reproducción audible.

Ejemplo de uso

// Each pair lasts one update. Priority controls replacement within each slot.
#include "gb_sound_example.h"
#pragma bank 2
__prg_rom u8 effect[]={33,0xC0,33,0xC0,33,0xC0,33,0xC0,33,0xC0,33,0xC0,
    40,0xC0,40,0xC0,40,0xC0,40,0xC0,40,0xC0,40,0xC0,0};
__prg_rom u8 wave_effect[]={AUDIO_SFX_CH3_MARKER,
    33,0x20,33,0x20,33,0x20,33,0x20,33,0x20,33,0x20,
    40,0x20,40,0x20,40,0x20,40,0x20,40,0x20,40,0x20,0};
#pragma bank 0
void main() {
    sound_begin("BANKED SOUND EFFECT");
    Audio_SetMasterVolume(3,3);
    // Read the marker in bank 2 while restoring the caller's original mapping.
    Audio_PlaySFXPannedBanked(2,effect,5,AUDIO_PAN_LEFT);
    sound_result[0]=Audio_EffectPriority;
    Audio_PlaySFXBanked(2,effect,4);
    sound_result[1]=Audio_EffectPriority;
    sound_wait(30);
    Audio_PlaySFXPannedBanked(2,wave_effect,5,AUDIO_PAN_RIGHT);
    sound_result[2]=Audio_EffectPriority3;
    sound_wait(30);
    // Implicit-bank entry points capture bank 2; the service restores bank 1.
    __bankswitch(2);
    Audio_PlaySFX(effect,5);
    __bankswitch(1);
    sound_result[3]=Audio_EffectBank;
    sound_wait(30);
    __bankswitch(2);
    Audio_PlaySFXPanned(effect,5,AUDIO_PAN_RIGHT);
    __bankswitch(1);
    sound_wait(6);
    Audio_StopSfx();
    sound_result[4]=(u8)(Audio_EffectPointer==0);
    sound_wait(24);
    // Disabling effects releases current owners; re-enable before the next request.
    Audio_PlaySFXBanked(2,effect,5);
    sound_wait(6);
    Audio_SetSfxEnabled(0);
    sound_result[5]=Audio_SfxEnabled;
    sound_result[6]=(u8)(Audio_EffectPointer==0);
    sound_wait(24);
    Audio_SetSfxEnabled(1);
    Audio_PlaySFXBanked(2,effect,5);
    sound_wait(30);
    sound_result[7]=Audio_SfxEnabled;
    sound_end();
}

Resultado esperado

Los datos del banco 2 reproducen un pulso ascendente corto a la izquierda, un efecto de onda a la derecha y un pulso centrado. Los ejemplos posteriores detienen antes un pulso derecho, deshabilitan un efecto y vuelven a habilitar la reproducción. Una solicitud de prioridad 4 no sustituye a la prioridad 5.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_sfx.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-sfx.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Enable effect note writes, or disable them and release both effect streams.
Disabling follows Audio_StopSfx recovery rules rather than silencing all channels.

void __stackcall Audio_SetSfxEnabled(u8 on) {
    if (on != 0) {
        Audio_SfxEnabled = 1;
    } else {
        Audio_SfxEnabled = 0;
        Audio_StopSfx();
    }
}

Detiene una voz física y elimina su nota musical de la máscara de reanudación.

Sintaxis

void __stackcall Audio_StopChannel(u8 ch);

Parámetros

ch

ID de canal: 0=CH1, 1=CH2, 2=CH3, 3=CH4. Las API directas y los flujos musicales usan los mismos ID.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

CH1/CH3 también borran su ranura de efecto. Los valores fuera de 0..3 no hacen nada. Las notas retenidas por VBlank se gestionan aparte.

Ejemplo de uso

// Four isolated voices, each lasting 30 frames, separated by 15 silent frames.
#include "gb_sound_example.h"
void main() {
    sound_begin("FOUR SOUND CHANNELS");
    Audio_SetMasterVolume(3,3);
    // CH1: A4, 50% duty, fixed envelope volume 12.
    Audio_SetCh1Duty(2);
    sound_result[0]=Audio_Ch1Duty;
    Audio_Ch1NoteOn(33,0xC0,Audio_Ch1Duty);
    sound_result[1]=NR12;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH1); sound_wait(15);
    // CH2: A4, 25% duty. Changing the cached duty takes effect on this trigger.
    Audio_SetCh2Duty(1);
    sound_result[2]=Audio_Ch2Duty;
    Audio_Ch2NoteOn(33,0xC0,Audio_Ch2Duty);
    sound_result[3]=NR22;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH2); sound_wait(15);
    // CH3: the initialized triangle wave, at 50% digital output level.
    Audio_SetCh3Level(AUDIO_CH3_LEVEL_50);
    sound_result[4]=Audio_Ch3Level;
    Audio_Ch3NoteOn(33,Audio_Ch3Level);
    sound_result[5]=NR32;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH3); sound_wait(15);
    // CH4: a sustained noise burst; param is NR43, not a pitched note number.
    Audio_SetCh4Param(0x35);
    sound_result[6]=Audio_Ch4Param;
    Audio_Ch4NoteOn(Audio_Ch4Param,0xC0);
    sound_result[7]=NR43;
    sound_wait(30); Audio_StopChannel(AUDIO_CHANNEL_CH4); sound_wait(15);
    sound_end();
}

Resultado esperado

Tras aproximadamente medio segundo de silencio, se oyen CH1 A4, CH2 A4, CH3 A3 y ruido. Cada voz dura 30 fotogramas, con pausas de 15. SEQUENCE COMPLETE indica el final del programa; usa la grabación para valorar el sonido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_channels.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-channels.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Stop a physical channel and clear its legacy resume bit. CH1 also clears the
pulse effect stream; CH3 clears the wave effect stream. This is the legacy
channel API and does not clear a VBlank driver's independently latched notes.

void __stackcall Audio_StopChannel(u8 ch) {
    if (ch == AUDIO_CHANNEL_CH1) {
        Audio_EffectPointer = 0;
        Audio_EffectPriority = 0;
        Audio_EffectBank = 0;
        Audio_EffectPan = AUDIO_PAN_INHERIT;
        Audio_LastChMask = (u8)(Audio_LastChMask & (u8)~AUDIO_RESUME_CH1);
        Audio_UpdateNR51();
        Audio_SilenceCh1();
    } else if (ch == AUDIO_CHANNEL_CH2) {
        Audio_LastChMask = (u8)(Audio_LastChMask & (u8)~AUDIO_RESUME_CH2);
        Audio_SilenceCh2();
    } else if (ch == AUDIO_CHANNEL_CH3) {
        Audio_EffectPointer3 = 0;
        Audio_EffectPriority3 = 0;
        Audio_EffectBank3 = 0;
        Audio_EffectPan3 = AUDIO_PAN_INHERIT;
        Audio_LastChMask = (u8)(Audio_LastChMask & (u8)~AUDIO_RESUME_CH3);
        Audio_UpdateNR51();
        Audio_Ch3Off();
    } else if (ch == AUDIO_CHANNEL_CH4) {
        Audio_LastChMask = (u8)(Audio_LastChMask & (u8)~AUDIO_RESUME_CH4);
        Audio_SilenceCh4();
    }
}

Borra la reproducción de canción y su máscara de reanudación, y silencia inmediatamente las cuatro voces.

Sintaxis

void Audio_StopMusic();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Los punteros de efectos se conservan, así que un Audio_Update posterior puede hacer sonar un efecto. Llama también a Audio_StopSfx para detenerlo todo.

Ejemplo de uso

// Original two-note phrase: pause preserves the cursor; the enable gate does not.
#include "gb_sound_example.h"
__prg_rom u8 song[]={
    AUDIO_CMD_SET_INST,AUDIO_STREAM_CHANNEL_CH1,2,0xC0,
    AUDIO_CMD_NOTE,AUDIO_STREAM_CHANNEL_CH1,33,AUDIO_CMD_WAIT,59,
    AUDIO_CMD_NOTE,AUDIO_STREAM_CHANNEL_CH1,40,AUDIO_CMD_WAIT,59,
    AUDIO_CMD_LOOP
};
void main() {
    u8 delay;
    sound_begin("MUSIC PAUSE GATE");
    Audio_SetMasterVolume(3,3);
    Audio_PlayMusic(0,song);
    sound_wait(30);
    delay=Audio_Delay;
    Audio_SetPaused(1);
    sound_wait(30);
    sound_result[0]=(u8)(Audio_Delay==delay);
    sound_result[1]=Audio_Paused;
    Audio_SetPaused(0);
    sound_wait(30);
    sound_result[2]=Audio_Paused;
    // Disabling suppresses note writes; the next 30 updates still consume data.
    Audio_SetMusicEnabled(0);
    sound_wait(30);
    sound_result[3]=Audio_Delay;
    sound_result[4]=Audio_MusicEnabled;
    // Explicitly stop the sounding channel while leaving the stream running.
    Audio_StopChannel(AUDIO_CHANNEL_CH1);
    sound_wait(30);
    Audio_SetMusicEnabled(1);
    sound_wait(30);
    Audio_StopMusic();
    sound_result[5]=Audio_PlayingMusic;
    sound_wait(30);
    sound_end();
}

Resultado esperado

Se oyen una nota, silencio en pausa, reanudación, una nota retenida al deshabilitar la música, silencio explícito del canal, la siguiente nota tras habilitar y, al final, parada. La RAM también verifica que 30 actualizaciones en pausa conservan delay, mientras que deshabilitar la música deja que avance hasta 30.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_music.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-music.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Stop legacy music and clear its resume mask, then silence all physical channels.
Effect pointers remain active and may produce sound on a later update.

void Audio_StopMusic() {
    Audio_PlayingMusic = 0;
    Audio_LastChMask = 0;
    Audio_SilenceAll();
}

Borra ambos flujos de efectos y sus panoramas específicos, y libera los canales prestados.

Sintaxis

void Audio_StopSfx();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Un efecto consume un par (note,value) por actualización y termina en note=0. value es NR12 para efectos de pulsos y NR32 para CH3. Antepon 0xFF a los datos CH3 y conserva la memoria hasta que termine. Las prioridades compiten dentro de una ranura; una prioridad igual también puede sustituir al efecto actual.

En la configuración normal, liberar un efecto apaga CH3. Silencia CH1 si la música está detenida, pero no vuelve a tocar automáticamente una nota anterior mientras la música sigue activa. Con AUDIO_VBLANK_SFX_RESTORE, la liberación solicita la recuperación a la ISR.

Ejemplo de uso

// Each pair lasts one update. Priority controls replacement within each slot.
#include "gb_sound_example.h"
#pragma bank 2
__prg_rom u8 effect[]={33,0xC0,33,0xC0,33,0xC0,33,0xC0,33,0xC0,33,0xC0,
    40,0xC0,40,0xC0,40,0xC0,40,0xC0,40,0xC0,40,0xC0,0};
__prg_rom u8 wave_effect[]={AUDIO_SFX_CH3_MARKER,
    33,0x20,33,0x20,33,0x20,33,0x20,33,0x20,33,0x20,
    40,0x20,40,0x20,40,0x20,40,0x20,40,0x20,40,0x20,0};
#pragma bank 0
void main() {
    sound_begin("BANKED SOUND EFFECT");
    Audio_SetMasterVolume(3,3);
    // Read the marker in bank 2 while restoring the caller's original mapping.
    Audio_PlaySFXPannedBanked(2,effect,5,AUDIO_PAN_LEFT);
    sound_result[0]=Audio_EffectPriority;
    Audio_PlaySFXBanked(2,effect,4);
    sound_result[1]=Audio_EffectPriority;
    sound_wait(30);
    Audio_PlaySFXPannedBanked(2,wave_effect,5,AUDIO_PAN_RIGHT);
    sound_result[2]=Audio_EffectPriority3;
    sound_wait(30);
    // Implicit-bank entry points capture bank 2; the service restores bank 1.
    __bankswitch(2);
    Audio_PlaySFX(effect,5);
    __bankswitch(1);
    sound_result[3]=Audio_EffectBank;
    sound_wait(30);
    __bankswitch(2);
    Audio_PlaySFXPanned(effect,5,AUDIO_PAN_RIGHT);
    __bankswitch(1);
    sound_wait(6);
    Audio_StopSfx();
    sound_result[4]=(u8)(Audio_EffectPointer==0);
    sound_wait(24);
    // Disabling effects releases current owners; re-enable before the next request.
    Audio_PlaySFXBanked(2,effect,5);
    sound_wait(6);
    Audio_SetSfxEnabled(0);
    sound_result[5]=Audio_SfxEnabled;
    sound_result[6]=(u8)(Audio_EffectPointer==0);
    sound_wait(24);
    Audio_SetSfxEnabled(1);
    Audio_PlaySFXBanked(2,effect,5);
    sound_wait(30);
    sound_result[7]=Audio_SfxEnabled;
    sound_end();
}

Resultado esperado

Los datos del banco 2 reproducen un pulso ascendente corto a la izquierda, un efecto de onda a la derecha y un pulso centrado. Los ejemplos posteriores detienen antes un pulso derecho, deshabilitan un efecto y vuelven a habilitar la reproducción. Una solicitud de prioridad 4 no sustituye a la prioridad 5.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_sfx.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-sfx.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Clear both effect streams and their pan overrides. When not paused, release
borrowed channels through the configured legacy or VBlank recovery path.

void Audio_StopSfx() {
    Audio_EffectPointer = 0;
    Audio_EffectPriority = 0;
    Audio_EffectBank = 0;
    Audio_EffectPointer3 = 0;
    Audio_EffectPriority3 = 0;
    Audio_EffectBank3 = 0;
    Audio_EffectPan = AUDIO_PAN_INHERIT;
    Audio_EffectPan3 = AUDIO_PAN_INHERIT;
    Audio_UpdateNR51();

    if (Audio_Paused != 0) return;
    Audio_ReleaseCh1AfterSfx();
    Audio_RestoreCh3FromMusic();
}

Avanza una vez el fundido de volumen; salvo en pausa, procesa después efectos y música, en ese orden.

Sintaxis

void Audio_Update();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

Incluye audio_hwregs_gb.c antes de audio.c y llama a Audio_Init al arrancar. Llama a Audio_Update exactamente una vez por fotograma, unos 59,7 Hz. Las lecturas del flujo cambian temporalmente el mapeo ROM; no vuelvas a entrar en este controlador desde una interrupción.

Los fundidos continúan en pausa. Leer WAIT n va seguido de n llamadas de espera, por lo que la orden siguiente llega tras n+1 actualizaciones.

Ejemplo de uso

// Original two-note phrase: pause preserves the cursor; the enable gate does not.
#include "gb_sound_example.h"
__prg_rom u8 song[]={
    AUDIO_CMD_SET_INST,AUDIO_STREAM_CHANNEL_CH1,2,0xC0,
    AUDIO_CMD_NOTE,AUDIO_STREAM_CHANNEL_CH1,33,AUDIO_CMD_WAIT,59,
    AUDIO_CMD_NOTE,AUDIO_STREAM_CHANNEL_CH1,40,AUDIO_CMD_WAIT,59,
    AUDIO_CMD_LOOP
};
void main() {
    u8 delay;
    sound_begin("MUSIC PAUSE GATE");
    Audio_SetMasterVolume(3,3);
    Audio_PlayMusic(0,song);
    sound_wait(30);
    delay=Audio_Delay;
    Audio_SetPaused(1);
    sound_wait(30);
    sound_result[0]=(u8)(Audio_Delay==delay);
    sound_result[1]=Audio_Paused;
    Audio_SetPaused(0);
    sound_wait(30);
    sound_result[2]=Audio_Paused;
    // Disabling suppresses note writes; the next 30 updates still consume data.
    Audio_SetMusicEnabled(0);
    sound_wait(30);
    sound_result[3]=Audio_Delay;
    sound_result[4]=Audio_MusicEnabled;
    // Explicitly stop the sounding channel while leaving the stream running.
    Audio_StopChannel(AUDIO_CHANNEL_CH1);
    sound_wait(30);
    Audio_SetMusicEnabled(1);
    sound_wait(30);
    Audio_StopMusic();
    sound_result[5]=Audio_PlayingMusic;
    sound_wait(30);
    sound_end();
}

Resultado esperado

Se oyen una nota, silencio en pausa, reanudación, una nota retenida al deshabilitar la música, silencio explícito del canal, la siguiente nota tras habilitar y, al final, parada. La RAM también verifica que 30 actualizaciones en pausa conservan delay, mientras que deshabilitar la música deja que avance hasta 30.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_music.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-music.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Advance the master fade first. Unless paused, service both effect streams
then the optional legacy music decoder. Call once per frame for frame-based timing.

void Audio_Update() {
    Audio_UpdateFade();
    if (Audio_Paused != 0) return;

    Audio_ServiceSfx();
#ifndef AUDIO_EXCLUDE_LEGACY_MUSIC_SERVICE
    Audio_ServiceMusic();
#endif
}

Borra solo el bit VBlank de IE, sin cambiar otras fuentes de interrupción ni el sonido.

Sintaxis

void AudioVBlank_DisableIrq();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

audio_vblank.c implementa __kq_vblank_vector; no instales además otro vector VBlank que compita con él. El ejemplo define Audio_NoiseEffectActive, excluye el decodificador musical normal y usa Audio_Update solo para efectos y fundidos. Bloquea las interrupciones al cambiar punteros de canción o estado compartido.

Guarda los datos de canción de lectura directa en ROM fija u otra zona siempre visible para la ISR. Cada registro tiene cinco bytes: delay, CH1, CH2, CH3, CH4. En los campos de nota, 0xFF mantiene la voz y 0xFD la detiene. En delay, 0xFF termina la reproducción y 0xFE repite. Es la disposición del registro, no la numeración de canales. La reproducción por cola WRAM es otro modo; envía registros completos de cinco bytes con AudioVBlank_QueueRefill.

Ejemplo de uso

// Direct fixed-bank music with an actual VBlank ISR and a counting frame hook.
#define SOUND_VBLANK
#include "gb_sound_example.h"
__wram u8 hook_count;
__prg_rom u8 irq_song[]={30,33,0xFF,0xFF,0xFF,30,40,0xFF,0xFF,0xFF,0xFE};
void frame_hook() { hook_count++; }
void main() {
    u8 before;
    sound_begin("VBLANK MUSIC GATES");
    Audio_NoiseEffectActive=0;
    AudioVBlank_Init();
    sound_result[0]=AudioVBlank_MusicPlaying;
    AudioVBlank_Ch1Envelope=0xC0;
    Audio_SetMasterVolume(3,3);
    hook_count=0; AudioVBlank_FrameHook=frame_hook;
    AudioVBlank_SetMusic(irq_song);
    AudioVBlank_Play();
    AudioVBlank_EnableIrq();
    sound_wait(45);
    // Disable music processing while the hook and current note remain active.
    __asm { DI }
    AudioVBlank_SetEnabled(0); before=hook_count;
    __asm { EI }
    sound_wait(30);
    sound_result[1]=(u8)(hook_count!=before);
    __asm { DI }
    AudioVBlank_Stop();
    __asm { EI }
    sound_wait(30);
    __asm { DI }
    AudioVBlank_SetEnabled(1); AudioVBlank_PlayMusic(irq_song);
    __asm { EI }
    sound_wait(45);
    AudioVBlank_DisableIrq();
    before=hook_count;
    sound_wait(30);
    sound_result[2]=(u8)(hook_count==before);
    sound_result[3]=(u8)(AudioVBlank_IE&1);
    AudioVBlank_Stop(); sound_wait(30);
    sound_end();
}

Resultado esperado

La ISR toca una canción de dos notas. Compara bloquear las actualizaciones musicales, que conserva el sonido; Stop, que lo silencia; y bloquear IRQ tras reiniciar, que también conserva el sonido. La RAM verifica que el hook sigue funcionando con la música deshabilitada y se detiene al deshabilitar IRQ.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_vblank.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-vblank.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Clear only the VBlank bit in IE. Other interrupt sources and current sound remain unchanged.

void AudioVBlank_DisableIrq()
{
    AudioVBlank_IE = (u8)(AudioVBlank_IE & 0xFE);
}

Activa el bit VBlank de IE y ejecuta EI para habilitar globalmente las interrupciones de CPU.

Sintaxis

void AudioVBlank_EnableIrq();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

audio_vblank.c implementa __kq_vblank_vector; no instales además otro vector VBlank que compita con él. El ejemplo define Audio_NoiseEffectActive, excluye el decodificador musical normal y usa Audio_Update solo para efectos y fundidos. Bloquea las interrupciones al cambiar punteros de canción o estado compartido.

Guarda los datos de canción de lectura directa en ROM fija u otra zona siempre visible para la ISR. Cada registro tiene cinco bytes: delay, CH1, CH2, CH3, CH4. En los campos de nota, 0xFF mantiene la voz y 0xFD la detiene. En delay, 0xFF termina la reproducción y 0xFE repite. Es la disposición del registro, no la numeración de canales. La reproducción por cola WRAM es otro modo; envía registros completos de cinco bytes con AudioVBlank_QueueRefill.

Ejemplo de uso

// Direct fixed-bank music with an actual VBlank ISR and a counting frame hook.
#define SOUND_VBLANK
#include "gb_sound_example.h"
__wram u8 hook_count;
__prg_rom u8 irq_song[]={30,33,0xFF,0xFF,0xFF,30,40,0xFF,0xFF,0xFF,0xFE};
void frame_hook() { hook_count++; }
void main() {
    u8 before;
    sound_begin("VBLANK MUSIC GATES");
    Audio_NoiseEffectActive=0;
    AudioVBlank_Init();
    sound_result[0]=AudioVBlank_MusicPlaying;
    AudioVBlank_Ch1Envelope=0xC0;
    Audio_SetMasterVolume(3,3);
    hook_count=0; AudioVBlank_FrameHook=frame_hook;
    AudioVBlank_SetMusic(irq_song);
    AudioVBlank_Play();
    AudioVBlank_EnableIrq();
    sound_wait(45);
    // Disable music processing while the hook and current note remain active.
    __asm { DI }
    AudioVBlank_SetEnabled(0); before=hook_count;
    __asm { EI }
    sound_wait(30);
    sound_result[1]=(u8)(hook_count!=before);
    __asm { DI }
    AudioVBlank_Stop();
    __asm { EI }
    sound_wait(30);
    __asm { DI }
    AudioVBlank_SetEnabled(1); AudioVBlank_PlayMusic(irq_song);
    __asm { EI }
    sound_wait(45);
    AudioVBlank_DisableIrq();
    before=hook_count;
    sound_wait(30);
    sound_result[2]=(u8)(hook_count==before);
    sound_result[3]=(u8)(AudioVBlank_IE&1);
    AudioVBlank_Stop(); sound_wait(30);
    sound_end();
}

Resultado esperado

La ISR toca una canción de dos notas. Compara bloquear las actualizaciones musicales, que conserva el sonido; Stop, que lo silencia; y bloquear IRQ tras reiniciar, que también conserva el sonido. La RAM verifica que el hook sigue funcionando con la música deshabilitada y se detiene al deshabilitar IRQ.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_vblank.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-vblank.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Enable the VBlank source in IE and execute EI, enabling CPU interrupts globally.
Install the correct interrupt vector and initialize driver state first.

void AudioVBlank_EnableIrq()
{
    AudioVBlank_IE = (u8)(AudioVBlank_IE | 0x01);
    __asm { EI }
}

Inicializa el estado musical VBlank, la cola, los instrumentos y el hook. No inicializa la APU ni bloquea interrupciones.

Sintaxis

void AudioVBlank_Init();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

audio_vblank.c implementa __kq_vblank_vector; no instales además otro vector VBlank que compita con él. El ejemplo define Audio_NoiseEffectActive, excluye el decodificador musical normal y usa Audio_Update solo para efectos y fundidos. Bloquea las interrupciones al cambiar punteros de canción o estado compartido.

Guarda los datos de canción de lectura directa en ROM fija u otra zona siempre visible para la ISR. Cada registro tiene cinco bytes: delay, CH1, CH2, CH3, CH4. En los campos de nota, 0xFF mantiene la voz y 0xFD la detiene. En delay, 0xFF termina la reproducción y 0xFE repite. Es la disposición del registro, no la numeración de canales. La reproducción por cola WRAM es otro modo; envía registros completos de cinco bytes con AudioVBlank_QueueRefill.

Ejemplo de uso

// Direct fixed-bank music with an actual VBlank ISR and a counting frame hook.
#define SOUND_VBLANK
#include "gb_sound_example.h"
__wram u8 hook_count;
__prg_rom u8 irq_song[]={30,33,0xFF,0xFF,0xFF,30,40,0xFF,0xFF,0xFF,0xFE};
void frame_hook() { hook_count++; }
void main() {
    u8 before;
    sound_begin("VBLANK MUSIC GATES");
    Audio_NoiseEffectActive=0;
    AudioVBlank_Init();
    sound_result[0]=AudioVBlank_MusicPlaying;
    AudioVBlank_Ch1Envelope=0xC0;
    Audio_SetMasterVolume(3,3);
    hook_count=0; AudioVBlank_FrameHook=frame_hook;
    AudioVBlank_SetMusic(irq_song);
    AudioVBlank_Play();
    AudioVBlank_EnableIrq();
    sound_wait(45);
    // Disable music processing while the hook and current note remain active.
    __asm { DI }
    AudioVBlank_SetEnabled(0); before=hook_count;
    __asm { EI }
    sound_wait(30);
    sound_result[1]=(u8)(hook_count!=before);
    __asm { DI }
    AudioVBlank_Stop();
    __asm { EI }
    sound_wait(30);
    __asm { DI }
    AudioVBlank_SetEnabled(1); AudioVBlank_PlayMusic(irq_song);
    __asm { EI }
    sound_wait(45);
    AudioVBlank_DisableIrq();
    before=hook_count;
    sound_wait(30);
    sound_result[2]=(u8)(hook_count==before);
    sound_result[3]=(u8)(AudioVBlank_IE&1);
    AudioVBlank_Stop(); sound_wait(30);
    sound_end();
}

Resultado esperado

La ISR toca una canción de dos notas. Compara bloquear las actualizaciones musicales, que conserva el sonido; Stop, que lo silencia; y bloquear IRQ tras reiniciar, que también conserva el sonido. La RAM verifica que el hook sigue funcionando con la música deshabilitada y se detiene al deshabilitar IRQ.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_vblank.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-vblank.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Reset software playback state, queue counters, instruments and the frame hook.
Call before enabling this ISR; the routine does not mask interrupts or
initialize the APU registers and cannot synchronize with an active handler.

void AudioVBlank_Init()
{
    AudioVBlank_MusicEnabled = 1;
    AudioVBlank_MusicPlaying = 0;
    AudioVBlank_MusicDelay = 0;
    AudioVBlank_MusicStart = 0;
    AudioVBlank_MusicPointer = 0;
    AudioVBlank_MusicLoopPoint = 0;
    AudioVBlank_Step = 0;
    AudioVBlank_Ch2Note = AUDIO_VBLANK_REST;
    AudioVBlank_Ch1Note = AUDIO_VBLANK_REST;
    AudioVBlank_Ch3Note = AUDIO_VBLANK_REST;
    AudioVBlank_Ch2LatchedNote = AUDIO_VBLANK_STOP;
    AudioVBlank_Ch1LatchedNote = AUDIO_VBLANK_STOP;
    AudioVBlank_Ch3LatchedNote = AUDIO_VBLANK_STOP;
    AudioVBlank_RestoreCh1Pending = 0;
    AudioVBlank_RestoreCh3Pending = 0;
    AudioVBlank_Ch4Param = AUDIO_VBLANK_REST;
    AudioVBlank_Ch1Envelope = 0xF1;
    AudioVBlank_Ch2Envelope = 0xF2;
    AudioVBlank_Ch4Envelope = 0xF1;
    AudioVBlank_Ch1Duty = 0x80;
    AudioVBlank_Ch2Duty = 0x80;
    AudioVBlank_Ch1Sweep = 0x00;
    AudioVBlank_Ch3Level = 0x20;
    AudioVBlank_ControlCommand = 0;
    AudioVBlank_ControlArg0 = 0;
    AudioVBlank_ControlArg1 = 0;
    AudioVBlank_ControlArg2 = 0;
    AudioVBlank_QueueMode = 0;
    AudioVBlank_QueueReadIndex = 0;
    AudioVBlank_QueueWriteIndex = 0;
    AudioVBlank_QueueCount = 0;
    AudioVBlank_QueueUnderruns = 0;
    AudioVBlank_FrameHook = 0;
}

Reinicia la canción seleccionada desde el principio y sale del modo cola. Una canción NULL detiene la reproducción.

Sintaxis

void AudioVBlank_Play();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

audio_vblank.c implementa __kq_vblank_vector; no instales además otro vector VBlank que compita con él. El ejemplo define Audio_NoiseEffectActive, excluye el decodificador musical normal y usa Audio_Update solo para efectos y fundidos. Bloquea las interrupciones al cambiar punteros de canción o estado compartido.

Guarda los datos de canción de lectura directa en ROM fija u otra zona siempre visible para la ISR. Cada registro tiene cinco bytes: delay, CH1, CH2, CH3, CH4. En los campos de nota, 0xFF mantiene la voz y 0xFD la detiene. En delay, 0xFF termina la reproducción y 0xFE repite. Es la disposición del registro, no la numeración de canales. La reproducción por cola WRAM es otro modo; envía registros completos de cinco bytes con AudioVBlank_QueueRefill.

Ejemplo de uso

// Direct fixed-bank music with an actual VBlank ISR and a counting frame hook.
#define SOUND_VBLANK
#include "gb_sound_example.h"
__wram u8 hook_count;
__prg_rom u8 irq_song[]={30,33,0xFF,0xFF,0xFF,30,40,0xFF,0xFF,0xFF,0xFE};
void frame_hook() { hook_count++; }
void main() {
    u8 before;
    sound_begin("VBLANK MUSIC GATES");
    Audio_NoiseEffectActive=0;
    AudioVBlank_Init();
    sound_result[0]=AudioVBlank_MusicPlaying;
    AudioVBlank_Ch1Envelope=0xC0;
    Audio_SetMasterVolume(3,3);
    hook_count=0; AudioVBlank_FrameHook=frame_hook;
    AudioVBlank_SetMusic(irq_song);
    AudioVBlank_Play();
    AudioVBlank_EnableIrq();
    sound_wait(45);
    // Disable music processing while the hook and current note remain active.
    __asm { DI }
    AudioVBlank_SetEnabled(0); before=hook_count;
    __asm { EI }
    sound_wait(30);
    sound_result[1]=(u8)(hook_count!=before);
    __asm { DI }
    AudioVBlank_Stop();
    __asm { EI }
    sound_wait(30);
    __asm { DI }
    AudioVBlank_SetEnabled(1); AudioVBlank_PlayMusic(irq_song);
    __asm { EI }
    sound_wait(45);
    AudioVBlank_DisableIrq();
    before=hook_count;
    sound_wait(30);
    sound_result[2]=(u8)(hook_count==before);
    sound_result[3]=(u8)(AudioVBlank_IE&1);
    AudioVBlank_Stop(); sound_wait(30);
    sound_end();
}

Resultado esperado

La ISR toca una canción de dos notas. Compara bloquear las actualizaciones musicales, que conserva el sonido; Stop, que lo silencia; y bloquear IRQ tras reiniciar, que también conserva el sonido. La RAM verifica que el hook sigue funcionando con la música deshabilitada y se detiene al deshabilitar IRQ.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_vblank.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-vblank.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Restart the selected direct song at its beginning, leaving queue mode.
A null song invokes Stop; this does not enable the music or IRQ gates.

void AudioVBlank_Play()
{
    if (AudioVBlank_MusicStart == 0) {
        AudioVBlank_Stop();
        return;
    }
    AudioVBlank_MusicPointer = AudioVBlank_MusicStart;
    AudioVBlank_MusicLoopPoint = AudioVBlank_MusicStart;
    AudioVBlank_MusicDelay = 0;
    AudioVBlank_Step = 0;
    AudioVBlank_QueueMode = 0;
    AudioVBlank_MusicPlaying = 1;
}

Selecciona una canción de lectura directa y prepara su reproducción desde el principio.

Sintaxis

void __stackcall AudioVBlank_PlayMusic(u8 *song);

Parámetros

song

Dirección inicial de la canción. El controlador usa el array prestado, que debe seguir siendo legible durante toda la reproducción.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

audio_vblank.c implementa __kq_vblank_vector; no instales además otro vector VBlank que compita con él. El ejemplo define Audio_NoiseEffectActive, excluye el decodificador musical normal y usa Audio_Update solo para efectos y fundidos. Bloquea las interrupciones al cambiar punteros de canción o estado compartido.

Guarda los datos de canción de lectura directa en ROM fija u otra zona siempre visible para la ISR. Cada registro tiene cinco bytes: delay, CH1, CH2, CH3, CH4. En los campos de nota, 0xFF mantiene la voz y 0xFD la detiene. En delay, 0xFF termina la reproducción y 0xFE repite. Es la disposición del registro, no la numeración de canales. La reproducción por cola WRAM es otro modo; envía registros completos de cinco bytes con AudioVBlank_QueueRefill.

Ejemplo de uso

// Direct fixed-bank music with an actual VBlank ISR and a counting frame hook.
#define SOUND_VBLANK
#include "gb_sound_example.h"
__wram u8 hook_count;
__prg_rom u8 irq_song[]={30,33,0xFF,0xFF,0xFF,30,40,0xFF,0xFF,0xFF,0xFE};
void frame_hook() { hook_count++; }
void main() {
    u8 before;
    sound_begin("VBLANK MUSIC GATES");
    Audio_NoiseEffectActive=0;
    AudioVBlank_Init();
    sound_result[0]=AudioVBlank_MusicPlaying;
    AudioVBlank_Ch1Envelope=0xC0;
    Audio_SetMasterVolume(3,3);
    hook_count=0; AudioVBlank_FrameHook=frame_hook;
    AudioVBlank_SetMusic(irq_song);
    AudioVBlank_Play();
    AudioVBlank_EnableIrq();
    sound_wait(45);
    // Disable music processing while the hook and current note remain active.
    __asm { DI }
    AudioVBlank_SetEnabled(0); before=hook_count;
    __asm { EI }
    sound_wait(30);
    sound_result[1]=(u8)(hook_count!=before);
    __asm { DI }
    AudioVBlank_Stop();
    __asm { EI }
    sound_wait(30);
    __asm { DI }
    AudioVBlank_SetEnabled(1); AudioVBlank_PlayMusic(irq_song);
    __asm { EI }
    sound_wait(45);
    AudioVBlank_DisableIrq();
    before=hook_count;
    sound_wait(30);
    sound_result[2]=(u8)(hook_count==before);
    sound_result[3]=(u8)(AudioVBlank_IE&1);
    AudioVBlank_Stop(); sound_wait(30);
    sound_end();
}

Resultado esperado

La ISR toca una canción de dos notas. Compara bloquear las actualizaciones musicales, que conserva el sonido; Stop, que lo silencia; y bloquear IRQ tras reiniciar, que también conserva el sonido. La RAM verifica que el hook sigue funcionando con la música deshabilitada y se detiene al deshabilitar IRQ.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_vblank.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-vblank.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Select and restart a directly addressed song. This is not the banked WRAM-queue path.

void __stackcall AudioVBlank_PlayMusic(u8 *song)
{
    AudioVBlank_SetMusic(song);
    AudioVBlank_Play();
}

Consulte los cambios y la verificación del 2026-10-03 para las diferencias locales de esta API.

Activa la reproducción si el modo de cola está activo y hay al menos un registro disponible. Conserva los cursores, el retardo, la activación de la música y el estado de pausa. Reinicia y precarga la cola antes de iniciar un nuevo flujo.

Sintaxis

u8 AudioVBlank_QueuePlay();

Valor devuelto

Devuelve uno si se acepta la solicitud, o cero si la cola está vacía o no está activo el modo de cola. Para consumir registros, la ISR debe ejecutarse, la música debe estar activada y el controlador no debe estar en pausa.

Condiciones y límites

Después de AudioVBlank_Init, llama a QueueReset, QueueRefill y QueuePlay, en ese orden. Compila audio_vblank.c en su configuración normal; AUDIO_VBLANK_CORE_ONLY excluye las funciones C que alimentan la cola. El código principal llena una cola de dieciséis registros de cinco bytes y la rutina de interrupción VBlank los consume.

Usa un único productor en el código principal. No lo invoques de forma recursiva ni desde una ISR o FrameHook. Cada paso breve que hace disponible un registro guarda IE y enmascara las fuentes de interrupción; después restaura IE y SVBK. IME no cambia. El código que llama debe seleccionar y mantener el banco ROM/RAM de origen.

Los registros temporizados contienen delay, ch1_note, ch2_note, ch3_note y ch4_noise_param. END también debe ser un registro completo de cinco bytes. El productor debe implementar LOOP volviendo a enviar los registros necesarios. No pases sin convertir un flujo de comandos de reproducción directa de longitud variable.

Ejemplo de uso

if(AudioVBlank_QueuePlay()==0) sound_result[0]++;
    AudioVBlank_EnableIrq();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo reproduce seis veces una frase original de ocho notas y se detiene. Envía 49 registros —48 notas y END— a través de la cola de dieciséis posiciones. Comprueba que se acepten los 49, que no haya falta de datos, que la reproducción se detenga y que se gestionen la cola vacía o llena, el puntero nulo y el recuento cero. También verifica la restauración del banco WRAM de CGB, la conservación de IME, la emisión de sonido y el silencio al terminar.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\audio_vblank_queue.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\audio_vblank_queue.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Start/resume queued playback; return 1 on success, 0 for an empty/nonqueue mode.
Does not enable the interrupt, music gate or clear pause. Queue before starting.

u8 AudioVBlank_QueuePlay()
{
    u8 saved_ie;
    u8 started;
    saved_ie = AudioVBlank_IE;
    AudioVBlank_IE = 0;
    started = 0;
    if (AudioVBlank_QueueMode != 0 && AudioVBlank_QueueCount != 0) {
        AudioVBlank_MusicPlaying = 1;
        started = 1;
    }
    AudioVBlank_IE = saved_ie;
    return started;
}

Consulte los cambios y la verificación del 2026-10-03 para las diferencias locales de esta API.

Copia registros completos de cinco bytes en las posiciones libres y hace disponible cada uno solo después de terminar su copia. Una llamada acepta como máximo dieciséis registros.

Sintaxis

u8 __stackcall AudioVBlank_QueueRefill(const u8 *records, u8 count);

Parámetros

records

Matriz de registros situada en el banco actualmente legible. Debe haber cinco bytes legibles por cada registro aceptado. Un puntero nulo hace que se devuelva cero.

count

Número de registros que se intentará enviar, no de bytes. Los valores superiores a dieciséis se limitan a dieciséis; cero no hace nada.

Valor devuelto

Devuelve el número de registros realmente aceptados, de 0 a 16. Devuelve cero si la cola está llena, la entrada es nula, el recuento es cero o no está activo el modo de cola. Avanza el origen cinco veces el valor devuelto. La ISR puede liberar posiciones durante la llamada, por lo que el resultado no tiene por qué coincidir con el espacio libre al entrar.

Condiciones y límites

Después de AudioVBlank_Init, llama a QueueReset, QueueRefill y QueuePlay, en ese orden. Compila audio_vblank.c en su configuración normal; AUDIO_VBLANK_CORE_ONLY excluye las funciones C que alimentan la cola. El código principal llena una cola de dieciséis registros de cinco bytes y la rutina de interrupción VBlank los consume.

Usa un único productor en el código principal. No lo invoques de forma recursiva ni desde una ISR o FrameHook. Cada paso breve que hace disponible un registro guarda IE y enmascara las fuentes de interrupción; después restaura IE y SVBK. IME no cambia. El código que llama debe seleccionar y mantener el banco ROM/RAM de origen.

Los registros temporizados contienen delay, ch1_note, ch2_note, ch3_note y ch4_noise_param. END también debe ser un registro completo de cinco bytes. El productor debe implementar LOOP volviendo a enviar los registros necesarios. No pases sin convertir un flujo de comandos de reproducción directa de longitud variable.

Ejemplo de uso

next=AudioVBlank_QueueRefill(queue_song,16);
    // next counts records; each record occupies five source bytes.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo reproduce seis veces una frase original de ocho notas y se detiene. Envía 49 registros —48 notas y END— a través de la cola de dieciséis posiciones. Comprueba que se acepten los 49, que no haya falta de datos, que la reproducción se detenga y que se gestionen la cola vacía o llena, el puntero nulo y el recuento cero. También verifica la restauración del banco WRAM de CGB, la conservación de IME, la emisión de sonido y el silencio al terminar.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\audio_vblank_queue.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\audio_vblank_queue.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Copy complete records from the currently mapped source; return records accepted.
Each call attempts at most 16 records and stops when full. Null/zero returns 0.
Supports ROM and RAM sources, restores SVBK and IE, and never changes IME.
Single foreground producer only: do not call from an ISR or frame hook.
LOOP must be expanded by the producer. END occupies a full five-byte record.

u8 __stackcall AudioVBlank_QueueRefill(const u8 *records, u8 count)
{
    u8 accepted;
    u8 i;
    if (records == 0 || count == 0 || AudioVBlank_QueueMode == 0) return 0;
    if (count > AUDIO_VBLANK_QUEUE_RECORDS) count = AUDIO_VBLANK_QUEUE_RECORDS;
    accepted = 0;
    while (accepted < count) {
        if (AudioVBlank_QueueCount >= AUDIO_VBLANK_QUEUE_RECORDS) break;
        for (i = 0; i < 5; i++) AudioVBlank_QueueStaging[i] = records[i];
        if (AudioVBlank_QueuePublish() == 0) break;
        records += 5;
        accepted++;
    }
    return accepted;
}

Consulte los cambios y la verificación del 2026-10-03 para las diferencias locales de esta API.

Detiene y silencia la reproducción, selecciona el modo de cola y pone a cero las posiciones de lectura y escritura, el número de registros y el contador de falta de datos. Descarta los registros pendientes para preparar un nuevo flujo.

Sintaxis

void AudioVBlank_QueueReset();

Valor devuelto

No devuelve ningún valor. Conserva los ajustes de activación de la música y de pausa.

Condiciones y límites

Después de AudioVBlank_Init, llama a QueueReset, QueueRefill y QueuePlay, en ese orden. Compila audio_vblank.c en su configuración normal; AUDIO_VBLANK_CORE_ONLY excluye las funciones C que alimentan la cola. El código principal llena una cola de dieciséis registros de cinco bytes y la rutina de interrupción VBlank los consume.

Usa un único productor en el código principal. No lo invoques de forma recursiva ni desde una ISR o FrameHook. Cada paso breve que hace disponible un registro guarda IE y enmascara las fuentes de interrupción; después restaura IE y SVBK. IME no cambia. El código que llama debe seleccionar y mantener el banco ROM/RAM de origen.

Los registros temporizados contienen delay, ch1_note, ch2_note, ch3_note y ch4_noise_param. END también debe ser un registro completo de cinco bytes. El productor debe implementar LOOP volviendo a enviar los registros necesarios. No pases sin convertir un flujo de comandos de reproducción directa de longitud variable.

Ejemplo de uso

AudioVBlank_QueueReset(); // Silence playback and discard any queued records.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo reproduce seis veces una frase original de ocho notas y se detiene. Envía 49 registros —48 notas y END— a través de la cola de dieciséis posiciones. Comprueba que se acepten los 49, que no haya falta de datos, que la reproducción se detenga y que se gestionen la cola vacía o llena, el puntero nulo y el recuento cero. También verifica la restauración del banco WRAM de CGB, la conservación de IME, la emisión de sonido y el silencio al terminar.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\audio_vblank_queue.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\audio_vblank_queue.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Stop music and select an empty WRAM queue; preserve IE, IME and enable/pause gates.

void AudioVBlank_QueueReset()
{
    u8 saved_ie;
    saved_ie = AudioVBlank_IE;
    AudioVBlank_IE = 0;
    AudioVBlank_Stop();
    AudioVBlank_QueueMode = 1;
    AudioVBlank_QueueReadIndex = 0;
    AudioVBlank_QueueWriteIndex = 0;
    AudioVBlank_QueueCount = 0;
    AudioVBlank_QueueUnderruns = 0;
    AudioVBlank_IE = saved_ie;
}

Establece la solicitud 2 de solo liberación de pulso si no hay nada pendiente, conservando una solicitud de recuperación 1 existente.

Sintaxis

void AudioVBlank_RequestRestoreCh1();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

audio_vblank.c implementa __kq_vblank_vector; no instales además otro vector VBlank que compita con él. El ejemplo define Audio_NoiseEffectActive, excluye el decodificador musical normal y usa Audio_Update solo para efectos y fundidos. Bloquea las interrupciones al cambiar punteros de canción o estado compartido.

Al llamar directamente a la recuperación, el código que llama debe asegurarse de que el efecto haya liberado la voz y borrar después la bandera pendiente. Las funciones de solicitud por sí solas no escriben registros de sonido.

Ejemplo de uso

// Exercise the recovery API with IRQ disabled and explicit effect ownership.
#define SOUND_VBLANK
#include "gb_sound_example.h"
void main() {
    sound_begin("EFFECT RECOVERY");
    Audio_NoiseEffectActive=0; AudioVBlank_Init();
    Audio_SetMasterVolume(3,3);
    AudioVBlank_MusicPlaying=1;
    AudioVBlank_Ch1Envelope=0xC0; AudioVBlank_Ch1LatchedNote=33;
    AudioVBlank_Ch3LatchedNote=33;
    // Value 1 represents a suppressed BGM event and survives a release request.
    AudioVBlank_RestoreCh1Pending=1;
    AudioVBlank_RequestRestoreCh1();
    sound_result[0]=AudioVBlank_RestoreCh1Pending;
    AudioVBlank_RestoreCh1(); AudioVBlank_RestoreCh1Pending=0;
    sound_wait(30);
    // Without a pending event, RequestRestore creates release-only value 2.
    AudioVBlank_RequestRestoreCh1();
    sound_result[1]=AudioVBlank_RestoreCh1Pending;
    AudioVBlank_RestoreCh1(); AudioVBlank_RestoreCh1Pending=0;
    sound_wait(30);
    AudioVBlank_RestoreCh3Pending=1;
    AudioVBlank_RequestRestoreCh3();
    sound_result[2]=AudioVBlank_RestoreCh3Pending;
    AudioVBlank_RestoreCh3(); AudioVBlank_RestoreCh3Pending=0;
    sound_wait(30);
    AudioVBlank_RequestRestoreCh3();
    sound_result[3]=AudioVBlank_RestoreCh3Pending;
    AudioVBlank_RestoreCh3(); AudioVBlank_RestoreCh3Pending=0;
    sound_wait(30);
    AudioVBlank_Stop();
    sound_end();
}

Resultado esperado

Se oyen recuperación de pulso, silencio, recuperación de onda y silencio, cada uno durante 30 fotogramas. Una solicitud de liberación conserva el valor pendiente 1; sin evento pendiente produce el valor 2, solo liberación. Aquí IRQ está deshabilitado y el código que llama gestiona explícitamente el uso de los canales.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_recovery.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-recovery.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Request deferred pulse-channel release only when no recovery is pending.
Preserve value 1, which records a music event suppressed while an effect owned it.

void AudioVBlank_RequestRestoreCh1()
{
    if (AudioVBlank_RestoreCh1Pending == 0)
        AudioVBlank_RestoreCh1Pending = 2;
}

Establece la solicitud 2 de solo liberación de onda si no hay nada pendiente, conservando una solicitud de recuperación 1 existente.

Sintaxis

void AudioVBlank_RequestRestoreCh3();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

audio_vblank.c implementa __kq_vblank_vector; no instales además otro vector VBlank que compita con él. El ejemplo define Audio_NoiseEffectActive, excluye el decodificador musical normal y usa Audio_Update solo para efectos y fundidos. Bloquea las interrupciones al cambiar punteros de canción o estado compartido.

Al llamar directamente a la recuperación, el código que llama debe asegurarse de que el efecto haya liberado la voz y borrar después la bandera pendiente. Las funciones de solicitud por sí solas no escriben registros de sonido.

Ejemplo de uso

// Exercise the recovery API with IRQ disabled and explicit effect ownership.
#define SOUND_VBLANK
#include "gb_sound_example.h"
void main() {
    sound_begin("EFFECT RECOVERY");
    Audio_NoiseEffectActive=0; AudioVBlank_Init();
    Audio_SetMasterVolume(3,3);
    AudioVBlank_MusicPlaying=1;
    AudioVBlank_Ch1Envelope=0xC0; AudioVBlank_Ch1LatchedNote=33;
    AudioVBlank_Ch3LatchedNote=33;
    // Value 1 represents a suppressed BGM event and survives a release request.
    AudioVBlank_RestoreCh1Pending=1;
    AudioVBlank_RequestRestoreCh1();
    sound_result[0]=AudioVBlank_RestoreCh1Pending;
    AudioVBlank_RestoreCh1(); AudioVBlank_RestoreCh1Pending=0;
    sound_wait(30);
    // Without a pending event, RequestRestore creates release-only value 2.
    AudioVBlank_RequestRestoreCh1();
    sound_result[1]=AudioVBlank_RestoreCh1Pending;
    AudioVBlank_RestoreCh1(); AudioVBlank_RestoreCh1Pending=0;
    sound_wait(30);
    AudioVBlank_RestoreCh3Pending=1;
    AudioVBlank_RequestRestoreCh3();
    sound_result[2]=AudioVBlank_RestoreCh3Pending;
    AudioVBlank_RestoreCh3(); AudioVBlank_RestoreCh3Pending=0;
    sound_wait(30);
    AudioVBlank_RequestRestoreCh3();
    sound_result[3]=AudioVBlank_RestoreCh3Pending;
    AudioVBlank_RestoreCh3(); AudioVBlank_RestoreCh3Pending=0;
    sound_wait(30);
    AudioVBlank_Stop();
    sound_end();
}

Resultado esperado

Se oyen recuperación de pulso, silencio, recuperación de onda y silencio, cada uno durante 30 fotogramas. Una solicitud de liberación conserva el valor pendiente 1; sin evento pendiente produce el valor 2, solo liberación. Aquí IRQ está deshabilitado y el código que llama gestiona explícitamente el uso de los canales.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_recovery.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-recovery.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Request a deferred wave-channel release only if no recovery is pending.
Preserve value 1, which records a new music event suppressed by the effect.

void AudioVBlank_RequestRestoreCh3()
{
    if (AudioVBlank_RestoreCh3Pending == 0)
        AudioVBlank_RestoreCh3Pending = 2;
}

Restaura una nota musical retenida en la voz de pulsos prestada al efecto (CH1 o CH2), o la libera en silencio.

Sintaxis

void AudioVBlank_RestoreCh1();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

audio_vblank.c implementa __kq_vblank_vector; no instales además otro vector VBlank que compita con él. El ejemplo define Audio_NoiseEffectActive, excluye el decodificador musical normal y usa Audio_Update solo para efectos y fundidos. Bloquea las interrupciones al cambiar punteros de canción o estado compartido.

Al llamar directamente a la recuperación, el código que llama debe asegurarse de que el efecto haya liberado la voz y borrar después la bandera pendiente. Las funciones de solicitud por sí solas no escriben registros de sonido.

Ejemplo de uso

// Exercise the recovery API with IRQ disabled and explicit effect ownership.
#define SOUND_VBLANK
#include "gb_sound_example.h"
void main() {
    sound_begin("EFFECT RECOVERY");
    Audio_NoiseEffectActive=0; AudioVBlank_Init();
    Audio_SetMasterVolume(3,3);
    AudioVBlank_MusicPlaying=1;
    AudioVBlank_Ch1Envelope=0xC0; AudioVBlank_Ch1LatchedNote=33;
    AudioVBlank_Ch3LatchedNote=33;
    // Value 1 represents a suppressed BGM event and survives a release request.
    AudioVBlank_RestoreCh1Pending=1;
    AudioVBlank_RequestRestoreCh1();
    sound_result[0]=AudioVBlank_RestoreCh1Pending;
    AudioVBlank_RestoreCh1(); AudioVBlank_RestoreCh1Pending=0;
    sound_wait(30);
    // Without a pending event, RequestRestore creates release-only value 2.
    AudioVBlank_RequestRestoreCh1();
    sound_result[1]=AudioVBlank_RestoreCh1Pending;
    AudioVBlank_RestoreCh1(); AudioVBlank_RestoreCh1Pending=0;
    sound_wait(30);
    AudioVBlank_RestoreCh3Pending=1;
    AudioVBlank_RequestRestoreCh3();
    sound_result[2]=AudioVBlank_RestoreCh3Pending;
    AudioVBlank_RestoreCh3(); AudioVBlank_RestoreCh3Pending=0;
    sound_wait(30);
    AudioVBlank_RequestRestoreCh3();
    sound_result[3]=AudioVBlank_RestoreCh3Pending;
    AudioVBlank_RestoreCh3(); AudioVBlank_RestoreCh3Pending=0;
    sound_wait(30);
    AudioVBlank_Stop();
    sound_end();
}

Resultado esperado

Se oyen recuperación de pulso, silencio, recuperación de onda y silencio, cada uno durante 30 fotogramas. Una solicitud de liberación conserva el valor pendiente 1; sin evento pendiente produce el valor 2, solo liberación. Aquí IRQ está deshabilitado y el código que llama gestiona explícitamente el uso de los canales.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_recovery.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-recovery.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Recover the borrowed pulse channel (CH1 or CH2) from its latched music event.
Pending value 2, disabled music, or a non-note latch silences it instead.
The caller must first establish that the effect has released the channel.

void AudioVBlank_RestoreCh1()
{
    __asm {
        LD_A_MEM Audio_EffectUsesCh2
        OR_A
        JR_NZ audiovb_restore_ch2
        LD_A_MEM AudioVBlank_RestoreCh1Pending
        CP_IMM 2
        JR_Z audiovb_restore_ch1_off
        LD_A_MEM AudioVBlank_MusicPlaying
        OR_A
        JR_Z audiovb_restore_ch1_off
        LD_A_MEM AudioVBlank_MusicEnabled
        OR_A
        JR_Z audiovb_restore_ch1_off
        LD_A_MEM Audio_MusicEnabled
        OR_A
        JR_Z audiovb_restore_ch1_off
        LD_A_MEM AudioVBlank_Ch1LatchedNote
        CP_IMM 0x44
        JR_NC audiovb_restore_ch1_off
        LD_C_A
        LD_A_MEM AudioVBlank_Ch1Sweep
        LDH_MEM_A 0x10
        LD_A_MEM AudioVBlank_Ch1Duty
        LDH_MEM_A 0x11
        LD_A_MEM AudioVBlank_Ch1Envelope
        LDH_MEM_A 0x12
        LD_A_C
        LD_E_A
        LD_D_IMM 0
        LD_HL_IMM AudioVBlank_FreqLo
        ADD_HL_DE
        LD_A_HL
        LDH_MEM_A 0x13
        LD_HL_IMM AudioVBlank_FreqHi
        ADD_HL_DE
        LD_A_HL
        OR_IMM 0x80
        LDH_MEM_A 0x14
        JR audiovb_restore_ch1_done
audiovb_restore_ch1_off:
        XOR_A
        LDH_MEM_A 0x12
audiovb_restore_ch1_done:
        JR audiovb_restore_square_done

audiovb_restore_ch2:
        LD_A_MEM AudioVBlank_RestoreCh1Pending
        CP_IMM 2
        JR_Z audiovb_restore_ch2_off
        LD_A_MEM AudioVBlank_MusicPlaying
        OR_A
        JR_Z audiovb_restore_ch2_off
        LD_A_MEM AudioVBlank_MusicEnabled
        OR_A
        JR_Z audiovb_restore_ch2_off
        LD_A_MEM Audio_MusicEnabled
        OR_A
        JR_Z audiovb_restore_ch2_off
        LD_A_MEM AudioVBlank_Ch2LatchedNote
        CP_IMM 0x44
        JR_NC audiovb_restore_ch2_off
        LD_C_A
        LD_A_MEM AudioVBlank_Ch2Duty
        LDH_MEM_A 0x16
        LD_A_MEM AudioVBlank_Ch2Envelope
        LDH_MEM_A 0x17
        LD_A_C
        LD_E_A
        LD_D_IMM 0
        LD_HL_IMM AudioVBlank_FreqLo
        ADD_HL_DE
        LD_A_HL
        LDH_MEM_A 0x18
        LD_HL_IMM AudioVBlank_FreqHi
        ADD_HL_DE
        LD_A_HL
        OR_IMM 0x80
        LDH_MEM_A 0x19
        JR audiovb_restore_square_done
audiovb_restore_ch2_off:
        XOR_A
        LDH_MEM_A 0x17
audiovb_restore_square_done:
    }
}

Restaura la nota retenida de CH3 tras liberar el efecto, o deshabilita su DAC.

Sintaxis

void AudioVBlank_RestoreCh3();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

audio_vblank.c implementa __kq_vblank_vector; no instales además otro vector VBlank que compita con él. El ejemplo define Audio_NoiseEffectActive, excluye el decodificador musical normal y usa Audio_Update solo para efectos y fundidos. Bloquea las interrupciones al cambiar punteros de canción o estado compartido.

Al llamar directamente a la recuperación, el código que llama debe asegurarse de que el efecto haya liberado la voz y borrar después la bandera pendiente. Las funciones de solicitud por sí solas no escriben registros de sonido.

Ejemplo de uso

// Exercise the recovery API with IRQ disabled and explicit effect ownership.
#define SOUND_VBLANK
#include "gb_sound_example.h"
void main() {
    sound_begin("EFFECT RECOVERY");
    Audio_NoiseEffectActive=0; AudioVBlank_Init();
    Audio_SetMasterVolume(3,3);
    AudioVBlank_MusicPlaying=1;
    AudioVBlank_Ch1Envelope=0xC0; AudioVBlank_Ch1LatchedNote=33;
    AudioVBlank_Ch3LatchedNote=33;
    // Value 1 represents a suppressed BGM event and survives a release request.
    AudioVBlank_RestoreCh1Pending=1;
    AudioVBlank_RequestRestoreCh1();
    sound_result[0]=AudioVBlank_RestoreCh1Pending;
    AudioVBlank_RestoreCh1(); AudioVBlank_RestoreCh1Pending=0;
    sound_wait(30);
    // Without a pending event, RequestRestore creates release-only value 2.
    AudioVBlank_RequestRestoreCh1();
    sound_result[1]=AudioVBlank_RestoreCh1Pending;
    AudioVBlank_RestoreCh1(); AudioVBlank_RestoreCh1Pending=0;
    sound_wait(30);
    AudioVBlank_RestoreCh3Pending=1;
    AudioVBlank_RequestRestoreCh3();
    sound_result[2]=AudioVBlank_RestoreCh3Pending;
    AudioVBlank_RestoreCh3(); AudioVBlank_RestoreCh3Pending=0;
    sound_wait(30);
    AudioVBlank_RequestRestoreCh3();
    sound_result[3]=AudioVBlank_RestoreCh3Pending;
    AudioVBlank_RestoreCh3(); AudioVBlank_RestoreCh3Pending=0;
    sound_wait(30);
    AudioVBlank_Stop();
    sound_end();
}

Resultado esperado

Se oyen recuperación de pulso, silencio, recuperación de onda y silencio, cada uno durante 30 fotogramas. Una solicitud de liberación conserva el valor pendiente 1; sin evento pendiente produce el valor 2, solo liberación. Aquí IRQ está deshabilitado y el código que llama gestiona explícitamente el uso de los canales.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_recovery.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-recovery.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Recover a latched wave-channel music event after effect release, or disable
the DAC for a release-only request, disabled music, or a non-note latch.
The caller owns effect arbitration and clearing the pending flag.

void AudioVBlank_RestoreCh3()
{
    __asm {
        LD_A_MEM AudioVBlank_RestoreCh3Pending
        CP_IMM 2
        JR_Z audiovb_restore_ch3_off
        LD_A_MEM AudioVBlank_MusicPlaying
        OR_A
        JR_Z audiovb_restore_ch3_off
        LD_A_MEM AudioVBlank_MusicEnabled
        OR_A
        JR_Z audiovb_restore_ch3_off
        LD_A_MEM Audio_MusicEnabled
        OR_A
        JR_Z audiovb_restore_ch3_off
        LD_A_MEM AudioVBlank_Ch3LatchedNote
        CP_IMM 0x44
        JR_NC audiovb_restore_ch3_off
        LD_C_A
        LD_A_IMM 0x80
        LDH_MEM_A 0x1A
        XOR_A
        LDH_MEM_A 0x1B
        LD_A_MEM AudioVBlank_Ch3Level
        LDH_MEM_A 0x1C
        LD_A_C
        LD_E_A
        LD_D_IMM 0
        LD_HL_IMM AudioVBlank_FreqLo
        ADD_HL_DE
        LD_A_HL
        LDH_MEM_A 0x1D
        LD_HL_IMM AudioVBlank_FreqHi
        ADD_HL_DE
        LD_A_HL
        OR_IMM 0x80
        LDH_MEM_A 0x1E
        JR audiovb_restore_ch3_done
audiovb_restore_ch3_off:
        XOR_A
        LDH_MEM_A 0x1A
audiovb_restore_ch3_done:
    }
}

Permite o bloquea la música VBlank y borra las solicitudes de recuperación al deshabilitarla. El sonido actual e IRQ no cambian.

Sintaxis

void __stackcall AudioVBlank_SetEnabled(u8 on);

Parámetros

on

Cero deshabilita y un valor no nulo habilita. Consulta la descripción para distinguir entre silenciar y bloquear las actualizaciones.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

audio_vblank.c implementa __kq_vblank_vector; no instales además otro vector VBlank que compita con él. El ejemplo define Audio_NoiseEffectActive, excluye el decodificador musical normal y usa Audio_Update solo para efectos y fundidos. Bloquea las interrupciones al cambiar punteros de canción o estado compartido.

Guarda los datos de canción de lectura directa en ROM fija u otra zona siempre visible para la ISR. Cada registro tiene cinco bytes: delay, CH1, CH2, CH3, CH4. En los campos de nota, 0xFF mantiene la voz y 0xFD la detiene. En delay, 0xFF termina la reproducción y 0xFE repite. Es la disposición del registro, no la numeración de canales. La reproducción por cola WRAM es otro modo; envía registros completos de cinco bytes con AudioVBlank_QueueRefill.

Ejemplo de uso

// Direct fixed-bank music with an actual VBlank ISR and a counting frame hook.
#define SOUND_VBLANK
#include "gb_sound_example.h"
__wram u8 hook_count;
__prg_rom u8 irq_song[]={30,33,0xFF,0xFF,0xFF,30,40,0xFF,0xFF,0xFF,0xFE};
void frame_hook() { hook_count++; }
void main() {
    u8 before;
    sound_begin("VBLANK MUSIC GATES");
    Audio_NoiseEffectActive=0;
    AudioVBlank_Init();
    sound_result[0]=AudioVBlank_MusicPlaying;
    AudioVBlank_Ch1Envelope=0xC0;
    Audio_SetMasterVolume(3,3);
    hook_count=0; AudioVBlank_FrameHook=frame_hook;
    AudioVBlank_SetMusic(irq_song);
    AudioVBlank_Play();
    AudioVBlank_EnableIrq();
    sound_wait(45);
    // Disable music processing while the hook and current note remain active.
    __asm { DI }
    AudioVBlank_SetEnabled(0); before=hook_count;
    __asm { EI }
    sound_wait(30);
    sound_result[1]=(u8)(hook_count!=before);
    __asm { DI }
    AudioVBlank_Stop();
    __asm { EI }
    sound_wait(30);
    __asm { DI }
    AudioVBlank_SetEnabled(1); AudioVBlank_PlayMusic(irq_song);
    __asm { EI }
    sound_wait(45);
    AudioVBlank_DisableIrq();
    before=hook_count;
    sound_wait(30);
    sound_result[2]=(u8)(hook_count==before);
    sound_result[3]=(u8)(AudioVBlank_IE&1);
    AudioVBlank_Stop(); sound_wait(30);
    sound_end();
}

Resultado esperado

La ISR toca una canción de dos notas. Compara bloquear las actualizaciones musicales, que conserva el sonido; Stop, que lo silencia; y bloquear IRQ tras reiniciar, que también conserva el sonido. La RAM verifica que el hook sigue funcionando con la música deshabilitada y se detiene al deshabilitar IRQ.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_vblank.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-vblank.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Gate music processing and clear pending CH1/CH3 recovery on disable.
No audio register is written here: disabling does not itself silence a note
already playing or disable the VBlank interrupt.

void __stackcall AudioVBlank_SetEnabled(u8 on)
{
    if (on != 0) AudioVBlank_MusicEnabled = 1;
    else {
        AudioVBlank_MusicEnabled = 0;
        // Do not carry a stale SFX-recovery request into a later song.
        AudioVBlank_RestoreCh1Pending = 0;
        AudioVBlank_RestoreCh3Pending = 0;
    }
}

Selecciona una canción de lectura directa y reinicia sus cursores sin cambiar la bandera de reproducción.

Sintaxis

void __stackcall AudioVBlank_SetMusic(u8 *song);

Parámetros

song

Dirección inicial de la canción. El controlador usa el array prestado, que debe seguir siendo legible durante toda la reproducción.

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

audio_vblank.c implementa __kq_vblank_vector; no instales además otro vector VBlank que compita con él. El ejemplo define Audio_NoiseEffectActive, excluye el decodificador musical normal y usa Audio_Update solo para efectos y fundidos. Bloquea las interrupciones al cambiar punteros de canción o estado compartido.

Guarda los datos de canción de lectura directa en ROM fija u otra zona siempre visible para la ISR. Cada registro tiene cinco bytes: delay, CH1, CH2, CH3, CH4. En los campos de nota, 0xFF mantiene la voz y 0xFD la detiene. En delay, 0xFF termina la reproducción y 0xFE repite. Es la disposición del registro, no la numeración de canales. La reproducción por cola WRAM es otro modo; envía registros completos de cinco bytes con AudioVBlank_QueueRefill.

Ejemplo de uso

// Direct fixed-bank music with an actual VBlank ISR and a counting frame hook.
#define SOUND_VBLANK
#include "gb_sound_example.h"
__wram u8 hook_count;
__prg_rom u8 irq_song[]={30,33,0xFF,0xFF,0xFF,30,40,0xFF,0xFF,0xFF,0xFE};
void frame_hook() { hook_count++; }
void main() {
    u8 before;
    sound_begin("VBLANK MUSIC GATES");
    Audio_NoiseEffectActive=0;
    AudioVBlank_Init();
    sound_result[0]=AudioVBlank_MusicPlaying;
    AudioVBlank_Ch1Envelope=0xC0;
    Audio_SetMasterVolume(3,3);
    hook_count=0; AudioVBlank_FrameHook=frame_hook;
    AudioVBlank_SetMusic(irq_song);
    AudioVBlank_Play();
    AudioVBlank_EnableIrq();
    sound_wait(45);
    // Disable music processing while the hook and current note remain active.
    __asm { DI }
    AudioVBlank_SetEnabled(0); before=hook_count;
    __asm { EI }
    sound_wait(30);
    sound_result[1]=(u8)(hook_count!=before);
    __asm { DI }
    AudioVBlank_Stop();
    __asm { EI }
    sound_wait(30);
    __asm { DI }
    AudioVBlank_SetEnabled(1); AudioVBlank_PlayMusic(irq_song);
    __asm { EI }
    sound_wait(45);
    AudioVBlank_DisableIrq();
    before=hook_count;
    sound_wait(30);
    sound_result[2]=(u8)(hook_count==before);
    sound_result[3]=(u8)(AudioVBlank_IE&1);
    AudioVBlank_Stop(); sound_wait(30);
    sound_end();
}

Resultado esperado

La ISR toca una canción de dos notas. Compara bloquear las actualizaciones musicales, que conserva el sonido; Stop, que lo silencia; y bloquear IRQ tras reiniciar, que también conserva el sonido. La RAM verifica que el hook sigue funcionando con la música deshabilitada y se detiene al deshabilitar IRQ.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_vblank.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-vblank.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Select a directly addressed song and reset its cursors, leaving the playing
flag unchanged. Song storage must remain accessible to the fixed-bank ISR;
coordinate this multi-field update with interrupt execution.

void __stackcall AudioVBlank_SetMusic(u8 *song)
{
    AudioVBlank_MusicStart = song;
    AudioVBlank_MusicPointer = song;
    AudioVBlank_MusicLoopPoint = song;
    AudioVBlank_MusicDelay = 0;
    AudioVBlank_Step = 0;
    AudioVBlank_QueueMode = 0;
}

Borra los estados de reproducción, delay y recuperación, y silencia inmediatamente pulsos, ruido y onda. IRQ sigue habilitado.

Sintaxis

void AudioVBlank_Stop();

Valor devuelto

Sin valor de retorno. Modifica registros de sonido o el estado del controlador.

Condiciones y límites

audio_vblank.c implementa __kq_vblank_vector; no instales además otro vector VBlank que compita con él. El ejemplo define Audio_NoiseEffectActive, excluye el decodificador musical normal y usa Audio_Update solo para efectos y fundidos. Bloquea las interrupciones al cambiar punteros de canción o estado compartido.

Guarda los datos de canción de lectura directa en ROM fija u otra zona siempre visible para la ISR. Cada registro tiene cinco bytes: delay, CH1, CH2, CH3, CH4. En los campos de nota, 0xFF mantiene la voz y 0xFD la detiene. En delay, 0xFF termina la reproducción y 0xFE repite. Es la disposición del registro, no la numeración de canales. La reproducción por cola WRAM es otro modo; envía registros completos de cinco bytes con AudioVBlank_QueueRefill.

Ejemplo de uso

// Direct fixed-bank music with an actual VBlank ISR and a counting frame hook.
#define SOUND_VBLANK
#include "gb_sound_example.h"
__wram u8 hook_count;
__prg_rom u8 irq_song[]={30,33,0xFF,0xFF,0xFF,30,40,0xFF,0xFF,0xFF,0xFE};
void frame_hook() { hook_count++; }
void main() {
    u8 before;
    sound_begin("VBLANK MUSIC GATES");
    Audio_NoiseEffectActive=0;
    AudioVBlank_Init();
    sound_result[0]=AudioVBlank_MusicPlaying;
    AudioVBlank_Ch1Envelope=0xC0;
    Audio_SetMasterVolume(3,3);
    hook_count=0; AudioVBlank_FrameHook=frame_hook;
    AudioVBlank_SetMusic(irq_song);
    AudioVBlank_Play();
    AudioVBlank_EnableIrq();
    sound_wait(45);
    // Disable music processing while the hook and current note remain active.
    __asm { DI }
    AudioVBlank_SetEnabled(0); before=hook_count;
    __asm { EI }
    sound_wait(30);
    sound_result[1]=(u8)(hook_count!=before);
    __asm { DI }
    AudioVBlank_Stop();
    __asm { EI }
    sound_wait(30);
    __asm { DI }
    AudioVBlank_SetEnabled(1); AudioVBlank_PlayMusic(irq_song);
    __asm { EI }
    sound_wait(45);
    AudioVBlank_DisableIrq();
    before=hook_count;
    sound_wait(30);
    sound_result[2]=(u8)(hook_count==before);
    sound_result[3]=(u8)(AudioVBlank_IE&1);
    AudioVBlank_Stop(); sound_wait(30);
    sound_end();
}

Resultado esperado

La ISR toca una canción de dos notas. Compara bloquear las actualizaciones musicales, que conserva el sonido; Stop, que lo silencia; y bloquear IRQ tras reiniciar, que también conserva el sonido. La RAM verifica que el hook sigue funcionando con la música deshabilitada y se detiene al deshabilitar IRQ.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\sound_vblank.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\gb-vblank.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --no-cache --no-disasm

Stop software playback and silence pulse/noise envelopes and the wave DAC.
Song pointers and the IRQ enable remain unchanged; the routine writes the
physical channels directly, so coordinate ownership with sound effects.

void AudioVBlank_Stop()
{
    AudioVBlank_MusicPlaying = 0;
    AudioVBlank_MusicDelay = 0;
    AudioVBlank_Step = 0;
    AudioVBlank_Ch2Note = AUDIO_VBLANK_REST;
    AudioVBlank_Ch1Note = AUDIO_VBLANK_REST;
    AudioVBlank_Ch3Note = AUDIO_VBLANK_REST;
    AudioVBlank_Ch2LatchedNote = AUDIO_VBLANK_STOP;
    AudioVBlank_Ch1LatchedNote = AUDIO_VBLANK_STOP;
    AudioVBlank_Ch3LatchedNote = AUDIO_VBLANK_STOP;
    AudioVBlank_RestoreCh1Pending = 0;
    AudioVBlank_RestoreCh3Pending = 0;
    AudioVBlank_Ch4Param = AUDIO_VBLANK_REST;
    __asm {
        XOR_A
        LDH_MEM_A 0x12
        LDH_MEM_A 0x17
        LDH_MEM_A 0x1C
        LDH_MEM_A 0x1A
        LDH_MEM_A 0x21
    }
}

Devuelve el último número de banco guardado por bank_switch. Lee un registro de software, no los registros del cartucho.

Sintaxis

u8 bank_get_current();

Valor devuelto

El valor u8 guardado por la última llamada a bank_switch; cero antes de inicializarlo.

Condiciones y límites

El registro de la biblioteca empieza en cero y no detecta el mapa inicial del cartucho. Inicialízalo con bank_switch. Las intrínsecas y las escrituras directas al mapper no actualizan este registro separado; bank_get_current no permite verificar el mapa real del hardware.

Ejemplo de uso

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

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

bank_switch(2) registra y selecciona inicialmente el banco 2. Después, el cambio directo selecciona el banco 1 y lee A1 de home1 mientras bank_get_current sigue indicando 2; al volver, home2 devuelve B2 otra vez.

El programa completo enseña a identificar datos con un banco y una dirección cercana, a llamar callbacks entre bancos y a distinguir el registro de la biblioteca del mapa real. Todos los números se muestran en hexadecimal. BANK IN y BANK OUT deben ser 02; BYTE HEX, D3; WORD HEX, 5C7A; FAILED CHECKS y FIRST FAILURE, 00. CGB y FC muestran texto azul; DMG, negro.

CALL COUNT muestra 03: far_call, __farcall y __farcall_ptr invocan el callback una vez cada uno.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Return the last bank recorded by bank_switch; this does not read cartridge hardware.

u8 bank_get_current()
{
    return kq_bank_current;
}

Consulte los cambios y la verificación del 2026-10-03 para las diferencias locales de esta API.

Selecciona el banco ROM y registra su número tanto en la biblioteca bank como en el estado del compilador. Las lecturas y llamadas lejanas usan este último para restaurar el banco anterior.

Sintaxis

void bank_switch(u8 bank);

Parámetros

bank

Número de banco ROM de 8 bits sin signo. En una llamada debe coincidir con la ubicación de la función; en una lectura selecciona el origen. Usa el intervalo válido para el cartucho.

Valor devuelto

Ninguno (void).

Condiciones y límites

Un cambio de banco persistente no debe retirar el código en ejecución ni su dirección de retorno. Coloca esta llamada, la propia bank_switch cuando se use y el código posterior en el banco común o fijo 0, como hace el ejemplo.

El registro de la biblioteca empieza en cero y no detecta el mapa inicial del cartucho. Inicialízalo con bank_switch. Las intrínsecas y las escrituras directas al mapper no actualizan este registro separado; bank_get_current no permite verificar el mapa real del hardware.

Estas interfaces GB manejan ocho bits de banco y no ajustan el noveno bit de MBC5. Siguen vigentes las reglas del cartucho, incluido el tratamiento del banco cero. El ejemplo usa explícitamente los bancos MBC5 1–3; no mezcles este estado con escrituras al mapper sin registrar.

Ejemplo de uso

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

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

bank_switch(2) registra y selecciona inicialmente el banco 2. Después, el cambio directo selecciona el banco 1 y lee A1 de home1 mientras bank_get_current sigue indicando 2; al volver, home2 devuelve B2 otra vez.

El programa completo enseña a identificar datos con un banco y una dirección cercana, a llamar callbacks entre bancos y a distinguir el registro de la biblioteca del mapa real. Todos los números se muestran en hexadecimal. BANK IN y BANK OUT deben ser 02; BYTE HEX, D3; WORD HEX, 5C7A; FAILED CHECKS y FIRST FAILURE, 00. CGB y FC muestran texto azul; DMG, negro.

CALL COUNT muestra 03: far_call, __farcall y __farcall_ptr invocan el callback una vez cada uno.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Update both the library bank record and the compiler shadow used by far
reads and calls. Invoke this permanent bank change from fixed-bank code.

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

Pasa un número de banco y un puntero de callback a __farcall_ptr. Esta función de biblioteca ejecuta el callback sin argumentos y vuelve una vez restaurado el banco del llamador.

Sintaxis

void far_call(u8 bank, const void* func);

Parámetros

bank

Número de banco ROM de 8 bits sin signo. En una llamada debe coincidir con la ubicación de la función; en una lectura selecciona el origen. Usa el intervalo válido para el cartucho.

func

Dirección ejecutable válida de un callback sin parámetros. Puede darse como nombre de función o puntero de ejecución. No se comprueban en ejecución los punteros nulos ni una combinación incorrecta de banco y dirección.

Valor devuelto

Ninguno (void).

Condiciones y límites

Estas llamadas no pasan argumentos del usuario ni hacen que el callback admita reentrada por interrupciones. Gestiona correctamente sus datos, pila e interrupciones. La restauración de bancos se prueba con llamadas anidadas y repetidas; el ejemplo no cubre hardware físico ni cualquier posible intercalado de interrupciones.

Estas interfaces GB manejan ocho bits de banco y no ajustan el noveno bit de MBC5. Siguen vigentes las reglas del cartucho, incluido el tratamiento del banco cero. El ejemplo usa explícitamente los bancos MBC5 1–3; no mezcles este estado con escrituras al mapper sin registrar.

Ejemplo de uso

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

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

En este punto del programa completo, far_call eleva callback_count a 1. El callback lee D3 del banco 3. Una lectura cercana posterior de B2 en home2 verifica el retorno con el banco 2 seleccionado.

El programa completo enseña a identificar datos con un banco y una dirección cercana, a llamar callbacks entre bancos y a distinguir el registro de la biblioteca del mapa real. Todos los números se muestran en hexadecimal. BANK IN y BANK OUT deben ser 02; BYTE HEX, D3; WORD HEX, 5C7A; FAILED CHECKS y FIRST FAILURE, 00. CGB y FC muestran texto azul; DMG, negro.

CALL COUNT muestra 03: far_call, __farcall y __farcall_ptr invocan el callback una vez cada uno.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Invoke a no-argument callback in its ROM bank, then restore the caller
bank. The pointer must identify executable code; no arguments are forwarded.

void far_call(u8 bank, const void* func)
{
    __farcall_ptr(bank, func);
}

Copia len bytes del banco ROM indicado a la RAM del llamador mediante la intrínseca de copia lejana. Restaura el banco anterior antes de volver.

Sintaxis

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

Parámetros

bank

Número de banco ROM de 8 bits sin signo. En una llamada debe coincidir con la ubicación de la función; en una lectura selecciona el origen. Usa el intervalo válido para el cartucho.

addr

Puntero cercano a bytes legibles del banco de ROM seleccionado. No incluye el número de banco.

dst

Destino en memoria escribible, con espacio para todos los bytes copiados. Salvo en una transferencia de cero bytes, no se comprueba si el destino es nulo o inválido.

len

Cantidad de bytes, de 0 a 65535. Con cero no se copia memoria, pero sí se selecciona y restaura el banco.

Valor devuelto

Ninguno (void).

Condiciones y límites

Mantenga todo el origen en el mapeo de ROM previsto y todo el destino en memoria escribible. La copia no cambia automáticamente de banco al cruzar una ventana, no trata solapamientos como memmove ni sincroniza escrituras en VRAM. Para VRAM, use las API de transferencia gráfica.

Las lecturas y copias lejanas son síncronas y usan memoria de trabajo compartida del compilador. No dejes que una interrupción ejecute otra transferencia sobre esa memoria mientras está en uso. En GB, la copia también guarda el banco anterior en una posición HRAM compartida. El ejemplo ejecuta las operaciones desde código fijo, sin un manejador de transferencia que compita.

Estas interfaces GB manejan ocho bits de banco y no ajustan el noveno bit de MBC5. Siguen vigentes las reglas del cartucho, incluido el tratamiento del banco cero. El ejemplo usa explícitamente los bancos MBC5 1–3; no mezcles este estado con escrituras al mapper sin registrar.

Ejemplo de uso

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

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Este fragmento copia 4 bytes mediante far_data_read y contrasta el búfer con D3 7A 5C 96. El llamador conserva su descriptor o puntero de origen; el programa completo comprueba aparte una copia de longitud cero y la restauración del banco.

El programa completo enseña a identificar datos con un banco y una dirección cercana, a llamar callbacks entre bancos y a distinguir el registro de la biblioteca del mapa real. Todos los números se muestran en hexadecimal. BANK IN y BANK OUT deben ser 02; BYTE HEX, D3; WORD HEX, 5C7A; FAILED CHECKS y FIRST FAILURE, 00. CGB y FC muestran texto azul; DMG, negro.

CALL COUNT muestra 03: far_call, __farcall y __farcall_ptr invocan el callback una vez cada uno.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

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

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

Lee dos bytes consecutivos mediante __farpeek16 y forma una palabra little-endian. El primer byte ocupa los ocho bits bajos.

Sintaxis

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

Parámetros

bank

Número de banco ROM de 8 bits sin signo. En una llamada debe coincidir con la ubicación de la función; en una lectura selecciona el origen. Usa el intervalo válido para el cartucho.

addr

Puntero cercano a bytes legibles del banco de ROM seleccionado. No incluye el número de banco.

Valor devuelto

La palabra little-endian leída, como u16 (0–65535).

Condiciones y límites

El byte o la palabra completos deben ser legibles en el mapa CPU seleccionado. No se validan punteros, no se recortan direcciones ni se cambia automáticamente de banco al cruzar una ventana. Una palabra necesita dos bytes consecutivos válidos.

Las lecturas y copias lejanas son síncronas y usan memoria de trabajo compartida del compilador. No dejes que una interrupción ejecute otra transferencia sobre esa memoria mientras está en uso. En GB, la copia también guarda el banco anterior en una posición HRAM compartida. El ejemplo ejecuta las operaciones desde código fijo, sin un manejador de transferencia que compita.

Estas interfaces GB manejan ocho bits de banco y no ajustan el noveno bit de MBC5. Siguen vigentes las reglas del cartucho, incluido el tratamiento del banco cero. El ejemplo usa explícitamente los bancos MBC5 1–3; no mezcles este estado con escrituras al mapper sin registrar.

Ejemplo de uso

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

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Este fragmento usa far_data_read16 para leer payload+1 del banco 3 y comprueba 5C7A. El programa completo también lee home2 con un puntero cercano para confirmar que se ha restaurado el banco 2.

El programa completo enseña a identificar datos con un banco y una dirección cercana, a llamar callbacks entre bancos y a distinguir el registro de la biblioteca del mapa real. Todos los números se muestran en hexadecimal. BANK IN y BANK OUT deben ser 02; BYTE HEX, D3; WORD HEX, 5C7A; FAILED CHECKS y FIRST FAILURE, 00. CGB y FC muestran texto azul; DMG, negro.

CALL COUNT muestra 03: far_call, __farcall y __farcall_ptr invocan el callback una vez cada uno.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Read a 16-bit value from the supplied bank and address through the far-read intrinsic.

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

Lee un byte del banco ROM y la dirección indicados mediante __farpeek8; restaura el banco anterior y devuelve el valor.

Sintaxis

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

Parámetros

bank

Número de banco ROM de 8 bits sin signo. En una llamada debe coincidir con la ubicación de la función; en una lectura selecciona el origen. Usa el intervalo válido para el cartucho.

addr

Puntero cercano a bytes legibles del banco de ROM seleccionado. No incluye el número de banco.

Valor devuelto

El byte leído, como u8 (0–255).

Condiciones y límites

El byte o la palabra completos deben ser legibles en el mapa CPU seleccionado. No se validan punteros, no se recortan direcciones ni se cambia automáticamente de banco al cruzar una ventana. Una palabra necesita dos bytes consecutivos válidos.

Las lecturas y copias lejanas son síncronas y usan memoria de trabajo compartida del compilador. No dejes que una interrupción ejecute otra transferencia sobre esa memoria mientras está en uso. En GB, la copia también guarda el banco anterior en una posición HRAM compartida. El ejemplo ejecuta las operaciones desde código fijo, sin un manejador de transferencia que compita.

Estas interfaces GB manejan ocho bits de banco y no ajustan el noveno bit de MBC5. Siguen vigentes las reglas del cartucho, incluido el tratamiento del banco cero. El ejemplo usa explícitamente los bancos MBC5 1–3; no mezcles este estado con escrituras al mapper sin registrar.

Ejemplo de uso

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

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Este fragmento usa far_data_read8 para leer payload del banco 3 y comprueba D3. El programa completo también lee home2 con un puntero cercano para confirmar que se ha restaurado el banco 2.

El programa completo enseña a identificar datos con un banco y una dirección cercana, a llamar callbacks entre bancos y a distinguir el registro de la biblioteca del mapa real. Todos los números se muestran en hexadecimal. BANK IN y BANK OUT deben ser 02; BYTE HEX, D3; WORD HEX, 5C7A; FAILED CHECKS y FIRST FAILURE, 00. CGB y FC muestran texto azul; DMG, negro.

CALL COUNT muestra 03: far_call, __farcall y __farcall_ptr invocan el callback una vez cada uno.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Read one byte through the compiler intrinsic that accepts an explicit ROM bank.

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

Guarda un byte de banco y un puntero visible para la CPU en el BankPtr del llamador. Construye un descriptor; no cambia de banco ni lee los datos apuntados.

Sintaxis

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

Parámetros

out

Puntero a espacio escribible para un BankPtr de tres bytes. Si out es nulo, no se escribe nada.

bank

Número de banco ROM de 8 bits sin signo. En una llamada debe coincidir con la ubicación de la función; en una lectura selecciona el origen. Usa el intervalo válido para el cartucho.

ptr

Dirección de 16 bits visible para la CPU que se guardará en el descriptor. Se copia sin cambios; no se comprueba su validez en el banco elegido.

Valor devuelto

Ninguno (void).

Ejemplo de uso

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.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El descriptor se fija en banco 3 y payload+1. Sus lectores obtienen 7A, 5C7A y los tres bytes 7A 5C 96. La llamada con salida nula no debe cambiar el estado.

El programa completo enseña a identificar datos con un banco y una dirección cercana, a llamar callbacks entre bancos y a distinguir el registro de la biblioteca del mapa real. Todos los números se muestran en hexadecimal. BANK IN y BANK OUT deben ser 02; BYTE HEX, D3; WORD HEX, 5C7A; FAILED CHECKS y FIRST FAILURE, 00. CGB y FC muestran texto azul; DMG, negro.

CALL COUNT muestra 03: far_call, __farcall y __farcall_ptr invocan el callback una vez cada uno.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Store a bank/address pair without accessing ROM; a null output pointer is ignored.

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

Copia len bytes desde un BankPtr a RAM escribible. El descriptor se pasa por valor, por lo que el puntero del llamador sigue señalando el inicio del origen.

Sintaxis

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

Parámetros

ptr

Un valor BankPtr con los campos bank y ptr. Pasa el descriptor, no su dirección. El descriptor del llamador no se modifica.

dst

Destino en memoria escribible, con espacio para todos los bytes copiados. Salvo en una transferencia de cero bytes, no se comprueba si el destino es nulo o inválido.

len

Cantidad de bytes, de 0 a 65535. Con cero no se copia memoria, pero sí se selecciona y restaura el banco.

Valor devuelto

Ninguno (void).

Condiciones y límites

Mantenga todo el origen en el mapeo de ROM previsto y todo el destino en memoria escribible. La copia no cambia automáticamente de banco al cruzar una ventana, no trata solapamientos como memmove ni sincroniza escrituras en VRAM. Para VRAM, use las API de transferencia gráfica.

Las lecturas y copias lejanas son síncronas y usan memoria de trabajo compartida del compilador. No dejes que una interrupción ejecute otra transferencia sobre esa memoria mientras está en uso. En GB, la copia también guarda el banco anterior en una posición HRAM compartida. El ejemplo ejecuta las operaciones desde código fijo, sin un manejador de transferencia que compita.

Estas interfaces GB manejan ocho bits de banco y no ajustan el noveno bit de MBC5. Siguen vigentes las reglas del cartucho, incluido el tratamiento del banco cero. El ejemplo usa explícitamente los bancos MBC5 1–3; no mezcles este estado con escrituras al mapper sin registrar.

Ejemplo de uso

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

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Este fragmento copia 3 bytes mediante farptr_read y contrasta el búfer con 7A 5C 96. El llamador conserva su descriptor o puntero de origen; el programa completo comprueba aparte una copia de longitud cero y la restauración del banco.

El programa completo enseña a identificar datos con un banco y una dirección cercana, a llamar callbacks entre bancos y a distinguir el registro de la biblioteca del mapa real. Todos los números se muestran en hexadecimal. BANK IN y BANK OUT deben ser 02; BYTE HEX, D3; WORD HEX, 5C7A; FAILED CHECKS y FIRST FAILURE, 00. CGB y FC muestran texto azul; DMG, negro.

CALL COUNT muestra 03: far_call, __farcall y __farcall_ptr invocan el callback una vez cada uno.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Copy len bytes from a bank-qualified pointer; dst must have room for the full copy.

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

Lee una palabra little-endian del banco y la dirección del BankPtr. El descriptor se pasa por valor y su puntero no avanza.

Sintaxis

u16 farptr_read16(BankPtr ptr);

Parámetros

ptr

Un valor BankPtr con los campos bank y ptr. Pasa el descriptor, no su dirección. El descriptor del llamador no se modifica.

Valor devuelto

La palabra little-endian leída, como u16 (0–65535).

Condiciones y límites

El byte o la palabra completos deben ser legibles en el mapa CPU seleccionado. No se validan punteros, no se recortan direcciones ni se cambia automáticamente de banco al cruzar una ventana. Una palabra necesita dos bytes consecutivos válidos.

Las lecturas y copias lejanas son síncronas y usan memoria de trabajo compartida del compilador. No dejes que una interrupción ejecute otra transferencia sobre esa memoria mientras está en uso. En GB, la copia también guarda el banco anterior en una posición HRAM compartida. El ejemplo ejecuta las operaciones desde código fijo, sin un manejador de transferencia que compita.

Estas interfaces GB manejan ocho bits de banco y no ajustan el noveno bit de MBC5. Siguen vigentes las reglas del cartucho, incluido el tratamiento del banco cero. El ejemplo usa explícitamente los bancos MBC5 1–3; no mezcles este estado con escrituras al mapper sin registrar.

Ejemplo de uso

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

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Este fragmento usa farptr_read16 para leer pointer.ptr del banco 3 y comprueba 5C7A. El programa completo también lee home2 con un puntero cercano para confirmar que se ha restaurado el banco 2.

El programa completo enseña a identificar datos con un banco y una dirección cercana, a llamar callbacks entre bancos y a distinguir el registro de la biblioteca del mapa real. Todos los números se muestran en hexadecimal. BANK IN y BANK OUT deben ser 02; BYTE HEX, D3; WORD HEX, 5C7A; FAILED CHECKS y FIRST FAILURE, 00. CGB y FC muestran texto azul; DMG, negro.

CALL COUNT muestra 03: far_call, __farcall y __farcall_ptr invocan el callback una vez cada uno.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

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

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

Lee un byte usando ambos campos de un BankPtr pasado por valor. El descriptor aporta el banco que un puntero cercano no contiene.

Sintaxis

u8 farptr_read8(BankPtr ptr);

Parámetros

ptr

Un valor BankPtr con los campos bank y ptr. Pasa el descriptor, no su dirección. El descriptor del llamador no se modifica.

Valor devuelto

El byte leído, como u8 (0–255).

Condiciones y límites

El byte o la palabra completos deben ser legibles en el mapa CPU seleccionado. No se validan punteros, no se recortan direcciones ni se cambia automáticamente de banco al cruzar una ventana. Una palabra necesita dos bytes consecutivos válidos.

Las lecturas y copias lejanas son síncronas y usan memoria de trabajo compartida del compilador. No dejes que una interrupción ejecute otra transferencia sobre esa memoria mientras está en uso. En GB, la copia también guarda el banco anterior en una posición HRAM compartida. El ejemplo ejecuta las operaciones desde código fijo, sin un manejador de transferencia que compita.

Estas interfaces GB manejan ocho bits de banco y no ajustan el noveno bit de MBC5. Siguen vigentes las reglas del cartucho, incluido el tratamiento del banco cero. El ejemplo usa explícitamente los bancos MBC5 1–3; no mezcles este estado con escrituras al mapper sin registrar.

Ejemplo de uso

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

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Este fragmento usa farptr_read8 para leer pointer.ptr del banco 3 y comprueba 7A. El programa completo también lee home2 con un puntero cercano para confirmar que se ha restaurado el banco 2.

El programa completo enseña a identificar datos con un banco y una dirección cercana, a llamar callbacks entre bancos y a distinguir el registro de la biblioteca del mapa real. Todos los números se muestran en hexadecimal. BANK IN y BANK OUT deben ser 02; BYTE HEX, D3; WORD HEX, 5C7A; FAILED CHECKS y FIRST FAILURE, 00. CGB y FC muestran texto azul; DMG, negro.

CALL COUNT muestra 03: far_call, __farcall y __farcall_ptr invocan el callback una vez cada uno.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\banked_data_calls.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\banked_data_calls.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k --no-cache --no-disasm

Read one byte using both components of the bank-qualified pointer.

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

Suma desplazamientos Q8.8 a la posición actual y después aplica los límites activados.

Sintaxis

void Camera_Add(Camera8_8* cam, s16 dfx, s16 dfy);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

dfx

Desplazamiento Q8.8 con signo; 256 equivale a un píxel.

dfy

Desplazamiento Q8.8 con signo; 256 equivale a un píxel.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer.

Ejemplo de uso

Camera_Add(&cam,256,512);result[13]=cam.fx;result[14]=cam.fy;

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Add Q8.8 deltas and clamp afterward. Keep the intermediate sums within s16;
clamping cannot repair arithmetic that already overflowed.

void Camera_Add(Camera8_8* cam, s16 dfx, s16 dfy)
{
    cam->fx += dfx;
    cam->fy += dfy;
    Camera_ApplyBounds(cam);
}

Aplica de inmediato la posición actual de la cámara compartida al desplazamiento del fondo.

Sintaxis

void camera_apply();

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

No espera a VBlank; sincroniza desde el código que llama si no quieres cambios a mitad de fotograma. Las fracciones negativas se redondean hacia abajo: −1/256 pasa a −1 píxel, es decir, al valor 255 del registro.

Ejemplo de uso

camera_apply();result[31]=M_SCX;result[32]=M_SCY;

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Write the shared camera's current integer position to background scroll registers.

void camera_apply()
{
    Camera_ApplyBg(&camera_default);
}

Redondea hacia abajo la posición de la cámara a píxeles enteros y escribe inmediatamente los ocho bits bajos en el desplazamiento del fondo.

Sintaxis

void Camera_ApplyBg(const Camera8_8* cam);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

No espera a VBlank; sincroniza desde el código que llama si no quieres cambios a mitad de fotograma. Las fracciones negativas se redondean hacia abajo: −1/256 pasa a −1 píxel, es decir, al valor 255 del registro.

Ejemplo de uso

Camera_ApplyBg(&cam);result[21]=M_SCX;result[22]=M_SCY;

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Discard fractional bits and write the low eight integer bits to background scroll registers.

void Camera_ApplyBg(const Camera8_8* cam)
{
    __scroll_bg_set((u8)(cam->fx >> 8), (u8)(cam->fy >> 8));
}

Redondea hacia abajo la posición de la cámara a píxeles enteros y la deja pendiente como desplazamiento del fondo.

Sintaxis

void Camera_ApplyBgBuffered(const Camera8_8* cam);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

El hardware y los valores actuales registrados no cambian hasta llamar a Scroll_Flush o __scroll_flush. Esta llamada no espera a VBlank.

Ejemplo de uso

Camera_Set(&cam,2048,4096);Camera_ApplyBgBuffered(&cam);result[23]=M_SCX;Scroll_Flush();result[24]=M_SCX;result[25]=M_SCY;

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Convert the Q8.8 position to byte scroll values and stage them for a later flush.

void Camera_ApplyBgBuffered(const Camera8_8* cam)
{
    __scroll_bg_set_buffered((u8)(cam->fx >> 8), (u8)(cam->fy >> 8));
}

Aplica a la cámara compartida los límites obtenidos al restar la pantalla del mundo.

Sintaxis

void camera_clamp(u16 world_w_px, u16 world_h_px, u8 screen_w_px, u8 screen_h_px);

Parámetros

world_w_px

Dimensión del mundo en píxeles enteros; la diferencia positiva respecto a la pantalla debe quedar entre 0 y 127.

world_h_px

Dimensión del mundo en píxeles enteros; la diferencia positiva respecto a la pantalla debe quedar entre 0 y 127.

screen_w_px

Tamaño del área visible en píxeles enteros; si es igual o mayor que el mundo, el recorrido en ese eje es cero.

screen_h_px

Tamaño del área visible en píxeles enteros; si es igual o mayor que el mundo, el recorrido en ese eje es cero.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

Si el mundo es menor que el área visible, el recorrido es cero. Una diferencia positiva de 128 o más supera el rango Q8.8 con signo al convertirla. Que los parámetros sean u16 no implica que la cámara pueda recorrer mundos de cualquier tamaño. Estas llamadas comparten una cámara; usa la API que empieza por mayúscula para objetos de cámara independientes. Las posiciones convertidas de píxeles enteros a Q8.8 deben estar entre −128 y 127.

Ejemplo de uso

camera_clamp(176,160,160,144);result[29]=camera_world_to_screen_x(100);result[30]=camera_world_to_screen_y(90);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Derive and apply world/screen bounds to the shared convenience camera.

void camera_clamp(u16 world_w_px, u16 world_h_px, u8 screen_w_px, u8 screen_h_px)
{
    Camera_ClampToSize(&camera_default, world_w_px, world_h_px, screen_w_px, screen_h_px);
}

Resta las dimensiones de la pantalla a las del mundo y establece los límites no negativos resultantes para la cámara.

Sintaxis

void Camera_ClampToSize(Camera8_8* cam, u16 world_w_px, u16 world_h_px, u8 screen_w_px, u8 screen_h_px);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

world_w_px

Dimensión del mundo en píxeles enteros; la diferencia positiva respecto a la pantalla debe quedar entre 0 y 127.

world_h_px

Dimensión del mundo en píxeles enteros; la diferencia positiva respecto a la pantalla debe quedar entre 0 y 127.

screen_w_px

Tamaño del área visible en píxeles enteros; si es igual o mayor que el mundo, el recorrido en ese eje es cero.

screen_h_px

Tamaño del área visible en píxeles enteros; si es igual o mayor que el mundo, el recorrido en ese eje es cero.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

Si el mundo es menor que el área visible, el recorrido es cero. Una diferencia positiva de 128 o más supera el rango Q8.8 con signo al convertirla. Que los parámetros sean u16 no implica que la cámara pueda recorrer mundos de cualquier tamaño.

Ejemplo de uso

Camera_ClampToSize(&cam,176,160,160,144);result[15]=cam.max_fx;result[16]=cam.max_fy;

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Derive nonnegative camera extents from world minus screen size, then convert
them to Q8.8 bounds. Extents must fit signed Q8.8; the u16 input type does
not imply support for arbitrary large worlds.

void Camera_ClampToSize(Camera8_8* cam, u16 world_w_px, u16 world_h_px, u8 screen_w_px, u8 screen_h_px)
{
    s16 max_x = 0;
    s16 max_y = 0;

    if (world_w_px > screen_w_px) max_x = (s16)((u16)(world_w_px - screen_w_px) << 8);
    if (world_h_px > screen_h_px) max_y = (s16)((u16)(world_h_px - screen_h_px) << 8);
    Camera_SetBounds(cam, (s16)0, (s16)0, max_x, max_y);
}

Desactiva los límites sin cambiar la posición, el objetivo ni los límites guardados.

Sintaxis

void Camera_ClearBounds(Camera8_8* cam);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer.

Ejemplo de uso

Camera_ClearBounds(&cam);result[12]=cam.use_bounds;

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Disable clamping while retaining the stored bounds and current position.

void Camera_ClearBounds(Camera8_8* cam)
{
    cam->use_bounds = 0;
}

Desactiva el seguimiento conservando la posición actual y el objetivo guardado.

Sintaxis

void Camera_ClearTarget(Camera8_8* cam);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer.

Ejemplo de uso

Camera_ClearTarget(&cam);result[8]=cam.use_target;result[9]=cam.target_fx;

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Disable target following without moving the camera or erasing the stored target.

void Camera_ClearTarget(Camera8_8* cam)
{
    cam->use_target = 0;
}

Mueve de inmediato la cámara compartida para que un punto del mundo aparezca en el punto de anclaje indicado en pantalla.

Sintaxis

void camera_follow_xy(s16 x, s16 y, u8 screen_cx, u8 screen_cy);

Parámetros

x

Coordenada X del mundo en píxeles enteros; el resultado y la diferencia intermedia deben caber en s16.

y

Coordenada Y del mundo en píxeles enteros; el resultado y la diferencia intermedia deben caber en s16.

screen_cx

Coordenada del punto de anclaje en pantalla en píxeles enteros, de 0 a 255.

screen_cy

Coordenada del punto de anclaje en pantalla en píxeles enteros, de 0 a 255.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer. Estas llamadas comparten una cámara; usa la API que empieza por mayúscula para objetos de cámara independientes. Las posiciones convertidas de píxeles enteros a Q8.8 deben estar entre −128 y 127.

Ejemplo de uso

camera_follow_xy(100,90,80,72);result[27]=camera_world_to_screen_x(100);result[28]=camera_world_to_screen_y(90);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Position the shared camera so the world point appears at the requested screen
anchor. This is an immediate move, not the smoothed target-following path.

void camera_follow_xy(s16 x, s16 y, u8 screen_cx, u8 screen_cy)
{
    s16 cx = (s16)(x - screen_cx);
    s16 cy = (s16)(y - screen_cy);
    Camera_Set(&camera_default, (s16)(cx << 8), (s16)(cy << 8));
}

Pone a cero la posición, el objetivo y los límites, y desactiva el seguimiento y la limitación al rango.

Sintaxis

void Camera_Init(Camera8_8* cam);

Parámetros

cam

Camera8_8 accesible para escritura que se va a inicializar; no debe ser NULL.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer.

Ejemplo de uso

Camera_Init(&cam);result[0]=cam.fx;result[1]=cam.use_target;result[2]=cam.use_bounds;

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Zero all position/target/bound fields and disable targeting and bounds.

void Camera_Init(Camera8_8* cam)
{
    cam->fx = 0;
    cam->fy = 0;
    cam->target_fx = 0;
    cam->target_fy = 0;
    cam->min_fx = 0;
    cam->min_fy = 0;
    cam->max_fx = 0;
    cam->max_fy = 0;
    cam->use_target = 0;
    cam->use_bounds = 0;
}

Suma la parte entera de X de la cámara a la X entera de pantalla para obtener la X del mundo.

Sintaxis

s16 Camera_ScreenToWorldX(const Camera8_8* cam, s16 screen_x);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

screen_x

Coordenada X de pantalla en píxeles enteros; el resultado y la diferencia intermedia deben caber en s16.

Valor devuelto

Devuelve la coordenada convertida en píxeles enteros como s16; no comprueba su visibilidad ni la recorta.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer.

Ejemplo de uso

result[19]=Camera_ScreenToWorldX(&cam,27);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Convert integer-pixel screen X back to world X using the camera's integer component.

s16 Camera_ScreenToWorldX(const Camera8_8* cam, s16 screen_x)
{
    return (s16)(screen_x + (cam->fx >> 8));
}

Suma la parte entera de Y de la cámara a la Y entera de pantalla para obtener la Y del mundo.

Sintaxis

s16 Camera_ScreenToWorldY(const Camera8_8* cam, s16 screen_y);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

screen_y

Coordenada Y de pantalla en píxeles enteros; el resultado y la diferencia intermedia deben caber en s16.

Valor devuelto

Devuelve la coordenada convertida en píxeles enteros como s16; no comprueba su visibilidad ni la recorta.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer.

Ejemplo de uso

result[20]=Camera_ScreenToWorldY(&cam,24);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Convert integer-pixel screen Y back to world Y using the camera's integer component.

s16 Camera_ScreenToWorldY(const Camera8_8* cam, s16 screen_y)
{
    return (s16)(screen_y + (cam->fy >> 8));
}

Sustituye la posición actual de la cámara y la ajusta inmediatamente a los límites que estén activados.

Sintaxis

void Camera_Set(Camera8_8* cam, s16 fx, s16 fy);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

fx

Coordenada X. Coordenada Q8.8 con signo: 256 equivale a un píxel; el rango va de −128 a 127+255/256 píxeles.

fy

Coordenada Y. Coordenada Q8.8 con signo: 256 equivale a un píxel; el rango va de −128 a 127+255/256 píxeles.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer.

Ejemplo de uso

Camera_Set(&cam,2560,5120);result[3]=cam.fx;result[4]=cam.fy;

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Replace the current Q8.8 position and immediately apply enabled bounds.

void Camera_Set(Camera8_8* cam, s16 fx, s16 fy)
{
    cam->fx = fx;
    cam->fy = fy;
    Camera_ApplyBounds(cam);
}

Mueve la cámara compartida con coordenadas de píxeles enteros y aplica sus límites activados.

Sintaxis

void camera_set(s16 x, s16 y);

Parámetros

x

Coordenada X del mundo en píxeles enteros; el resultado y la diferencia intermedia deben caber en s16.

y

Coordenada Y del mundo en píxeles enteros; el resultado y la diferencia intermedia deben caber en s16.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer. Estas llamadas comparten una cámara; usa la API que empieza por mayúscula para objetos de cámara independientes. Las posiciones convertidas de píxeles enteros a Q8.8 deben estar entre −128 y 127.

Ejemplo de uso

camera_set(5,6);result[26]=camera_world_to_screen_x(20);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Set the shared camera from integer pixels, converting to the representable Q8.8 range.

void camera_set(s16 x, s16 y)
{
    Camera_Set(&camera_default, (s16)(x << 8), (s16)(y << 8));
}

Establece las coordenadas mínimas y máximas, activa los límites y ajusta de inmediato la posición actual.

Sintaxis

void Camera_SetBounds(Camera8_8* cam, s16 min_fx, s16 min_fy, s16 max_fx, s16 max_fy);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

min_fx

Coordenada X mínima. Coordenada Q8.8 con signo: 256 equivale a un píxel; el rango va de −128 a 127+255/256 píxeles.

min_fy

Coordenada Y mínima. Coordenada Q8.8 con signo: 256 equivale a un píxel; el rango va de −128 a 127+255/256 píxeles.

max_fx

Coordenada X máxima. Coordenada Q8.8 con signo: 256 equivale a un píxel; el rango va de −128 a 127+255/256 píxeles.

max_fy

Coordenada Y máxima. Coordenada Q8.8 con signo: 256 equivale a un píxel; el rango va de −128 a 127+255/256 píxeles.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

Proporciona un mínimo ≤ máximo en cada eje; los límites no se reordenan. El objetivo guardado no se ajusta a ellos.

Ejemplo de uso

Camera_SetBounds(&cam,0,0,3072,3584);result[10]=cam.fx;result[11]=cam.fy;

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Install ordered Q8.8 bounds, enable them and clamp the current position immediately.

void Camera_SetBounds(Camera8_8* cam, s16 min_fx, s16 min_fy, s16 max_fx, s16 max_fy)
{
    cam->min_fx = min_fx;
    cam->min_fy = min_fy;
    cam->max_fx = max_fx;
    cam->max_fy = max_fy;
    cam->use_bounds = 1;
    Camera_ApplyBounds(cam);
}

Guarda un objetivo y activa el seguimiento sin mover la posición actual.

Sintaxis

void Camera_SetTarget(Camera8_8* cam, s16 fx, s16 fy);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

fx

Coordenada X. Coordenada Q8.8 con signo: 256 equivale a un píxel; el rango va de −128 a 127+255/256 píxeles.

fy

Coordenada Y. Coordenada Q8.8 con signo: 256 equivale a un píxel; el rango va de −128 a 127+255/256 píxeles.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer.

Ejemplo de uso

Camera_SetTarget(&cam,4608,3072);result[5]=cam.use_target;

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Store a Q8.8 target and enable subsequent step-toward-target updates.

void Camera_SetTarget(Camera8_8* cam, s16 fx, s16 fy)
{
    cam->target_fx = fx;
    cam->target_fy = fy;
    cam->use_target = 1;
}

Se acerca al objetivo una fracción de la distancia restante, calculada mediante un desplazamiento a la derecha; no hace nada si el seguimiento está desactivado.

Sintaxis

void Camera_StepTowardTarget(Camera8_8* cam, u8 shift);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

shift

Exponente de la potencia de dos que divide la diferencia: 0 usa toda la diferencia y 1 usa la mitad. Los valores superiores a 7 se limitan a 7.

Valor devuelto

No devuelve ningún valor. Esta entrada describe el estado afectado y cuándo surte efecto.

Condiciones y límites

Una diferencia positiva pequeña puede truncarse a cero; un desplazamiento aritmético a la derecha puede convertir una diferencia negativa pequeña en −1. La igualdad con el objetivo se comprueba antes de aplicar los límites. Por ello, un objetivo fuera de rango puede mantener activo el seguimiento o desactivarlo aunque la posición final limitada sea distinta del objetivo.

Ejemplo de uso

Camera_StepTowardTarget(&cam,1);result[6]=cam.fx;result[7]=cam.fy;

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Move by the signed target delta shifted by 0..7 bits, then apply bounds.
Quantization can make a small delta produce no movement; only exact equality
clears targeting, and a target outside the bounds may remain active indefinitely.

void Camera_StepTowardTarget(Camera8_8* cam, u8 shift)
{
    s16 dx;
    s16 dy;

    if (cam->use_target == 0) return;
    if (shift > 7) shift = 7;

    // Keep target-minus-position differences within s16 as well as the individual positions.
    dx = cam->target_fx - cam->fx;
    dy = cam->target_fy - cam->fy;

    if (dx != 0) cam->fx += (dx >> shift);
    if (dy != 0) cam->fy += (dy >> shift);

    if (cam->fx == cam->target_fx && cam->fy == cam->target_fy) cam->use_target = 0;
    Camera_ApplyBounds(cam);
}

Convierte la X del mundo en X de pantalla restando la parte entera de X de la cámara compartida.

Sintaxis

s16 camera_world_to_screen_x(s16 world_x);

Parámetros

world_x

Coordenada X del mundo en píxeles enteros; el resultado y la diferencia intermedia deben caber en s16.

Valor devuelto

Devuelve la coordenada convertida en píxeles enteros como s16; no comprueba su visibilidad ni la recorta.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer. Estas llamadas comparten una cámara; usa la API que empieza por mayúscula para objetos de cámara independientes. Las posiciones convertidas de píxeles enteros a Q8.8 deben estar entre −128 y 127.

Ejemplo de uso

result[33]=camera_world_to_screen_x(20);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Convert integer-pixel world X using the shared convenience camera.

s16 camera_world_to_screen_x(s16 world_x)
{
    return Camera_WorldToScreenX(&camera_default, world_x);
}

Convierte la Y del mundo en Y de pantalla restando la parte entera de Y de la cámara compartida.

Sintaxis

s16 camera_world_to_screen_y(s16 world_y);

Parámetros

world_y

Coordenada Y del mundo en píxeles enteros; el resultado y la diferencia intermedia deben caber en s16.

Valor devuelto

Devuelve la coordenada convertida en píxeles enteros como s16; no comprueba su visibilidad ni la recorta.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer. Estas llamadas comparten una cámara; usa la API que empieza por mayúscula para objetos de cámara independientes. Las posiciones convertidas de píxeles enteros a Q8.8 deben estar entre −128 y 127.

Ejemplo de uso

result[34]=camera_world_to_screen_y(20);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Convert integer-pixel world Y using the shared convenience camera.

s16 camera_world_to_screen_y(s16 world_y)
{
    return Camera_WorldToScreenY(&camera_default, world_y);
}

Resta la parte entera de X de la cámara a una coordenada X entera del mundo para obtener la X en pantalla.

Sintaxis

s16 Camera_WorldToScreenX(const Camera8_8* cam, s16 world_x);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

world_x

Coordenada X del mundo en píxeles enteros; el resultado y la diferencia intermedia deben caber en s16.

Valor devuelto

Devuelve la coordenada convertida en píxeles enteros como s16; no comprueba su visibilidad ni la recorta.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer.

Ejemplo de uso

result[17]=Camera_WorldToScreenX(&cam,40);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Convert an integer-pixel world X by subtracting the camera's integer X component.

s16 Camera_WorldToScreenX(const Camera8_8* cam, s16 world_x)
{
    return (s16)(world_x - (cam->fx >> 8));
}

Resta la parte entera de Y de la cámara a una coordenada Y entera del mundo para obtener la Y en pantalla.

Sintaxis

s16 Camera_WorldToScreenY(const Camera8_8* cam, s16 world_y);

Parámetros

cam

Puntero válido a un Camera8_8 inicializado y propiedad del código que llama.

world_y

Coordenada Y del mundo en píxeles enteros; el resultado y la diferencia intermedia deben caber en s16.

Valor devuelto

Devuelve la coordenada convertida en píxeles enteros como s16; no comprueba su visibilidad ni la recorta.

Condiciones y límites

Las coordenadas tienen ocho bits fraccionarios. Mantén las posiciones, los objetivos y las sumas o diferencias intermedias dentro de s16. Actualiza la pantalla por separado con Camera_ApplyBg o aplicando los valores pendientes del búfer.

Ejemplo de uso

result[18]=Camera_WorldToScreenY(&cam,40);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El ejemplo enseña seguimiento Q8.8, límites y conversión de coordenadas. El seguimiento produce X/Y=3584/4096 y los límites dan 3072/3584. BG X permanece en 13 mientras el cambio está pendiente y pasa a 8 al aplicar el búfer. La imagen adicional muestra cómo una cámara en (8,16) sitúa en pantalla (24,16) un rectángulo de 32×24 ubicado en el mundo en (32,32).

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Ejemplo de uso

Camera_Init(&view);
Camera_Set(&view,2048,4096);
Camera_ApplyBg(&view);
Scroll_SetWindow(103,80);
Scroll_WindowShow();

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Con la cámara en (8,16), el rectángulo rojo de 32×24 aparece en pantalla en (24,16). La ventana muestra un marco azul de 64×64 en (96,80) y un cuadrado verde de 16×16 en (112,96). En DMG todas las figuras son negras.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\batch2_camera_view.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\batch2_camera_view.gb --no-cache --no-disasm --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=64k

Convert an integer-pixel world Y by subtracting the camera's integer Y component.

s16 Camera_WorldToScreenY(const Camera8_8* cam, s16 world_y)
{
    return (s16)(world_y - (cam->fy >> 8));
}

Consulte los cambios y la verificación del 2026-10-03 para las diferencias locales de esta API.

Escribe inmediatamente un color RGB15 empaquetado en las paletas de fondo/ventana. Los índices de paleta y color eligen una de las 32 posiciones de color; no modifica los patrones ni la paleta asignada a una casilla.

Sintaxis

void cgb_bg_color(u8 palette_index, u8 color_index, u16 rgb15);

Parámetros

palette_index

Número de paleta, 0–7; solo usa los tres bits bajos (& 7).

color_index

Índice de color dentro de la paleta, 0–3; solo usa los dos bits bajos (& 3).

rgb15

Color RGB de 15 bits empaquetado, normalmente 0–32767. Se escriben ambos bytes del u16, primero el bajo; la biblioteca no borra explícitamente el bit 15. Usa CGB_RGB15 o cgb_rgb15 para construirlo.

Valor devuelto

Ninguno (void).

Condiciones y límites

Las escrituras de paleta y de registros protegidos no escriben nada en modo DMG. Safe indica una comprobación de modo CGB, no una espera de acceso a PPU ni una sección crítica. Configura con LCD apagado o realiza una actualización breve durante una fase accesible. No espera VBlank ni protege una escritura de varios bytes frente a interrupciones.

Las paletas BG/ventana y OBJ son almacenes separados. Las escrituras de la biblioteca activan el incremento y dejan modificado el registro de índice. El color OBJ cero es transparente al dibujar sprites, aunque sus bytes se puedan guardar y leer.

Ejemplo de uso

cgb_bg_color(1,3,31); // Red background color 3 of palette 1.
expect_color(0,7,31);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Set one background color through the indexed palette wrapper.

void cgb_bg_color(u8 palette_index, u8 color_index, u16 rgb15)
{
    cgb__write_color_bg_raw(cgb__palette_color_slot(palette_index, color_index), rgb15);
}

Escribe palabras RGB15 consecutivas en las paletas de fondo/ventana, a partir de la pareja de índices indicada. Puede atravesar el límite de una paleta de cuatro colores; se detiene al final de las 32 posiciones.

Sintaxis

void cgb_bg_colors(u8 palette_index, u8 start_color_index, const u16* colors, u8 color_count);

Parámetros

palette_index

Número de paleta, 0–7; solo usa los tres bits bajos (& 7).

start_color_index

Índice de color dentro de la paleta, 0–3; solo usa los dos bits bajos (& 3).

colors

const u16* legible con las palabras de color necesarias. Los datos se consumen durante la llamada, sin encolarlos. Mantén accesibles la fuente y su banco ROM; no se cambia de banco automáticamente. Un puntero nulo no produce escrituras.

color_count

Cantidad de palabras de color, no de bytes, como u8 (0–255). Cero no hace nada. Se limita a 32 - posición_inicial_normalizada; solo se leen esas palabras de la fuente.

Valor devuelto

Ninguno (void).

Condiciones y límites

Las escrituras de paleta y de registros protegidos no escriben nada en modo DMG. Safe indica una comprobación de modo CGB, no una espera de acceso a PPU ni una sección crítica. Configura con LCD apagado o realiza una actualización breve durante una fase accesible. No espera VBlank ni protege una escritura de varios bytes frente a interrupciones.

Las paletas BG/ventana y OBJ son almacenes separados. Las escrituras de la biblioteca activan el incremento y dejan modificado el registro de índice. El color OBJ cero es transparente al dibujar sprites, aunque sus bytes se puedan guardar y leer.

Ejemplo de uso

cgb_bg_colors(3,2,tail_green,2); // Two color words; color 3 becomes green.
expect_color(0,14,0); expect_color(0,15,992);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write background colors starting at the indexed slot. The range may cross
palette boundaries and is clamped only at the end of all 32 slots.

void cgb_bg_colors(u8 palette_index, u8 start_color_index, const u16* colors, u8 color_count)
{
    cgb__write_colors_bg_raw(cgb__palette_color_slot(palette_index, start_color_index), colors, color_count);
}

Escribe palabras RGB15 consecutivas en las paletas de fondo/ventana usando una posición absoluta de color. El inicio es un único índice de 0 a 31, no una pareja paleta/color. Los datos son palabras de color, no bytes de patrones.

Sintaxis

void cgb_bg_colors_raw(u8 start_color_slot, const u16* colors, u8 color_count);

Parámetros

start_color_slot

Posición absoluta de color, 0–31; se normaliza con & 31 antes de limitar la longitud. Posición = paleta × 4 + color. No es un desplazamiento en bytes.

colors

const u16* legible con las palabras de color necesarias. Los datos se consumen durante la llamada, sin encolarlos. Mantén accesibles la fuente y su banco ROM; no se cambia de banco automáticamente. Un puntero nulo no produce escrituras.

color_count

Cantidad de palabras de color, no de bytes, como u8 (0–255). Cero no hace nada. Se limita a 32 - posición_inicial_normalizada; solo se leen esas palabras de la fuente.

Valor devuelto

Ninguno (void).

Condiciones y límites

Las escrituras de paleta y de registros protegidos no escriben nada en modo DMG. Safe indica una comprobación de modo CGB, no una espera de acceso a PPU ni una sección crítica. Configura con LCD apagado o realiza una actualización breve durante una fase accesible. No espera VBlank ni protege una escritura de varios bytes frente a interrupciones.

Las paletas BG/ventana y OBJ son almacenes separados. Las escrituras de la biblioteca activan el incremento y dejan modificado el registro de índice. El color OBJ cero es transparente al dibujar sprites, aunque sus bytes se puedan guardar y leer.

Ejemplo de uso

cgb_bg_colors_raw(23,blue_word,1); // Absolute slot 23 = palette 5, color 3.
expect_color(0,23,31744);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Expose sequential background writes using an absolute color-slot index.

void cgb_bg_colors_raw(u8 start_color_slot, const u16* colors, u8 color_count)
{
    cgb__write_colors_bg_raw(start_color_slot, colors, color_count);
}

Sustituye los cuatro colores de una paleta de fondo/ventana con cuatro palabras RGB15. Equivale a escribir un rango desde el color cero con cantidad cuatro; no asigna la paleta a casillas ni sprites.

Sintaxis

void cgb_bg_palette(u8 palette_index, const u16* colors);

Parámetros

palette_index

Número de paleta, 0–7; solo usa los tres bits bajos (& 7).

colors

const u16* legible con las palabras de color necesarias. Los datos se consumen durante la llamada, sin encolarlos. Mantén accesibles la fuente y su banco ROM; no se cambia de banco automáticamente. Un puntero nulo no produce escrituras.

Valor devuelto

Ninguno (void).

Condiciones y límites

Las escrituras de paleta y de registros protegidos no escriben nada en modo DMG. Safe indica una comprobación de modo CGB, no una espera de acceso a PPU ni una sección crítica. Configura con LCD apagado o realiza una actualización breve durante una fase accesible. No espera VBlank ni protege una escritura de varios bytes frente a interrupciones.

Las paletas BG/ventana y OBJ son almacenes separados. Las escrituras de la biblioteca activan el incremento y dejan modificado el registro de índice. El color OBJ cero es transparente al dibujar sprites, aunque sus bytes se puedan guardar y leer.

Ejemplo de uso

cgb_bg_palette(4,red_palette); // Exactly four color words for BG palette 4.
expect_color(0,16,32767); expect_color(0,19,31);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write four consecutive colors for one background palette.

void cgb_bg_palette(u8 palette_index, const u16* colors)
{
    cgb_bg_colors(palette_index, 0, colors, 4);
}

Consulte los cambios y la verificación del 2026-10-03 para las diferencias locales de esta API.

Empaqueta los componentes rojo, verde y azul con cgb_rgb15 y escribe un color en las paletas de fondo/ventana. Úsalo para proporcionar los componentes por separado en lugar de una palabra empaquetada.

Sintaxis

void cgb_bg_rgb(u8 palette_index, u8 color_index, u8 r5, u8 g5, u8 b5);

Parámetros

palette_index

Número de paleta, 0–7; solo usa los tres bits bajos (& 7).

color_index

Índice de color dentro de la paleta, 0–3; solo usa los dos bits bajos (& 3).

r5, g5, b5

Componentes rojo, verde y azul respectivamente, normalmente 0–31 cada uno. Se enmascaran sin saturación; cada argumento aparece una sola vez en la expansión de la macro.

Valor devuelto

Ninguno (void).

Condiciones y límites

Las escrituras de paleta y de registros protegidos no escriben nada en modo DMG. Safe indica una comprobación de modo CGB, no una espera de acceso a PPU ni una sección crítica. Configura con LCD apagado o realiza una actualización breve durante una fase accesible. No espera VBlank ni protege una escritura de varios bytes frente a interrupciones.

Las paletas BG/ventana y OBJ son almacenes separados. Las escrituras de la biblioteca activan el incremento y dejan modificado el registro de índice. El color OBJ cero es transparente al dibujar sprites, aunque sus bytes se puedan guardar y leer.

Ejemplo de uso

cgb_bg_rgb(2,3,0,0,31); // Blue, supplied as three five-bit components.
expect_color(0,11,31744);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Pack component values and write one background color.

void cgb_bg_rgb(u8 palette_index, u8 color_index, u8 r5, u8 g5, u8 b5)
{
    cgb_bg_color(palette_index, color_index, cgb_rgb15(r5, g5, b5));
}

Consulte los cambios y la verificación del 2026-10-03 para las diferencias locales de esta API.

Escribe inmediatamente un color RGB15 empaquetado en las paletas de sprites (OBJ). Los índices de paleta y color eligen una de las 32 posiciones de color; no modifica los patrones ni la paleta asignada a una casilla.

Sintaxis

void cgb_obj_color(u8 palette_index, u8 color_index, u16 rgb15);

Parámetros

palette_index

Número de paleta, 0–7; solo usa los tres bits bajos (& 7).

color_index

Índice de color dentro de la paleta, 0–3; solo usa los dos bits bajos (& 3).

rgb15

Color RGB de 15 bits empaquetado, normalmente 0–32767. Se escriben ambos bytes del u16, primero el bajo; la biblioteca no borra explícitamente el bit 15. Usa CGB_RGB15 o cgb_rgb15 para construirlo.

Valor devuelto

Ninguno (void).

Condiciones y límites

Las escrituras de paleta y de registros protegidos no escriben nada en modo DMG. Safe indica una comprobación de modo CGB, no una espera de acceso a PPU ni una sección crítica. Configura con LCD apagado o realiza una actualización breve durante una fase accesible. No espera VBlank ni protege una escritura de varios bytes frente a interrupciones.

Las paletas BG/ventana y OBJ son almacenes separados. Las escrituras de la biblioteca activan el incremento y dejan modificado el registro de índice. El color OBJ cero es transparente al dibujar sprites, aunque sus bytes se puedan guardar y leer.

Ejemplo de uso

cgb_obj_color(1,3,31744); // Blue sprite color at the same palette/color indices.
expect_color(1,7,31744);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Set one object color through the indexed palette wrapper.

void cgb_obj_color(u8 palette_index, u8 color_index, u16 rgb15)
{
    cgb__write_color_obj_raw(cgb__palette_color_slot(palette_index, color_index), rgb15);
}

Escribe palabras RGB15 consecutivas en las paletas de sprites (OBJ), a partir de la pareja de índices indicada. Puede atravesar el límite de una paleta de cuatro colores; se detiene al final de las 32 posiciones.

Sintaxis

void cgb_obj_colors(u8 palette_index, u8 start_color_index, const u16* colors, u8 color_count);

Parámetros

palette_index

Número de paleta, 0–7; solo usa los tres bits bajos (& 7).

start_color_index

Índice de color dentro de la paleta, 0–3; solo usa los dos bits bajos (& 3).

colors

const u16* legible con las palabras de color necesarias. Los datos se consumen durante la llamada, sin encolarlos. Mantén accesibles la fuente y su banco ROM; no se cambia de banco automáticamente. Un puntero nulo no produce escrituras.

color_count

Cantidad de palabras de color, no de bytes, como u8 (0–255). Cero no hace nada. Se limita a 32 - posición_inicial_normalizada; solo se leen esas palabras de la fuente.

Valor devuelto

Ninguno (void).

Condiciones y límites

Las escrituras de paleta y de registros protegidos no escriben nada en modo DMG. Safe indica una comprobación de modo CGB, no una espera de acceso a PPU ni una sección crítica. Configura con LCD apagado o realiza una actualización breve durante una fase accesible. No espera VBlank ni protege una escritura de varios bytes frente a interrupciones.

Las paletas BG/ventana y OBJ son almacenes separados. Las escrituras de la biblioteca activan el incremento y dejan modificado el registro de índice. El color OBJ cero es transparente al dibujar sprites, aunque sus bytes se puedan guardar y leer.

Ejemplo de uso

cgb_obj_colors(3,2,tail_red,2); // Sprite color 3 becomes red.
expect_color(1,14,0); expect_color(1,15,31);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write object colors from the indexed slot, potentially crossing into later palettes.

void cgb_obj_colors(u8 palette_index, u8 start_color_index, const u16* colors, u8 color_count)
{
    cgb__write_colors_obj_raw(cgb__palette_color_slot(palette_index, start_color_index), colors, color_count);
}

Escribe palabras RGB15 consecutivas en las paletas de sprites (OBJ) usando una posición absoluta de color. El inicio es un único índice de 0 a 31, no una pareja paleta/color. Los datos son palabras de color, no bytes de patrones.

Sintaxis

void cgb_obj_colors_raw(u8 start_color_slot, const u16* colors, u8 color_count);

Parámetros

start_color_slot

Posición absoluta de color, 0–31; se normaliza con & 31 antes de limitar la longitud. Posición = paleta × 4 + color. No es un desplazamiento en bytes.

colors

const u16* legible con las palabras de color necesarias. Los datos se consumen durante la llamada, sin encolarlos. Mantén accesibles la fuente y su banco ROM; no se cambia de banco automáticamente. Un puntero nulo no produce escrituras.

color_count

Cantidad de palabras de color, no de bytes, como u8 (0–255). Cero no hace nada. Se limita a 32 - posición_inicial_normalizada; solo se leen esas palabras de la fuente.

Valor devuelto

Ninguno (void).

Condiciones y límites

Las escrituras de paleta y de registros protegidos no escriben nada en modo DMG. Safe indica una comprobación de modo CGB, no una espera de acceso a PPU ni una sección crítica. Configura con LCD apagado o realiza una actualización breve durante una fase accesible. No espera VBlank ni protege una escritura de varios bytes frente a interrupciones.

Las paletas BG/ventana y OBJ son almacenes separados. Las escrituras de la biblioteca activan el incremento y dejan modificado el registro de índice. El color OBJ cero es transparente al dibujar sprites, aunque sus bytes se puedan guardar y leer.

Ejemplo de uso

cgb_obj_colors_raw(23,green_word,1); // Same absolute slot in the separate OBJ store.
expect_color(1,23,992);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Expose sequential object writes using an absolute color-slot index.

void cgb_obj_colors_raw(u8 start_color_slot, const u16* colors, u8 color_count)
{
    cgb__write_colors_obj_raw(start_color_slot, colors, color_count);
}

Sustituye los cuatro colores de una paleta de sprites (OBJ) con cuatro palabras RGB15. Equivale a escribir un rango desde el color cero con cantidad cuatro; no asigna la paleta a casillas ni sprites.

Sintaxis

void cgb_obj_palette(u8 palette_index, const u16* colors);

Parámetros

palette_index

Número de paleta, 0–7; solo usa los tres bits bajos (& 7).

colors

const u16* legible con las palabras de color necesarias. Los datos se consumen durante la llamada, sin encolarlos. Mantén accesibles la fuente y su banco ROM; no se cambia de banco automáticamente. Un puntero nulo no produce escrituras.

Valor devuelto

Ninguno (void).

Condiciones y límites

Las escrituras de paleta y de registros protegidos no escriben nada en modo DMG. Safe indica una comprobación de modo CGB, no una espera de acceso a PPU ni una sección crítica. Configura con LCD apagado o realiza una actualización breve durante una fase accesible. No espera VBlank ni protege una escritura de varios bytes frente a interrupciones.

Las paletas BG/ventana y OBJ son almacenes separados. Las escrituras de la biblioteca activan el incremento y dejan modificado el registro de índice. El color OBJ cero es transparente al dibujar sprites, aunque sus bytes se puedan guardar y leer.

Ejemplo de uso

cgb_obj_palette(4,blue_palette); // Exactly four words; OBJ color zero is transparent on screen.
expect_color(1,16,32767); expect_color(1,19,31744);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Write four consecutive colors for one object palette.

void cgb_obj_palette(u8 palette_index, const u16* colors)
{
    cgb_obj_colors(palette_index, 0, colors, 4);
}

Consulte los cambios y la verificación del 2026-10-03 para las diferencias locales de esta API.

Empaqueta los componentes rojo, verde y azul con cgb_rgb15 y escribe un color en las paletas de sprites (OBJ). Úsalo para proporcionar los componentes por separado en lugar de una palabra empaquetada.

Sintaxis

void cgb_obj_rgb(u8 palette_index, u8 color_index, u8 r5, u8 g5, u8 b5);

Parámetros

palette_index

Número de paleta, 0–7; solo usa los tres bits bajos (& 7).

color_index

Índice de color dentro de la paleta, 0–3; solo usa los dos bits bajos (& 3).

r5, g5, b5

Componentes rojo, verde y azul respectivamente, normalmente 0–31 cada uno. Se enmascaran sin saturación; cada argumento aparece una sola vez en la expansión de la macro.

Valor devuelto

Ninguno (void).

Condiciones y límites

Las escrituras de paleta y de registros protegidos no escriben nada en modo DMG. Safe indica una comprobación de modo CGB, no una espera de acceso a PPU ni una sección crítica. Configura con LCD apagado o realiza una actualización breve durante una fase accesible. No espera VBlank ni protege una escritura de varios bytes frente a interrupciones.

Las paletas BG/ventana y OBJ son almacenes separados. Las escrituras de la biblioteca activan el incremento y dejan modificado el registro de índice. El color OBJ cero es transparente al dibujar sprites, aunque sus bytes se puedan guardar y leer.

Ejemplo de uso

cgb_obj_rgb(2,3,0,31,0); // Green sprite color.
expect_color(1,11,992);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Pack component values and write one object color.

void cgb_obj_rgb(u8 palette_index, u8 color_index, u8 r5, u8 g5, u8 b5)
{
    cgb_obj_color(palette_index, color_index, cgb_rgb15(r5, g5, b5));
}

Empaqueta RGB en un u16: rojo en bits 0–4, verde en 5–9 y azul en 10–14; el bit 15 queda a cero. Cada componente se enmascara con 31: se conservan sus cinco bits bajos, sin saturación. Solo calcula el valor, tanto en DMG como en CGB; no escribe en el hardware.

Sintaxis

#define CGB_RGB15(r5, g5, b5) ((u16)((u16)((r5) & 31) | ((u16)((g5) & 31) << 5) | ((u16)((b5) & 31) << 10)))

Parámetros

r5, g5, b5

Componentes rojo, verde y azul respectivamente, normalmente 0–31 cada uno. Se enmascaran sin saturación; cada argumento aparece una sola vez en la expansión de la macro.

Valor devuelto

Valor RGB15 empaquetado como u16, de 0 a 32767.

Ejemplo de uso

if (CGB_RGB15(component,64,95)!=31775) failures++; // (31,0,31), not saturation.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Empaqueta RGB en un u16: rojo en bits 0–4, verde en 5–9 y azul en 10–14; el bit 15 queda a cero. Cada componente se enmascara con 31: se conservan sus cinco bits bajos, sin saturación. Solo calcula el valor, tanto en DMG como en CGB; no escribe en el hardware.

Sintaxis

u16 cgb_rgb15(u8 r5, u8 g5, u8 b5);

Parámetros

r5, g5, b5

Componentes rojo, verde y azul respectivamente, normalmente 0–31 cada uno. Se enmascaran sin saturación; cada argumento aparece una sola vez en la expansión de la macro.

Valor devuelto

Valor RGB15 empaquetado como u16, de 0 a 32767.

Ejemplo de uso

if (cgb_rgb15(component,64,95)!=31775) failures++; // Same packed value through a function.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Pack the red, green and blue components using the public RGB15 macro.

u16 cgb_rgb15(u8 r5, u8 g5, u8 b5)
{
    return CGB_RGB15(r5, g5, b5);
}

Construye el byte completo de atributo de mapa CGB con paleta, banco de patrones, reflejo horizontal, reflejo vertical y prioridad BG. La paleta ocupa bits 0–2; los cuatro booleanos activan bits 3, 5, 6 y 7. El bit 4 queda a cero.

Sintaxis

#define KQ_CGB_ATTR(palette, bank, xflip, yflip, priority) ((u8)(((palette) & KQ_CGB_ATTR_PAL_MASK) | ((bank) ? KQ_CGB_ATTR_BANK1 : 0) | ((xflip) ? KQ_CGB_ATTR_XFLIP : 0) | ((yflip) ? KQ_CGB_ATTR_YFLIP : 0) | ((priority) ? KQ_CGB_ATTR_PRIORITY : 0)))

Parámetros

palette

Número de paleta, 0–7; solo usa los tres bits bajos (& 7).

bank, xflip, yflip, priority

Cero desactiva el campo; cualquier valor no nulo lo activa. El 2 también lo activa: se comprueba si es distinto de cero, no su bit bajo.

Valor devuelto

Campo o byte de atributo combinado como u8, con la disposición de bits descrita.

Condiciones y límites

Estas macros solo calculan valores u8; no escriben VRAM ni registros. Cada argumento aparece una vez. Aplica el resultado con una API de atributos CGB o escribiendo explícitamente en el mapa del banco 1. DMG no muestra los atributos CGB.

Construye el bit 3 del atributo de mapa CGB: devuelve 0x08 si bank no es cero y 0 en caso contrario. Elige el banco VRAM del patrón mostrado; no escribe VBK ni cambia el banco de la CPU.

Construye la marca de reflejo horizontal: 0x20 si enabled no es cero, o 0. En un atributo de mapa CGB, invierte los ocho píxeles de cada fila del patrón al mostrarlo, sin modificarlo en memoria.

Construye la marca de reflejo vertical: 0x40 si enabled no es cero, o 0. En el mapa CGB, muestra las ocho filas en orden inverso sin cambiar el patrón almacenado.

Construye la prioridad BG sobre OBJ: 0x80 si enabled no es cero, o 0. Con la prioridad general CGB activa (bit 0 de LCDC), los índices de color BG distintos de cero cubren los sprites. El índice cero deja verlos; la marca no vuelve opaca toda la casilla.

Ejemplo de uso

attr=KQ_CGB_ATTR(10,0,2,2,0); // Palette 2, bank 0, both reflections: 0x62.
if (attr!=98 || KQ_CGB_ATTR(10,2,3,4,5)!=234) failures++;
cell(10,11,1,attr);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Construye el bit 3 del atributo de mapa CGB: devuelve 0x08 si bank no es cero y 0 en caso contrario. Elige el banco VRAM del patrón mostrado; no escribe VBK ni cambia el banco de la CPU.

Sintaxis

#define KQ_CGB_ATTR_BANK(bank) ((u8)((bank) ? KQ_CGB_ATTR_BANK1 : 0))

Parámetros

bank

Cero desactiva el campo; cualquier valor no nulo lo activa. El 2 también lo activa: se comprueba si es distinto de cero, no su bit bajo.

Valor devuelto

Campo o byte de atributo combinado como u8, con la disposición de bits descrita.

Condiciones y límites

Estas macros solo calculan valores u8; no escriben VRAM ni registros. Cada argumento aparece una vez. Aplica el resultado con una API de atributos CGB o escribiendo explícitamente en el mapa del banco 1. DMG no muestra los atributos CGB.

Ejemplo de uso

attr=(u8)(2|KQ_CGB_ATTR_BANK(enabled)); // Any nonzero value selects tile-data bank 1.
if (attr!=10) failures++;
cell(4,11,1,attr); // Blue hollow square, unlike the bank-0 triangle.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Construye el campo de paleta de un atributo de mapa CGB: n & 7, como u8. Combínalo con otras marcas mediante OR bit a bit.

Sintaxis

#define KQ_CGB_ATTR_PAL(n) ((u8)((n) & KQ_CGB_ATTR_PAL_MASK))

Parámetros

n

Número de paleta, 0–7; solo usa los tres bits bajos (& 7).

Valor devuelto

Campo o byte de atributo combinado como u8, con la disposición de bits descrita.

Condiciones y límites

Estas macros solo calculan valores u8; no escriben VRAM ni registros. Cada argumento aparece una vez. Aplica el resultado con una API de atributos CGB o escribiendo explícitamente en el mapa del banco 1. DMG no muestra los atributos CGB.

Ejemplo de uso

attr=KQ_CGB_ATTR_PAL(9); // 9 & 7 = palette 1, red in this BG example.
if (attr!=1) failures++;
cell(2,11,1,attr);

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Construye la prioridad BG sobre OBJ: 0x80 si enabled no es cero, o 0. Con la prioridad general CGB activa (bit 0 de LCDC), los índices de color BG distintos de cero cubren los sprites. El índice cero deja verlos; la marca no vuelve opaca toda la casilla.

Sintaxis

#define KQ_CGB_ATTR_PRIORITY_IF(enabled) ((u8)((enabled) ? KQ_CGB_ATTR_PRIORITY : 0))

Parámetros

enabled

Cero desactiva el campo; cualquier valor no nulo lo activa. El 2 también lo activa: se comprueba si es distinto de cero, no su bit bajo.

Valor devuelto

Campo o byte de atributo combinado como u8, con la disposición de bits descrita.

Condiciones y límites

Estas macros solo calculan valores u8; no escriben VRAM ni registros. Cada argumento aparece una vez. Aplica el resultado con una API de atributos CGB o escribiendo explícitamente en el mapa del banco 1. DMG no muestra los atributos CGB.

Ejemplo de uso

attr=(u8)(3|KQ_CGB_ATTR_PRIORITY_IF(enabled)); // Keep nonzero BG pixels in front of sprites.
if (attr!=131) failures++;
cell(12,11,1,attr);
sprite(7,96,88,2,3); // Red full tile behind the green priority triangle.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Construye la marca de reflejo horizontal: 0x20 si enabled no es cero, o 0. En un atributo de mapa CGB, invierte los ocho píxeles de cada fila del patrón al mostrarlo, sin modificarlo en memoria.

Sintaxis

#define KQ_CGB_ATTR_XFLIP_IF(enabled) ((u8)((enabled) ? KQ_CGB_ATTR_XFLIP : 0))

Parámetros

enabled

Cero desactiva el campo; cualquier valor no nulo lo activa. El 2 también lo activa: se comprueba si es distinto de cero, no su bit bajo.

Valor devuelto

Campo o byte de atributo combinado como u8, con la disposición de bits descrita.

Condiciones y límites

Estas macros solo calculan valores u8; no escriben VRAM ni registros. Cada argumento aparece una vez. Aplica el resultado con una API de atributos CGB o escribiendo explícitamente en el mapa del banco 1. DMG no muestra los atributos CGB.

Ejemplo de uso

attr=(u8)(3|KQ_CGB_ATTR_XFLIP_IF(enabled));
if (attr!=35) failures++;
cell(6,11,1,attr); // Green triangle reflected horizontally.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Construye la marca de reflejo vertical: 0x40 si enabled no es cero, o 0. En el mapa CGB, muestra las ocho filas en orden inverso sin cambiar el patrón almacenado.

Sintaxis

#define KQ_CGB_ATTR_YFLIP_IF(enabled) ((u8)((enabled) ? KQ_CGB_ATTR_YFLIP : 0))

Parámetros

enabled

Cero desactiva el campo; cualquier valor no nulo lo activa. El 2 también lo activa: se comprueba si es distinto de cero, no su bit bajo.

Valor devuelto

Campo o byte de atributo combinado como u8, con la disposición de bits descrita.

Condiciones y límites

Estas macros solo calculan valores u8; no escriben VRAM ni registros. Cada argumento aparece una vez. Aplica el resultado con una API de atributos CGB o escribiendo explícitamente en el mapa del banco 1. DMG no muestra los atributos CGB.

Ejemplo de uso

attr=(u8)(1|KQ_CGB_ATTR_YFLIP_IF(enabled));
if (attr!=65) failures++;
cell(8,11,1,attr); // Red triangle reflected vertically.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

El programa muestra cómo las paletas BG y OBJ colorean de forma independiente el mismo patrón. Cada triángulo ocupa 8 × 8 píxeles: comienza con un píxel a la izquierda arriba y termina con una fila completa abajo. En x = 16, 32, 48, 64, 80, 96, 112, la fila BG de y = 24 es roja, azul, verde, roja, azul, verde, roja; la OBJ de y = 64 es azul, verde, roja, azul, verde, roja, azul. Las columnas usan, respectivamente, color único, componentes, rango indexado, paleta completa, rango absoluto, registro canónico y alias de registro.

En y = 88 hay siete casillas de 8 × 8: triángulo rojo (x = 16), contorno cuadrado azul de un píxel del banco 1 (32), triángulo verde reflejado horizontalmente (48), rojo reflejado verticalmente (64), azul reflejado en ambos ejes (80), triángulo verde sobre un sprite rojo visible a través del color cero (96), y sprite rojo sólido delante del triángulo BG como control sin prioridad (112). Las coordenadas son píxeles desde la esquina superior izquierda. Fondo blanco y texto negro.

FAILED CHECKS 000 confirma máscaras RGB, booleanos (incluido 2), índices de paleta normalizados, cruce de paletas, límite en posición 31, punteros nulos y longitud cero sin escrituras, y lectura de colores con LCD apagado. Se prueban cuatro combinaciones: ROM dual en DMG/CGB, ROM solo DMG en DMG y solo CGB en CGB. En DMG, CGB MODE vale 0, los triángulos son negros, banco/reflejos no afectan a la imagen y las dos últimas casillas inferiores son cuadrados negros. En CGB, CGB MODE vale 1. No se prueban hardware real ni conflictos de paleta con LCD encendido.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\cgb_palette_attributes.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\cgb_palette_attributes.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --no-cache --no-disasm

Calcula el desplazamiento con signo más corto desde la posición actual al objetivo en un eje cuyos extremos se unen. Úsalo para seguimiento o comparación de distancias a través del borde del campo.

Sintaxis

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

Parámetros

target

Coordenada objetivo, de 0 a size−1.

current

Coordenada actual, de 0 a size−1.

size

Longitud del eje circular, de 1 a 256: ancho para X y alto para Y. Es un argumento de 16 bits para poder representar 256.

Valor devuelto

Devuelve el desplazamiento más corto como s16: positivo hacia coordenadas crecientes, negativo hacia decrecientes y cero en la misma posición. Las entradas válidas dan −128..+128. En pantalla, derecha y abajo son positivos.

Condiciones y límites

Incluye chain.h y compila chain.c exactamente una vez. No hace falta inicializar Chain ni ChainBody. La función solo calcula un desplazamiento; no modifica arrays de coordenadas, número de articulaciones ni pantalla.

La función no valida ni normaliza entradas. No pases size=0, size>256 ni coordenadas iguales o mayores que size. Ajusta de forma circular las de un sistema mayor a 0..size−1 antes de llamar.

Si ambas rutas tienen la misma longitud, conserva el signo del desplazamiento directo target−current. Con size=160, 0→80 devuelve +80 y 80→0 devuelve −80. Con size=1, cero es la única coordenada válida y el resultado es cero.

Ejemplo de uso

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.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

Este ejemplo muestra coordenadas circulares. Cada flecha va de la posición actual al objetivo. Muestra +02/−02 al cruzar un borde de ancho 160, +80/−80 para medio campo y +00 para ancho 1. El cero inicial es relleno decimal. El ejemplo no dibuja ni mueve un objeto.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\chain_wrap.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\chain_wrap.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --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 (delta > half) delta = (s16)(delta - (s16)size);
    else if (delta < (s16)(0 - half)) delta = (s16)(delta + (s16)size);
    return delta;
}

Asocia tres arrays de articulaciones del código que llama y pone el número a cero, sin reservar memoria.

Sintaxis

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

Parámetros

body

ChainBody de destino; se ignora null. Salvo al inicializar, pasa un estado inicializado.

x

Array de coordenadas X de las articulaciones.

y

Array de coordenadas Y de las articulaciones.

heading

Array de direcciones de las articulaciones.

capacity

Longitud reservada del array, de 1 a 255.

width

Ancho del campo con bordes conectados, de 1 a 256.

height

Alto del campo con bordes conectados, de 1 a 256.

Valor devuelto

Devuelve 1 si tiene éxito y 0 si los argumentos no son válidos. Si falla con un cuerpo no nulo, pone capacity y count a cero y desactiva las actualizaciones.

Condiciones y límites

Incluye chain.h y compila chain.c exactamente una vez. ChainBody guarda la posición y dirección actuales de cada articulación. Es un tipo de estado distinto del historial circular de posiciones Chain.

Proporciona tres arrays escribibles separados, x, y y heading, de capacity bytes cada uno. Mantenlos válidos mientras se use el cuerpo. El índice cero es la cabeza, incluida en count. No cambies los punteros, la capacidad ni las dimensiones del campo tras inicializar.

Las direcciones usan 16 sectores en sentido horario: 0=derecha, 4=abajo, 8=izquierda, 12=arriba. Solo se usan los cuatro bits bajos. Las coordenadas crecen hacia la derecha y abajo; cada dimensión va de 1 a 256 píxeles.

Ejemplo de uso

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.

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

La imagen muestra arriba un cuerpo recto, en medio una actualización después de girar hacia abajo y abajo cuatro actualizaciones tras el giro. Las coordenadas se dibujan al doble de su tamaño lógico. El giro se propaga hacia atrás desde la cabeza a la derecha. CGB y FC usan rojo para la cabeza, azul para el cuerpo y verde para la cola; DMG usa negro. Cuatro actualizaciones de estabilización separan la cola duplicada tras crecer. Son tres vistas de las mismas ocho articulaciones, no un cuerpo de 24.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\chain_body.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\chain_body.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --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;
}

Construye una postura inicial recta colocando articulaciones detrás de la cabeza indicada.

Sintaxis

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

Parámetros

body

ChainBody de destino; se ignora null. Salvo al inicializar, pasa un estado inicializado.

count

Número de articulaciones, incluida la cabeza, de 1 a capacity.

head_x

Coordenada X de la cabeza, ajustada de forma circular al ancho del campo.

head_y

Coordenada Y de la cabeza, ajustada de forma circular al alto del campo.

heading

Dirección de la cabeza en el sistema de 16 sectores.

Valor devuelto

Devuelve 1 si tiene éxito. Un número cero o excesivo, o un cuerpo nulo, devuelve 0 sin cambiar la postura.

Condiciones y límites

Incluye chain.h y compila chain.c exactamente una vez. ChainBody guarda la posición y dirección actuales de cada articulación. Es un tipo de estado distinto del historial circular de posiciones Chain.

Proporciona tres arrays escribibles separados, x, y y heading, de capacity bytes cada uno. Mantenlos válidos mientras se use el cuerpo. El índice cero es la cabeza, incluida en count. No cambies los punteros, la capacidad ni las dimensiones del campo tras inicializar.

Las direcciones usan 16 sectores en sentido horario: 0=derecha, 4=abajo, 8=izquierda, 12=arriba. Solo se usan los cuatro bits bajos. Las coordenadas crecen hacia la derecha y abajo; cada dimensión va de 1 a 256 píxeles.

La separación cardinal es de cuatro píxeles. Las direcciones intermedias usan vectores enteros como (4,1), (3,3) y (1,4), así que la distancia euclídea no es exactamente cuatro píxeles. La postura inicial puede cruzar un borde del campo.

Ejemplo de uso

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

Este fragmento muestra la llamada. Antes de incorporarlo a un programa completo, cumple los requisitos de inicialización y de los búferes indicados.

Resultado esperado

La imagen muestra arriba un cuerpo recto, en medio una actualización después de girar hacia abajo y abajo cuatro actualizaciones tras el giro. Las coordenadas se dibujan al doble de su tamaño lógico. El giro se propaga hacia atrás desde la cabeza a la derecha. CGB y FC usan rojo para la cabeza, azul para el cuerpo y verde para la cola; DMG usa negro. Cuatro actualizaciones de estabilización separan la cola duplicada tras crecer. Son tres vistas de las mismas ocho articulaciones, no un cuerpo de 24.

Programa de ejemplo completo

Comando de compilación

New-Item -ItemType Directory -Force .\out | Out-Null
.\kitaqgb\kitaqgb.exe .\kitaq-docs\samples\api-examples\gb\chain_body.c -I .\kitaqgb\lib -I .\kitaq-docs\samples -o .\out\chain_body.gb --profile=dev --rst-disable --stack-bank=fixed --cgb=cgb --cart=mbc5 --romsize=128k --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)
{
    u8 i;
    u8 x;
    u8 y;
    s16 ox;
    s16 oy;
    if (body == 0) return 0;
    if (count == 0 || count > body->capacity) return 0;
    heading = (u8)(heading & 15);
    x = chain_body_wrap((s16)head_x, body->width);
    y = chain_body_wrap((s16)head_y, body->height);
    ox = chain_body_offset_x(heading);
    oy = chain_body_offset_y(heading);
    i = 0;
    while (i < count) {
        body->x[(__safe_index u8)i] = x;
        body->y[(__safe_index u8)i] = y;
        body->heading[(__safe_index u8)i] = heading;
        x = chain_body_wrap((s16)((s16)x - ox), body->width);
        y = chain_body_wrap((s16)((s16)y - oy), body->height);
        i = (u8)(i + 1);
    }
    body->count = count;
    return 1;
}

Establece la postura de la cabeza y acerca gradualmente cada articulación al punto de unión detrás de su predecesora. Los cambios de dirección se propagan una articulación por actualización.

Sintaxis

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

Parámetros

body

ChainBody de destino; se ignora null. Salvo al inicializar, pasa un estado inicializado.

head_x

Coordenada X de la cabeza, ajustada de forma circular al ancho del campo.

head_y

Coordenada Y de la cabeza, ajustada de forma circular al alto del campo.

heading

Dirección de la cabeza en el sistema de 16 sectores.