docs to english
This commit is contained in:
@@ -1,4 +1,4 @@
|
||||
# IDE (clangd) segédkonfig: az Oscar64 vendorolt headerjeit így találja
|
||||
# meg a nyelvi szerver; a tényleges fordítást az oscar64 végzi (Makefile).
|
||||
# IDE (clangd) helper config: lets the language server find the vendored
|
||||
# Oscar64 headers; the actual compilation is done by oscar64 (see Makefile).
|
||||
CompileFlags:
|
||||
Add: [-Ioscar64/include, -I../oscar64/include, -Wno-unknown-pragmas]
|
||||
|
||||
+4
-4
@@ -1,11 +1,11 @@
|
||||
# a demo fordítási kimenete (demo.prg + generált .asm/.map/.lbl/.int)
|
||||
# demo build output (demo.prg + generated .asm/.map/.lbl/.int)
|
||||
build/
|
||||
|
||||
# a vendorolt Oscar64 lokálisan épített binárisa és köztes objektumai
|
||||
# (a Makefile első futáskor újraépíti: make -C oscar64/make compiler)
|
||||
# locally built binary and intermediate objects of the vendored Oscar64
|
||||
# (the Makefile rebuilds it on first run: make -C oscar64/make compiler)
|
||||
oscar64/bin/
|
||||
oscar64/build/
|
||||
|
||||
# szerkesztő / OS szemét
|
||||
# editor / OS junk
|
||||
.DS_Store
|
||||
*.swp
|
||||
|
||||
@@ -11,11 +11,11 @@ all: build
|
||||
|
||||
deps:
|
||||
ifeq ($(UNAME_S),Darwin)
|
||||
@command -v brew >/dev/null 2>&1 || { echo "Homebrew kell ehhez. Telepitsd: https://brew.sh"; exit 1; }
|
||||
@command -v brew >/dev/null 2>&1 || { echo "Homebrew is required. Install it: https://brew.sh"; exit 1; }
|
||||
brew install vice
|
||||
else
|
||||
@echo "A 'deps' target csak macOS-en (Darwin) automatikus. Detektalt OS: $(UNAME_S)"
|
||||
@echo "Telepitsd kezzel a VICE emulatort (x64sc). Az Oscar64 vendorolt, magatol epul."
|
||||
@echo "The 'deps' target is only automated on macOS (Darwin). Detected OS: $(UNAME_S)"
|
||||
@echo "Install the VICE emulator (x64sc) manually. Oscar64 is vendored and builds itself."
|
||||
@exit 1
|
||||
endif
|
||||
|
||||
|
||||
@@ -1,138 +1,143 @@
|
||||
# C64 Demo — Teletype Games slide show (Oscar64)
|
||||
|
||||
A Commodore 64 slide show, C-ben, az [Oscar64](https://github.com/drmortalwombat/oscar64)
|
||||
fordítóval. Az eredetileg 6502 assemblyben (ACME) írt [c64-demo](../c64-demo)
|
||||
portja: öt slide váltakozik automatikusan, slide-onkénti átmenetekkel feketén
|
||||
keresztül, és a show billentyűzetről is vezérelhető.
|
||||
A Commodore 64 slide show written in C, built with the
|
||||
[Oscar64](https://github.com/drmortalwombat/oscar64) compiler. A port of the
|
||||
[c64-demo](../c64-demo) originally written in 6502 assembly (ACME): five slides
|
||||
rotate automatically with per-slide transitions through black, and the show can
|
||||
also be driven from the keyboard.
|
||||
|
||||
## A slide-ok
|
||||
## The slides
|
||||
|
||||
1. **TTG logó + credits scroller** — óriás TTG betűk 8×8-as bitmapekből, arany
|
||||
színfutással, pulzáló **TELETYPE GAMES** felirat, sima pixel-scroller a
|
||||
stáblistával.
|
||||
2. **Az első játékunk** — *DEFINITELY NOT AN IMPOSTOR* nagy 3×5-ös
|
||||
blokkbetűkkel, arany wash-sal, „introduced on TIC-80".
|
||||
3. **A második játékunk** — *IS COMING* nagybetűkkel, vetett árnyékkal;
|
||||
a raszterbárok csak a kereten futnak, így a szöveg olvasható marad.
|
||||
4. **Kapcsolat** — pulzáló *CONTACT* cím, web / BBS / IRC sorok, 12 cellás
|
||||
háromrétegű parallax csillagmező és hat hardveres sprite (négyágú csillagok)
|
||||
szinusz-pályán a szöveg mögött.
|
||||
5. **Az assembly vallomás** — sorkizárt szöveg arról, hogy ez a slide show egy
|
||||
kis AI-segítséggel készült; a törzs élőben gépelődik be (karakterenként egy
|
||||
frame, fehér blokk-kurzorral), a záró sor a gépelés végén jelenik meg és pulzál.
|
||||
1. **TTG logo + credits scroller** — giant TTG letters built from 8×8 bitmaps
|
||||
with a gold color wash running across them, a pulsing **TELETYPE GAMES**
|
||||
title, and a smooth pixel scroller with the crew credits.
|
||||
2. **Our first game** — *DEFINITELY NOT AN IMPOSTOR* in big 3×5 block letters
|
||||
with the gold wash, "introduced on TIC-80".
|
||||
3. **Our second game** — *IS COMING* in big letters with a drop shadow; raster
|
||||
bars run on the border only, so the text stays readable.
|
||||
4. **Contact** — pulsing big *CONTACT* title, web / BBS / IRC lines, a 12-cell
|
||||
three-layer parallax starfield, and six hardware sprites (four-pointed
|
||||
stars) floating on sine-wave paths behind the text.
|
||||
5. **The assembly confession** — a justified-text piece about how this slide
|
||||
show was written with a little help from an AI; the body types in live (one
|
||||
character per frame with a white block cursor), and a closing line appears
|
||||
and pulses when the typing is done.
|
||||
|
||||
Minden slide 8 másodpercig látszik (`SLIDE_TIME` a `src/defs.h`-ban, PAL
|
||||
frame-ekben); az 5-ös slide 9 másodpercet kap (`S5_TIME`), hogy az írógép végezzen.
|
||||
Each slide is shown for 8 seconds (`SLIDE_TIME` in `src/defs.h`, PAL frames);
|
||||
slide 5 gets 9 seconds (`S5_TIME`) to let the typewriter finish.
|
||||
|
||||
## Vezérlés
|
||||
## Controls
|
||||
|
||||
| Billentyű | Funkció |
|
||||
|-----------|---------|
|
||||
| `SPACE` | következő slide azonnal |
|
||||
| `INST/DEL` (backspace) | előző slide |
|
||||
| `P` | pause — a visszaszámlálás megáll, fehér `P` jelző a jobb felső sarokban; az effektek futnak tovább, SPACE/DEL működik |
|
||||
| `M` | némítás — a SID zene ki/be |
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| `SPACE` | next slide immediately |
|
||||
| `INST/DEL` (backspace) | previous slide |
|
||||
| `P` | pause toggle — the countdown freezes and a white `P` marker appears in the top-right corner; effects keep running, and SPACE/DEL still work while paused |
|
||||
| `M` | mute/unmute — toggles the SID music on or off |
|
||||
|
||||
A billentyűket közvetlenül a CIA1 mátrixból olvassuk (a KERNAL IRQ le van tiltva).
|
||||
Keys are read directly from the CIA1 keyboard matrix (the KERNAL IRQ is
|
||||
disabled).
|
||||
|
||||
## Fordítás és futtatás
|
||||
## Build and run
|
||||
|
||||
```sh
|
||||
make build # fordítás -> build/demo.prg (első futáskor a fordítót is megépíti)
|
||||
make run # futtatás VICE emulátorban (x64sc kell hozzá)
|
||||
make rebuildrun # tiszta újrafordítás + futtatás
|
||||
make clean # build mappa törlése
|
||||
make deps # macOS-en: VICE telepítése Homebrew-val
|
||||
make build # compile -> build/demo.prg (builds the compiler too on first run)
|
||||
make run # build + launch in VICE (requires x64sc)
|
||||
make rebuildrun # clean rebuild + run
|
||||
make clean # remove the build directory
|
||||
make deps # on macOS: install VICE via Homebrew
|
||||
```
|
||||
|
||||
Ugyanezek a `.vscode/tasks.json`-ból VS Code taskként is futtathatók
|
||||
(a `build` az alapértelmezett build task).
|
||||
The same targets are available as VS Code tasks from `.vscode/tasks.json`
|
||||
(`build` is the default build task).
|
||||
|
||||
Betöltés igazi vagy emulált C64-en:
|
||||
Loading the `.prg` on a real or emulated C64:
|
||||
|
||||
```
|
||||
LOAD"*",8,1
|
||||
RUN
|
||||
```
|
||||
|
||||
## Forrás-elrendezés
|
||||
## Source layout
|
||||
|
||||
| Fájl | Tartalom |
|
||||
| File | Contents |
|
||||
|------|----------|
|
||||
| `src/main.c` | főciklus, slide-szekvenszer, billentyűolvasás (SPACE / DEL / P / M), slide-táblák |
|
||||
| `src/defs.h` | hardvermutatók, színek, elrendezés/időzítés konstansok, screen code charmap |
|
||||
| `src/transitions.c` | átmenet-motor: show/hide, három átmenettípus (fade, dissolve, wipe), `wait_frame` raszter-szinkron, színsnapshot |
|
||||
| `src/common.c` | közös rutinok (`clear_screen`, `print_text`, `draw_big`), közös táblák (sor×40, 3×5 blokkfont, wash/pulse/fade rámpák) |
|
||||
| `src/music.c` | SID zenemotor: háromszólamú pattern-lejátszó (basszus, dob, echo lead) az *Impostor* dallam adataival |
|
||||
| `src/slide1.c` … `slide5.c` | slide-onként egy fájl: `sN_init` (képernyőrajzolás), `sN_update` (frame-enként egyszer fut) + slide-lokális adatok |
|
||||
| `src/main.c` | main loop, slide sequencer, keyboard scanning (SPACE / DEL / P / M), slide tables |
|
||||
| `src/defs.h` | hardware pointers, colors, layout/timing constants, the screen-code charmap |
|
||||
| `src/transitions.c` | slide transition engine: show/hide, three transition types (fade, dissolve, wipe), `wait_frame` raster sync, color snapshot |
|
||||
| `src/common.c` | shared routines (`clear_screen`, `print_text`, `draw_big`), shared tables (row×40 lookup, 3×5 block font, wash/pulse/fade color ramps) |
|
||||
| `src/music.c` | SID music driver: three-voice pattern player (bass, drums, echo lead) with the note/pattern tables of the *Impostor* tune |
|
||||
| `src/slide1.c` … `slide5.c` | one file per slide: `sN_init` (draws the screen), `sN_update` (runs once per frame), plus slide-local data |
|
||||
|
||||
A fordítási egységeket az Oscar64 `#pragma compile("file.c")` mechanizmusa fűzi
|
||||
össze: minden header behúzza a hozzá tartozó `.c`-t, ezért a `make`-nek elég a
|
||||
`src/main.c`-t átadni.
|
||||
The translation units are tied together by Oscar64's
|
||||
`#pragma compile("file.c")` mechanism: every header pulls in its matching
|
||||
`.c` file, so `make` only needs to pass `src/main.c` to the compiler.
|
||||
|
||||
## Hogyan működik
|
||||
## How it works
|
||||
|
||||
### Slide-keretrendszer
|
||||
### Slide framework
|
||||
|
||||
Minden slide egy **init** rutinból (megrajzolja a teljes képernyőt), egy
|
||||
**update** rutinból (frame-enként egyszer hívódik, pontosan egy frame-et fut)
|
||||
és egy frame-ben mért időtartamból áll. A `main.c` főciklusa hívja az aktuális
|
||||
update-et, számolja vissza a frame-eket, és lejáratkor — vagy SPACE/DEL-re
|
||||
azonnal — a következő slide-ra lép.
|
||||
Every slide consists of an **init** routine (draws the whole screen), an
|
||||
**update** routine (called once per frame, runs exactly one frame) and a
|
||||
duration in frames. The main loop in `main.c` calls the current update, counts
|
||||
the frames down, and steps to the next slide when time runs out — or
|
||||
immediately on SPACE/DEL.
|
||||
|
||||
### Időzítés
|
||||
### Timing
|
||||
|
||||
Nincs megszakítás: a kód a raszterregisztert (`$D012`, `vic.raster`) pollozza,
|
||||
és minden képernyőfrissítést az alsó keretben végez (`RAS_BOTTOM`). Az 1-es
|
||||
slide ezen felül képközépen megbontja a frame-et, hogy csak a scroller sorára
|
||||
kapcsolja be a vízszintes finomscrollt (`vic.ctrl2`); a 3-as slide a sugarat
|
||||
üldözve 4 soronként átszínezi a keretet a raszterbárokhoz.
|
||||
There are no interrupts: the code polls the raster register (`$D012`,
|
||||
`vic.raster`) and does all screen updates while the beam is in the lower border
|
||||
(`RAS_BOTTOM`). Slide 1 additionally splits the frame mid-screen to enable
|
||||
horizontal fine scrolling (`vic.ctrl2`) for the scroller row only; slide 3
|
||||
chases the beam down the frame, recoloring the border every 4 lines to draw
|
||||
the raster bars.
|
||||
|
||||
### Átmenetek
|
||||
### Transitions
|
||||
|
||||
Minden slide-nak saját be- és kilépő átmenete van (`tin_tbl` / `tout_tbl` a
|
||||
`main.c`-ben), három típusból:
|
||||
Each slide has its own in-transition and out-transition, chosen from three
|
||||
types via `tin_tbl` / `tout_tbl` in `main.c`:
|
||||
|
||||
- **Fade** — minden color RAM cellát a `fadetbl` rámpán léptet (minden szín →
|
||||
egy árnyalattal sötétebb; minden lánc legfeljebb 4 lépésben fekete). Az új
|
||||
slide kikapcsolt képernyővel rajzolódik, színei a `$C000`-es bufferbe
|
||||
mentődnek és feketére váltanak, majd a fade-in cellánként visszasétál a
|
||||
mentett színre.
|
||||
- **Dissolve** — egy 10 bites Galois LFSR (periódus 1023) minden cellát pontosan
|
||||
egyszer, álvéletlen sorrendben jár be. 25 cella/frame = 40 frame (~0,8 s).
|
||||
- **Wipe** — oszloponkénti söprés balról jobbra, oszloponként egy frame.
|
||||
- **Fade** — steps every color RAM cell through `fadetbl` (each color → one
|
||||
shade darker; every chain hits black within 4 steps). The new slide is drawn
|
||||
with the display off, its colors are snapshotted to the buffer at `$C000`
|
||||
and blanked, then the fade-in walks each cell back up to its snapshot color.
|
||||
- **Dissolve** — a 10-bit Galois LFSR (period 1023) visits every screen cell
|
||||
exactly once in pseudo-random order. 25 cells per frame = 40-frame (~0.8 s)
|
||||
full reveal.
|
||||
- **Wipe** — column-by-column sweep from left to right, one column per frame.
|
||||
|
||||
Minden átmenet rövid fehér-szürke keretvillanással indul.
|
||||
All transitions start with a short white-to-grey border flash.
|
||||
|
||||
### Zene
|
||||
### Music
|
||||
|
||||
A `src/music.c` háromszólamú SID pattern-lejátszó; a dallam az *Impostor*
|
||||
TIC-80 cart 0-s trackje („room work"), kézzel konvertálva 128 soros
|
||||
pattern-ráccsá (basszus: 50% pulzus, dob: zaj, echo-kánon: háromszög pluck
|
||||
3 oktávval feljebb, 2 sorral késleltetve). Egy sor egy bájt szólamonként:
|
||||
`$00` = semmi, `$01` = key off, `$80|n` = n. hang. A `music_play` frame-enként
|
||||
egyszer tickel: a főciklusból és a `wait_frame`-ből is, így az átmenetek alatt
|
||||
sem áll meg.
|
||||
`src/music.c` is a three-voice SID pattern player; the tune is track 0
|
||||
("room work") of the *Impostor* TIC-80 cart, converted by hand into a 128-row
|
||||
pattern grid (bass: 50% pulse, drums: noise, echo canon: decaying triangle
|
||||
pluck 3 octaves up, delayed by 2 rows). Rows are one byte per voice:
|
||||
`$00` = nothing, `$01` = key off, `$80|n` = play note *n*. `music_play` is
|
||||
ticked once per frame: from the main loop and from `wait_frame`, so the music
|
||||
keeps playing through transitions.
|
||||
|
||||
## Memóriatérkép
|
||||
## Memory map
|
||||
|
||||
```
|
||||
$0801 .. ... BASIC stub + gépi kód (Oscar64 alapértelmezés)
|
||||
$0340 .. $037E sprite-alakzat (kazettabuffer, 64-re igazított)
|
||||
$0400 .. $07E7 képernyő RAM (közvetlen írás)
|
||||
$C000 .. $C3E7 color RAM snapshot buffer az átmenetekhez
|
||||
$D000 .. $D02E VIC-II regiszterek (kép, sprite-ok, raszter)
|
||||
$D400 .. $D418 SID regiszterek (zene)
|
||||
$0801 .. ... BASIC stub + machine code (Oscar64 defaults)
|
||||
$0340 .. $037E sprite shape (cassette buffer, 64-aligned)
|
||||
$0400 .. $07E7 screen RAM (written directly)
|
||||
$C000 .. $C3E7 color RAM snapshot buffer for transitions
|
||||
$D000 .. $D02E VIC-II registers (display, sprites, raster)
|
||||
$D400 .. $D418 SID registers (music)
|
||||
$D800 .. color RAM
|
||||
$DC00 / $DC01 CIA1 billentyűmátrix
|
||||
$DC00 / $DC01 CIA1 keyboard matrix
|
||||
```
|
||||
|
||||
## Az eredetihez képest
|
||||
## Differences from the original
|
||||
|
||||
- A szövegek a `#pragma charmap(97, 1, 26)` révén fordítási időben
|
||||
screen code-dá alakulnak, így a C string literálok közvetlenül a képernyőre
|
||||
írhatók.
|
||||
- Az önmódosító vektorok és zeropage-mutatók helyett függvénypointerek és
|
||||
normál C tömbindexelés; a viselkedés (időzítés, effektek, zene) megegyezik.
|
||||
- A fordítás `-n -O2`-vel történik (teljes natív 6502 kód), hogy a
|
||||
raszter-pollozó részek elég gyorsak legyenek.
|
||||
- Texts are converted to screen codes at compile time via
|
||||
`#pragma charmap(97, 1, 26)`, so plain C string literals can be written
|
||||
straight to the screen.
|
||||
- Self-modifying vectors and zero-page pointers are replaced by function
|
||||
pointers and ordinary C array indexing; the behavior (timing, effects,
|
||||
music) is unchanged.
|
||||
- Compiled with `-n -O2` (fully native 6502 code) so the raster-polling parts
|
||||
are fast enough to fit in the frame.
|
||||
|
||||
Reference in New Issue
Block a user