KITAQFC 라이브러리

월드 좌표에서 축에 정렬된 액터 사각형의 겹침을 검사합니다.

사용 형식

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

매개변수

a

첫 번째 액터입니다.

b

두 번째 액터입니다.

반환값

겹치면 1, 분리되어 있거나 가장자리만 닿으면 0을 반환합니다.

사용 조건과 제한

너비·높이는 양수를 쓰고 위치+크기≤65535를 유지하세요. 화면 좌표, attr, flags는 무시합니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

월드 (300,95)를 카메라 (268,32)로 변환하면 빨강·파랑 8×8 부분이 (32,64), (40,64)에 나타납니다. 원시 OAM Y=63이 화면의 64에 나타나는 것과, 가장자리 접촉일 때 0이던 충돌 결과가 1픽셀 겹치면 1이 되는 것을 보여 줍니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

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

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

    return 1;
}

액터의 저장된 화면 좌표로 메타스프라이트를 OAM 복사본에 씁니다.

사용 형식

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

매개변수

actor

쓰기 가능한 NesActor 포인터입니다.

oam_index

첫 슬롯 0~63입니다. 모든 부분을 담을 공간을 예약하세요.

metasprite

dx,dy,tile,attr의 4바이트 레코드입니다. dx=255이면 끝납니다.

반환값

다음 OAM 슬롯 인덱스를 반환하며, 64개 슬롯의 끝에서 순환합니다.

사용 조건과 제한

runtime.c를 링크하세요. 큐는 나중의 NMI나 렌더링이 꺼진 안전한 시점에 반영할 데이터를 복사합니다. 큐 생성과 소비가 겹치지 않게 하세요. 여러 행을 처리하다 용량이 부족해져도 이미 수락한 행은 큐에 남습니다.

액터의 attr/flags 필드는 적용하지 않습니다. Y는 원시 OAM 바이트이므로 실제 상단은 1픽셀 아래입니다. OAM 복사본을 화면에 표시하려면 OAM DMA가 필요합니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

월드 (300,95)를 카메라 (268,32)로 변환하면 빨강·파랑 8×8 부분이 (32,64), (40,64)에 나타납니다. 원시 OAM Y=63이 화면의 64에 나타나는 것과, 가장자리 접촉일 때 0이던 충돌 결과가 1픽셀 겹치면 1이 되는 것을 보여 줍니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

액터의 월드 X/Y를 설정합니다.

사용 형식

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

매개변수

actor

쓰기 가능한 NesActor 포인터입니다.

x

월드 X, 0~65535픽셀입니다.

y

월드 Y, 0~65535픽셀입니다.

반환값

반환값은 없습니다.

사용 조건과 제한

screen_x/screen_y는 갱신하지 않습니다. 카메라를 통해 화면 좌표로 변환하려면 update_screen을 호출하세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

월드 (300,95)를 카메라 (268,32)로 변환하면 빨강·파랑 8×8 부분이 (32,64), (40,64)에 나타납니다. 원시 OAM Y=63이 화면의 64에 나타나는 것과, 가장자리 접촉일 때 0이던 충돌 결과가 1픽셀 겹치면 1이 되는 것을 보여 줍니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

월드 좌표에서 카메라 좌표를 빼고, 하위 바이트를 화면 좌표로 저장합니다.

사용 형식

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

매개변수

actor

쓰기 가능한 NesActor 포인터입니다.

camera_x

카메라의 월드 X입니다.

camera_y

카메라의 월드 Y입니다.

반환값

반환값은 없습니다.

사용 조건과 제한

음수이거나 256 이상인 결과는 래핑됩니다. 화면 밖 액터를 숨기지 않으므로 그리기 전에 게임에서 제외해야 합니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

월드 (300,95)를 카메라 (268,32)로 변환하면 빨강·파랑 8×8 부분이 (32,64), (40,64)에 나타납니다. 원시 OAM Y=63이 화면의 64에 나타나는 것과, 가장자리 접촉일 때 0이던 충돌 결과가 1픽셀 겹치면 1이 되는 것을 보여 줍니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

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

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

등록된 목록의 ROM 뱅크에서 AssetDesc 하나를 읽어 호출자가 준비한 공간에 복사합니다. 소재 본체가 아니라 소재의 정보를 가져옵니다.

사용 형식

u8 asset_get(u8 asset_id, AssetDesc* out_desc);

매개변수

asset_id

0부터 시작하는 소재 번호입니다. 등록된 목록의 항목 수가 count일 때 asset_id < count인 ID가 유효합니다.

out_desc

6바이트 설명자 하나를 저장할 수 있는 쓰기 가능한 영역입니다. 널 포인터이면 목록에 접근하기 전에 실패를 반환합니다.

반환값

설명자를 복사하면 1, 출력 포인터가 널이거나 ID가 범위를 벗어나면 0입니다. 이 실패 경로에서는 출력 공간을 변경하지 않습니다.

사용 조건과 제한

조회 전에 목록을 등록하세요. 등록 정보는 공유 전역 상태이므로 조회 중에 바꾸면 안 됩니다. 라이브러리는 ID와 asset_get의 출력 포인터를 검사하지만 등록된 목록, 소재 주소, 카트리지 내용의 유효성은 검사하지 않습니다.

예제의 호출 코드는 고정 뱅크 0에 두어 원본 뱅크를 바꿔도 실행 중인 코드가 사라지지 않도록 합니다. 전송은 동기식입니다. 전송 도중 인터럽트에서 다른 뱅크 전환 복사를 실행하지 마세요. 이 함수만으로 프로그램 전체의 인터럽트 안전성이 확보되지는 않습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

설명자 0을 읽어 TILES 유형, 뱅크 2, 소재 포인터, 144바이트 길이를 확인합니다. 범위 밖 ID와 널 출력 포인터는 실패해야 하며, 조회 실패 시 기존 출력값이 유지되는지도 확인합니다.

예상 화면의 빨간 줄은 픽셀 좌표 (16,32)에서 시작하며 72×8픽셀입니다. 8×8 삼각형, 테두리 두께 1픽셀인 8×8 사각형, 왼쪽 네 열을 채운 타일을 세 번 반복합니다. 삼각형은 왼쪽 위의 1픽셀에서 맨 아래 줄의 8픽셀까지 넓어집니다.

FC에서 (16,64)의 파란 삼각형과 테두리는 __far_memcpy 결과이며, (16,96)의 초록색 쌍은 asset_load_raw 후 CHR로 전송한 결과입니다. 검은 바탕에서 각 쌍은 16×8픽셀입니다. 숫자 상태값뿐 아니라 복사된 이미지 바이트를 직접 확인할 수 있습니다.

예상 상태 표시는 FAILED CHECKS 000과 FIRST FAILURE 00입니다. 검증은 300프레임 동안 실행한 뒤 글자, 도형 마스크, 색을 예상값과 비교합니다. 에뮬레이터 검증이며 실제 하드웨어 시험은 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

설명자에서 소재 본체의 뱅크 번호를 읽습니다. 목록이 들어 있는 뱅크 번호가 아닙니다. 반환 후에도 소재 뱅크가 선택된 상태로 남지 않습니다.

사용 형식

u8 asset_get_bank(u8 asset_id);

매개변수

asset_id

0부터 시작하는 소재 번호입니다. 등록된 목록의 항목 수가 count일 때 asset_id < count인 ID가 유효합니다.

반환값

설명자의 8비트 bank를 반환하며 조회 실패 시 0입니다. 유효한 뱅크도 0일 수 있으므로 성공 여부를 구분하려면 asset_get()을 사용하세요.

사용 조건과 제한

조회 전에 목록을 등록하세요. 등록 정보는 공유 전역 상태이므로 조회 중에 바꾸면 안 됩니다. 라이브러리는 ID와 asset_get의 출력 포인터를 검사하지만 등록된 목록, 소재 주소, 카트리지 내용의 유효성은 검사하지 않습니다.

각 조회 함수는 호출할 때마다 asset_get으로 설명자를 복사합니다. 뱅크, 포인터, 길이가 모두 필요하다면 asset_get을 한 번 호출하고 필드를 읽으세요.

예제의 호출 코드는 고정 뱅크 0에 두어 원본 뱅크를 바꿔도 실행 중인 코드가 사라지지 않도록 합니다. 전송은 동기식입니다. 전송 도중 인터럽트에서 다른 뱅크 전환 복사를 실행하지 마세요. 이 함수만으로 프로그램 전체의 인터럽트 안전성이 확보되지는 않습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

목록이 뱅크 3에 있어도 소재 본체의 뱅크 2를 반환하는지 확인합니다. 잘못된 ID에서 0을 반환하는지도 검사합니다.

예상 화면의 빨간 줄은 픽셀 좌표 (16,32)에서 시작하며 72×8픽셀입니다. 8×8 삼각형, 테두리 두께 1픽셀인 8×8 사각형, 왼쪽 네 열을 채운 타일을 세 번 반복합니다. 삼각형은 왼쪽 위의 1픽셀에서 맨 아래 줄의 8픽셀까지 넓어집니다.

FC에서 (16,64)의 파란 삼각형과 테두리는 __far_memcpy 결과이며, (16,96)의 초록색 쌍은 asset_load_raw 후 CHR로 전송한 결과입니다. 검은 바탕에서 각 쌍은 16×8픽셀입니다. 숫자 상태값뿐 아니라 복사된 이미지 바이트를 직접 확인할 수 있습니다.

예상 상태 표시는 FAILED CHECKS 000과 FIRST FAILURE 00입니다. 검증은 300프레임 동안 실행한 뒤 글자, 도형 마스크, 색을 예상값과 비교합니다. 에뮬레이터 검증이며 실제 하드웨어 시험은 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

설명자에서 소재 길이를 바이트 단위로 읽습니다. 등록된 정보를 반환할 뿐, 소재 본체를 검사하거나 타일 수, 요소 수, 프레임 수로 환산하지 않습니다.

사용 형식

u16 asset_get_len(u8 asset_id);

매개변수

asset_id

0부터 시작하는 소재 번호입니다. 등록된 목록의 항목 수가 count일 때 asset_id < count인 ID가 유효합니다.

반환값

바이트 단위의 16비트 len을 반환하며 조회 실패 시 0입니다. 빈 소재도 길이가 0이므로 두 경우를 구분하려면 asset_get()을 사용하세요.

사용 조건과 제한

조회 전에 목록을 등록하세요. 등록 정보는 공유 전역 상태이므로 조회 중에 바꾸면 안 됩니다. 라이브러리는 ID와 asset_get의 출력 포인터를 검사하지만 등록된 목록, 소재 주소, 카트리지 내용의 유효성은 검사하지 않습니다.

각 조회 함수는 호출할 때마다 asset_get으로 설명자를 복사합니다. 뱅크, 포인터, 길이가 모두 필요하다면 asset_get을 한 번 호출하고 필드를 읽으세요.

예제의 호출 코드는 고정 뱅크 0에 두어 원본 뱅크를 바꿔도 실행 중인 코드가 사라지지 않도록 합니다. 전송은 동기식입니다. 전송 도중 인터럽트에서 다른 뱅크 전환 복사를 실행하지 마세요. 이 함수만으로 프로그램 전체의 인터럽트 안전성이 확보되지는 않습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

9타일 소재가 타일 수 9가 아닌 바이트 수 144를 반환하는지 확인합니다. 빈 소재와 잘못된 ID는 모두 0이어야 합니다.

예상 화면의 빨간 줄은 픽셀 좌표 (16,32)에서 시작하며 72×8픽셀입니다. 8×8 삼각형, 테두리 두께 1픽셀인 8×8 사각형, 왼쪽 네 열을 채운 타일을 세 번 반복합니다. 삼각형은 왼쪽 위의 1픽셀에서 맨 아래 줄의 8픽셀까지 넓어집니다.

FC에서 (16,64)의 파란 삼각형과 테두리는 __far_memcpy 결과이며, (16,96)의 초록색 쌍은 asset_load_raw 후 CHR로 전송한 결과입니다. 검은 바탕에서 각 쌍은 16×8픽셀입니다. 숫자 상태값뿐 아니라 복사된 이미지 바이트를 직접 확인할 수 있습니다.

예상 상태 표시는 FAILED CHECKS 000과 FIRST FAILURE 00입니다. 검증은 300프레임 동안 실행한 뒤 글자, 도형 마스크, 색을 예상값과 비교합니다. 에뮬레이터 검증이며 실제 하드웨어 시험은 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

설명자에 저장된 16비트 소재 주소를 읽습니다. 반환되는 근거리 포인터에는 뱅크 번호가 없습니다. 다른 ROM 뱅크의 소재를 읽을 때는 asset_get_bank()의 결과와 함께 뱅크 간 복사 함수를 사용하세요.

사용 형식

const u8* asset_get_ptr(u8 asset_id);

매개변수

asset_id

0부터 시작하는 소재 번호입니다. 등록된 목록의 항목 수가 count일 때 asset_id < count인 ID가 유효합니다.

반환값

저장된 const u8*를 반환하며 조회 실패 시 널입니다. 설명자 안의 소재 포인터가 널인지 검사하지 않으므로 조회 실패를 구분하려면 asset_get()을 사용하세요.

사용 조건과 제한

조회 전에 목록을 등록하세요. 등록 정보는 공유 전역 상태이므로 조회 중에 바꾸면 안 됩니다. 라이브러리는 ID와 asset_get의 출력 포인터를 검사하지만 등록된 목록, 소재 주소, 카트리지 내용의 유효성은 검사하지 않습니다.

각 조회 함수는 호출할 때마다 asset_get으로 설명자를 복사합니다. 뱅크, 포인터, 길이가 모두 필요하다면 asset_get을 한 번 호출하고 필드를 읽으세요.

예제의 호출 코드는 고정 뱅크 0에 두어 원본 뱅크를 바꿔도 실행 중인 코드가 사라지지 않도록 합니다. 전송은 동기식입니다. 전송 도중 인터럽트에서 다른 뱅크 전환 복사를 실행하지 마세요. 이 함수만으로 프로그램 전체의 인터럽트 안전성이 확보되지는 않습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

반환된 포인터가 ROM 배치 후의 소재 주소와 같고 뱅크 1의 확인용 값도 계속 읽히는지 확인합니다. 이후 그 포인터와 소재 뱅크 2를 뱅크 간 복사 함수에 전달합니다.

예상 화면의 빨간 줄은 픽셀 좌표 (16,32)에서 시작하며 72×8픽셀입니다. 8×8 삼각형, 테두리 두께 1픽셀인 8×8 사각형, 왼쪽 네 열을 채운 타일을 세 번 반복합니다. 삼각형은 왼쪽 위의 1픽셀에서 맨 아래 줄의 8픽셀까지 넓어집니다.

FC에서 (16,64)의 파란 삼각형과 테두리는 __far_memcpy 결과이며, (16,96)의 초록색 쌍은 asset_load_raw 후 CHR로 전송한 결과입니다. 검은 바탕에서 각 쌍은 16×8픽셀입니다. 숫자 상태값뿐 아니라 복사된 이미지 바이트를 직접 확인할 수 있습니다.

예상 상태 표시는 FAILED CHECKS 000과 FIRST FAILURE 00입니다. 검증은 300프레임 동안 실행한 뒤 글자, 도형 마스크, 색을 예상값과 비교합니다. 에뮬레이터 검증이며 실제 하드웨어 시험은 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

소재를 찾아 해당 ROM 뱅크에서 쓰기 가능한 메모리로 min(desc.len, max_len)바이트를 복사합니다. 유형은 검사하지 않으며 타일, 맵, 곡 데이터도 바이트 그대로 복사합니다. 디코딩이나 압축 해제는 하지 않습니다.

사용 형식

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

매개변수

asset_id

0부터 시작하는 소재 번호입니다. 등록된 목록의 항목 수가 count일 때 asset_id < count인 ID가 유효합니다.

dst

쓰기 대상 메모리입니다. 실제 복사량을 모두 담을 공간을 확보하세요. 0바이트 전송을 제외하면 널 포인터나 잘못된 대상 주소를 검사하지 않습니다.

max_len

복사할 최대 바이트 수이며 범위는 0~65535입니다. 소재 길이보다 작으면 일부만 복사합니다. 0이면 소재 바이트를 복사하지 않습니다.

반환값

조회 실패 시 0, 그 외에는 1입니다. 일부만 복사했거나 한도가 0이거나 빈 소재여도 1입니다. 반환값은 바이트 수가 아니며 전체 소재를 담았다는 보장도 아닙니다.

사용 조건과 제한

조회 전에 목록을 등록하세요. 등록 정보는 공유 전역 상태이므로 조회 중에 바꾸면 안 됩니다. 라이브러리는 ID와 asset_get의 출력 포인터를 검사하지만 등록된 목록, 소재 주소, 카트리지 내용의 유효성은 검사하지 않습니다.

원본 전체가 의도한 ROM 매핑에서 읽히고 대상 전체가 쓰기 가능한 메모리 안에 있어야 합니다. 뱅크 창 경계에서 다음 뱅크로 넘어가거나, memmove처럼 겹치는 범위를 처리하거나, VRAM 쓰기 시점을 제어하지 않습니다. VRAM에는 그래픽 전송 API를 사용하세요.

예제의 호출 코드는 고정 뱅크 0에 두어 원본 뱅크를 바꿔도 실행 중인 코드가 사라지지 않도록 합니다. 전송은 동기식입니다. 전송 도중 인터럽트에서 다른 뱅크 전환 복사를 실행하지 마세요. 이 함수만으로 프로그램 전체의 인터럽트 안전성이 확보되지는 않습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

144바이트 소재에 한도 7을 지정해 처음 7바이트만 복사하고 다음 바이트의 0x55를 유지하면서도 성공을 반환하는지 확인합니다. 전체 복사, 한도 0, 빈 소재, MAP 소재의 원시 복사도 검사합니다.

예상 화면의 빨간 줄은 픽셀 좌표 (16,32)에서 시작하며 72×8픽셀입니다. 8×8 삼각형, 테두리 두께 1픽셀인 8×8 사각형, 왼쪽 네 열을 채운 타일을 세 번 반복합니다. 삼각형은 왼쪽 위의 1픽셀에서 맨 아래 줄의 8픽셀까지 넓어집니다.

FC에서 (16,64)의 파란 삼각형과 테두리는 __far_memcpy 결과이며, (16,96)의 초록색 쌍은 asset_load_raw 후 CHR로 전송한 결과입니다. 검은 바탕에서 각 쌍은 16×8픽셀입니다. 숫자 상태값뿐 아니라 복사된 이미지 바이트를 직접 확인할 수 있습니다.

