SAP (format pliku)

From Atariki

(Różnice między wersjami)
Jump to: navigation, search
Wersja z dnia 19:11, 31 mar 2006
Miker (Dyskusja | wkład)
(na razie tak - przy okazji się translejtnie...)
← Previous diff		 Wersja z dnia 21:13, 31 mar 2006
Miker (Dyskusja | wkład)
(no i po polsku :))
Next diff →
Linia 1: Linia 1:
-<pre>+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.
-SAP file divides into two parts. First part (in text format) describes+
-player/music type and contains credits for the song. Second part (in binary+
-format) contains player and music data formed into Atari Binary File format.+
-First part - text info 
-~~~~~~~~~~~~~~~~~~~~~~ 
-For identification of the format, it always starts with "SAP" string. 
-After that the credits follow. However, this is not fixed order, just a 
-recommendation. Each line should end with EOL string (0D 0A). 
-Credits tags:+ Część pierwsza - informacja tekstowa
-AUTHOR "" - Name of composer. For ASMA purposes, the name should consist of + ------------------------------------
- real name and nickname (scene handle) in parentheses. No scene+
- group allowed. If song was composed by more authors, use "&".+
- Examples: +
- AUTHOR "Dariusz Duma (Dhor)"+
- AUTHOR "Lukasz Sychowicz (X-Ray) & Piotr Swierszcz (Samurai)"+
-NAME "" - Song title. No restrictions, except for it shouldn't contain+
- quotation marks. Use apostrophes instead.+
- Example:+
- NAME "Jocky Wilson's Darts Challenge"+
-DATE "" - Copyright year or year of creation. If exact date is known, it can+
- also be included in DD/MM/YYYY format.+
- Examples:+
- DATE "1986"+
- DATE "1993-1994"+
- DATE "28/08/1997"+
- DATE "12/2001" +
-After that the player info follows:+Dla identyfikacji formatu plik zawsze rozpoczyna się ciągiem "SAP", po czym następują
-TYPE - player type (see below)+informacje o osobie, lub osobach, odpowiedzialnych za dany utwór. Wprawdzie nie ma z góry
-PLAYER - address of player part which will be executed in 1/50 sec+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).
- intervals (or as defined with FASTPLAY)+
-MUSIC - address with music data (for C type)+
-INIT - address of player part which will init player (for all types+
- except C)+
-SONGS - number of songs. If SONGS tag not defined, the default value is+
- 1.+
-DEFSONG - first song which will be played when .sap is loaded (i.e. the+
- main game theme). This value is counted from zero (if there are 5+
- songs in the file and the last is the default, the value will be+
- DEFSONG 4). The default is 0 if DEFSONG not defined.+
-FASTPLAY - number of lines between each call of playing routine (312 by+
- default, which is one screen - 1/50 of sec.). For example for+
- double-speed song put here the value 156 (312/2). 99% of songs+
- are single-speed which means that you don't have to define the+
- FASTPLAY variable for them. Works for player TYPE "B".+
- Another values recommended: 104 (triple speed), 78 (quadruple+
- speed)+
-STEREO - song uses dual POKEY configuration.+
-commands PLAYER, MUSIC, INIT contain addresses in hexadecimal format. Both 
-lower- and uppercase characters are allowed for the number. 
-PLAYER A000+Wyświetlane informacje:
-MUSIC 1234+
-INIT f42e+
-commands SONGS, DEFSONG contain decimal numbers:+*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 "&".
-SONGS 10 
-DEFSONG 9 
-command TYPE contains single character which describes player type. The+ Przykłady:
-following player types are supported:+ AUTHOR "Dariusz Duma (Dhor)"
 + AUTHOR "Lukasz Sychowicz (X-Ray) & Piotr Swierszcz (Samurai)"
-TYPE C - player from CMC (Chaos Music Composer). In this case, also these+ 
- commands must appear: PLAYER, MUSIC. Additionaly you can define+*NAME "" - Tytuł utworu. W zasadzie bez ograniczeń, nie używa się tylko cudzysłowów. Zamiast tego stosuje się apostrofy.
- SONGS and DEFSONG. Player will be initialized as follows:+ 
 + Przykład:
 + 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
 + 
 + Przykłady:
 + DATE "1986"
 + DATE "1993-1994"
 + DATE "28/08/1997"
 + DATE "12/2001"
 + 
 + 
 +Potem 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 "SONGS" nie jest zdefiniowany, 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" nie został zdefiniowany
 +*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ę")
 +*STEREO - utwór używa drugiego [[POKEY]]a (stereo lub/i 8 kanałów)
 + 
 + 
 +Komendy PLAYER, MUSIC, INIT zawierają adresy w formacie hexadecymalnym. Zarówno wielkie, jak i małe litery są w nich dopuszczalne.
 + 
 + 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 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:
lda #$70 lda #$70
Linia 79: Linia 73:
jsr PLAYER+3 jsr PLAYER+3
- in 1/50 intervals will be executed:+ 
 +Natomiast co 1/50 sekundy wywołane zostanie:
jsr PLAYER+6 jsr PLAYER+6
- This is just internal structure already contained in SAP player, you 
- don't have to add this code to the CMC player. 
-TYPE B - any player. In this case, also these commands must appear: PLAYER,+W tym przypadku nie ma potrzeby dodawania playera z CMC, ponieważ jest on zawarty w pliku SAP.
- INIT. Additionaly you can define SONGS and DEFSONG. Player will be initialized as follows:+ 
 + 
 +*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 lda #DEFSONG
