151 lines
2.9 KiB
Markdown
151 lines
2.9 KiB
Markdown
# SOUND
|
|
|
|
Krótki efekt dźwiękowy wczytywany z pliku `.WAV`. Obsługuje sterowanie odtwarzaniem oraz zmianę próbkowania, co pozwala dynamicznie zmieniać wysokość i prędkość odtwarzanego dźwięku.
|
|
|
|
## Pola
|
|
|
|
### FILENAME
|
|
|
|
```
|
|
STRING FILENAME
|
|
```
|
|
|
|
Nazwa pliku `.WAV` z dźwiękiem. Jeżeli ścieżka nie zaczyna się od `$`, silnik dokleja prefiks `$WAVS\`. Pole odczytywane podczas inicjalizacji zmiennej; może być również ustawione w trakcie działania metodą [`LOAD`](#load).
|
|
|
|
### PRELOAD
|
|
|
|
```
|
|
BOOL PRELOAD
|
|
```
|
|
|
|
Określa, czy dane dźwięku mają być załadowane od razu przy inicjalizacji, czy dopiero przed pierwszym odtworzeniem.
|
|
|
|
## Metody
|
|
|
|
### ISPLAYING
|
|
|
|
```
|
|
BOOL ISPLAYING()
|
|
```
|
|
|
|
Sprawdza, czy dźwięk jest aktualnie odtwarzany.
|
|
|
|
**Zwraca**: [`BOOL`](BOOL.md) — `TRUE`, jeżeli dźwięk jest odtwarzany.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
SNDATGOAL^ISPLAYING();
|
|
SNDREX0^ISPLAYING();
|
|
```
|
|
|
|
### LOAD
|
|
|
|
```
|
|
void LOAD(STRING path)
|
|
```
|
|
|
|
Wczytuje plik dźwiękowy do zmiennej, zastępując dotychczas załadowany dźwięk. Bieżące odtwarzanie zostaje zatrzymane. Jeżeli ścieżka nie zaczyna się od `$`, dodawany jest prefiks `$WAVS\`.
|
|
|
|
**Parametry**
|
|
|
|
- `path` — ścieżka pliku `.WAV` w VFS gry.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
SNDATGOAL^LOAD(VARSTEMP0);
|
|
SNDWAV^LOAD("$WAVS\NAR_I000.WAV");
|
|
SNDANSWER^LOAD(ARRSEQ^GET(0));
|
|
```
|
|
|
|
### PAUSE
|
|
|
|
```
|
|
void PAUSE()
|
|
```
|
|
|
|
Pauzuje odtwarzanie dźwięku.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
SND_SHIP_GAZ2^PAUSE();
|
|
```
|
|
|
|
### PLAY
|
|
|
|
```
|
|
void PLAY()
|
|
```
|
|
|
|
Rozpoczyna odtwarzanie dźwięku. Po starcie emitowany jest sygnał [`ONSTARTED`](#onstarted); po zakończeniu odtwarzania — [`ONFINISHED`](#onfinished). Jeżeli dźwięk już gra, jest najpierw zatrzymywany i odtwarzany od początku.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
SNDTAKE^PLAY();
|
|
SNDATGOAL^PLAY();
|
|
```
|
|
|
|
### RESUME
|
|
|
|
```
|
|
void RESUME()
|
|
```
|
|
|
|
Wznawia odtwarzanie zatrzymane wcześniej przez [`PAUSE`](#pause).
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
SND_SHIP_GAZ2^RESUME();
|
|
```
|
|
|
|
### SETFREQ
|
|
|
|
```
|
|
void SETFREQ(INTEGER sampleRate)
|
|
```
|
|
|
|
Ustawia bieżące próbkowanie odtwarzanego dźwięku (w hercach). Wartość różna od próbkowania oryginalnego pliku zmienia wysokość i prędkość odtwarzania proporcjonalnie do stosunku obu wartości. Próbkowanie pliku oryginalnego silnik traktuje domyślnie jako `22050` Hz.
|
|
|
|
**Parametry**
|
|
|
|
- `sampleRate` — docelowe próbkowanie w Hz.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
SNDENGINE0^SETFREQ(10025);
|
|
```
|
|
|
|
### STOP
|
|
|
|
```
|
|
void STOP([BOOL emitSignal])
|
|
```
|
|
|
|
Zatrzymuje odtwarzanie dźwięku.
|
|
|
|
**Parametry**
|
|
|
|
- `emitSignal` — (opcjonalnie) jeżeli `FALSE`, sygnał [`ONFINISHED`](#onfinished) nie zostanie wyemitowany. Domyślnie sygnał jest emitowany.
|
|
|
|
**Przykłady**
|
|
|
|
```
|
|
SNDATGOAL^STOP(FALSE);
|
|
SNDIDLEREX^STOP();
|
|
```
|
|
|
|
## Sygnały
|
|
|
|
### ONSTARTED
|
|
|
|
Wywoływany po rozpoczęciu odtwarzania dźwięku przez metodę [`PLAY`](#play).
|
|
|
|
### ONFINISHED
|
|
|
|
Wywoływany po zakończeniu odtwarzania (naturalnym lub przez metodę [`STOP`](#stop) bez argumentu `FALSE`).
|