예상 상태 표시는 FAILED CHECKS 000과 FIRST FAILURE 00입니다. 검증은 300프레임 동안 실행한 뒤 글자, 도형 마스크, 색을 예상값과 비교합니다. 에뮬레이터 검증이며 실제 하드웨어 시험은 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

RAW 또는 TILES 소재를 찾아 해당 ROM 뱅크로 전환한 뒤, __vram_write로 최대 128바이트씩 전체 데이터를 전송합니다. 끝나면 bank_get_current()로 저장한 뱅크로 돌아갑니다. 청크 사이에 다음 프레임을 기다리지 않습니다.

사용 형식

u8 asset_load_tiles(u8 asset_id, u16 vram_dst);

매개변수

asset_id

0부터 시작하는 소재 번호입니다. 등록된 목록의 항목 수가 count일 때 asset_id < count인 ID가 유효합니다.

vram_dst

CPU 주소나 타일 번호가 아닌 PPU 바이트 주소입니다. 타일 패턴은 $0000~$1FFF의 쓰기 가능한 CHR RAM에 전송하며 타일 하나는 16바이트입니다. 전체 전송이 의도한 PPU 영역 안에 들어가도록 하세요.

반환값

ID가 잘못되었거나 유형이 RAW/TILES가 아니면 0입니다. 허용된 전송을 마치면 1이며 길이 0인 소재도 포함합니다. 성공값이 타일 인코딩이나 VRAM 표시의 정확성을 보장하지는 않습니다.

사용 조건과 제한

조회 전에 목록을 등록하세요. 등록 정보는 공유 전역 상태이므로 조회 중에 바꾸면 안 됩니다. 라이브러리는 ID와 asset_get의 출력 포인터를 검사하지만 등록된 목록, 소재 주소, 카트리지 내용의 유효성은 검사하지 않습니다.

예제의 호출 코드는 고정 뱅크 0에 두어 원본 뱅크를 바꿔도 실행 중인 코드가 사라지지 않도록 합니다. 전송은 동기식입니다. 전송 도중 인터럽트에서 다른 뱅크 전환 복사를 실행하지 마세요. 이 함수만으로 프로그램 전체의 인터럽트 안전성이 확보되지는 않습니다.

전송은 바이트만 쓰며 맵에 타일을 배치하거나 색을 지정하거나 VRAM을 할당하지 않습니다. 타일 맵과 팔레트는 따로 설정하세요. 예제는 렌더링을 끈 상태로 전송하고 이미지가 준비된 뒤 화면을 켭니다.

asset_load_tiles는 매퍼에서 읽은 값이 아니라 bank.c가 기록한 뱅크로 돌아갑니다. bank_switch로 상태를 초기화하고 유지하세요. 매퍼에 직접 쓰거나 __bankswitch만 호출하면 라이브러리 상태는 갱신되지 않습니다. 뱅크 간 복사 내장 함수는 별도로 컴파일러의 뱅크 상태를 복원합니다.

패턴 데이터에는 쓰기 가능한 CHR RAM을 사용하고 긴 전송 동안은 렌더링을 끄세요. VBlank에서 전송한다면 전체 작업이 허용 시간 안에 끝나야 하며 128바이트 분할만으로 이를 보장하지 않습니다. 예제는 --mapper=mmc1 --board=surom512로 빌드합니다. 일반 보드에서 --nes-chr를 생략하면 CHR RAM이 아니라 빈 CHR ROM이 만들어집니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

타일 전송 예제는 직접 만든 8×8 패턴 9개, 총 144바이트를 사용합니다. MAP 유형과 잘못된 ID가 거부되는지도 확인합니다. FC에서는 128바이트 청크와 나머지 16바이트를 모두 검증합니다.

예상 화면의 빨간 줄은 픽셀 좌표 (16,32)에서 시작하며 72×8픽셀입니다. 8×8 삼각형, 테두리 두께 1픽셀인 8×8 사각형, 왼쪽 네 열을 채운 타일을 세 번 반복합니다. 삼각형은 왼쪽 위의 1픽셀에서 맨 아래 줄의 8픽셀까지 넓어집니다.

FC에서 (16,64)의 파란 삼각형과 테두리는 __far_memcpy 결과이며, (16,96)의 초록색 쌍은 asset_load_raw 후 CHR로 전송한 결과입니다. 검은 바탕에서 각 쌍은 16×8픽셀입니다. 숫자 상태값뿐 아니라 복사된 이미지 바이트를 직접 확인할 수 있습니다.

예상 상태 표시는 FAILED CHECKS 000과 FIRST FAILURE 00입니다. 검증은 300프레임 동안 실행한 뒤 글자, 도형 마스크, 색을 예상값과 비교합니다. 에뮬레이터 검증이며 실제 하드웨어 시험은 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

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

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

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

    bank_switch(old_bank);
    return 1;
}

사용할 소재 목록의 뱅크 번호, 주소, 항목 수를 등록합니다. 활성 목록은 하나뿐입니다. 이 함수는 세 값만 보관하며 목록 복사, 소재 읽기, 메모리 할당은 하지 않습니다.

사용 형식

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

매개변수

bank

소재 본체가 아닌 설명자 목록이 저장된 ROM 뱅크 번호입니다. 8비트 값입니다.

table

AssetDesc 항목 count개가 연속으로 놓인 영역의 근거리 포인터입니다. 등록된 동안 해당 목록 뱅크의 count * 6바이트를 읽을 수 있어야 합니다.

count

항목 수이며 범위는 0~255입니다. 0이면 모든 ID가 무효입니다. asset_set_table(0, 0, 0)으로 빈 목록을 안전하게 등록할 수 있습니다.

반환값

없음(void).

사용 조건과 제한

조회 전에 목록을 등록하세요. 등록 정보는 공유 전역 상태이므로 조회 중에 바꾸면 안 됩니다. 라이브러리는 ID와 asset_get의 출력 포인터를 검사하지만 등록된 목록, 소재 주소, 카트리지 내용의 유효성은 검사하지 않습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

이 예제는 뱅크 3의 설명자 4개를 등록하고, 비어 있지 않은 소재는 뱅크 2에서 가져옵니다. 빈 목록도 등록해 주소 0을 읽지 않고 조회가 실패하는지 확인합니다.

예상 화면의 빨간 줄은 픽셀 좌표 (16,32)에서 시작하며 72×8픽셀입니다. 8×8 삼각형, 테두리 두께 1픽셀인 8×8 사각형, 왼쪽 네 열을 채운 타일을 세 번 반복합니다. 삼각형은 왼쪽 위의 1픽셀에서 맨 아래 줄의 8픽셀까지 넓어집니다.

FC에서 (16,64)의 파란 삼각형과 테두리는 __far_memcpy 결과이며, (16,96)의 초록색 쌍은 asset_load_raw 후 CHR로 전송한 결과입니다. 검은 바탕에서 각 쌍은 16×8픽셀입니다. 숫자 상태값뿐 아니라 복사된 이미지 바이트를 직접 확인할 수 있습니다.

예상 상태 표시는 FAILED CHECKS 000과 FIRST FAILURE 00입니다. 검증은 300프레임 동안 실행한 뒤 글자, 도형 마스크, 색을 예상값과 비교합니다. 에뮬레이터 검증이며 실제 하드웨어 시험은 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

타일 사각형을 덮는 속성 바이트 행들을 큐에 복사합니다.

사용 형식

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

매개변수

nt_base

논리 네임테이블 시작 주소 $2000/$2400/$2800/$2C00입니다. 물리적으로 독립적인지는 미러링에 따라 결정됩니다.

tile_x

왼쪽 타일 열이며, 가시 범위는 0~31입니다.

tile_y

맨 위 타일 행이며, 가시 범위는 0~29입니다.

width

타일 단위 너비입니다.

height

타일 단위 높이입니다.

반환값

전부 큐에 들어갔거나 빈 사각형이면 1, 경계가 유효하지 않거나 용량이 부족하면 0을 반환합니다. 경계가 잘못되면 아무것도 큐에 넣지 않습니다.

사용 조건과 제한

공유 속성 복사본 64바이트는 CPU RAM $03E0~$041F를 사용하므로 이 범위를 예약하세요. 속성 1바이트는 4×4타일을 담당하며, 각 2비트 필드는 2×2타일 사분면의 팔레트를 선택합니다.

runtime.c를 링크하세요. 큐는 나중의 NMI나 렌더링이 꺼진 안전한 시점에 반영할 데이터를 복사합니다. 큐 생성과 소비가 겹치지 않게 하세요. 여러 행을 처리하다 용량이 부족해져도 이미 수락한 행은 큐에 남습니다.

속성 1바이트는 4×4타일을 담당합니다. 겹치는 바이트 전체를 전송하므로 이웃 사분면의 올바른 값을 복사본에 유지하세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

직사각형 속성 전송 예제입니다. (16,32)의 빨간 32×32, (80,32)의 파란 32×32, 오른쪽 아래 (240,224)의 초록 16×16 도형을 표시합니다. 인접 사분면을 보존하며 마지막 속성 바이트까지 올바르게 처리합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

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

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

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

이미 비트 단위로 구성된 속성 64바이트를 공유 복사본에 복사합니다.

사용 형식

void nes_attr_shadow_build_from_palette_map(unsigned char* src64);

매개변수

src64

읽기 가능한 64바이트 속성 테이블입니다. 타일마다 팔레트 ID 하나를 담은 배열이 아닙니다.

반환값

반환값은 없습니다.

사용 조건과 제한

공유 속성 복사본 64바이트는 CPU RAM $03E0~$041F를 사용하므로 이 범위를 예약하세요. 속성 1바이트는 4×4타일을 담당하며, 각 2비트 필드는 2×2타일 사분면의 팔레트를 선택합니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

직사각형 속성 전송 예제입니다. (16,32)의 빨간 32×32, (80,32)의 파란 32×32, 오른쪽 아래 (240,224)의 초록 16×16 도형을 표시합니다. 인접 사분면을 보존하며 마지막 속성 바이트까지 올바르게 처리합니다.

사용 예의 전체 프로그램

빌드 명령

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

KITAQFC phase15 attribute patch helpers.


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

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

사각형이 닿는 모든 2×2타일 사분면의 팔레트 필드를 바꿉니다.

사용 형식

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

매개변수

tile_x

왼쪽 타일 열이며, 가시 범위는 0~31입니다.

tile_y

맨 위 타일 행이며, 가시 범위는 0~29입니다.

width

타일 단위 너비입니다.

height

타일 단위 높이입니다.

pal_index

팔레트 인덱스입니다. 하위 2비트만 사용합니다.

반환값

반환값은 없습니다.

사용 조건과 제한

공유 속성 복사본 64바이트는 CPU RAM $03E0~$041F를 사용하므로 이 범위를 예약하세요. 속성 1바이트는 4×4타일을 담당하며, 각 2비트 필드는 2×2타일 사분면의 팔레트를 선택합니다.

사각형 전체를 32×30타일 안에 유지하세요. 비어 있거나 유효하지 않은 사각형은 아무것도 바꾸지 않습니다. 홀수 경계는 사분면 경계까지 확장되므로 사각형 밖의 이웃 타일에도 새 팔레트가 적용될 수 있습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

직사각형 속성 전송 예제입니다. (16,32)의 빨간 32×32, (80,32)의 파란 32×32, 오른쪽 아래 (240,224)의 초록 16×16 도형을 표시합니다. 인접 사분면을 보존하며 마지막 속성 바이트까지 올바르게 처리합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

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

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

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

지정한 마스크로 APU 다섯 채널 전체의 활성 상태를 바꿉니다.

사용 형식

void nes_apu_channel_enable(u8 mask);

매개변수

mask

전체 APU_STATUS 활성 마스크입니다. 비트 0..4는 pulse1, pulse2, triangle, noise, DMC를 선택하며 상위 비트는 버립니다.

반환값

반환값은 없습니다. 사운드 레지스터나 드라이버 상태를 변경합니다.

사용 예

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

예상 결과

pulse1, pulse2, triangle, noise, tick, move 순서로 납니다. NTSC에서 타이머 253은 약 440 Hz 펄스와 220 Hz 삼각파를 만듭니다. tick은 약 111 Hz, move는 약 174 Hz이며 더 빨리 끝납니다. 마지막 구간은 무음입니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

프레임 IRQ를 끄고 네 채널을 활성화한 뒤 조용한 제어값을 설정합니다. DMC는 비활성 상태입니다.

사용 형식

void nes_apu_init(void);

반환값

반환값은 없습니다. 사운드 레지스터나 드라이버 상태를 변경합니다.

사용 예

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

예상 결과

pulse1, pulse2, triangle, noise, tick, move 순서로 납니다. NTSC에서 타이머 253은 약 440 Hz 펄스와 220 Hz 삼각파를 만듭니다. tick은 약 111 Hz, move는 약 174 Hz이며 더 빨리 끝납니다. 마지막 구간은 무음입니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

모든 채널을 끄고 펄스·노이즈 음량과 DMC 출력을 지웁니다.

사용 형식

void nes_apu_silence_all(void);

반환값

반환값은 없습니다. 사운드 레지스터나 드라이버 상태를 변경합니다.

사용 예

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

예상 결과

pulse1, pulse2, triangle, noise, tick, move 순서로 납니다. NTSC에서 타이머 253은 약 440 Hz 펄스와 220 Hz 삼각파를 만듭니다. tick은 약 111 Hz, move는 약 174 Hz이며 더 빨리 끝납니다. 마지막 구간은 무음입니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

DMC 제어·출력을 설정하고 샘플 주소와 길이를 레지스터 단위로 변환합니다.

사용 형식

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

매개변수

flags_rate

DMC의 비트 7은 IRQ, 비트 6은 반복, 하위 니블은 재생률 인덱스입니다. 샘플은 IRQ를 활성화하지 않습니다.

output_level

초기 DMC 출력 카운터 0..127입니다. 하위 7비트만 씁니다.

sample_addr

DMC 데이터의 CPU 주소입니다. $C000..$FFC0 안의 64바이트 경계여야 합니다.

sample_len

바이트 길이는 16*n+1 형식의 1..4081입니다. 0이나 표현할 수 없는 길이를 전달하지 마세요.

반환값

반환값은 없습니다. 사운드 레지스터나 드라이버 상태를 변경합니다.

사용 조건과 제한

DMC는 $C000..$FFC0의 64바이트 경계에서 ROM을 읽습니다. 길이는 16*n+1바이트로 1..4081입니다. 이 함수들은 정렬·범위를 검사하거나 뱅크를 전환하지 않습니다. 샘플은 독자 데이터를 __aligned(64)로 고정 뱅크 0에 두고 실행 중 배치를 검사합니다.

사용 예

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

예상 결과

독자 델타 패턴을 속도 인덱스 10으로 재생하고 쉬었다가 더 빠른 12로 재생합니다. DMC 정지는 출력 카운터를 유지하므로 간격에 과도음이 남을 수 있습니다. 마지막 연산은 APU 전체를 무음으로 만듭니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

DMC 샘플을 설정하고 즉시 재생을 시작합니다.

사용 형식

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

매개변수

flags_rate

DMC의 비트 7은 IRQ, 비트 6은 반복, 하위 니블은 재생률 인덱스입니다. 샘플은 IRQ를 활성화하지 않습니다.

output_level

초기 DMC 출력 카운터 0..127입니다. 하위 7비트만 씁니다.

sample_addr

DMC 데이터의 CPU 주소입니다. $C000..$FFC0 안의 64바이트 경계여야 합니다.

sample_len

바이트 길이는 16*n+1 형식의 1..4081입니다. 0이나 표현할 수 없는 길이를 전달하지 마세요.

반환값

반환값은 없습니다. 사운드 레지스터나 드라이버 상태를 변경합니다.

사용 조건과 제한

DMC는 $C000..$FFC0의 64바이트 경계에서 ROM을 읽습니다. 길이는 16*n+1바이트로 1..4081입니다. 이 함수들은 정렬·범위를 검사하거나 뱅크를 전환하지 않습니다. 샘플은 독자 데이터를 __aligned(64)로 고정 뱅크 0에 두고 실행 중 배치를 검사합니다.

사용 예

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

예상 결과

독자 델타 패턴을 속도 인덱스 10으로 재생하고 쉬었다가 더 빠른 12로 재생합니다. DMC 정지는 출력 카운터를 유지하므로 간격에 과도음이 남을 수 있습니다. 마지막 연산은 APU 전체를 무음으로 만듭니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

APU_STATUS=0x1F를 써서 DMC와 나머지 네 채널을 모두 활성화합니다.

사용 형식

void nes_dmc_start(void);

반환값

반환값은 없습니다. 사운드 레지스터나 드라이버 상태를 변경합니다.

사용 조건과 제한

DMC는 $C000..$FFC0의 64바이트 경계에서 ROM을 읽습니다. 길이는 16*n+1바이트로 1..4081입니다. 이 함수들은 정렬·범위를 검사하거나 뱅크를 전환하지 않습니다. 샘플은 독자 데이터를 __aligned(64)로 고정 뱅크 0에 두고 실행 중 배치를 검사합니다.

사용 예

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

예상 결과

독자 델타 패턴을 속도 인덱스 10으로 재생하고 쉬었다가 더 빠른 12로 재생합니다. DMC 정지는 출력 카운터를 유지하므로 간격에 과도음이 남을 수 있습니다. 마지막 연산은 APU 전체를 무음으로 만듭니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

APU_STATUS=0x0F를 써서 DMC를 멈추고 나머지 네 채널 활성 비트를 모두 설정합니다.

사용 형식

void nes_dmc_stop(void);

반환값

반환값은 없습니다. 사운드 레지스터나 드라이버 상태를 변경합니다.

사용 조건과 제한

DMC는 $C000..$FFC0의 64바이트 경계에서 ROM을 읽습니다. 길이는 16*n+1바이트로 1..4081입니다. 이 함수들은 정렬·범위를 검사하거나 뱅크를 전환하지 않습니다. 샘플은 독자 데이터를 __aligned(64)로 고정 뱅크 0에 두고 실행 중 배치를 검사합니다.

사용 예

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

예상 결과

독자 델타 패턴을 속도 인덱스 10으로 재생하고 쉬었다가 더 빠른 12로 재생합니다. DMC 정지는 출력 카운터를 유지하므로 간격에 과도음이 남을 수 있습니다. 마지막 연산은 APU 전체를 무음으로 만듭니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

