SAP (format pliku): Różnice pomiędzy wersjami

Z Atariki
Przejdź do nawigacji Przejdź do wyszukiwania
następna edycja →

Miker (dyskusja | edycje)

1 grupa użytkowników
4175 edycji
m na razie tak - przy okazji się translejtnie...
 
no i po polsku :)
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.
 
 
*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).


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:
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 31 mar 2006, 23:13

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: „https://atariki.krap.pl/index.php?title=SAP_(format_pliku)&oldid=11298”