jsr INIT jsr INIT
- in 1/50 intervals will be executed:+ 
 +Natomiast co 1/50 sekundy wywołane zostanie:
jsr PLAYER jsr PLAYER
-TYPE S - SoftSynth. Like type "C", this type is temporary, and is used only 
- for special type of songs, that were composed using program 
- SoftSynth. 
-TYPE D - Digital. In SAP file with this type, there must be also defined  
- commands "INIT" and "PLAYER". "PLAYER" (like in type B) sets  
- address of procedure that will be called in 1/50s intervals and  
- (like in type B) must end with RTS opcode. INIT this time is a bit 
- different. It sets address of procedure that will be called (with  
- number of song in register A) to initialize program, but it can't 
- end with RTS. It should start playing digis in endless loop. In SAP 
- player two ANTIC registers $D40A and $D40B are emulated. They help 
- playing samples. D40B register increases its contents each two 
- screen lines. D40A holds CPU till the end of actually drawn line. 
- SAP emulates Atari in PAL with disabled screen. It means that we 
- have 312 lines per screen, each taking 105 CPU cycles and 9 cycles 
- of memory refresh (114 cycles per line). 
-One more type is recognized by SAP player - TYPE M. Right now it's exactly+*TYPE S - 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.
-the same as TYPE B but this differentiation is for future SAP releases.+
-Planned features: 
-TYPE R - Registers. In this type, binary part is not an Atari binary file. 
- This part contains values that will be directly written to Pokey 
- registers ($D200-$D208) in 1/50s intervals (or intervals defined 
- with FASTPLAY tag). 
-TIME xx:xx - Song duration. This is actually already supported by SAP WinAMP 
- plug-in. It's still unclear how will subsongs be handled with 
- TIME tag. Possibly it will also support tenths or hundredths of 
- second (xx:xx.x or xx:xx.xx). 
-Example of the header:+*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.
 + 
 + 
 +Planowane parametry:
 + 
 +*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-plgin do WinAMP-a. Ciągle nie jest jasne jak subsongi będą traktowane z parametrm TIME. Możliwe, że będzie również wsparcie dla dziesiątych oraz setnych częsci sekundy (xx:xx.x lub xx:xx.xx).
 + 
 + 
 +Przykład nagłówka:
SAP SAP
AUTHOR "Jakub Husak" AUTHOR "Jakub Husak"
Linia 138: Linia 127:
-Second part - binary data+ Część druga - dane binarne
-~~~~~~~~~~~~~~~~~~~~~~~~~+ --------------------------
-This part contains player and music data represented in Atari binary file+ 
-format. This format has two bytes header FF,FF. The following two bytes tell+ 
-the loader where to load data, and next two bytes tell where the data end.+Część ta zawiera dane playera oraz muzyki zapisane w pliku binarnym. Format ten ma
-Init data block ($02E2,$02E3) is not supported.+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.
 + 
 + 
 +Mały przykład:
-A little example:+ FF FF 00 20 04 20 01 42 A3 04 D5
 + \___/ \_________/ \____________/
 + A B C
-FF FF 00 20 04 20 01 42 A3 04 D5+A - Identyfikacja pliku binarnego (zawsze FF FF)
-\___/ \_________/ \____________/+B - Adres wczytania (StartAddr, EndAddr w kolejności ''STARSZY, MŁODSZY'' bajt - $2000 do $2004)
- A B C+C - Dane (które zostaną załadowane od ''StartAddr'')
-A - Binary file header identification (always FF FF)+Przykład ten wczyta wartości ''01,42,A3,04,D5'' do pamięci od $2000 do $2004
-B - Load addres (StartAddr, EndAddr in LO,HI order - $2000 to $2004)+
-C - Data (that will be loaded from StartAddr)+
-This example will load values 01,42,A3,04,D5 into memory from $2000 to $2004. 
 + Jak stworzyć plik SAP
 + ---------------------
-How to create .SAP file+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:
-First of all we need to rip music from a game or a demo and save it in Atari+
-binary file. Next we can create a text file with description (as described+
-above), then we can make .sap file by linking these two files. We can do that+
-using DOS command "copy", e.g.:+
-copy /b music.txt+music.bin music.sap+ copy /b music.txt+music.bin music.sap
-The file is made now!+Plik SAP jest gotowy!
-</pre>+

Wersja z dnia 21:13, 31 mar 2006

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ń, nie używa się tylko cudzysłowów. Zamiast tego stosuje się apostrofy. 
 Przykład:
 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 
 Przykłady:
 DATE "1986"
 DATE "1993-1994"
 DATE "28/08/1997"
 DATE "12/2001"


Potem 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 "SONGS" nie jest zdefiniowany, 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" nie został zdefiniowany
  • 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ę")
  • STEREO - utwór używa drugiego POKEYa (stereo lub/i 8 kanałów)


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

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

        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. 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 ANTICa

($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.


Planowane parametry:

  • 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-plgin do WinAMP-a. Ciągle nie jest jasne jak subsongi będą traktowane z parametrm TIME. Możliwe, że będzie również wsparcie dla dziesiątych oraz setnych częsci sekundy (xx:xx.x lub xx:xx.xx).


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 ma 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.


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

Źródło: "http://atariki.krap.pl/index.php/SAP_%28format_pliku%29"
Personal tools