제어값 0x5A, 타이머 0x0280, 길이 인덱스 2로 펄스 1을 트리거해 더 높고 짧은 이동음을 냅니다.

사용 형식

void nes_sfx_move_blip(void);

반환값

반환값은 없습니다. 사운드 레지스터나 드라이버 상태를 변경합니다.

사용 조건과 제한

이 보조 함수는 단일 채널 APU_STATUS 마스크를 써서 다른 소리를 끕니다. 다중 음원 믹서가 아닙니다. 펄스·삼각파의 period는 타이머값이며 작을수록 음높이가 높습니다. 샘플 음높이와 길이는 NTSC 타이밍으로 확인했습니다.

사용 예

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

예상 결과

pulse1, pulse2, triangle, noise, tick, move 순서로 납니다. NTSC에서 타이머 253은 약 440 Hz 펄스와 220 Hz 삼각파를 만듭니다. tick은 약 111 Hz, move는 약 174 Hz이며 더 빨리 끝납니다. 마지막 구간은 무음입니다.

사용 예의 전체 프로그램

빌드 명령

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

Trigger the predefined pulse-1 movement effect.

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

노이즈만 활성화하고 엔벌로프, 주기/모드, 길이 인덱스를 씁니다.

사용 형식

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

매개변수

volume

원시 노이즈 제어값: 비트 5는 길이 카운터 정지, 비트 4는 고정 음량, 하위 니블은 음량 또는 엔벌로프 주기입니다.

period_mode

노이즈 레지스터: 비트 7은 짧은 모드, 하위 니블은 주기 테이블 인덱스입니다.

length_index

길이 테이블 인덱스 0..31이며 프레임 수가 아닙니다. 하위 5비트만 레지스터에 전달됩니다.

반환값

반환값은 없습니다. 사운드 레지스터나 드라이버 상태를 변경합니다.

사용 조건과 제한

이 보조 함수는 단일 채널 APU_STATUS 마스크를 써서 다른 소리를 끕니다. 다중 음원 믹서가 아닙니다. 펄스·삼각파의 period는 타이머값이며 작을수록 음높이가 높습니다. 샘플 음높이와 길이는 NTSC 타이밍으로 확인했습니다.

사용 예

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

예상 결과

pulse1, pulse2, triangle, noise, tick, move 순서로 납니다. NTSC에서 타이머 253은 약 440 Hz 펄스와 220 Hz 삼각파를 만듭니다. tick은 약 111 Hz, move는 약 174 Hz이며 더 빨리 끝납니다. 마지막 구간은 무음입니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

펄스 1만 활성화하고 스윕을 끈 뒤 제어값, 타이머, 길이 인덱스를 씁니다.

사용 형식

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

매개변수

duty_volume

원시 펄스 제어값입니다. 비트 7..6은 듀티, 비트 5는 길이 카운터 정지, 비트 4는 고정 음량, 하위 니블은 음량 또는 엔벌로프 주기입니다.

period

11비트 타이머 0..2047입니다. 펄스 주파수는 CPU 클록/[16*(period+1)], 삼각파는 CPU 클록/[32*(period+1)]입니다.

length_index

길이 테이블 인덱스 0..31이며 프레임 수가 아닙니다. 하위 5비트만 레지스터에 전달됩니다.

반환값

반환값은 없습니다. 사운드 레지스터나 드라이버 상태를 변경합니다.

사용 조건과 제한

이 보조 함수는 단일 채널 APU_STATUS 마스크를 써서 다른 소리를 끕니다. 다중 음원 믹서가 아닙니다. 펄스·삼각파의 period는 타이머값이며 작을수록 음높이가 높습니다. 샘플 음높이와 길이는 NTSC 타이밍으로 확인했습니다.

사용 예

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

예상 결과

pulse1, pulse2, triangle, noise, tick, move 순서로 납니다. NTSC에서 타이머 253은 약 440 Hz 펄스와 220 Hz 삼각파를 만듭니다. tick은 약 111 Hz, move는 약 174 Hz이며 더 빨리 끝납니다. 마지막 구간은 무음입니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

펄스 2만 활성화하고 스윕을 끈 뒤 제어값, 타이머, 길이 인덱스를 씁니다.

사용 형식

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

매개변수

duty_volume

원시 펄스 제어값입니다. 비트 7..6은 듀티, 비트 5는 길이 카운터 정지, 비트 4는 고정 음량, 하위 니블은 음량 또는 엔벌로프 주기입니다.

period

11비트 타이머 0..2047입니다. 펄스 주파수는 CPU 클록/[16*(period+1)], 삼각파는 CPU 클록/[32*(period+1)]입니다.

length_index

길이 테이블 인덱스 0..31이며 프레임 수가 아닙니다. 하위 5비트만 레지스터에 전달됩니다.

반환값

반환값은 없습니다. 사운드 레지스터나 드라이버 상태를 변경합니다.

사용 조건과 제한

이 보조 함수는 단일 채널 APU_STATUS 마스크를 써서 다른 소리를 끕니다. 다중 음원 믹서가 아닙니다. 펄스·삼각파의 period는 타이머값이며 작을수록 음높이가 높습니다. 샘플 음높이와 길이는 NTSC 타이밍으로 확인했습니다.

사용 예

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

예상 결과

pulse1, pulse2, triangle, noise, tick, move 순서로 납니다. NTSC에서 타이머 253은 약 440 Hz 펄스와 220 Hz 삼각파를 만듭니다. tick은 약 111 Hz, move는 약 174 Hz이며 더 빨리 끝납니다. 마지막 구간은 무음입니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

제어값 0x9A, 타이머 0x03F0, 길이 인덱스 4로 펄스 1을 트리거해 짧고 낮은 틱 소리를 냅니다.

사용 형식

void nes_sfx_tick_blip(void);

반환값

반환값은 없습니다. 사운드 레지스터나 드라이버 상태를 변경합니다.

사용 조건과 제한

이 보조 함수는 단일 채널 APU_STATUS 마스크를 써서 다른 소리를 끕니다. 다중 음원 믹서가 아닙니다. 펄스·삼각파의 period는 타이머값이며 작을수록 음높이가 높습니다. 샘플 음높이와 길이는 NTSC 타이밍으로 확인했습니다.

사용 예

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

예상 결과

pulse1, pulse2, triangle, noise, tick, move 순서로 납니다. NTSC에서 타이머 253은 약 440 Hz 펄스와 220 Hz 삼각파를 만듭니다. tick은 약 111 Hz, move는 약 174 Hz이며 더 빨리 끝납니다. 마지막 구간은 무음입니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

삼각파만 활성화하고 선형 카운터, 타이머, 길이 인덱스를 씁니다.

사용 형식

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

매개변수

linear

삼각파 선형 카운터: 비트 7은 제어/길이 정지, 하위 7비트는 재로드값입니다.

period

11비트 타이머 0..2047입니다. 펄스 주파수는 CPU 클록/[16*(period+1)], 삼각파는 CPU 클록/[32*(period+1)]입니다.

length_index

길이 테이블 인덱스 0..31이며 프레임 수가 아닙니다. 하위 5비트만 레지스터에 전달됩니다.

반환값

반환값은 없습니다. 사운드 레지스터나 드라이버 상태를 변경합니다.

사용 조건과 제한

이 보조 함수는 단일 채널 APU_STATUS 마스크를 써서 다른 소리를 끕니다. 다중 음원 믹서가 아닙니다. 펄스·삼각파의 period는 타이머값이며 작을수록 음높이가 높습니다. 샘플 음높이와 길이는 NTSC 타이밍으로 확인했습니다.

사용 예

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

예상 결과

pulse1, pulse2, triangle, noise, tick, move 순서로 납니다. NTSC에서 타이머 253은 약 440 Hz 펄스와 220 Hz 삼각파를 만듭니다. tick은 약 111 Hz, move는 약 174 Hz이며 더 빨리 끝납니다. 마지막 구간은 무음입니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

bank_switch가 마지막으로 기록한 뱅크 번호를 반환합니다. 카트리지 레지스터가 아니라 소프트웨어의 기록을 읽습니다.

사용 형식

u8 bank_get_current(void);

반환값

bank_switch가 마지막으로 저장한 u8 값입니다. 초기화 전에는 0입니다.

사용 조건과 제한

라이브러리 기록은 0으로 시작하며 카트리지의 시작 매핑을 알아내지 않습니다. bank_switch로 초기화하세요. 내장 함수나 매퍼에 대한 직접 쓰기는 이 별도 기록을 갱신하지 않으므로 bank_get_current로 실제 하드웨어 매핑을 검증할 수는 없습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

처음 bank_switch(2)는 뱅크 2를 기록하고 선택합니다. 이후 직접 전환으로 뱅크 1을 선택해 home1에서 A1을 읽어도 bank_get_current는 여전히 2입니다. 복귀하면 home2에서 다시 B2를 읽습니다.

완성 프로그램은 뱅크 번호와 근거리 주소로 데이터를 지정하는 방법, 뱅크를 넘는 콜백, 라이브러리 기록과 실제 매핑의 구별을 보여 줍니다. 모든 표시 숫자는 16진수입니다. BANK IN과 BANK OUT은 02, BYTE HEX는 D3, WORD HEX는 5C7A, FAILED CHECKS와 FIRST FAILURE는 모두 00이어야 합니다. CGB와 FC는 파란 글자, DMG는 검은 글자를 표시합니다.

CALL COUNT는 02입니다. far_call 매크로와 __farcall이 각각 콜백을 한 번 호출합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

u8 bank_get_current(void)
{
    return kq_bank_current;
}

요청한 뱅크 번호를 라이브러리에 기록한 뒤, 컴파일러의 매퍼별 PRG 뱅크 전환 처리로 선택합니다.

사용 형식

void bank_switch(u8 bank);

매개변수

bank

부호 없는 8비트 ROM 뱅크 번호입니다. 호출 시에는 함수 배치와 일치해야 하고, 읽기 시에는 원본 매핑을 지정합니다. 대상 카트리지에서 유효한 범위를 사용하세요.

반환값

없음(void).

사용 조건과 제한

지속되는 뱅크 변경으로 실행 중인 코드나 반환 주소가 사라져서는 안 됩니다. 예제처럼 호출 위치, 사용하는 bank_switch 본체, 이후 실행할 코드를 공통·고정 뱅크 0에 두세요.

라이브러리 기록은 0으로 시작하며 카트리지의 시작 매핑을 알아내지 않습니다. bank_switch로 초기화하세요. 내장 함수나 매퍼에 대한 직접 쓰기는 이 별도 기록을 갱신하지 않으므로 bank_get_current로 실제 하드웨어 매핑을 검증할 수는 없습니다.

FC 전환 번호는 컴파일러의 논리 뱅크 번호입니다. 0은 공통 ROM이며 전환 대상이 아닙니다. 보조 코드는 0을 뱅크 1로 처리합니다. SUROM512에서는 1~30만 유효합니다. 전환 내장 함수에 범위를 벗어난 상수를 직접 전달하면 빌드 오류가 나며, 잘못된 실행 시점 값은 1로 대체되고 매퍼 오류 상태가 설정됩니다. 공통 ROM은 뱅크 0 전환을 요청하지 말고 직접 읽으세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

처음 bank_switch(2)는 뱅크 2를 기록하고 선택합니다. 이후 직접 전환으로 뱅크 1을 선택해 home1에서 A1을 읽어도 bank_get_current는 여전히 2입니다. 복귀하면 home2에서 다시 B2를 읽습니다.

완성 프로그램은 뱅크 번호와 근거리 주소로 데이터를 지정하는 방법, 뱅크를 넘는 콜백, 라이브러리 기록과 실제 매핑의 구별을 보여 줍니다. 모든 표시 숫자는 16진수입니다. BANK IN과 BANK OUT은 02, BYTE HEX는 D3, WORD HEX는 5C7A, FAILED CHECKS와 FIRST FAILURE는 모두 00이어야 합니다. CGB와 FC는 파란 글자, DMG는 검은 글자를 표시합니다.

CALL COUNT는 02입니다. far_call 매크로와 __farcall이 각각 콜백을 한 번 호출합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

__farcall((bank), func)로 확장되는 매크로입니다. 컴파일러가 함수 이름으로 처리할 수 있도록 대상을 전달하며, 콜백 포인터를 통한 간접 호출은 아닙니다.

사용 형식

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

매개변수

bank

부호 없는 8비트 ROM 뱅크 번호입니다. 호출 시에는 함수 배치와 일치해야 하고, 읽기 시에는 원본 매핑을 지정합니다. 대상 카트리지에서 유효한 범위를 사용하세요.

func

선언된 매개변수 없는 함수의 이름입니다. 이 이름 기반 호출 내장 함수에는 함수 주소를 담은 변수를 전달할 수 없습니다. bank 인수는 콜백 매개변수로 전달되지 않습니다.

반환값

반환형은 호출한 함수에 따릅니다. void 콜백은 값을 반환하지 않고 u8·u16 콜백은 해당 값을 반환합니다. 화면 예제는 void 콜백을 사용합니다.

사용 조건과 제한

이 호출은 사용자 인수를 전달하거나 콜백의 인터럽트 재진입성을 보장하지 않습니다. 콜백 자체의 데이터, 스택, 인터럽트 사용을 올바르게 관리하세요. 뱅크 복귀는 중첩 및 반복 호출로 검사했지만 실제 하드웨어와 임의의 인터럽트 타이밍은 이 예제의 검증 범위가 아닙니다.

FC 전환 번호는 컴파일러의 논리 뱅크 번호입니다. 0은 공통 ROM이며 전환 대상이 아닙니다. 보조 코드는 0을 뱅크 1로 처리합니다. SUROM512에서는 1~30만 유효합니다. 전환 내장 함수에 범위를 벗어난 상수를 직접 전달하면 빌드 오류가 나며, 잘못된 실행 시점 값은 1로 대체되고 매퍼 오류 상태가 설정됩니다. 공통 ROM은 뱅크 0 전환을 요청하지 말고 직접 읽으세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

완성 프로그램의 이 지점에서 far_call는 callback_count를 1으로 만듭니다. 콜백은 뱅크 3에서 D3을 읽습니다. 이후 home2를 근거리로 읽어 B2인지 검사함으로써 뱅크 2가 매핑된 상태로 복귀했는지 확인합니다.

완성 프로그램은 뱅크 번호와 근거리 주소로 데이터를 지정하는 방법, 뱅크를 넘는 콜백, 라이브러리 기록과 실제 매핑의 구별을 보여 줍니다. 모든 표시 숫자는 16진수입니다. BANK IN과 BANK OUT은 02, BYTE HEX는 D3, WORD HEX는 5C7A, FAILED CHECKS와 FIRST FAILURE는 모두 00이어야 합니다. CGB와 FC는 파란 글자, DMG는 검은 글자를 표시합니다.

CALL COUNT는 02입니다. far_call 매크로와 __farcall이 각각 콜백을 한 번 호출합니다.

사용 예의 전체 프로그램

빌드 명령

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

원거리 메모리 복사 내장 함수를 사용해 지정한 ROM 뱅크에서 호출자가 제공한 RAM으로 len바이트를 복사합니다. 반환 전에 이전 뱅크를 복원합니다.

사용 형식

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

매개변수

bank

부호 없는 8비트 ROM 뱅크 번호입니다. 호출 시에는 함수 배치와 일치해야 하고, 읽기 시에는 원본 매핑을 지정합니다. 대상 카트리지에서 유효한 범위를 사용하세요.

addr

선택한 ROM 뱅크에서 읽을 수 있는 바이트열을 가리키는 근거리 포인터입니다. 포인터 자체에는 뱅크 번호가 없습니다.

dst

쓰기 대상 메모리입니다. 실제 복사량을 모두 담을 공간을 확보하세요. 0바이트 전송을 제외하면 널 포인터나 잘못된 대상 주소를 검사하지 않습니다.

len

바이트 수이며 범위는 0~65535입니다. 0이면 메모리를 복사하지 않지만 뱅크 선택과 복구 과정은 실행합니다.

반환값

없음(void).

사용 조건과 제한

원본 전체가 의도한 ROM 매핑에서 읽히고 대상 전체가 쓰기 가능한 메모리 안에 있어야 합니다. 뱅크 창 경계에서 다음 뱅크로 넘어가거나, memmove처럼 겹치는 범위를 처리하거나, VRAM 쓰기 시점을 제어하지 않습니다. VRAM에는 그래픽 전송 API를 사용하세요.

원거리 읽기와 복사는 동기식이며 컴파일러의 공유 작업 공간을 사용합니다. 처리 중 인터럽트에서 다른 뱅크 전송을 실행해 같은 공간을 덮어쓰지 마세요. GB 복사 보조 코드는 복귀 뱅크에도 공유 HRAM 슬롯 하나를 씁니다. 예제는 경쟁하는 전송 인터럽트 없이 고정 코드에서 실행합니다.

FC 전환 번호는 컴파일러의 논리 뱅크 번호입니다. 0은 공통 ROM이며 전환 대상이 아닙니다. 보조 코드는 0을 뱅크 1로 처리합니다. SUROM512에서는 1~30만 유효합니다. 전환 내장 함수에 범위를 벗어난 상수를 직접 전달하면 빌드 오류가 나며, 잘못된 실행 시점 값은 1로 대체되고 매퍼 오류 상태가 설정됩니다. 공통 ROM은 뱅크 0 전환을 요청하지 말고 직접 읽으세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

이 코드 조각은 far_data_read로 4바이트를 복사하고 버퍼를 D3 7A 5C 96와 비교합니다. 호출자의 원본 설명자나 포인터는 유지됩니다. 완성 프로그램은 길이 0 복사와 뱅크 복원도 별도로 확인합니다.

완성 프로그램은 뱅크 번호와 근거리 주소로 데이터를 지정하는 방법, 뱅크를 넘는 콜백, 라이브러리 기록과 실제 매핑의 구별을 보여 줍니다. 모든 표시 숫자는 16진수입니다. BANK IN과 BANK OUT은 02, BYTE HEX는 D3, WORD HEX는 5C7A, FAILED CHECKS와 FIRST FAILURE는 모두 00이어야 합니다. CGB와 FC는 파란 글자, DMG는 검은 글자를 표시합니다.

CALL COUNT는 02입니다. far_call 매크로와 __farcall이 각각 콜백을 한 번 호출합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

__farpeek16으로 연속된 두 바이트를 읽어 리틀 엔디언 워드로 반환합니다. 첫 번째 바이트가 하위 8비트입니다.

