SAP (format pliku)

From Atariki

(Różnice między wersjami)
Jump to: navigation, search
Wersja z dnia 07:28, 22 kwi 2006
Miker (Dyskusja | wkład)
(Część pierwsza - informacja tekstowa - parę popraweczek)
← Previous diff
Aktualna wersja
Mono (Dyskusja | wkład)
(link do aktualnej specyfikacji)
Linia 1: Linia 1:
 +===Wstęp===
 +
Plik '''SAP''' składa się z dwóch części. Pierwsza (tekst) opisuje typ playera/muzyki oraz zawiera informacje o autorze (lub autorach). Druga - zawiera samą procedurę odtwarzającą oraz dane muzyki - w zwykłym (znanym z Atari) pliku binarnym. Plik '''SAP''' składa się z dwóch części. Pierwsza (tekst) opisuje typ playera/muzyki oraz zawiera informacje o autorze (lub autorach). Druga - zawiera samą procedurę odtwarzającą oraz dane muzyki - w zwykłym (znanym z Atari) pliku binarnym.
- +===Część pierwsza - informacja tekstowa===
- +
-==Część pierwsza - informacja tekstowa==+
Dla identyfikacji formatu plik zawsze rozpoczyna się ciągiem "SAP", po czym następują Dla identyfikacji formatu plik zawsze rozpoczyna się ciągiem "SAP", po czym następują
informacje o osobie, lub osobach, odpowiedzialnych za dany utwór. Wprawdzie nie ma z góry informacje o osobie, lub osobach, odpowiedzialnych za dany utwór. Wprawdzie nie ma z góry
ustalonej ich kolejności, jednak zwyczajowo utarło się podawać je tak jak poniżej. Każda linia powinna kończyć się kodami 0D i 0A (EOL). ustalonej ich kolejności, jednak zwyczajowo utarło się podawać je tak jak poniżej. Każda linia powinna kończyć się kodami 0D i 0A (EOL).
- 
Wyświetlane informacje: Wyświetlane informacje:
*AUTHOR "" - Imię i nazwisko kompozytora. Dla potrzeb [[ASMA]] powinno się podać prawdziwe personalia oraz nick (ksywę scenową) w nawiasach. Nie podaje się grupy. Jeżeli utwór został skomponowany przez więcej niż innego autora, stosuje się znak "&". *AUTHOR "" - Imię i nazwisko kompozytora. Dla potrzeb [[ASMA]] powinno się podać prawdziwe personalia oraz nick (ksywę scenową) w nawiasach. Nie podaje się grupy. Jeżeli utwór został skomponowany przez więcej niż innego autora, stosuje się znak "&".
- 
Przykłady: Przykłady:
Linia 19: Linia 17:
AUTHOR "Lukasz Sychowicz (X-Ray) & Piotr Swierszcz (Samurai)" AUTHOR "Lukasz Sychowicz (X-Ray) & Piotr Swierszcz (Samurai)"
-*NAME "" - Tytuł utworu. W zasadzie bez ograniczeń, nie używa się tylko cudzysłowów. Zamiast tego stosuje się apostrofy.+*NAME "" - Tytuł utworu. W zasadzie bez ograniczeń, stosować można wszystkie znaki prócz cudzysłowów. Zamiast nich można użyć apostrofów.
Przykład: Przykład:
NAME "Jocky Wilson's Darts Challenge" NAME "Jocky Wilson's Darts Challenge"
-*DATE "" - Rok "copyrightu" lub rok powstania. Jeżeli dokładna data jest znana, może być zawarta w formacie DD/MM/RRRR+*DATE "" - Rok "copyrightu" lub rok powstania. Jeżeli dokładna data jest znana, może być przedstawiona w formacie DD/MM/RRRR
Przykłady: Przykłady:
Linia 32: Linia 30:
DATE "12/2001" DATE "12/2001"
- +W dalszej kolejności następują informacje dla playera:
-Potem następują informacje dla playera:+
*TYPE - typ playera (patrz niżej) *TYPE - typ playera (patrz niżej)
*PLAYER - adres playera, który będzie wywoływany w odstępach 1/50-sekundowych (lub takich jak zdefiniowano przez FASTPLAY) *PLAYER - adres playera, który będzie wywoływany w odstępach 1/50-sekundowych (lub takich jak zdefiniowano przez FASTPLAY)
Linia 40: Linia 37:
*SONGS - ilość utworów. Jeśli pominiemy ten parametr, domyślną wartością jest 1 *SONGS - ilość utworów. Jeśli pominiemy ten parametr, domyślną wartością jest 1
*DEFSONG - pierwszy utwór, który będzie odgrywany bezpośrednio po wgraniu .sap-a (np. główny temat z gry). Wartość ta jest liczona od zera (jeżeli w pliku jest 5 utworów a ostatni jest domyślny, bedzie wpisane DEFSONG 4). Wartością domyślną jest 0, jeśli "DEFSONG" został pominięty *DEFSONG - pierwszy utwór, który będzie odgrywany bezpośrednio po wgraniu .sap-a (np. główny temat z gry). Wartość ta jest liczona od zera (jeżeli w pliku jest 5 utworów a ostatni jest domyślny, bedzie wpisane DEFSONG 4). Wartością domyślną jest 0, jeśli "DEFSONG" został pominięty
-*FASTPLAY - ilość linii, co którą jest wywoływana procedura odgrywająca (312 domyślnie, czyli jeden ekran - 1/50 sekundy). Na przykład dla podwójnej szybkości utworu ("2 razy na ramkę") wpisz tutaj wartość 156 (312/2). 99% utworów gra z pojedynczą szybkością ("raz na ramkę"), także nie jest konieczne ustawianie tego parametru. Inne wartości polecane: 104 ("3 razy na ramkę"), 78 ("4 razy na ramkę")+*FASTPLAY - ilość linii, co którą jest wywoływana procedura odgrywająca (312 domyślnie, czyli jeden ekran - 1/50 sekundy). Na przykład dla podwójnej szybkości utworu ("2 razy na ramkę") wpisz tutaj wartość 156 (312/2). Większość utworów gra z pojedynczą szybkością ("raz na ramkę"), nie jest więc konieczne ustawianie tego parametru. Inne często spotykane wartości: 104 ("3 razy na ramkę"), 78 ("4 razy na ramkę")
*STEREO - utwór używa drugiego [[POKEY]]a (stereo lub/i 8 kanałów) *STEREO - utwór używa drugiego [[POKEY]]a (stereo lub/i 8 kanałów)
- 
Komendy PLAYER, MUSIC, INIT zawierają adresy w formacie hexadecymalnym. Przyjmowane są zarówno wielkie, jak i małe litery. Komendy PLAYER, MUSIC, INIT zawierają adresy w formacie hexadecymalnym. Przyjmowane są zarówno wielkie, jak i małe litery.
Linia 49: Linia 45:
MUSIC 1234 MUSIC 1234
INIT f42e INIT f42e
- 
Komendy SONGS, DEFSONG zawierają liczby w formacie dziesiętnym: Komendy SONGS, DEFSONG zawierają liczby w formacie dziesiętnym:
Linia 55: Linia 50:
SONGS 10 SONGS 10
DEFSONG 9 DEFSONG 9
- 
Komenda TYPE zawiera pojedynczy znak, który określa typ playera. Obsługiwane są następujące typy: Komenda TYPE zawiera pojedynczy znak, który określa typ playera. Obsługiwane są następujące typy:
- +*TYPE C - player do modułów w formacie[[CMC (format pliku)|CMC]] ([[Chaos Music Composer]]). W tym przypadku muszą pojawić się także komendy: PLAYER, MUSIC. Można również zdefiniować SONGS i DEFSONG.
-*TYPE C - player z [[CMC]] (Chaos Music Composer). W tym przypadku muszą pojawić się także komendy: PLAYER, MUSIC. Można również zdefiniować SONGS i DEFSONG.+
Player zostanie zainicjowany następująco: Player zostanie zainicjowany następująco:
Linia 75: Linia 68:
jsr PLAYER+6 jsr PLAYER+6
- 
W tym przypadku nie ma potrzeby dodawania playera z CMC, ponieważ jest on zawarty w pliku SAP. W tym przypadku nie ma potrzeby dodawania playera z CMC, ponieważ jest on zawarty w pliku SAP.
- 
- 
*TYPE B - dowolny player. W tym przypadku także powinny pojawić się komendy PLAYER, INIT. Dodatkowo mozna zdefiniować SONGS i DEFSONG. *TYPE B - dowolny player. W tym przypadku także powinny pojawić się komendy PLAYER, INIT. Dodatkowo mozna zdefiniować SONGS i DEFSONG.
Linia 92: Linia 82:
jsr PLAYER jsr PLAYER
 +*TYPE S - [[Softsynth|SoftSynth]]. W założeniach tymczasowy rodzaj playera (podobnie zresztą jak typ "C"). Może on być użyty tylko w przypadku specjalnego typu utworów, które zostały skomponowane za pomocą programu SoftSynth.
