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

Z Atariki
Przejdź do nawigacji Przejdź do wyszukiwania

Mono (dyskusja | edycje)

2792 edycje
m na razie tak - przy okazji się translejtnie...
 
Mono (dyskusja | edycje)
2792 edycje
link do aktualnej specyfikacji
 
(Nie pokazano 27 wersji utworzonych przez 5 użytkowników)
Linia 1: Linia 1:
<pre>
===Wstęp===
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.


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.


First part - text info
===Część pierwsza - informacja tekstowa===
~~~~~~~~~~~~~~~~~~~~~~
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:
Dla identyfikacji formatu plik zawsze rozpoczyna się ciągiem "SAP", po czym następują
AUTHOR "" - Name of composer. For ASMA purposes, the name should consist of
informacje o osobie, lub osobach, odpowiedzialnych za dany utwór. Wprawdzie nie ma z góry
            real name and nickname (scene handle) in parentheses. No scene
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).
            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:
Wyświetlane informacje:
TYPE      - player type (see below)
PLAYER    - address of player part which will be executed in 1/50 sec
            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
*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 "&".
lower- and uppercase characters are allowed for the number.


PLAYER A000
Przykłady:
MUSIC 1234
  AUTHOR "Dariusz Duma (Dhor)"
INIT f42e
  AUTHOR "Lukasz Sychowicz (X-Ray) & Piotr Swierszcz (Samurai)"


commands SONGS, DEFSONG contain decimal numbers:
*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.


SONGS 10
Przykład:
DEFSONG 9
  NAME "Jocky Wilson's Darts Challenge"


command TYPE contains single character which describes player type. The
*DATE "" - Rok "copyrightu" lub rok powstania. Jeżeli dokładna data jest znana, może być przedstawiona w formacie DD/MM/RRRR
following player types are supported:


TYPE C - player from CMC (Chaos Music Composer). In this case, also these
Przykłady:
        commands must appear: PLAYER, MUSIC. Additionaly you can define
  DATE "1986"
        SONGS and DEFSONG. Player will be initialized as follows:
  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 [[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.
 
  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 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.
 
Player zostanie zainicjowany następująco:


         lda #$70
         lda #$70
Linia 79: Linia 65:
         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
W tym przypadku nie ma potrzeby dodawania playera z CMC, ponieważ jest on zawarty w pliku SAP.
        don't have to add this code to the CMC player.


TYPE B - any player. In this case, also these commands must appear: PLAYER,
*TYPE B - dowolny player. W tym przypadku także powinny pojawić się komendy PLAYER, INIT. Dodatkowo mozna zdefiniować SONGS i DEFSONG.
        INIT. Additionaly you can define SONGS and DEFSONG. Player will be initialized as follows:
 
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
*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.
        for special type of songs, that were composed using program
 
        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 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 M - póki co identyczny z typem "B". Zróżnicowanie to ma na celu wykorzystanie w przyszłych wersjach SAP-a.
the same as TYPE B but this differentiation is for future SAP releases.


Planned features:
*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).
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:
Planowany był również ''TYPE R'' - Rejestry.
SAP
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ą.
AUTHOR "Jakub Husak"
NAME "Inside"
DATE "1990"
SONGS 3
DEFSONG 0
TYPE B
INIT 0F80
PLAYER 247F




Second part - binary data
Przykład nagłówka:
~~~~~~~~~~~~~~~~~~~~~~~~~
  SAP
This part contains player and music data represented in Atari binary file
  AUTHOR "Jakub Husak"
format. This format has two bytes header FF,FF. The following two bytes tell
  NAME "Inside"
the loader where to load data, and next two bytes tell where the data end.
  DATE "1990"
Init data block ($02E2,$02E3) is not supported.
  SONGS 3
  DEFSONG 0
  TYPE B
  INIT 0F80
  PLAYER 247F


A little example:
===Część druga - dane binarne===


FF FF 00 20 04 20 01 42 A3 04 D5
Część ta zawiera dane playera oraz muzyki zapisane w pliku binarnym. Format ten to [[COM]]. Bloki typu ''Init'' ($02E2,$02E3) nie są obsługiwane.
\___/ \_________/ \____________/
  A        B            C


A - Binary file header identification (always FF FF)
===Jak stworzyć plik SAP===
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.
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


How to create .SAP file
Plik SAP jest gotowy!
~~~~~~~~~~~~~~~~~~~~~~~
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
===Linki===
* [http://asap.sourceforge.net/sap-format.html Specyfikacja pliku]


The file is made now!
[[Kategoria:Formaty plików]]
</pre>

Aktualna wersja z 22 kwi 2021, 00:13

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

Źródło: „https://atariki.krap.pl/index.php?title=SAP_(format_pliku)&oldid=38530”