사용 형식

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

매개변수

bank

부호 없는 8비트 ROM 뱅크 번호입니다. 호출 시에는 함수 배치와 일치해야 하고, 읽기 시에는 원본 매핑을 지정합니다. 대상 카트리지에서 유효한 범위를 사용하세요.

addr

선택한 ROM 뱅크에서 읽을 수 있는 바이트열을 가리키는 근거리 포인터입니다. 포인터 자체에는 뱅크 번호가 없습니다.

반환값

읽은 리틀 엔디언 워드를 u16(0~65535)으로 반환합니다.

사용 조건과 제한

선택한 CPU 매핑에서 바이트 또는 워드 전체를 읽을 수 있어야 합니다. 포인터 검사, 주소 잘라내기, 창 경계에서 다음 ROM 뱅크로의 자동 전환은 수행하지 않습니다. 워드 읽기에는 연속된 유효한 두 바이트가 필요합니다.

원거리 읽기와 복사는 동기식이며 컴파일러의 공유 작업 공간을 사용합니다. 처리 중 인터럽트에서 다른 뱅크 전송을 실행해 같은 공간을 덮어쓰지 마세요. GB 복사 보조 코드는 복귀 뱅크에도 공유 HRAM 슬롯 하나를 씁니다. 예제는 경쟁하는 전송 인터럽트 없이 고정 코드에서 실행합니다.

FC 전환 번호는 컴파일러의 논리 뱅크 번호입니다. 0은 공통 ROM이며 전환 대상이 아닙니다. 보조 코드는 0을 뱅크 1로 처리합니다. SUROM512에서는 1~30만 유효합니다. 전환 내장 함수에 범위를 벗어난 상수를 직접 전달하면 빌드 오류가 나며, 잘못된 실행 시점 값은 1로 대체되고 매퍼 오류 상태가 설정됩니다. 공통 ROM은 뱅크 0 전환을 요청하지 말고 직접 읽으세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

이 코드 조각은 far_data_read16로 뱅크 3의 payload+1를 읽고 5C7A를 확인합니다. 완성 프로그램은 home2의 근거리 읽기로 뱅크 2 매핑이 복원되었는지도 확인합니다.

완성 프로그램은 뱅크 번호와 근거리 주소로 데이터를 지정하는 방법, 뱅크를 넘는 콜백, 라이브러리 기록과 실제 매핑의 구별을 보여 줍니다. 모든 표시 숫자는 16진수입니다. BANK IN과 BANK OUT은 02, BYTE HEX는 D3, WORD HEX는 5C7A, FAILED CHECKS와 FIRST FAILURE는 모두 00이어야 합니다. CGB와 FC는 파란 글자, DMG는 검은 글자를 표시합니다.

CALL COUNT는 02입니다. far_call 매크로와 __farcall이 각각 콜백을 한 번 호출합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

지정한 ROM 뱅크와 주소에서 __farpeek8로 한 바이트를 읽고, 이전 뱅크를 복원한 뒤 값을 반환합니다.

사용 형식

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

매개변수

bank

부호 없는 8비트 ROM 뱅크 번호입니다. 호출 시에는 함수 배치와 일치해야 하고, 읽기 시에는 원본 매핑을 지정합니다. 대상 카트리지에서 유효한 범위를 사용하세요.

addr

선택한 ROM 뱅크에서 읽을 수 있는 바이트열을 가리키는 근거리 포인터입니다. 포인터 자체에는 뱅크 번호가 없습니다.

반환값

읽은 바이트를 u8(0~255)로 반환합니다.

사용 조건과 제한

선택한 CPU 매핑에서 바이트 또는 워드 전체를 읽을 수 있어야 합니다. 포인터 검사, 주소 잘라내기, 창 경계에서 다음 ROM 뱅크로의 자동 전환은 수행하지 않습니다. 워드 읽기에는 연속된 유효한 두 바이트가 필요합니다.

원거리 읽기와 복사는 동기식이며 컴파일러의 공유 작업 공간을 사용합니다. 처리 중 인터럽트에서 다른 뱅크 전송을 실행해 같은 공간을 덮어쓰지 마세요. GB 복사 보조 코드는 복귀 뱅크에도 공유 HRAM 슬롯 하나를 씁니다. 예제는 경쟁하는 전송 인터럽트 없이 고정 코드에서 실행합니다.

FC 전환 번호는 컴파일러의 논리 뱅크 번호입니다. 0은 공통 ROM이며 전환 대상이 아닙니다. 보조 코드는 0을 뱅크 1로 처리합니다. SUROM512에서는 1~30만 유효합니다. 전환 내장 함수에 범위를 벗어난 상수를 직접 전달하면 빌드 오류가 나며, 잘못된 실행 시점 값은 1로 대체되고 매퍼 오류 상태가 설정됩니다. 공통 ROM은 뱅크 0 전환을 요청하지 말고 직접 읽으세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

이 코드 조각은 far_data_read8로 뱅크 3의 payload를 읽고 D3를 확인합니다. 완성 프로그램은 home2의 근거리 읽기로 뱅크 2 매핑이 복원되었는지도 확인합니다.

완성 프로그램은 뱅크 번호와 근거리 주소로 데이터를 지정하는 방법, 뱅크를 넘는 콜백, 라이브러리 기록과 실제 매핑의 구별을 보여 줍니다. 모든 표시 숫자는 16진수입니다. BANK IN과 BANK OUT은 02, BYTE HEX는 D3, WORD HEX는 5C7A, FAILED CHECKS와 FIRST FAILURE는 모두 00이어야 합니다. CGB와 FC는 파란 글자, DMG는 검은 글자를 표시합니다.

CALL COUNT는 02입니다. far_call 매크로와 __farcall이 각각 콜백을 한 번 호출합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

뱅크 번호 한 바이트와 CPU 주소 공간의 포인터를 호출자의 BankPtr에 저장합니다. 설명자를 만들 뿐, 뱅크를 전환하거나 가리키는 데이터를 읽지 않습니다.

사용 형식

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

매개변수

out

3바이트 BankPtr 하나를 저장할 수 있는 쓰기 가능한 영역의 포인터입니다. out이 널이면 아무것도 쓰지 않습니다.

bank

부호 없는 8비트 ROM 뱅크 번호입니다. 호출 시에는 함수 배치와 일치해야 하고, 읽기 시에는 원본 매핑을 지정합니다. 대상 카트리지에서 유효한 범위를 사용하세요.

ptr

설명자에 저장할 CPU 주소 공간의 16비트 주소입니다. 그대로 저장하며 선택한 뱅크에서 유효한 주소인지 검사하지 않습니다.

반환값

없음(void).

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

설명자를 뱅크 3과 payload+1로 설정합니다. 읽기 함수들은 7A, 5C7A, 세 바이트 7A 5C 96을 얻습니다. 출력 포인터가 널인 호출은 상태를 바꾸지 않아야 합니다.

완성 프로그램은 뱅크 번호와 근거리 주소로 데이터를 지정하는 방법, 뱅크를 넘는 콜백, 라이브러리 기록과 실제 매핑의 구별을 보여 줍니다. 모든 표시 숫자는 16진수입니다. BANK IN과 BANK OUT은 02, BYTE HEX는 D3, WORD HEX는 5C7A, FAILED CHECKS와 FIRST FAILURE는 모두 00이어야 합니다. CGB와 FC는 파란 글자, DMG는 검은 글자를 표시합니다.

CALL COUNT는 02입니다. far_call 매크로와 __farcall이 각각 콜백을 한 번 호출합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

BankPtr이 가리키는 곳에서 쓰기 가능한 RAM으로 len바이트를 복사합니다. 설명자는 값으로 전달되므로 호출자의 포인터는 계속 원본 시작점을 가리킵니다.

사용 형식

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

매개변수

ptr

bank와 ptr을 담은 BankPtr 값입니다. 주소가 아니라 설명자 자체를 전달합니다. 호출자의 설명자는 변경되지 않습니다.

dst

쓰기 대상 메모리입니다. 실제 복사량을 모두 담을 공간을 확보하세요. 0바이트 전송을 제외하면 널 포인터나 잘못된 대상 주소를 검사하지 않습니다.

len

바이트 수이며 범위는 0~65535입니다. 0이면 메모리를 복사하지 않지만 뱅크 선택과 복구 과정은 실행합니다.

반환값

없음(void).

사용 조건과 제한

원본 전체가 의도한 ROM 매핑에서 읽히고 대상 전체가 쓰기 가능한 메모리 안에 있어야 합니다. 뱅크 창 경계에서 다음 뱅크로 넘어가거나, memmove처럼 겹치는 범위를 처리하거나, VRAM 쓰기 시점을 제어하지 않습니다. VRAM에는 그래픽 전송 API를 사용하세요.

원거리 읽기와 복사는 동기식이며 컴파일러의 공유 작업 공간을 사용합니다. 처리 중 인터럽트에서 다른 뱅크 전송을 실행해 같은 공간을 덮어쓰지 마세요. GB 복사 보조 코드는 복귀 뱅크에도 공유 HRAM 슬롯 하나를 씁니다. 예제는 경쟁하는 전송 인터럽트 없이 고정 코드에서 실행합니다.

FC 전환 번호는 컴파일러의 논리 뱅크 번호입니다. 0은 공통 ROM이며 전환 대상이 아닙니다. 보조 코드는 0을 뱅크 1로 처리합니다. SUROM512에서는 1~30만 유효합니다. 전환 내장 함수에 범위를 벗어난 상수를 직접 전달하면 빌드 오류가 나며, 잘못된 실행 시점 값은 1로 대체되고 매퍼 오류 상태가 설정됩니다. 공통 ROM은 뱅크 0 전환을 요청하지 말고 직접 읽으세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

이 코드 조각은 farptr_read로 3바이트를 복사하고 버퍼를 7A 5C 96와 비교합니다. 호출자의 원본 설명자나 포인터는 유지됩니다. 완성 프로그램은 길이 0 복사와 뱅크 복원도 별도로 확인합니다.

완성 프로그램은 뱅크 번호와 근거리 주소로 데이터를 지정하는 방법, 뱅크를 넘는 콜백, 라이브러리 기록과 실제 매핑의 구별을 보여 줍니다. 모든 표시 숫자는 16진수입니다. BANK IN과 BANK OUT은 02, BYTE HEX는 D3, WORD HEX는 5C7A, FAILED CHECKS와 FIRST FAILURE는 모두 00이어야 합니다. CGB와 FC는 파란 글자, DMG는 검은 글자를 표시합니다.

CALL COUNT는 02입니다. far_call 매크로와 __farcall이 각각 콜백을 한 번 호출합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

BankPtr에 저장된 뱅크와 주소에서 리틀 엔디언 워드를 읽습니다. 설명자는 값으로 전달되며 포인터는 증가하지 않습니다.

사용 형식

u16 farptr_read16(BankPtr ptr);

매개변수

ptr

bank와 ptr을 담은 BankPtr 값입니다. 주소가 아니라 설명자 자체를 전달합니다. 호출자의 설명자는 변경되지 않습니다.

반환값

읽은 리틀 엔디언 워드를 u16(0~65535)으로 반환합니다.

사용 조건과 제한

선택한 CPU 매핑에서 바이트 또는 워드 전체를 읽을 수 있어야 합니다. 포인터 검사, 주소 잘라내기, 창 경계에서 다음 ROM 뱅크로의 자동 전환은 수행하지 않습니다. 워드 읽기에는 연속된 유효한 두 바이트가 필요합니다.

원거리 읽기와 복사는 동기식이며 컴파일러의 공유 작업 공간을 사용합니다. 처리 중 인터럽트에서 다른 뱅크 전송을 실행해 같은 공간을 덮어쓰지 마세요. GB 복사 보조 코드는 복귀 뱅크에도 공유 HRAM 슬롯 하나를 씁니다. 예제는 경쟁하는 전송 인터럽트 없이 고정 코드에서 실행합니다.

FC 전환 번호는 컴파일러의 논리 뱅크 번호입니다. 0은 공통 ROM이며 전환 대상이 아닙니다. 보조 코드는 0을 뱅크 1로 처리합니다. SUROM512에서는 1~30만 유효합니다. 전환 내장 함수에 범위를 벗어난 상수를 직접 전달하면 빌드 오류가 나며, 잘못된 실행 시점 값은 1로 대체되고 매퍼 오류 상태가 설정됩니다. 공통 ROM은 뱅크 0 전환을 요청하지 말고 직접 읽으세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

이 코드 조각은 farptr_read16로 뱅크 3의 pointer.ptr를 읽고 5C7A를 확인합니다. 완성 프로그램은 home2의 근거리 읽기로 뱅크 2 매핑이 복원되었는지도 확인합니다.

완성 프로그램은 뱅크 번호와 근거리 주소로 데이터를 지정하는 방법, 뱅크를 넘는 콜백, 라이브러리 기록과 실제 매핑의 구별을 보여 줍니다. 모든 표시 숫자는 16진수입니다. BANK IN과 BANK OUT은 02, BYTE HEX는 D3, WORD HEX는 5C7A, FAILED CHECKS와 FIRST FAILURE는 모두 00이어야 합니다. CGB와 FC는 파란 글자, DMG는 검은 글자를 표시합니다.

CALL COUNT는 02입니다. far_call 매크로와 __farcall이 각각 콜백을 한 번 호출합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

값으로 전달된 BankPtr의 두 필드를 사용해 한 바이트를 읽습니다. 일반 근거리 포인터에 없는 뱅크 번호를 설명자에서 가져옵니다.

사용 형식

u8 farptr_read8(BankPtr ptr);

매개변수

ptr

bank와 ptr을 담은 BankPtr 값입니다. 주소가 아니라 설명자 자체를 전달합니다. 호출자의 설명자는 변경되지 않습니다.

반환값

읽은 바이트를 u8(0~255)로 반환합니다.

사용 조건과 제한

선택한 CPU 매핑에서 바이트 또는 워드 전체를 읽을 수 있어야 합니다. 포인터 검사, 주소 잘라내기, 창 경계에서 다음 ROM 뱅크로의 자동 전환은 수행하지 않습니다. 워드 읽기에는 연속된 유효한 두 바이트가 필요합니다.

원거리 읽기와 복사는 동기식이며 컴파일러의 공유 작업 공간을 사용합니다. 처리 중 인터럽트에서 다른 뱅크 전송을 실행해 같은 공간을 덮어쓰지 마세요. GB 복사 보조 코드는 복귀 뱅크에도 공유 HRAM 슬롯 하나를 씁니다. 예제는 경쟁하는 전송 인터럽트 없이 고정 코드에서 실행합니다.

FC 전환 번호는 컴파일러의 논리 뱅크 번호입니다. 0은 공통 ROM이며 전환 대상이 아닙니다. 보조 코드는 0을 뱅크 1로 처리합니다. SUROM512에서는 1~30만 유효합니다. 전환 내장 함수에 범위를 벗어난 상수를 직접 전달하면 빌드 오류가 나며, 잘못된 실행 시점 값은 1로 대체되고 매퍼 오류 상태가 설정됩니다. 공통 ROM은 뱅크 0 전환을 요청하지 말고 직접 읽으세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

이 코드 조각은 farptr_read8로 뱅크 3의 pointer.ptr를 읽고 7A를 확인합니다. 완성 프로그램은 home2의 근거리 읽기로 뱅크 2 매핑이 복원되었는지도 확인합니다.

완성 프로그램은 뱅크 번호와 근거리 주소로 데이터를 지정하는 방법, 뱅크를 넘는 콜백, 라이브러리 기록과 실제 매핑의 구별을 보여 줍니다. 모든 표시 숫자는 16진수입니다. BANK IN과 BANK OUT은 02, BYTE HEX는 D3, WORD HEX는 5C7A, FAILED CHECKS와 FIRST FAILURE는 모두 00이어야 합니다. CGB와 FC는 파란 글자, DMG는 검은 글자를 표시합니다.

CALL COUNT는 02입니다. far_call 매크로와 __farcall이 각각 콜백을 한 번 호출합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

양 끝이 연결된 축에서 현재 위치부터 목표까지의 가장 짧은 부호 있는 변위를 계산합니다. 필드 경계를 넘는 추적이나 거리 비교에 사용하세요.

사용 형식

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

매개변수

target

목표 좌표이며, 범위는 0~size−1입니다.

current

현재 좌표이며, 범위는 0~size−1입니다.

size

경계가 이어지는 축 길이 1~256입니다. X에는 너비, Y에는 높이를 사용합니다. 256을 표현할 수 있도록 16비트 인수입니다.

반환값

최단 변위를 s16으로 반환합니다. 좌표가 증가하는 방향은 양수, 감소하는 방향은 음수, 같은 위치는 0입니다. 유효한 입력의 결과는 −128~+128입니다. 화면 좌표에서는 오른쪽과 아래 방향이 양수입니다.

사용 조건과 제한

chain.h를 포함하고 chain.c를 정확히 한 번 컴파일하세요. Chain이나 ChainBody를 초기화할 필요는 없습니다. 이 함수는 변위만 계산하며 좌표 배열, 관절 수, 화면을 변경하지 않습니다.

입력을 검사하거나 정규화하지 않습니다. size=0, size>256 또는 size 이상의 좌표를 전달하지 마세요. 더 큰 좌표계에서 온 좌표는 호출 전에 0~size−1로 래핑하세요.

양쪽 경로 길이가 같으면 직접 계산한 target−current의 부호를 유지합니다. size=160일 때 0→80은 +80, 80→0은 −80입니다. size=1이면 유효한 좌표는 0뿐이며 결과도 0입니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

경계 래핑 좌표를 보여 주는 예제입니다. 각 화살표는 현재 위치에서 목표로 향합니다. 너비 160의 경계 통과는 +02/−02, 필드 절반은 +80/−80, 너비 1은 +00으로 표시합니다. 앞의 0은 10진수 자리 채움입니다. 이 예제는 오브젝트를 그리거나 움직이지 않습니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

메모리를 할당하지 않고 호출자가 소유한 관절 배열 3개를 연결한 뒤 관절 수를 0으로 설정합니다.

사용 형식

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

매개변수

body

대상 ChainBody입니다. null은 무시합니다. 초기화 함수 외에는 초기화된 상태를 전달하세요.

x

관절 X 좌표 배열입니다.

y

관절 Y 좌표 배열입니다.

heading

관절 방향 배열입니다.

capacity

할당한 배열 길이 1~255입니다.

width

경계가 이어지는 필드 너비 1~256입니다.

height

경계가 이어지는 필드 높이 1~256입니다.