- +*TYPE D - Digital (sample). W tym typie pliku SAP powinny być zdefiniowane komendy INIT i PLAYER. PLAYER (zupełnie jak w typie "B") ustawia adres procedury, która będzie wywoływana co 1/50 sekundy i (także jak w typie "B") będzie kończyć się rozkazem RTS. INIT tym razem działa nieco inaczej. Ustawia on adres procedury, która będzie wywoływana (z numerem utworu w rejestrze A) do zainicjowania programu, ale nie może się kończyć RTS-em. Procedura ta powinna odgrywać sample w nieskończonej pętli. W playerze SAP emulowane są dwa rejestry [[ANTIC (układ)|ANTIC-a]] ($D40A i $D40B). Pomagają one odgrywać sample. Rejestr $D40B zwiększa swoją zawartość co 2 linie obrazu, natomiast $D40A wstrzymuje [[procesor]] do końca aktualnie rysowanej linii. SAP emuluje Atari w systemie PAL z wyłączonym ekranem. Znaczy to, że mamy do dyspozycji 312 linii/ekran, gdzie każda zabiera 105 cykli procesora i 9 cykli na odświeżenie pamięci (co daje 114 cykli na linię).
-*TYPE S - [[Softsynth|SoftSynth]]. Podobny do typu "C". Jest to typ tymczasowy i może być użyty tylko w przypadku specjalnego typu utworów, które zostały skomponowane za pomocą programu SoftSynth.+
- +
- +
-*TYPE D - Digital (sample). W tym typie pliku SAP powinny być zdefiniowane komendy INIT i PLAYER. PLAYER (zupełnie jak w typie "B") ustawia adres procedury, która będzie wywoływana co 1/50 sekundy i (także jak w typie "B") będzie kończyć się rozkazem RTS. INIT tym razem działa nieco inaczej. Ustawia on adres procedury, która będzie wywoływana (z numerem utworu w rejestrze A) do zainicjowania programu, ale nie może się kończyć RTS-em. Powinna zacząć odgrywać sample w nieskończonej pętli. W playerze SAP emulowane są dwa rejestry [[ANTIC]]a+
-($D40A i $D40B). Pomagają one odgrywać sample. Rejestr $D40B zwiększa swoją zawartość co 2+
-linie obrazu, natomiast $D40A wstrzymuje procesor do końca aktualnie rysowanej linii. SAP+
-emuluje Atari w systemie PAL z wyłączonym ekranem. Znaczy to, że mamy do dyspozycji 312+
-linii/ekran, gdzie każda zabiera 105 cykli procesora i 9 cykli na odźwieżenie pamięci (co daje 114 cykli na linię).+
- +
*TYPE M - póki co identyczny z typem "B". Zróżnicowanie to ma na celu wykorzystanie w przyszłych wersjach SAP-a. *TYPE M - póki co identyczny z typem "B". Zróżnicowanie to ma na celu wykorzystanie w przyszłych wersjach SAP-a.
 +*TIME xx:xx - Czas trwania utworu z dokładnością do tysięcznych częsci sekundy. Aktualnie jest on rozpoznawany przez pakiet [[ASAP]] oraz wszelkie jego "odgałęzienia". W zależności od ilości subsongów jest on powtórzony odpowiednią ilość razy (kolejno dla każdego subsongu).