반환값

성공하면 1, 인수가 유효하지 않으면 0을 반환합니다. null이 아닌 몸체에서 실패하면 capacity와 count를 0으로 설정하여 갱신을 비활성화합니다.

사용 조건과 제한

chain.h를 포함하고 chain.c를 정확히 한 번 컴파일하세요. ChainBody는 각 관절의 현재 위치와 방향을 저장합니다. Chain 위치 이력 링과는 별도의 상태 형식입니다.

각각 capacity바이트인 별도의 쓰기 가능한 배열 x, y, heading을 제공하세요. 몸체를 사용하는 동안 배열을 유지해야 합니다. 인덱스 0은 머리이며 count에 포함됩니다. 초기화 후에는 저장 공간 포인터, 용량, 필드 크기를 바꾸지 마세요.

방향은 시계 방향의 16구간입니다. 0=오른쪽, 4=아래, 8=왼쪽, 12=위이며 입력의 하위 4비트만 사용합니다. 화면 좌표는 오른쪽·아래로 증가하고 각 필드 크기는 1~256픽셀입니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

이미지 위쪽은 곧은 몸체, 가운데는 아래로 방향을 바꾼 뒤 한 번 갱신한 모습, 아래쪽은 네 번 갱신한 모습입니다. 좌표는 논리 크기의 두 배로 그립니다. 굽힘은 오른쪽 머리에서 뒤로 전달됩니다. CGB와 FC는 머리를 빨강, 몸통을 파랑, 꼬리를 초록으로 표시하며 DMG는 검은색입니다. 성장 후 네 번 안정화 갱신을 하면 겹친 꼬리가 분리됩니다. 이는 같은 여덟 관절의 세 상태이며, 관절 24개짜리 몸체 하나가 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

지정한 머리 뒤에 관절을 배치하여 곧은 초기 자세를 만듭니다.

사용 형식

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

매개변수

body

대상 ChainBody입니다. null은 무시합니다. 초기화 함수 외에는 초기화된 상태를 전달하세요.

count

머리를 포함한 관절 수이며 1~capacity입니다.

head_x

머리 X 좌표이며 필드 너비에 맞게 래핑됩니다.

head_y

머리 Y 좌표이며 필드 높이에 맞게 래핑됩니다.

heading

16구간 체계의 머리 방향입니다.

반환값

성공하면 1을 반환합니다. count가 0이거나 너무 크거나 body가 null이면 자세를 바꾸지 않고 0을 반환합니다.

사용 조건과 제한

chain.h를 포함하고 chain.c를 정확히 한 번 컴파일하세요. ChainBody는 각 관절의 현재 위치와 방향을 저장합니다. Chain 위치 이력 링과는 별도의 상태 형식입니다.

각각 capacity바이트인 별도의 쓰기 가능한 배열 x, y, heading을 제공하세요. 몸체를 사용하는 동안 배열을 유지해야 합니다. 인덱스 0은 머리이며 count에 포함됩니다. 초기화 후에는 저장 공간 포인터, 용량, 필드 크기를 바꾸지 마세요.

방향은 시계 방향의 16구간입니다. 0=오른쪽, 4=아래, 8=왼쪽, 12=위이며 입력의 하위 4비트만 사용합니다. 화면 좌표는 오른쪽·아래로 증가하고 각 필드 크기는 1~256픽셀입니다.

상하좌우 간격은 4픽셀입니다. 중간 방향은 (4,1), (3,3), (1,4) 같은 정수 벡터를 사용하므로 유클리드 거리가 정확히 4픽셀은 아닙니다. 초기 자세가 필드 경계를 넘을 수 있습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

이미지 위쪽은 곧은 몸체, 가운데는 아래로 방향을 바꾼 뒤 한 번 갱신한 모습, 아래쪽은 네 번 갱신한 모습입니다. 좌표는 논리 크기의 두 배로 그립니다. 굽힘은 오른쪽 머리에서 뒤로 전달됩니다. CGB와 FC는 머리를 빨강, 몸통을 파랑, 꼬리를 초록으로 표시하며 DMG는 검은색입니다. 성장 후 네 번 안정화 갱신을 하면 겹친 꼬리가 분리됩니다. 이는 같은 여덟 관절의 세 상태이며, 관절 24개짜리 몸체 하나가 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

머리 자세를 설정하고 각 관절을 앞 관절 뒤의 연결점으로 조금씩 끌어당깁니다. 방향 변화는 갱신마다 한 관절씩 전파됩니다.

사용 형식

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

매개변수

body

대상 ChainBody입니다. null은 무시합니다. 초기화 함수 외에는 초기화된 상태를 전달하세요.

head_x

머리 X 좌표이며 필드 너비에 맞게 래핑됩니다.

head_y

머리 Y 좌표이며 필드 높이에 맞게 래핑됩니다.

heading

16구간 체계의 머리 방향입니다.

반환값

반환값은 없습니다.

사용 조건과 제한

chain.h를 포함하고 chain.c를 정확히 한 번 컴파일하세요. ChainBody는 각 관절의 현재 위치와 방향을 저장합니다. Chain 위치 이력 링과는 별도의 상태 형식입니다.

각각 capacity바이트인 별도의 쓰기 가능한 배열 x, y, heading을 제공하세요. 몸체를 사용하는 동안 배열을 유지해야 합니다. 인덱스 0은 머리이며 count에 포함됩니다. 초기화 후에는 저장 공간 포인터, 용량, 필드 크기를 바꾸지 마세요.

방향은 시계 방향의 16구간입니다. 0=오른쪽, 4=아래, 8=왼쪽, 12=위이며 입력의 하위 4비트만 사용합니다. 화면 좌표는 오른쪽·아래로 증가하고 각 필드 크기는 1~256픽셀입니다.

앞 관절의 갱신된 위치로 목표 연결점을 구한 뒤, 각 축에서 경계를 고려한 최단 변위를 계산합니다. 변위가 0이면 이동하지 않고, 크기 1~4는 1픽셀, 5 이상은 2픽셀 이동합니다. 정확히 필드 절반이면 원래 변위의 부호를 유지합니다.

각 관절의 갱신 전 저장된 방향을 다음 관절로 전달하여 굽힘이 몸체를 따라 이동하게 합니다. 빈 몸체는 변경하지 않습니다.

머리 속도, 가속도, 충돌, 그리기, 대기는 호출자가 처리합니다. 보통 머리를 먼저 갱신하고 시뮬레이션 틱마다 chain_body_step을 한 번 호출하세요. 관절 추적 기능이며, 강체나 정확한 길이 제약을 푸는 솔버는 아닙니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

이미지 위쪽은 곧은 몸체, 가운데는 아래로 방향을 바꾼 뒤 한 번 갱신한 모습, 아래쪽은 네 번 갱신한 모습입니다. 좌표는 논리 크기의 두 배로 그립니다. 굽힘은 오른쪽 머리에서 뒤로 전달됩니다. CGB와 FC는 머리를 빨강, 몸통을 파랑, 꼬리를 초록으로 표시하며 DMG는 검은색입니다. 성장 후 네 번 안정화 갱신을 하면 겹친 꼬리가 분리됩니다. 이는 같은 여덟 관절의 세 상태이며, 관절 24개짜리 몸체 하나가 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

꼬리의 현재 위치와 방향을 다음 빈 슬롯에 복사하고 개수를 1 늘립니다.

사용 형식

u8 chain_body_grow(ChainBody* body);

매개변수

body

대상 ChainBody입니다. null은 무시합니다. 초기화 함수 외에는 초기화된 상태를 전달하세요.

반환값

관절을 추가하면 1을 반환합니다. 몸체가 비어 있거나 가득 찼거나 비활성 또는 null이면 0입니다.

사용 조건과 제한

chain.h를 포함하고 chain.c를 정확히 한 번 컴파일하세요. ChainBody는 각 관절의 현재 위치와 방향을 저장합니다. Chain 위치 이력 링과는 별도의 상태 형식입니다.

각각 capacity바이트인 별도의 쓰기 가능한 배열 x, y, heading을 제공하세요. 몸체를 사용하는 동안 배열을 유지해야 합니다. 인덱스 0은 머리이며 count에 포함됩니다. 초기화 후에는 저장 공간 포인터, 용량, 필드 크기를 바꾸지 마세요.

방향은 시계 방향의 16구간입니다. 0=오른쪽, 4=아래, 8=왼쪽, 12=위이며 입력의 하위 4비트만 사용합니다. 화면 좌표는 오른쪽·아래로 증가하고 각 필드 크기는 1~256픽셀입니다.

새 꼬리는 처음에 이전 꼬리와 겹치고, 이후 chain_body_step 호출로 분리됩니다. 성장 자체는 머리나 다른 관절을 움직이지 않습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

이미지 위쪽은 곧은 몸체, 가운데는 아래로 방향을 바꾼 뒤 한 번 갱신한 모습, 아래쪽은 네 번 갱신한 모습입니다. 좌표는 논리 크기의 두 배로 그립니다. 굽힘은 오른쪽 머리에서 뒤로 전달됩니다. CGB와 FC는 머리를 빨강, 몸통을 파랑, 꼬리를 초록으로 표시하며 DMG는 검은색입니다. 성장 후 네 번 안정화 갱신을 하면 겹친 꼬리가 분리됩니다. 이는 같은 여덟 관절의 세 상태이며, 관절 24개짜리 몸체 하나가 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

배열과 필드 설정을 유지하면서 관절 수를 0으로 설정합니다.

사용 형식

void chain_body_clear(ChainBody* body);

매개변수

body

대상 ChainBody입니다. null은 무시합니다. 초기화 함수 외에는 초기화된 상태를 전달하세요.

반환값

반환값은 없습니다.

사용 조건과 제한

chain.h를 포함하고 chain.c를 정확히 한 번 컴파일하세요. ChainBody는 각 관절의 현재 위치와 방향을 저장합니다. Chain 위치 이력 링과는 별도의 상태 형식입니다.

각각 capacity바이트인 별도의 쓰기 가능한 배열 x, y, heading을 제공하세요. 몸체를 사용하는 동안 배열을 유지해야 합니다. 인덱스 0은 머리이며 count에 포함됩니다. 초기화 후에는 저장 공간 포인터, 용량, 필드 크기를 바꾸지 마세요.

방향은 시계 방향의 16구간입니다. 0=오른쪽, 4=아래, 8=왼쪽, 12=위이며 입력의 하위 4비트만 사용합니다. 화면 좌표는 오른쪽·아래로 증가하고 각 필드 크기는 1~256픽셀입니다.

배열 바이트는 지우지 않습니다. 다시 시작하려면 chain_body_reset을 사용하세요. 비운 직후 chain_body_grow를 호출해도 관절은 추가되지 않습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

이미지 위쪽은 곧은 몸체, 가운데는 아래로 방향을 바꾼 뒤 한 번 갱신한 모습, 아래쪽은 네 번 갱신한 모습입니다. 좌표는 논리 크기의 두 배로 그립니다. 굽힘은 오른쪽 머리에서 뒤로 전달됩니다. CGB와 FC는 머리를 빨강, 몸통을 파랑, 꼬리를 초록으로 표시하며 DMG는 검은색입니다. 성장 후 네 번 안정화 갱신을 하면 겹친 꼬리가 분리됩니다. 이는 같은 여덟 관절의 세 상태이며, 관절 24개짜리 몸체 하나가 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

기록된 이력을 비워 같은 저장 배열을 다시 사용할 수 있게 합니다.

사용 형식

void chain_clear(Chain* chain);

매개변수

chain

초기화된 Chain을 가리키는 포인터입니다.

반환값

반환값은 없습니다.

사용 조건과 제한

저장 배열을 지우거나 해제하지 않고 개수와 head를 0으로 초기화합니다. Chain과 점 배열은 호출 측이 소유하며 사용 중 계속 유효해야 합니다. 읽기 함수의 8비트 인덱스 덧셈이 넘치지 않도록 용량은 128 이하로 지정하세요.

FC 버전은 chain == 0이면 아무 동작도 하지 않습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

예제는 점 네 개의 이력을 비우고 개수가 0이 되는지 확인합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

현재 이력에서 읽을 수 있는 위치의 개수를 반환합니다.

사용 형식

u8 chain_get_count(const Chain* chain);

매개변수

chain

초기화된 Chain을 가리키는 포인터입니다.

반환값

0부터 용량까지의 개수를 반환합니다. chain이 NULL이면 0입니다.

사용 조건과 제한

Chain과 점 배열은 호출 측이 소유하며 사용 중 계속 유효해야 합니다. 읽기 함수의 8비트 인덱스 덧셈이 넘치지 않도록 용량은 128 이하로 지정하세요.

사용 예

result[4]=chain_get_count(&trail);

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

네 슬롯에 다섯 번 추가해도 개수는 4입니다. 비우면 0이 되며, 용량이 0인 이력에서는 계속 0입니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

얼마나 오래된 점인지 지정하여 저장된 위치를 읽습니다.

사용 형식

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

매개변수

chain

초기화된 Chain을 가리키는 포인터입니다.

index

점의 이력 인덱스입니다. 0이 최신 점이며 count - 1이 남아 있는 가장 오래된 점입니다.

out

결과를 받을 별도의 쓰기 가능한 ChainPoint입니다. NULL이면 실패합니다.

반환값

성공하면 1, 요청이 유효하지 않으면 0을 반환합니다. out이 NULL이 아니면 유효성 검사 전에 (0,0)으로 초기화합니다.

사용 조건과 제한

out이 저장 배열이나 Chain과 같은 메모리를 가리키면 안 됩니다. 출력을 초기화하면서 소스 데이터가 손상되기 때문입니다. Chain과 점 배열은 호출 측이 소유하며 사용 중 계속 유효해야 합니다. 읽기 함수의 8비트 인덱스 덧셈이 넘치지 않도록 용량은 128 이하로 지정하세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

인덱스 0은 최신 점 (40,24), 인덱스 3은 가장 오래된 점 (16,8)을 읽습니다. 유효하지 않은 인덱스 4는 실패를 반환하고 출력은 (0,0)이 됩니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

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

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

위치 이력용 순환 버퍼에 저장 공간을 연결하고, 기록된 점이 없는 상태로 시작합니다.

사용 형식

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

매개변수

chain

초기화할 쓰기 가능한 Chain입니다.

storage

ChainPoint 항목을 capacity개 담을 수 있는 배열입니다.

capacity

점 슬롯 수입니다. 이력을 사용하려면 1~128을 지정하세요. 0이면 기록하지 않습니다.

반환값

반환값은 없습니다.

사용 조건과 제한

Chain과 점 배열은 호출 측이 소유하며 사용 중 계속 유효해야 합니다. 읽기 함수의 8비트 인덱스 덧셈이 넘치지 않도록 용량은 128 이하로 지정하세요.

FC 버전은 chain == 0이면 아무 동작도 하지 않습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

예제는 점 슬롯 네 개를 연결하고 초기 개수가 0인지 검사합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

이력의 head에 최신 위치를 추가합니다. 가득 찬 경우 가장 오래된 점을 덮어씁니다.

사용 형식

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

매개변수

chain

초기화된 Chain을 가리키는 포인터입니다.

x

새 점의 부호 있는 X 좌표입니다.

y

새 점의 부호 있는 Y 좌표입니다.

반환값

반환값은 없습니다.

사용 조건과 제한

chain이 NULL이거나 용량이 0이면 아무 작업도 하지 않습니다. Chain과 점 배열은 호출 측이 소유하며 사용 중 계속 유효해야 합니다. 읽기 함수의 8비트 인덱스 덧셈이 넘치지 않도록 용량은 128 이하로 지정하세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

네 슬롯에 다섯 번 추가하면 최신 점은 (40,24), 남아 있는 가장 오래된 점은 (16,8)이 됩니다. 원래의 (8,8)은 덮어써집니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

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

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

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

점이 FC 사각형 안에 있는지 검사합니다. 왼쪽과 위쪽 가장자리는 포함하고, 오른쪽과 아래쪽 가장자리는 제외합니다.

사용 형식

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

매개변수

box

읽을 수 있는 NesBox16입니다. null을 전달하지 마세요.

px

점의 X 좌표입니다. 부호 없는 16비트 값입니다.

py

점의 Y 좌표입니다. 부호 없는 16비트 값입니다.

반환값

안쪽이면 1, 바깥쪽이면 0을 반환합니다.

사용 조건과 제한

x, y는 부호 없는 16비트 좌표이고, 너비와 높이는 바이트 값입니다. 양수인 크기를 사용하고, 좌표와 크기의 합이 65535를 넘지 않게 하세요. 좌표의 래핑 경계를 가로지르는 사각형은 처리하지 못합니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

좌표 1단위는 타일 하나입니다. (1,1)의 사각형 A와 (5,4)의 사각형 B는 모두 8×6 크기입니다. A만 차지하는 칸은 A, B만 차지하는 칸은 B로 표시하고, 4×3 겹침 영역의 12칸은 O로 표시합니다. A의 오른쪽 가장자리 x=9는 포함하지 않습니다. CGB에서는 A가 빨간색, B가 파란색, O가 초록색입니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

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

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

    return 1;
}

포인터로 전달된 두 FC 사각형이 면적을 갖고 겹치는지 검사합니다.

사용 형식

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

매개변수

a

읽을 수 있는 첫 번째 NesBox16입니다. null을 전달하지 마세요.

b

읽을 수 있는 두 번째 NesBox16입니다.

반환값

겹치면 1, 떨어져 있거나 가장자리만 닿으면 0을 반환합니다.

사용 조건과 제한

x, y는 부호 없는 16비트 좌표이고, 너비와 높이는 바이트 값입니다. 양수인 크기를 사용하고, 좌표와 크기의 합이 65535를 넘지 않게 하세요. 좌표의 래핑 경계를 가로지르는 사각형은 처리하지 못합니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

좌표 1단위는 타일 하나입니다. (1,1)의 사각형 A와 (5,4)의 사각형 B는 모두 8×6 크기입니다. A만 차지하는 칸은 A, B만 차지하는 칸은 B로 표시하고, 4×3 겹침 영역의 12칸은 O로 표시합니다. A의 오른쪽 가장자리 x=9는 포함하지 않습니다. CGB에서는 A가 빨간색, B가 파란색, O가 초록색입니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

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

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

    return 1;
}

어설션 실패 코드를 보관하고 ASSERT 항목 추가를 시도합니다.

사용 형식

void debug_assert_fail(u16 code);

매개변수

code

보관할 16비트 오류 식별자입니다.

반환값

반환값은 없습니다.

사용 조건과 제한

실행은 계속됩니다. 로그가 가득 차도 마지막 어설션 코드는 갱신합니다. 로그는 기본적으로 32개 항목을 담으며 가득 차면 새 항목을 버립니다. DEBUG_TRACE_MAX를 재정의할 때는 모든 번역 단위에서 동일한 1~255 값을 사용하세요. 이름은 복사하지 않고 포인터로 보관하므로 확인이 끝날 때까지 해당 메모리를 읽을 수 있어야 합니다. 인터럽트와 메인 코드의 쓰기가 겹치지 않도록 호출 측에서 순서를 보장하세요.

사용 예

debug_assert_fail(42);

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

예제는 코드 42를 기록하고 로그를 가득 채운 뒤 코드 999를 기록합니다. 개수는 32로 유지되지만 마지막 코드는 999로 바뀝니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

남은 로그 공간과 관계없이 최근 어설션 코드를 읽습니다.

사용 형식

u16 debug_get_last_assert(void);

반환값

최근 16비트 코드를 반환합니다. 초기화 직후의 값은 0입니다.

사용 조건과 제한

0은 초기값이기도 하므로 코드 0으로 기록한 실패와 구분할 수 없습니다. 읽어도 코드는 지워지지 않습니다.

사용 예

result[22]=debug_get_last_assert();

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

예제는 어설션 매크로의 77, 로그가 가득 찬 뒤의 999, 재초기화 후의 0을 확인합니다.

사용 예의 전체 프로그램

빌드 명령

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

Read the latest assertion code, initially zero after debug_init.

u16 debug_get_last_assert(void)
{
    return kq_debug_last_assert;
}

추적 배열의 유효한 항목 수를 읽습니다.

사용 형식

u8 debug_get_trace_count(void);

반환값

0~DEBUG_TRACE_MAX 범위의 개수를 반환합니다.

사용 조건과 제한

로그는 기본적으로 32개 항목을 담으며 가득 차면 새 항목을 버립니다. DEBUG_TRACE_MAX를 재정의할 때는 모든 번역 단위에서 동일한 1~255 값을 사용하세요. 이름은 복사하지 않고 포인터로 보관하므로 확인이 끝날 때까지 해당 메모리를 읽을 수 있어야 합니다. 인터럽트와 메인 코드의 쓰기가 겹치지 않도록 호출 측에서 순서를 보장하세요.

사용 예

result[1]=debug_get_trace_count();

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

예제는 처음 열 개의 항목과, 추가 기록 후의 상한 32를 확인합니다. 가득 차도 개수는 순환하여 0으로 돌아가지 않습니다.

사용 예의 전체 프로그램

빌드 명령

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

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

u8 debug_get_trace_count(void)
{
    return kq_debug_trace_count;
}

기록된 이름, 값, 프레임 태그를 확인할 수 있도록 내부 배열의 참조를 얻습니다.

사용 형식

const DebugTraceEntry* debug_get_trace_log(void);

반환값

내부 DebugTraceEntry 배열의 읽기 전용 포인터를 반환합니다.

사용 조건과 제한

복사본이 아닙니다. debug_get_trace_count()가 반환한 개수만큼만 읽으세요. 초기화 후 남아 있는 이전 바이트는 유효한 레코드가 아닙니다. 로그는 기본적으로 32개 항목을 담으며 가득 차면 새 항목을 버립니다. DEBUG_TRACE_MAX를 재정의할 때는 모든 번역 단위에서 동일한 1~255 값을 사용하세요. 이름은 복사하지 않고 포인터로 보관하므로 확인이 끝날 때까지 해당 메모리를 읽을 수 있어야 합니다. 인터럽트와 메인 코드의 쓰기가 겹치지 않도록 호출 측에서 순서를 보장하세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

예제는 열 개 항목의 값과 프레임 필드를 모두 읽고, BEGIN 이름의 첫 글자가 B인지 확인합니다.

사용 예의 전체 프로그램

빌드 명령

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

Borrow the internal trace array; bound inspection by debug_get_trace_count.

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

유효한 로그 길이, 프레임 태그, 마지막 어설션 코드를 초기화합니다.

사용 형식

void debug_init(void);

반환값

반환값은 없습니다.

사용 조건과 제한

기존 항목의 바이트는 지우지 않습니다. 첫 항목을 기록하기 전에 호출하세요. 로그는 기본적으로 32개 항목을 담으며 가득 차면 새 항목을 버립니다. DEBUG_TRACE_MAX를 재정의할 때는 모든 번역 단위에서 동일한 1~255 값을 사용하세요. 이름은 복사하지 않고 포인터로 보관하므로 확인이 끝날 때까지 해당 메모리를 읽을 수 있어야 합니다. 인터럽트와 메인 코드의 쓰기가 겹치지 않도록 호출 측에서 순서를 보장하세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

초기 개수가 0인지 확인한 뒤, 데이터가 있는 로그를 초기화합니다. 이전 배열 값은 남아 있지만 개수와 어설션 코드는 0이 되는지 검사합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

처리 흐름의 특정 지점을 식별하도록 이름 있는 프레임 마커를 기록합니다.

사용 형식

void debug_mark_frame(const u8* label);

매개변수

label

0으로 끝나는 이름 문자열입니다. 해당 메모리는 확인할 때까지 읽을 수 있어야 합니다.

반환값

반환값은 없습니다.

사용 조건과 제한

로그는 기본적으로 32개 항목을 담으며 가득 차면 새 항목을 버립니다. DEBUG_TRACE_MAX를 재정의할 때는 모든 번역 단위에서 동일한 1~255 값을 사용하세요. 이름은 복사하지 않고 포인터로 보관하므로 확인이 끝날 때까지 해당 메모리를 읽을 수 있어야 합니다. 인터럽트와 메인 코드의 쓰기가 겹치지 않도록 호출 측에서 순서를 보장하세요.

사용 예

debug_mark_frame("BEGIN");

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

BEGIN 마커를 추가하면 프레임 태그 513과 함께 값 65535(0xFFFF)가 기록됩니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

이후 로그 항목에 복사할 프레임 태그를 설정합니다.

사용 형식

void debug_set_frame(u16 frame);

매개변수

frame

이후 항목에 사용할 16비트 프레임 번호입니다.

반환값

반환값은 없습니다.

사용 조건과 제한

프레임을 기다리거나 태그를 자동으로 증가시키지 않습니다. 게임의 프레임 카운터를 명시적으로 전달하세요. 로그는 기본적으로 32개 항목을 담으며 가득 차면 새 항목을 버립니다. DEBUG_TRACE_MAX를 재정의할 때는 모든 번역 단위에서 동일한 1~255 값을 사용하세요. 이름은 복사하지 않고 포인터로 보관하므로 확인이 끝날 때까지 해당 메모리를 읽을 수 있어야 합니다. 인터럽트와 메인 코드의 쓰기가 겹치지 않도록 호출 측에서 순서를 보장하세요.

사용 예

debug_set_frame(513);

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

예제는 태그를 513으로 설정하고 항목 열 개를 기록한 뒤, 열 개의 프레임 필드를 모두 다시 읽어 태그를 확인합니다.

사용 예의 전체 프로그램

빌드 명령

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

Choose the frame tag stored in subsequent debug entries.

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

이름을 붙여 16비트 점수나 카운터를 기록합니다.

사용 형식

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

매개변수

name

0으로 끝나는 이름 문자열입니다. 해당 메모리는 확인할 때까지 읽을 수 있어야 합니다.

value

기록할 0~65535의 값입니다.

반환값

반환값은 없습니다.

사용 조건과 제한

로그는 기본적으로 32개 항목을 담으며 가득 차면 새 항목을 버립니다. DEBUG_TRACE_MAX를 재정의할 때는 모든 번역 단위에서 동일한 1~255 값을 사용하세요. 이름은 복사하지 않고 포인터로 보관하므로 확인이 끝날 때까지 해당 메모리를 읽을 수 있어야 합니다. 인터럽트와 메인 코드의 쓰기가 겹치지 않도록 호출 측에서 순서를 보장하세요.

사용 예

debug_trace_u16("WORD",4660);

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

WORD 항목은 4660(0x1234)을 저장하며, 예제에서 다시 읽어 두 바이트를 모두 확인합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

이름 및 현재 프레임 태그와 함께 8비트 상태값을 기록합니다.

사용 형식

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

매개변수

name

0으로 끝나는 이름 문자열입니다. 해당 메모리는 확인할 때까지 읽을 수 있어야 합니다.

value

0~255의 값이며, 상위 비트를 0으로 채워 로그의 16비트 필드에 저장합니다.

반환값

반환값은 없습니다.

사용 조건과 제한

로그는 기본적으로 32개 항목을 담으며 가득 차면 새 항목을 버립니다. DEBUG_TRACE_MAX를 재정의할 때는 모든 번역 단위에서 동일한 1~255 값을 사용하세요. 이름은 복사하지 않고 포인터로 보관하므로 확인이 끝날 때까지 해당 메모리를 읽을 수 있어야 합니다. 인터럽트와 메인 코드의 쓰기가 겹치지 않도록 호출 측에서 순서를 보장하세요.

사용 예

debug_trace_u8("BYTE",255);

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

BYTE 항목에 255를 기록하고, 로그의 16비트 값 필드에도 255가 들어 있는지 확인합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

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

조건이 거짓이면 어설션 코드 1을 기록하는 문장 형태의 매크로입니다.

사용 형식

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

매개변수

cond

성립해야 하는 조건입니다. 0이면 실패입니다.

반환값

반환값은 없습니다.

사용 조건과 제한

조건은 한 번 평가합니다. 참이면 아무것도 기록하지 않고, 거짓이면 실행을 멈추지 않은 채 실패를 기록합니다. do…while (0) 형태이므로 if…else에서 하나의 문장처럼 사용할 수 있습니다.

사용 예

KITAQGB_ASSERT(1);KITAQGB_ASSERT(0);

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

참인 어설션과 거짓인 어설션을 하나씩 실행하면 코드 1인 항목이 정확히 하나 생깁니다.

사용 예의 전체 프로그램

빌드 명령

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

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

조건이 거짓일 때만 지정한 어설션 코드를 기록합니다.

사용 형식

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

매개변수

cond

성립해야 하는 조건입니다.

code

실패했을 때 평가하고 16비트로 변환할 코드 식입니다.

반환값

반환값은 없습니다.

사용 조건과 제한

조건은 한 번 평가하고, 코드 식은 실패했을 때만 평가합니다. 기록 후에도 실행은 계속됩니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

조건이 참이면 코드 식 ++side_effect는 평가하지 않으며 변수는 0으로 유지됩니다. 조건이 거짓이면 코드 77을 기록합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

이름을 문자열 포인터로 변환하고 값이 0xFFFF인 프레임 마커를 추가합니다.

사용 형식

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

매개변수

label

0으로 끝나는 이름 문자열입니다. 해당 메모리는 확인할 때까지 읽을 수 있어야 합니다.

반환값

반환값은 없습니다.

사용 조건과 제한

로그는 기본적으로 32개 항목을 담으며 가득 차면 새 항목을 버립니다. DEBUG_TRACE_MAX를 재정의할 때는 모든 번역 단위에서 동일한 1~255 값을 사용하세요. 이름은 복사하지 않고 포인터로 보관하므로 확인이 끝날 때까지 해당 메모리를 읽을 수 있어야 합니다. 인터럽트와 메인 코드의 쓰기가 겹치지 않도록 호출 측에서 순서를 보장하세요.

사용 예

KITAQGB_MARK_FRAME("END");

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

END 마커의 값이 65535, 프레임 태그가 513인지 확인합니다.

사용 예의 전체 프로그램

빌드 명령

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

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

값을 명시적으로 16비트로 변환한 뒤 이름과 함께 기록합니다.

사용 형식

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

매개변수

name

0으로 끝나는 이름 문자열입니다. 해당 메모리는 확인할 때까지 읽을 수 있어야 합니다.

value

기록 전에 16비트로 변환할 식입니다.

반환값

반환값은 없습니다.

사용 조건과 제한

매크로는 항상 활성화되어 있으며 빌드 설정으로 자동 비활성화되지 않습니다. 16비트 기록 동작은 KITAQGB_TRACE_U16과 같습니다. 로그는 기본적으로 32개 항목을 담으며 가득 차면 새 항목을 버립니다. DEBUG_TRACE_MAX를 재정의할 때는 모든 번역 단위에서 동일한 1~255 값을 사용하세요. 이름은 복사하지 않고 포인터로 보관하므로 확인이 끝날 때까지 해당 메모리를 읽을 수 있어야 합니다. 인터럽트와 메인 코드의 쓰기가 겹치지 않도록 호출 측에서 순서를 보장하세요.

사용 예

KITAQGB_TRACE("SCORE",600);

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

예제는 600을 기록합니다. 검증을 위해 로그에서 값을 다시 읽습니다.

사용 예의 전체 프로그램

빌드 명령

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

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

값을 명시적으로 16비트로 변환한 뒤 이름과 함께 기록합니다.

사용 형식

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

매개변수

name

0으로 끝나는 이름 문자열입니다. 해당 메모리는 확인할 때까지 읽을 수 있어야 합니다.

value

기록 전에 16비트로 변환할 식입니다.

반환값

반환값은 없습니다.

사용 조건과 제한

매크로는 항상 활성화되어 있으며 빌드 설정으로 자동 비활성화되지 않습니다. 로그는 기본적으로 32개 항목을 담으며 가득 차면 새 항목을 버립니다. DEBUG_TRACE_MAX를 재정의할 때는 모든 번역 단위에서 동일한 1~255 값을 사용하세요. 이름은 복사하지 않고 포인터로 보관하므로 확인이 끝날 때까지 해당 메모리를 읽을 수 있어야 합니다. 인터럽트와 메인 코드의 쓰기가 겹치지 않도록 호출 측에서 순서를 보장하세요.

사용 예

KITAQGB_TRACE_U16("WORD2",500);

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

예제는 500을 기록합니다. 검증을 위해 로그에서 값을 다시 읽습니다.

사용 예의 전체 프로그램

빌드 명령

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

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

값을 명시적으로 8비트로 변환한 뒤 이름과 함께 기록합니다.

사용 형식

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

매개변수

name

0으로 끝나는 이름 문자열입니다. 해당 메모리는 확인할 때까지 읽을 수 있어야 합니다.

value

기록 전에 8비트로 변환할 식입니다.

반환값

반환값은 없습니다.

사용 조건과 제한

매크로는 항상 활성화되어 있으며 빌드 설정으로 자동 비활성화되지 않습니다. 로그는 기본적으로 32개 항목을 담으며 가득 차면 새 항목을 버립니다. DEBUG_TRACE_MAX를 재정의할 때는 모든 번역 단위에서 동일한 1~255 값을 사용하세요. 이름은 복사하지 않고 포인터로 보관하므로 확인이 끝날 때까지 해당 메모리를 읽을 수 있어야 합니다. 인터럽트와 메인 코드의 쓰기가 겹치지 않도록 호출 측에서 순서를 보장하세요.

사용 예

KITAQGB_TRACE_U8("CAST",0x1234);

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

예제는 52를 기록합니다. 0x1234의 하위 바이트인 0x34만 남습니다.

사용 예의 전체 프로그램

빌드 명령

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

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

모든 엔티티를 해제하고 스프라이트 미할당 표시를 포함한 필드를 초기화합니다.

사용 형식

void entity_clear_all(void);

반환값

없음(void).

사용 조건과 제한

풀은 고정 배열이며 힙을 동적으로 할당하지 않습니다. ENTITY_MAX의 기본값은 16이고 범위는 1~255입니다. 모든 컴파일 단위에서 같은 값으로 정의하세요. ID는 0부터 시작하며 0xFF는 실패를 나타냅니다.

모든 슬롯의 active,type,x,y,vx,vy,state,timer를 0, sprite를 0xFF로 설정합니다. 하드웨어 스프라이트를 숨기거나 해제하지는 않으므로 렌더링 자원은 별도로 정리하세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

전체 프로그램은 재사용되는 풀 슬롯의 수명 주기를 보여 줍니다. 숫자는 라벨과 함께 읽으세요. 두 개를 할당하면 CREATED 002, 첫 번째를 해제하면 AFTER FREE 001, 가장 작은 빈 ID를 재사용하면 REUSED ID 000, 전체를 해제하면 AFTER CLEAR 000입니다. 해제 후 조회가 null인지, 재할당 시 필드가 초기화되는지도 검사합니다. FAILED CHECKS 000은 기대값과 일치했다는 뜻입니다.

FC 순회는 활성 엔티티 두 개에 각각 콜백을 호출하므로 UPDATE CALLS 002, DRAW CALLS 002가 됩니다. 예제의 갱신 콜백은 둘을 오른쪽으로 한 타일 이동합니다. 그리기 콜백은 두 객체를 나타내는 A를 타일 (3,12), B를 (7,12)에 놓습니다. 콜백이 그린 배경 글자 타일이며 자동 할당된 스프라이트가 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

Release every entity and restore deterministic defaults, including the no-sprite sentinel.

void entity_clear_all(void)
{
    u8 i;
    i = 0;
    while (i < ENTITY_MAX) {
        entity_pool[(__safe_index u8)i].active = 0;
        entity_pool[(__safe_index u8)i].type = 0;
        entity_pool[(__safe_index u8)i].x = 0;
        entity_pool[(__safe_index u8)i].y = 0;
        entity_pool[(__safe_index u8)i].vx = 0;
        entity_pool[(__safe_index u8)i].vy = 0;
        entity_pool[(__safe_index u8)i].state = 0;
        entity_pool[(__safe_index u8)i].timer = 0;
        entity_pool[(__safe_index u8)i].sprite = 0xFF;
        i = (u8)(i + 1);
    }
}

엔티티 상태를 바꾸지 않고 사용 중인 슬롯 수를 반환합니다.

사용 형식

u8 entity_count_active(void);

반환값

active 바이트가 0이 아닌 슬롯 수로, 0~ENTITY_MAX입니다. 사용 중인 수이며 가장 큰 ID나 화면의 스프라이트 수가 아닙니다.

사용 조건과 제한

풀은 고정 배열이며 힙을 동적으로 할당하지 않습니다. ENTITY_MAX의 기본값은 16이고 범위는 1~255입니다. 모든 컴파일 단위에서 같은 값으로 정의하세요. ID는 0부터 시작하며 0xFF는 실패를 나타냅니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