-Planowane parametry:+Planowany był również ''TYPE R'' - Rejestry.
- +W tym typie część binarna nie ma postaci pliku binarnego. Część ta zawiera wartości, które będą bezpośrednio wpisywane do rejestrów POKEYa ($D200-$D208) w odstępach 1/50-sekundowych (lub takich jak zdefiniowano przez FASTPLAY). Próby zastosowania tego parametru podjął się Don Mahurin (oto jego [http://sap.openright.org strona]). Wątpliwe jest jednak, by typ R zyskał wsparcie w oprogramowaniu w postaci zaproponowanej przez Dona, z uwagi na dodakowe paramery w stylu AUDCTL (niekompatybilne z żadnym z istniejących odtwarzaczy) oraz brak wsparcia dla możliwych zapętleń i subsongów. Także w przyszłości najprawdopodobniej typ ten zostanie zastąpiony przez ''TYPE B'', tylko z odpowiednio napisaną procedurą odtwarzającą.
-*TYPE R - Rejestry. W tym typie część binarna nie ma postaci pliku binarnego. Część ta zawiera wartości, które będą bezpośrdnio wpisywane do rejestrów POKEYa ($D200-$D208) w odstępach 1/50-sekundowych (lub takich jak zdefiniowano przez FASTPLAY).+
- +
-*TIME xx:xx - Czas trwania utworu. Aktualnie jest on rozpoznawany przez SAP-plugin do WinAMP-a. Ciągle nie jest jasne jak subsongi będą traktowane z parametrem TIME. Możliwe, że będzie również wsparcie dla części dziesiątych oraz setnych sekundy (xx:xx.x lub xx:xx.xx).+
Linia 125: Linia 105:
PLAYER 247F PLAYER 247F
-==Część druga - dane binarne==+===Część druga - dane binarne===
-Część ta zawiera dane playera oraz muzyki zapisane w pliku binarnym. Format ten ma+Część ta zawiera dane playera oraz muzyki zapisane w pliku binarnym. Format ten to [[COM]]. Bloki typu ''Init'' ($02E2,$02E3) nie są obsługiwane.
-dwubajtowy nagłówek FF,FF. Kolejne dwa bajty wskazują loaderowi odkąd ma dane wczytywać,+
-natomiast dwa następne wskazują adres końca danych. Bloki typu ''Init'' ($02E2,$02E3) nie są+
-obsługiwane.+
- +===Jak stworzyć plik SAP===
-Mały przykład:+
- +
- FF FF 00 20 04 20 01 42 A3 04 D5+
- \___/ \_________/ \____________/+
- A B C+
- +
-A - Identyfikacja pliku binarnego (zawsze FF FF)+
-B - Adres wczytania (StartAddr, EndAddr w kolejności ''STARSZY, MŁODSZY'' bajt - $2000 do $2004)+
-C - Dane (które zostaną załadowane od ''StartAddr'')+
- +
-Przykład ten wczyta wartości ''01,42,A3,04,D5'' do pamięci od $2000 do $2004+
- +
- +
- +
-==Jak stworzyć plik SAP==+
Pierwsze co należy zrobić to wyciąć muzykę z gry lub dema i zapisać ją w pliku binarnym. Następnie należy stworzyć plik tekstowy z opisem (tak jak opisano wyżej), po czym można Pierwsze co należy zrobić to wyciąć muzykę z gry lub dema i zapisać ją w pliku binarnym. Następnie należy stworzyć plik tekstowy z opisem (tak jak opisano wyżej), po czym można
Linia 155: Linia 117:
Plik SAP jest gotowy! Plik SAP jest gotowy!
 +
 +===Linki===
 +* [http://asap.sourceforge.net/sap-format.html Specyfikacja pliku]
[[Kategoria:Formaty plików]] [[Kategoria:Formaty plików]]

Aktualna wersja

Spis treści

Wstęp

Plik SAP składa się z dwóch części. Pierwsza (tekst) opisuje typ playera/muzyki oraz zawiera informacje o autorze (lub autorach). Druga - zawiera samą procedurę odtwarzającą oraz dane muzyki - w zwykłym (znanym z Atari) pliku binarnym.

Część pierwsza - informacja tekstowa

Dla identyfikacji formatu plik zawsze rozpoczyna się ciągiem "SAP", po czym następują informacje o osobie, lub osobach, odpowiedzialnych za dany utwór. Wprawdzie nie ma z góry ustalonej ich kolejności, jednak zwyczajowo utarło się podawać je tak jak poniżej. Każda linia powinna kończyć się kodami 0D i 0A (EOL).

Wyświetlane informacje:

  • AUTHOR "" - Imię i nazwisko kompozytora. Dla potrzeb ASMA powinno się podać prawdziwe personalia oraz nick (ksywę scenową) w nawiasach. Nie podaje się grupy. Jeżeli utwór został skomponowany przez więcej niż innego autora, stosuje się znak "&".

Przykłady:

 AUTHOR "Dariusz Duma (Dhor)"
 AUTHOR "Lukasz Sychowicz (X-Ray) & Piotr Swierszcz (Samurai)"
  • NAME "" - Tytuł utworu. W zasadzie bez ograniczeń, stosować można wszystkie znaki prócz cudzysłowów. Zamiast nich można użyć apostrofów.

Przykład:

 NAME "Jocky Wilson's Darts Challenge"
  • DATE "" - Rok "copyrightu" lub rok powstania. Jeżeli dokładna data jest znana, może być przedstawiona w formacie DD/MM/RRRR

Przykłady:

 DATE "1986"
 DATE "1993-1994"
 DATE "28/08/1997"
 DATE "12/2001" 

W dalszej kolejności następują informacje dla playera:

  • TYPE - typ playera (patrz niżej)
  • PLAYER - adres playera, który będzie wywoływany w odstępach 1/50-sekundowych (lub takich jak zdefiniowano przez FASTPLAY)
  • MUSIC - adres danych muzyki (dla "TYPE C" - typ playera "C")
  • INIT - adres części playera odpowiedzialnej za jego zainicjowanie (wszystkie typy oprócz "C")
  • SONGS - ilość utworów. Jeśli pominiemy ten parametr, domyślną wartością jest 1
  • DEFSONG - pierwszy utwór, który będzie odgrywany bezpośrednio po wgraniu .sap-a (np. główny temat z gry). Wartość ta jest liczona od zera (jeżeli w pliku jest 5 utworów a ostatni jest domyślny, bedzie wpisane DEFSONG 4). Wartością domyślną jest 0, jeśli "DEFSONG" został pominięty
  • FASTPLAY - ilość linii, co którą jest wywoływana procedura odgrywająca (312 domyślnie, czyli jeden ekran - 1/50 sekundy). Na przykład dla podwójnej szybkości utworu ("2 razy na ramkę") wpisz tutaj wartość 156 (312/2). Większość utworów gra z pojedynczą szybkością ("raz na ramkę"), nie jest więc konieczne ustawianie tego parametru. Inne często spotykane wartości: 104 ("3 razy na ramkę"), 78 ("4 razy na ramkę")
  • STEREO - utwór używa drugiego POKEYa (stereo lub/i 8 kanałów)

Komendy PLAYER, MUSIC, INIT zawierają adresy w formacie hexadecymalnym. Przyjmowane są zarówno wielkie, jak i małe litery.

 PLAYER A000
 MUSIC 1234
 INIT f42e

Komendy SONGS, DEFSONG zawierają liczby w formacie dziesiętnym:

 SONGS 10
 DEFSONG 9

Komenda TYPE zawiera pojedynczy znak, który określa typ playera. Obsługiwane są następujące typy:

  • TYPE C - player do modułów w formacieCMC (Chaos Music Composer). W tym przypadku muszą pojawić się także komendy: PLAYER, MUSIC. Można również zdefiniować SONGS i DEFSONG.

Player zostanie zainicjowany następująco:

        lda #$70
        ldx #<MUSIC
        ldy #>MUSIC
        jsr PLAYER+3
        lda #$00
        ldx #DEFSONG
        jsr PLAYER+3

Natomiast co 1/50 sekundy wywołane zostanie:

        jsr PLAYER+6

W tym przypadku nie ma potrzeby dodawania playera z CMC, ponieważ jest on zawarty w pliku SAP.

  • TYPE B - dowolny player. W tym przypadku także powinny pojawić się komendy PLAYER, INIT. Dodatkowo mozna zdefiniować SONGS i DEFSONG.

Wywołanie playera odbędzie się w sposób następujący:

        lda #DEFSONG
        jsr INIT

Natomiast co 1/50 sekundy wywołane zostanie:

        jsr PLAYER
  • TYPE S - SoftSynth. W założeniach tymczasowy rodzaj playera (podobnie zresztą jak typ "C"). Może on być użyty tylko w przypadku specjalnego typu utworów, które zostały skomponowane za pomocą programu SoftSynth.
  • TYPE D - Digital (sample). W tym typie pliku SAP powinny być zdefiniowane komendy INIT i PLAYER. PLAYER (zupełnie jak w typie "B") ustawia adres procedury, która będzie wywoływana co 1/50 sekundy i (także jak w typie "B") będzie kończyć się rozkazem RTS. INIT tym razem działa nieco inaczej. Ustawia on adres procedury, która będzie wywoływana (z numerem utworu w rejestrze A) do zainicjowania programu, ale nie może się kończyć RTS-em. Procedura ta powinna odgrywać sample w nieskończonej pętli. W playerze SAP emulowane są dwa rejestry ANTIC-a ($D40A i $D40B). Pomagają one odgrywać sample. Rejestr $D40B zwiększa swoją zawartość co 2 linie obrazu, natomiast $D40A wstrzymuje procesor do końca aktualnie rysowanej linii. SAP emuluje Atari w systemie PAL z wyłączonym ekranem. Znaczy to, że mamy do dyspozycji 312 linii/ekran, gdzie każda zabiera 105 cykli procesora i 9 cykli na odświeżenie pamięci (co daje 114 cykli na linię).
  • TYPE M - póki co identyczny z typem "B". Zróżnicowanie to ma na celu wykorzystanie w przyszłych wersjach SAP-a.
  • TIME xx:xx - Czas trwania utworu z dokładnością do tysięcznych częsci sekundy. Aktualnie jest on rozpoznawany przez pakiet ASAP oraz wszelkie jego "odgałęzienia". W zależności od ilości subsongów jest on powtórzony odpowiednią ilość razy (kolejno dla każdego subsongu).

Planowany był również TYPE R - Rejestry. W tym typie część binarna nie ma postaci pliku binarnego. Część ta zawiera wartości, które będą bezpośrednio wpisywane do rejestrów POKEYa ($D200-$D208) w odstępach 1/50-sekundowych (lub takich jak zdefiniowano przez FASTPLAY). Próby zastosowania tego parametru podjął się Don Mahurin (oto jego strona). Wątpliwe jest jednak, by typ R zyskał wsparcie w oprogramowaniu w postaci zaproponowanej przez Dona, z uwagi na dodakowe paramery w stylu AUDCTL (niekompatybilne z żadnym z istniejących odtwarzaczy) oraz brak wsparcia dla możliwych zapętleń i subsongów. Także w przyszłości najprawdopodobniej typ ten zostanie zastąpiony przez TYPE B, tylko z odpowiednio napisaną procedurą odtwarzającą.


Przykład nagłówka:

 SAP
 AUTHOR "Jakub Husak"
 NAME "Inside"
 DATE "1990"
 SONGS 3
 DEFSONG 0
 TYPE B
 INIT 0F80
 PLAYER 247F

Część druga - dane binarne

Część ta zawiera dane playera oraz muzyki zapisane w pliku binarnym. Format ten to COM. Bloki typu Init ($02E2,$02E3) nie są obsługiwane.

Jak stworzyć plik SAP

Pierwsze co należy zrobić to wyciąć muzykę z gry lub dema i zapisać ją w pliku binarnym. Następnie należy stworzyć plik tekstowy z opisem (tak jak opisano wyżej), po czym można zbudować plik .sap poprzez połączenie tych dwóch plików. Można tego dokonać na przykład za pomocą DOSowej komendy COPY:

 copy /b music.txt+music.bin music.sap

Plik SAP jest gotowy!

Linki

Personal tools