전체 프로그램은 재사용되는 풀 슬롯의 수명 주기를 보여 줍니다. 숫자는 라벨과 함께 읽으세요. 두 개를 할당하면 CREATED 002, 첫 번째를 해제하면 AFTER FREE 001, 가장 작은 빈 ID를 재사용하면 REUSED ID 000, 전체를 해제하면 AFTER CLEAR 000입니다. 해제 후 조회가 null인지, 재할당 시 필드가 초기화되는지도 검사합니다. FAILED CHECKS 000은 기대값과 일치했다는 뜻입니다.

FC 순회는 활성 엔티티 두 개에 각각 콜백을 호출하므로 UPDATE CALLS 002, DRAW CALLS 002가 됩니다. 예제의 갱신 콜백은 둘을 오른쪽으로 한 타일 이동합니다. 그리기 콜백은 두 객체를 나타내는 A를 타일 (3,12), B를 (7,12)에 놓습니다. 콜백이 그린 배경 글자 타일이며 자동 할당된 스프라이트가 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

Count occupied slots without changing entity state.

u8 entity_count_active(void)
{
    u8 i;
    u8 count;
    i = 0;
    count = 0;
    while (i < ENTITY_MAX) {
        if (entity_pool[(__safe_index u8)i].active != 0) count = (u8)(count + 1);
        i = (u8)(i + 1);
    }
    return count;
}

지정한 종류와 좌표로 엔티티를 할당하고 재사용 가능한 ID를 반환합니다. 빈 슬롯이 없으면 0xFF입니다.

사용 형식

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

매개변수

type

게임에서 정의하는 0~255의 종류 번호입니다. 풀은 값을 저장할 뿐, 종류에 따라 동작이나 그리기 함수를 선택하지 않습니다.

x, y

부호 있는 16비트 좌표(-32768~32767)입니다. 픽셀이나 Q8.8 등 단위는 게임이 정합니다. 풀은 단위 변환, 좌표 제한, 속도에 따른 자동 이동을 하지 않습니다.

반환값

가장 작은 빈 슬롯 ID(0~ENTITY_MAX-1)를 반환하며, 빈 슬롯이 없으면 0xFF입니다. 성공하면 active=1로 설정하고 종류·좌표를 저장하며 속도·상태·타이머는 0, sprite는 0xFF로 초기화합니다.

사용 조건과 제한

풀은 고정 배열이며 힙을 동적으로 할당하지 않습니다. ENTITY_MAX의 기본값은 16이고 범위는 1~255입니다. 모든 컴파일 단위에서 같은 값으로 정의하세요. ID는 0부터 시작하며 0xFF는 실패를 나타냅니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

전체 프로그램은 재사용되는 풀 슬롯의 수명 주기를 보여 줍니다. 숫자는 라벨과 함께 읽으세요. 두 개를 할당하면 CREATED 002, 첫 번째를 해제하면 AFTER FREE 001, 가장 작은 빈 ID를 재사용하면 REUSED ID 000, 전체를 해제하면 AFTER CLEAR 000입니다. 해제 후 조회가 null인지, 재할당 시 필드가 초기화되는지도 검사합니다. FAILED CHECKS 000은 기대값과 일치했다는 뜻입니다.

FC 순회는 활성 엔티티 두 개에 각각 콜백을 호출하므로 UPDATE CALLS 002, DRAW CALLS 002가 됩니다. 예제의 갱신 콜백은 둘을 오른쪽으로 한 타일 이동합니다. 그리기 콜백은 두 객체를 나타내는 A를 타일 (3,12), B를 (7,12)에 놓습니다. 콜백이 그린 배경 글자 타일이며 자동 할당된 스프라이트가 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

Returns a reusable slot ID, or 0xFF if no slot is free.

u8 entity_create(u8 type, s16 x, s16 y)
{
    u8 i;
    i = 0;
    while (i < ENTITY_MAX) {
        if (entity_pool[(__safe_index u8)i].active == 0) {
            entity_pool[(__safe_index u8)i].active = 1;
            entity_pool[(__safe_index u8)i].type = type;
            entity_pool[(__safe_index u8)i].x = x;
            entity_pool[(__safe_index u8)i].y = y;
            entity_pool[(__safe_index u8)i].vx = 0;
            entity_pool[(__safe_index u8)i].vy = 0;
            entity_pool[(__safe_index u8)i].state = 0;
            entity_pool[(__safe_index u8)i].timer = 0;
            entity_pool[(__safe_index u8)i].sprite = 0xFF;
            return i;
        }
        i = (u8)(i + 1);
    }
    return 0xFF;
}

id의 엔티티 슬롯을 해제합니다. 저장된 데이터는 다시 할당할 때 초기화됩니다.

사용 형식

void entity_destroy(u8 id);

매개변수

id

0~ENTITY_MAX-1의 재사용 가능한 슬롯 번호입니다. 범위 밖 ID는 유효하지 않습니다. 잘못된 ID를 해제해도 변화가 없고 조회하면 null을 반환합니다.

반환값

없음(void).

사용 조건과 제한

풀은 고정 배열이며 힙을 동적으로 할당하지 않습니다. ENTITY_MAX의 기본값은 16이고 범위는 1~255입니다. 모든 컴파일 단위에서 같은 값으로 정의하세요. ID는 0부터 시작하며 0xFF는 실패를 나타냅니다.

해제는 active만 0으로 만듭니다. 다른 필드를 지우거나 스프라이트·에셋을 해제하지 않습니다. 이후 같은 ID와 주소가 다른 엔티티에 재사용될 수 있습니다. 관련 자원은 게임에서 정리하세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

전체 프로그램은 재사용되는 풀 슬롯의 수명 주기를 보여 줍니다. 숫자는 라벨과 함께 읽으세요. 두 개를 할당하면 CREATED 002, 첫 번째를 해제하면 AFTER FREE 001, 가장 작은 빈 ID를 재사용하면 REUSED ID 000, 전체를 해제하면 AFTER CLEAR 000입니다. 해제 후 조회가 null인지, 재할당 시 필드가 초기화되는지도 검사합니다. FAILED CHECKS 000은 기대값과 일치했다는 뜻입니다.

FC 순회는 활성 엔티티 두 개에 각각 콜백을 호출하므로 UPDATE CALLS 002, DRAW CALLS 002가 됩니다. 예제의 갱신 콜백은 둘을 오른쪽으로 한 타일 이동합니다. 그리기 콜백은 두 객체를 나타내는 A를 타일 (3,12), B를 (7,12)에 놓습니다. 콜백이 그린 배경 글자 타일이며 자동 할당된 스프라이트가 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

Release a valid slot without clearing its payload. Reallocation resets the payload;
a saved pointer or ID must not be treated as a persistent entity identity.

void entity_destroy(u8 id)
{
    if (id >= ENTITY_MAX) return;
    entity_pool[(__safe_index u8)id].active = 0;
}

활성 엔티티를 순회하며 각 ID를 그리기 콜백에 전달합니다. 순회 방식은 entity_update_all과 같습니다. 콜백이 그리기 데이터를 제출하지 않으면 스프라이트나 픽셀은 그려지지 않습니다.

사용 형식

void entity_draw_all(EntityFn fn);

매개변수

fn

형식이 void fn(u8 id)인 함수 포인터입니다. 슬롯 ID를 받으므로 필드에 접근하려면 entity_get(id)를 사용하세요. null도 허용되며 이때는 호출하지 않습니다.

반환값

없음(void).

사용 조건과 제한

풀은 고정 배열이며 힙을 동적으로 할당하지 않습니다. ENTITY_MAX의 기본값은 16이고 범위는 1~255입니다. 모든 컴파일 단위에서 같은 값으로 정의하세요. ID는 0부터 시작하며 0xFF는 실패를 나타냅니다.

순회가 슬롯에 도달했을 때 활성 상태를 검사합니다. 콜백이 뒤쪽 슬롯을 비활성화하면 건너뛰고, 활성화하면 이번 순회에서 처리할 수 있습니다. 시작 시점의 활성 목록을 고정한 스냅샷이 아닙니다.

콜백을 공통 PRG 뱅크 0에 두거나, 호출이 끝날 때까지 해당 뱅크가 매핑된 상태를 유지하세요. 함수 포인터는 16비트 CPU 주소만 저장하며 뱅크를 선택하지 않습니다. FC의 함수 매개변수와 지역 변수는 고정된 메모리를 사용하므로 엔티티 순회를 재귀적으로 호출하거나 인터럽트에서 같은 순회에 재진입하면 안 됩니다.

사용 예

void demo_draw(u8 id) {
    Entity* entity;
    entity = entity_get(id);
    if (entity != 0) {
        m_put((u8)entity->x, (u8)entity->y, (u8)('A' + entity->type - 1));
        draw_calls++;
    }
}

// From main(), after creating two entities:
draw_calls = 0;
entity_draw_all(demo_draw);
automatic_draws = draw_calls;
if (automatic_draws != 2) { failures++; }

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

전체 프로그램은 재사용되는 풀 슬롯의 수명 주기를 보여 줍니다. 숫자는 라벨과 함께 읽으세요. 두 개를 할당하면 CREATED 002, 첫 번째를 해제하면 AFTER FREE 001, 가장 작은 빈 ID를 재사용하면 REUSED ID 000, 전체를 해제하면 AFTER CLEAR 000입니다. 해제 후 조회가 null인지, 재할당 시 필드가 초기화되는지도 검사합니다. FAILED CHECKS 000은 기대값과 일치했다는 뜻입니다.

FC 순회는 활성 엔티티 두 개에 각각 콜백을 호출하므로 UPDATE CALLS 002, DRAW CALLS 002가 됩니다. 예제의 갱신 콜백은 둘을 오른쪽으로 한 타일 이동합니다. 그리기 콜백은 두 객체를 나타내는 A를 타일 (3,12), B를 (7,12)에 놓습니다. 콜백이 그린 배경 글자 타일이며 자동 할당된 스프라이트가 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

Call the drawing callback for each active slot, using the same traversal rules as update.
The callback submits drawing data; the pool does not allocate sprites.

void entity_draw_all(EntityFn fn)
{
    entity_update_all(fn);
}

사용 중인 유효 ID의 엔티티 포인터를 반환하며, 그 외에는 null입니다. 해당 저장 공간은 재사용됩니다.

사용 형식

Entity* entity_get(u8 id);

매개변수

id

0~ENTITY_MAX-1의 재사용 가능한 슬롯 번호입니다. 범위 밖 ID는 유효하지 않습니다. 잘못된 ID를 해제해도 변화가 없고 조회하면 null을 반환합니다.

반환값

사용 중인 슬롯을 수정할 수 있는 포인터를 반환하며, ID가 잘못됐거나 비활성이면 null입니다. 메모리는 풀 소유입니다. 직접 해제하거나 삭제·재할당을 거치는 영구 식별자로 사용하지 마세요.

사용 조건과 제한

풀은 고정 배열이며 힙을 동적으로 할당하지 않습니다. ENTITY_MAX의 기본값은 16이고 범위는 1~255입니다. 모든 컴파일 단위에서 같은 값으로 정의하세요. ID는 0부터 시작하며 0xFF는 실패를 나타냅니다.

해제는 active만 0으로 만듭니다. 다른 필드를 지우거나 스프라이트·에셋을 해제하지 않습니다. 이후 같은 ID와 주소가 다른 엔티티에 재사용될 수 있습니다. 관련 자원은 게임에서 정리하세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

전체 프로그램은 재사용되는 풀 슬롯의 수명 주기를 보여 줍니다. 숫자는 라벨과 함께 읽으세요. 두 개를 할당하면 CREATED 002, 첫 번째를 해제하면 AFTER FREE 001, 가장 작은 빈 ID를 재사용하면 REUSED ID 000, 전체를 해제하면 AFTER CLEAR 000입니다. 해제 후 조회가 null인지, 재할당 시 필드가 초기화되는지도 검사합니다. FAILED CHECKS 000은 기대값과 일치했다는 뜻입니다.

FC 순회는 활성 엔티티 두 개에 각각 콜백을 호출하므로 UPDATE CALLS 002, DRAW CALLS 002가 됩니다. 예제의 갱신 콜백은 둘을 오른쪽으로 한 타일 이동합니다. 그리기 콜백은 두 객체를 나타내는 A를 타일 (3,12), B를 (7,12)에 놓습니다. 콜백이 그린 배경 글자 타일이며 자동 할당된 스프라이트가 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

Returns null for an invalid or inactive ID; the returned pointer aliases reusable pool storage.

Entity* entity_get(u8 id)
{
    if (id >= ENTITY_MAX) return 0;
    if (entity_pool[(__safe_index u8)id].active == 0) return 0;
    return &entity_pool[(__safe_index u8)id];
}

엔티티 풀의 모든 슬롯을 초기화합니다.

사용 형식

void entity_init(void);

반환값

없음(void).

사용 조건과 제한

풀은 고정 배열이며 힙을 동적으로 할당하지 않습니다. ENTITY_MAX의 기본값은 16이고 범위는 1~255입니다. 모든 컴파일 단위에서 같은 값으로 정의하세요. ID는 0부터 시작하며 0xFF는 실패를 나타냅니다.

모든 슬롯의 active,type,x,y,vx,vy,state,timer를 0, sprite를 0xFF로 설정합니다. 하드웨어 스프라이트를 숨기거나 해제하지는 않으므로 렌더링 자원은 별도로 정리하세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

전체 프로그램은 재사용되는 풀 슬롯의 수명 주기를 보여 줍니다. 숫자는 라벨과 함께 읽으세요. 두 개를 할당하면 CREATED 002, 첫 번째를 해제하면 AFTER FREE 001, 가장 작은 빈 ID를 재사용하면 REUSED ID 000, 전체를 해제하면 AFTER CLEAR 000입니다. 해제 후 조회가 null인지, 재할당 시 필드가 초기화되는지도 검사합니다. FAILED CHECKS 000은 기대값과 일치했다는 뜻입니다.

FC 순회는 활성 엔티티 두 개에 각각 콜백을 호출하므로 UPDATE CALLS 002, DRAW CALLS 002가 됩니다. 예제의 갱신 콜백은 둘을 오른쪽으로 한 타일 이동합니다. 그리기 콜백은 두 객체를 나타내는 A를 타일 (3,12), B를 (7,12)에 놓습니다. 콜백이 그린 배경 글자 타일이며 자동 할당된 스프라이트가 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

Reset every slot before the game starts using the pool.

void entity_init(void)
{
    entity_clear_all();
}

ID 오름차순으로 활성 슬롯을 살펴보고 각각 fn(id)를 한 번 호출합니다. 이동·충돌·타이머 로직은 콜백에 작성하며 풀은 이 로직을 제공하지 않습니다. 콜백이 null이면 아무것도 하지 않습니다.

사용 형식

void entity_update_all(EntityFn fn);

매개변수

fn

형식이 void fn(u8 id)인 함수 포인터입니다. 슬롯 ID를 받으므로 필드에 접근하려면 entity_get(id)를 사용하세요. null도 허용되며 이때는 호출하지 않습니다.

반환값

없음(void).

사용 조건과 제한

풀은 고정 배열이며 힙을 동적으로 할당하지 않습니다. ENTITY_MAX의 기본값은 16이고 범위는 1~255입니다. 모든 컴파일 단위에서 같은 값으로 정의하세요. ID는 0부터 시작하며 0xFF는 실패를 나타냅니다.

순회가 슬롯에 도달했을 때 활성 상태를 검사합니다. 콜백이 뒤쪽 슬롯을 비활성화하면 건너뛰고, 활성화하면 이번 순회에서 처리할 수 있습니다. 시작 시점의 활성 목록을 고정한 스냅샷이 아닙니다.

콜백을 공통 PRG 뱅크 0에 두거나, 호출이 끝날 때까지 해당 뱅크가 매핑된 상태를 유지하세요. 함수 포인터는 16비트 CPU 주소만 저장하며 뱅크를 선택하지 않습니다. FC의 함수 매개변수와 지역 변수는 고정된 메모리를 사용하므로 엔티티 순회를 재귀적으로 호출하거나 인터럽트에서 같은 순회에 재진입하면 안 됩니다.

사용 예

void demo_update(u8 id) {
    Entity* entity;
    entity = entity_get(id);
    if (entity != 0) { entity->x = entity->x + 1; update_calls++; }
}

// From main(), after creating two entities:
update_calls = 0;
entity_update_all(demo_update);
automatic_updates = update_calls;
if (automatic_updates != 2) { failures++; }

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

전체 프로그램은 재사용되는 풀 슬롯의 수명 주기를 보여 줍니다. 숫자는 라벨과 함께 읽으세요. 두 개를 할당하면 CREATED 002, 첫 번째를 해제하면 AFTER FREE 001, 가장 작은 빈 ID를 재사용하면 REUSED ID 000, 전체를 해제하면 AFTER CLEAR 000입니다. 해제 후 조회가 null인지, 재할당 시 필드가 초기화되는지도 검사합니다. FAILED CHECKS 000은 기대값과 일치했다는 뜻입니다.

FC 순회는 활성 엔티티 두 개에 각각 콜백을 호출하므로 UPDATE CALLS 002, DRAW CALLS 002가 됩니다. 예제의 갱신 콜백은 둘을 오른쪽으로 한 타일 이동합니다. 그리기 콜백은 두 객체를 나타내는 A를 타일 (3,12), B를 (7,12)에 놓습니다. 콜백이 그린 배경 글자 타일이며 자동 할당된 스프라이트가 아닙니다.

사용 예의 전체 프로그램

빌드 명령

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

Call fn(id) for each active slot in ascending order. A null callback does nothing.
Changes to later slots take effect during the same traversal. Do not reenter this traversal.

void entity_update_all(EntityFn fn)
{
    u8 i;
    if (fn == 0) return;
    i = 0;
    while (i < ENTITY_MAX) {
        if (entity_pool[(__safe_index u8)i].active != 0) fn(i);
        i = (u8)(i + 1);
    }
}

피연산자의 정밀도를 줄인 뒤 Q8.8 나눗셈을 수행합니다.

사용 형식

fix8 fix_div(fix8 a, fix8 b);

매개변수

a

Q8.8 형식의 왼쪽 피연산자입니다.

b

Q8.8 형식의 오른쪽 피연산자입니다.

반환값

Q8.8 몫을 반환합니다. b == 0이면 0을 반환합니다.

사용 조건과 제한

계산식은 ((a >> 4) * 256) / (b >> 4)입니다. 0이 아닌 제수는 비트 이동 후에도 0이 아니어야 하므로 양의 원시값 1~15를 전달하면 안 됩니다. 배율을 적용한 분자도 16비트 안에 들어가야 합니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

3.0을 2.0으로 나누면 1.5(원시값 384)가 됩니다. 제수가 정확히 0인 경우의 반환값도 별도로 검사합니다.

사용 예의 전체 프로그램

빌드 명령

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

Scale the reduced-precision quotient back to 8.8 and return zero for b == 0.
Callers must also ensure (b >> 4) is nonzero; the explicit check only tests b.
The intermediate product must fit the compiler's integer arithmetic.

fix8 fix_div(fix8 a, fix8 b)
{
    if (b == 0) return 0;
    return (fix8)(((a >> 4) * 256) / (b >> 4));
}

정수 좌표나 속도를 Q8.8로 변환하여 이후 계산에서 소수부를 유지할 수 있게 합니다.

사용 형식

fix8 fix_from_int(s16 n);

매개변수

n

변환할 정수이며 범위는 −128~127입니다.

반환값

원시값 n × 256을 반환합니다.

사용 조건과 제한

fix8은 부호 있는 Q8.8 형식입니다. 원시값 256이 1.0을 나타냅니다. 중간값과 결과가 16비트 범위를 벗어나지 않게 하세요.

사용 예

result[0]=fix_from_int(-3);

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

이 예제는 −3을 변환합니다. 화면의 −00768은 Q8.8 원시 결과값 −768입니다.

사용 예의 전체 프로그램

빌드 명령

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

Convert an integer to signed 8.8 fixed point by moving it into the high byte.
The caller must keep the result within the representable 16-bit range.

fix8 fix_from_int(s16 n)
{
    return (fix8)(n << 8);
}

8비트 가중치를 사용하여 한 Q8.8 값에서 다른 값 쪽으로 보간합니다.

사용 형식

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

매개변수

a

Q8.8 형식의 왼쪽 피연산자입니다.

b

Q8.8 형식의 오른쪽 피연산자입니다.

t_q8

보간 가중치이며 범위는 0~255입니다.

반환값

근사 보간 결과를 Q8.8로 반환합니다.

사용 조건과 제한

차이값과 가중치를 각각 오른쪽으로 4비트 이동합니다. 가중치는 16단계가 되므로 255를 주어도 끝값에 도달하지 않을 수 있습니다. b - a와 최종 결과를 16비트 범위 안에 두세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

0과 4.0 사이에서 가중치 128을 쓰면 2.0(원시값 512)이 됩니다. 가중치 255에서는 3.75(원시값 960)가 되어 끝값에 도달하지 않음을 보여 줍니다.

사용 예의 전체 프로그램

빌드 명령

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

Interpolate toward b using a quantized Q0.8 weight. Both shifts discard low
bits, so small changes may vanish and a weight of 255 need not reach b.

fix8 fix_lerp(fix8 a, fix8 b, u8 t_q8)
{
    fix8 d;
    // The endpoint difference must fit s16 before the reduced-precision interpolation.
    d = (fix8)(b - a);
    return (fix8)(a + (fix8)((d >> 4) * (s16)(t_q8 >> 4)));
}

연산 비용이 낮은 근사 방식으로 Q8.8 값 두 개를 곱합니다.

사용 형식

fix8 fix_mul(fix8 a, fix8 b);

매개변수

a

Q8.8 형식의 왼쪽 피연산자입니다.

b

Q8.8 형식의 오른쪽 피연산자입니다.

반환값

곱을 Q8.8 형식으로 반환합니다.

사용 조건과 제한

곱셈 전에 각 피연산자를 오른쪽으로 4비트 이동하여 하위 4비트를 버립니다. 따라서 완전한 16×16비트 곱셈보다 정밀도가 낮습니다. fix8은 부호 있는 Q8.8이며 원시값 256이 1.0을 나타냅니다. 중간값과 결과는 16비트 범위 안에 두세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

1.5와 2.0을 곱하면 3.0(원시값 768)이 됩니다. 원시값 271끼리 곱했을 때 256이 나오는 양자화 사례도 검사합니다.

사용 예의 전체 프로그램

빌드 명령

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

Approximate 8.8 multiplication by discarding four low bits from each operand
before multiplying. This trades precision for a smaller intermediate product.

fix8 fix_mul(fix8 a, fix8 b)
{
    return (fix8)((a >> 4) * (b >> 4));
}

Q8.8의 소수 비트를 버려 정수 좌표를 추출합니다. 음수는 음의 무한대 방향으로 내림합니다.

사용 형식

s16 fix_to_int(fix8 x);

매개변수

x

정수로 변환할 Q8.8 값입니다.

반환값

부호 있는 정수를 반환합니다.

사용 조건과 제한

fix8은 부호 있는 Q8.8 형식입니다. 원시값 256이 1.0을 나타냅니다. 중간값과 결과가 16비트 범위를 벗어나지 않게 하세요.

사용 예

result[1]=fix_to_int(-384);

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

원시값 −384(−1.5)를 전달하면 −2가 되어 −00002로 표시됩니다. 경계값 검사에서는 원시값 −1도 −1이 되는지 확인합니다.

사용 예의 전체 프로그램

빌드 명령

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

Discard the eight fractional bits using a signed right shift.

s16 fix_to_int(fix8 x)
{
    return (s16)(x >> 8);
}

부호 있는 16비트 값의 절댓값을 구합니다.

사용 형식

s16 kq_abs_s16(s16 v);

매개변수

v

절댓값을 구할 부호 있는 16비트 값입니다.

반환값

−32768의 절댓값처럼 표현할 수 없는 경우를 제외하고, 0 이상의 절댓값을 반환합니다.

사용 조건과 제한

양의 값 32768은 s16에 들어가지 않습니다. 0 이상의 결과가 필요하다면 입력에서 −32768을 제외하세요.

사용 예

result[0]=kq_abs_s16(-123);

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

예제는 −123을 123으로 바꿉니다. 좌표 차이의 크기를 구할 때와 같은 사용법입니다.

사용 예의 전체 프로그램

빌드 명령

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

Return the magnitude in s16. The most-negative s16 has no positive s16
representation and must be excluded by callers needing a nonnegative result.

s16 kq_abs_s16(s16 v)
{
    if (v < 0) return (s16)(0 - v);
    return v;
}

좌표나 속도를 양 끝값을 포함한 구간 안으로 제한합니다.

사용 형식

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

매개변수

v

제한할 부호 있는 값입니다.

lo

포함되는 하한값입니다.

hi

포함되는 상한값입니다.

반환값

구간보다 작으면 lo, 크면 hi, 구간 안이면 v를 반환합니다.

사용 조건과 제한

lo <= hi를 만족하는 유효한 구간을 지정하세요.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

25를 −10~10으로 제한하면 10이 됩니다. 하한에서 −11→−10, 구간 안에서 3→3인 경우도 검사합니다.

사용 예의 전체 프로그램

빌드 명령

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

Clamp to an inclusive interval; callers must provide lo <= hi.

s16 kq_clamp_s16(s16 v, s16 lo, s16 hi)
{
    if (v < lo) return lo;
    if (v > hi) return hi;
    return v;
}

부호 있는 16비트 값 두 개 중 큰 값을 선택합니다.

사용 형식

s16 kq_max_s16(s16 a, s16 b);

매개변수

a

비교할 첫 번째 부호 있는 값입니다.

b

비교할 두 번째 부호 있는 값입니다.

반환값

선택한 피연산자를 반환합니다.

사용 조건과 제한

부호를 고려하여 비교합니다. 두 피연산자가 같으면 그 값을 반환하며, 입력값은 수정하지 않습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

−7과 4를 비교하면 4가 나옵니다. 음수 결과에는 마이너스 기호가 표시됩니다.

사용 예의 전체 프로그램

빌드 명령

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

Select the larger signed value.

s16 kq_max_s16(s16 a, s16 b)
{
    if (a > b) return a;
    return b;
}

부호 있는 16비트 값 두 개 중 작은 값을 선택합니다.

사용 형식

s16 kq_min_s16(s16 a, s16 b);

매개변수

a

비교할 첫 번째 부호 있는 값입니다.

b

비교할 두 번째 부호 있는 값입니다.

반환값

선택한 피연산자를 반환합니다.

사용 조건과 제한

부호를 고려하여 비교합니다. 두 피연산자가 같으면 그 값을 반환하며, 입력값은 수정하지 않습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

−7과 4를 비교하면 -7이 나옵니다. 음수 결과에는 마이너스 기호가 표시됩니다.

사용 예의 전체 프로그램

빌드 명령

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

Select the smaller signed value.

s16 kq_min_s16(s16 a, s16 b)
{
    if (a < b) return a;
    return b;
}

점이 사각형 안에 있는지 검사하며, 왼쪽과 위쪽 경계는 포함합니다.

사용 형식

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

매개변수

x

사각형과 같은 좌표계에서의 점 X 좌표입니다.

y

점의 Y 좌표입니다.

r

검사할 사각형이며 값으로 전달합니다.

반환값

안에 있으면 1, 밖에 있으면 0을 반환합니다.

사용 조건과 제한

너비와 높이는 양수여야 하며, 좌표와 크기의 합을 s16으로 표현할 수 있어야 합니다. 오른쪽과 아래쪽 경계는 포함하지 않습니다. 면적이 0인 사각형을 명시적으로 거부하지는 않습니다.

사용 예

result[1]=kq_point_in_rect(9,1,a);
for(gy=0;gy<11;gy++){for(gx=0;gx<15;gx++){
inside_a=kq_point_in_rect(gx,gy,a);inside_b=kq_point_in_rect(gx,gy,b);
tile=0;if(inside_a){tile=65;result[3]=result[3]+1;}if(inside_b)tile=66;if(inside_a && inside_b){tile=79;result[4]=result[4]+1;}
m_put(1+gx,2+gy,tile);__vramq_commit();__vramq_exec();
}}

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

좌표 1단위는 타일 하나입니다. (1,1)의 사각형 A와 (5,4)의 사각형 B는 모두 8×6 크기입니다. A만 차지하는 칸은 A, B만 차지하는 칸은 B로 표시하고, 4×3 겹침 영역의 12칸은 O로 표시합니다. A의 오른쪽 가장자리 x=9는 포함하지 않습니다. CGB에서는 A가 빨간색, B가 파란색, O가 초록색입니다.

사용 예의 전체 프로그램

빌드 명령

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

Test a half-open rectangle: left/top edges are included, right/bottom excluded.
The coordinate-plus-size sums must remain representable as s16.

u8 kq_point_in_rect(s16 x, s16 y, KQRect r)
{
    if (x < r.x) return 0;
    if (y < r.y) return 0;
    if (x >= (s16)(r.x + r.w)) return 0;
    if (y >= (s16)(r.y + r.h)) return 0;
    return 1;
}

축에 정렬된 두 사각형이 면적을 가지며 겹치는지 검사합니다.

사용 형식

u8 kq_rect_intersect(KQRect a, KQRect b);

매개변수

a

값으로 전달하는 첫 번째 사각형입니다. x, y는 왼쪽 위 모서리, w, h는 너비와 높이입니다.

b

A와 같은 좌표계를 사용하는 두 번째 사각형입니다.

반환값

겹치면 1, 떨어져 있거나 가장자리만 닿으면 0을 반환합니다.

사용 조건과 제한

너비와 높이는 양수여야 하며, 좌표와 크기의 합을 s16으로 표현할 수 있어야 합니다. 오른쪽과 아래쪽 경계는 포함하지 않습니다. 면적이 0인 사각형을 명시적으로 거부하지는 않습니다.

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

좌표 1단위는 타일 하나입니다. (1,1)의 사각형 A와 (5,4)의 사각형 B는 모두 8×6 크기입니다. A만 차지하는 칸은 A, B만 차지하는 칸은 B로 표시하고, 4×3 겹침 영역의 12칸은 O로 표시합니다. A의 오른쪽 가장자리 x=9는 포함하지 않습니다. CGB에서는 A가 빨간색, B가 파란색, O가 초록색입니다.

사용 예의 전체 프로그램

빌드 명령

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

Test overlap using exclusive right/bottom edges; touching edges do not collide.
Require positive dimensions and edge sums that fit s16; zero-sized rectangles
are not explicitly rejected and may be reported as overlapping.

u8 kq_rect_intersect(KQRect a, KQRect b)
{
    if ((s16)(a.x + a.w) <= b.x) return 0;
    if ((s16)(b.x + b.w) <= a.x) return 0;
    if ((s16)(a.y + a.h) <= b.y) return 0;
    if ((s16)(b.y + b.h) <= a.y) return 0;
    return 1;
}

btn_down은 input_down의 별칭입니다. 선택한 버튼 중 하나라도 현재 눌려 있는지 확인합니다.

mask에 지정한 버튼 중 현재 누르고 있는 버튼이 있는지 반환합니다.

사용 형식

u8 btn_down(u8 mask);

매개변수

mask

BTN_* 하나 또는 여러 값을 |로 결합한 마스크입니다. 선택한 버튼 중 하나라도 해당하면 참이므로 BTN_A | BTN_B가 두 버튼의 동시 누름을 요구하지는 않습니다. 마스크 0은 항상 0을 반환합니다. 모두 눌렸는지는 (input_current() & mask) == mask로 확인하세요.

반환값

선택한 버튼 중 하나라도 조회 조건에 맞으면 정확히 1, 아니면 0입니다. 반환값은 버튼 비트 마스크가 아닙니다。

사용 조건과 제한

헤더는 구현 이름으로 확장되는 객체형 매크로를 정의합니다. 인수, 반환값, 상태 접근은 대상 함수와 같으며 별칭 때문에 별도의 상태나 처리가 추가되지는 않습니다. 완전한 예제와 빌드 명령처럼 입력에는 input.h/input.c를, 프레임 서비스에는 system.h/system.c를 사용하세요.

공통 마스크는 BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80입니다. 1인 비트가 눌림을 뜻합니다. GB와 FC의 input_*는 이 형식을 쓰지만 FC의 원시 패드 함수는 비트 순서가 다릅니다.

조회 함수는 마지막 input_update()가 저장한 값을 읽습니다. 다시 폴링하거나 에지를 소비하거나 반복 타이머를 진행하지 않습니다. 같은 틱에서 여러 번 조회해도 결과는 같습니다. 버튼을 누른 채 input_update()를 두 번 호출하면 두 번째 호출에서는 새 누름 에지가 사라집니다.

input_down

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

버튼을 누르고 있는 상태, 처음 누른 순간, 뗀 순간, 자동 반복의 차이를 보여 주는 프로그램입니다. A를 40회 갱신 동안 누른 뒤 놓습니다. FIRST DOWN, FIRST PRESS, FIRST REPEAT는 1이고 FIRST CURRENT는 16입니다. HELD TICKS는 40, PRESS COUNT는 1, REPEAT COUNT는 5입니다. 버튼을 놓으면 RELEASE는 1, LAST CURRENT는 0, LAST PREVIOUS는 16이 됩니다. FAILED CHECKS는 0이어야 합니다. 누르는 시간을 바꾸면 횟수도 달라지며, 프로그램은 실제로 관측한 시간을 기준으로 반복 간격을 검사합니다.

사용 예의 전체 프로그램

빌드 명령

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

#define btn_down input_down

u8 input_down(u8 mask) { return (u8)((kq_input_keys & mask) != 0); }

btn_pressed는 input_pressed의 별칭입니다. 최근 입력 갱신에서 선택한 버튼 중 하나라도 새로 눌렸는지 확인합니다.

최근 입력 갱신에서 마스크에 해당하는 버튼이 눌리지 않은 상태에서 눌린 상태로 바뀌었는지 반환합니다.

사용 형식

u8 btn_pressed(u8 mask);

매개변수

mask

BTN_* 하나 또는 여러 값을 |로 결합한 마스크입니다. 선택한 버튼 중 하나라도 해당하면 참이므로 BTN_A | BTN_B가 두 버튼의 동시 누름을 요구하지는 않습니다. 마스크 0은 항상 0을 반환합니다. 모두 눌렸는지는 (input_current() & mask) == mask로 확인하세요.

반환값

선택한 버튼 중 하나라도 조회 조건에 맞으면 정확히 1, 아니면 0입니다. 반환값은 버튼 비트 마스크가 아닙니다。

사용 조건과 제한

헤더는 구현 이름으로 확장되는 객체형 매크로를 정의합니다. 인수, 반환값, 상태 접근은 대상 함수와 같으며 별칭 때문에 별도의 상태나 처리가 추가되지는 않습니다. 완전한 예제와 빌드 명령처럼 입력에는 input.h/input.c를, 프레임 서비스에는 system.h/system.c를 사용하세요.

공통 마스크는 BTN_RIGHT=0x01, BTN_LEFT=0x02, BTN_UP=0x04, BTN_DOWN=0x08, BTN_A=0x10, BTN_B=0x20, BTN_SELECT=0x40, BTN_START=0x80입니다. 1인 비트가 눌림을 뜻합니다. GB와 FC의 input_*는 이 형식을 쓰지만 FC의 원시 패드 함수는 비트 순서가 다릅니다.

조회 함수는 마지막 input_update()가 저장한 값을 읽습니다. 다시 폴링하거나 에지를 소비하거나 반복 타이머를 진행하지 않습니다. 같은 틱에서 여러 번 조회해도 결과는 같습니다. 버튼을 누른 채 input_update()를 두 번 호출하면 두 번째 호출에서는 새 누름 에지가 사라집니다.

input_pressed

사용 예

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

호출 부분을 보여 주는 코드입니다. 완전한 프로그램에 넣을 때는 명시된 초기화 및 버퍼 조건을 충족해야 합니다.

예상 결과

버튼을 누르고 있는 상태, 처음 누른 순간, 뗀 순간, 자동 반복의 차이를 보여 주는 프로그램입니다. A를 40회 갱신 동안 누른 뒤 놓습니다. FIRST DOWN, FIRST PRESS, FIRST REPEAT는 1이고 FIRST CURRENT는 16입니다. HELD TICKS는 40, PRESS COUNT는 1, REPEAT COUNT는 5입니다. 버튼을 놓으면 RELEASE는 1, LAST CURRENT는 0, LAST PREVIOUS는 16이 됩니다. FAILED CHECKS는 0이어야 합니다. 누르는 시간을 바꾸면 횟수도 달라지며, 프로그램은 실제로 관측한 시간을 기준으로 반복 간격을 검사합니다.

사용 예의 전체 프로그램

빌드 명령

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