Bez šálku teorie to někdy nejde.

Teorie k DirectSound
Funkce knihovny vorbisfile.dll

Teorie k DirectSound

Předem říkm že tady nenajdete kompletní teorii k DirectSound, ale jen něco málo co je myslím dobré vědět nejen k pochopení tohoto kurzu. V DirectSound přehráváme zvuková data pomocí zvukových bufferů (sound buffer, rozhraní IDirectSoundBuffer8.) Zvukové buffery jsou dvojího typu. První z nich je primární buffer a to co v něm je je slyšet v repráčcích. Pokud jste se učili grafiku v DirectX, je to obdoba primárního povrchu, který představoval aktuální obsah obrazovky monitoru. Primární buffer je jen jeden. Ve struktuře DSCAPS která odráží schopnosti vašeho audio zařízení je sice členská proměnná uchovávající počet podporovaných primárních bufferů, ale i v dokumentaci se píše že tato hodnota bude vždy 1. Druhý, jak se dá možná očekávat, je sekundární buffer (obdoba offscreen povrchů z grafiky). Těchto bufferů můžete mít kolik jen chcete (pokud počítáme i softwarové). Hardwarových samozřejmě být kolik chcete nemůže. Opět najdeme příslušnou členskou proměnnou, která udává maximální počet sekundárních bufferů (všech, statických i streamovaných) ve struktuře DSCAPS. Dále můžeme sekundární buffery rozdělit na statické a streamované (dynamické). Liší se ve způsobu zápisu dat do bufferu. Do statického bufferu zapíšete data jednou a pak ho přehrajete. Streamovaný buffer se přehrává pořád dokola dokud ho nezastavíme a data se do něj zapisují v periodických intervalech. Sekundárních bufferů může hrát najednou víc než jeden. Výsledný zvuk vznikne mixováním bufferů. Mixování se provádí v primárním bufferu. Sekundární buffery mohou mít totiž různou vzorkovací frekvenci i jiné parametry a před výstupem z repráčku je nutno tyto parametry sjednotit. Proto data z každého sekundárního bufferu nejdřív putují do primárního bufferu a zde jsou přehrána. Pro tento kurz budeme potřebovat rozhraní IDirectSound8, což je hlavní rozhraní DirectSound. Bez něj nic neuděláme. Další rozhraní je IDirectSoundBuffer8 které představuje zvukový buffer (statický i dynamický). DirectSound disponuje ještě dalšími rozhraními, těmi se ale nebudeme zabývat, pro tento kurz nejsou důležitá. Více o práci s rozhraními se dozvíte v jednotlivých kapitolách.

Funkce knihovny vorbisfile.dll

Předem říkám, že všechny funkce vyžadují jako parametr strukturu OggVorbis_File. A tento parametr je vždy jako první. Také nebudu popisovat všechny funkce které se v knihovně nacházejí, ale jen ty nejdůležitější a myslím že také nejpoužívanější.

Struktury:

OggVorbis_File - je základní struktura. Obsahuje dílčí struktury a proměnné a tento celek po incialiaci obsahuje všechny důležité informace o ogg souboru. Obahuje proměnné a struktury nutné k dekódování ogg souboru.

vorbis_comment - je obsažena v OggVorbis_File a obsahuje pole komentářů v ogg souboru. Komentáře jsou textové řetězce. Na proměnnou udávající počet kometářů se také pamatovalo.

vorbis_info - je obsažena v OggVorbis_File a obsahuje informace o formátu audio dat jako je vzorkovací frekvence, počet kanálů, verze souboru a bitrate.

ov_callbacks - je obsažena v OggVorbis_File a obsahuje ukazatele na funkce pro práci se soubory (čtení, zápis, posun, získání pozice.) Je důležitá z hlediska možnosti čtení z jiných zdrojů než z jakých se dá číst funkcemi z knihovny stdio.h. Standartně jsou ukaztele nastaveny na funkce fread, fwrite, fseek a ftell.

Inicializace, otevření souboru a úklid na konci:

int ov_open(FILE *f,OggVorbis_File *vf,char *initial,long ibytes); - funkce otevře ogg soubor a inicializuje strukturu OggVorbis_File, samozřejmě pokud při otevírání nedojde k chybě. První parametr je ukazatel na otevřený soubor, zdroj dat, například pomocí funkce fopen. Druhý je ukazatel na strukturu OggVorbis_File, tj. strukturu kterou funkce inicializuje. Poslední dva paramtry mají význam v případě že nějaká data už byla načtena a zdrojový soubor nepodporuje seeking, přesouvání se v rámci zdroje. Pak může být druhý parametr ukazatel na buffer obsahující již načtená data, třetí parametr pak velikost bufferu v bajtech. Formát ogg je přizpůsobený i pro přenos po síti,to jest zdroj který nepodporuje přesouvání se. Nepřesunete se v něm zpět ani napřed. V případě kdy by se něco na síti vysílalo v ogg formátu, můžete jen poslouchat. S tím jsem se ale ještě nesetkal :( Na zdrojový soubor se musí vždy nechat odkazovat pomocí FILE*. Pokud funkce vrátí nula, je to v pořádku. Hodnoty menší než nula jsou chyby, viz dokumentace.

int ov_open_callbacks(void *datasource, OggVorbis_File *vf, char *initial, long ibytes, ov_callbacks callbacks); - má stejnou funkci jako ov_open, ale má o parametr navíc a to je struktura ov_callbacks. Použijte namísto ov_open v případě že nelze číst data ze zdroje standartními stdio funkcemi (fread, fwrite, fseek, ftell). Nula jako vrácená hodnota značí že je vše OK, číslo menší než nula je chyba.

ov_clear - funkce uvolní zdroje alokované pro dekódování souboru. Je nutné ji volat vždy po skončení dekódování, po ukončení práce s ogg souborem, když už s ním nebudeme nic dělat. Nemusíte volat funkci fclose pro zavření datového zdroje otevřeného například funkcí fopen, ov_clear volá fclose pro datový zdroj sama. Vrcí jen nulu.

int ov_test(FILE *f,OggVorbis_File *vf,char *initial,long ibytes); - otevírání ogg souboru se vnitřně provádí voláním dvou funkcí. Funkce ov_open volá obě za sebou, tato funkce volá jen první, která ověří že zdroj je ogg vorbis (načte první hlavičky) a otestuje zda zdroj podporuje přesouvání (seeking).Vrácené hodnoty menší než nula opět značí chybu, nula je OK :)

int ov_test_callbacks(void *datasource, OggVorbis_File *vf, char *initial, long ibytes, ov_callbacks callbacks); - varianta předchozí funkce s možností zadat vlastní funkce pro práci se soubory ve struktuře ov_callbacks. Viz struktura ov_callbacks a funkce ov_open_callbacks. Vrácené hodnoty menší než nula opět značí chybu, nula je OK :)

int ov_test_open(OggVorbis_File *vf); - dokončí otevírání zdroje otevřeného pomocí jedné z předchozích dvou funkcí. Vrátí-li nula, je vše OK. Hodnota menší než nula je opět chyba.

Dekódování (dekomprese zvuku):

long ov_read(OggVorbis_File *vf, char *buffer, int length, int bigendianp, int word, int sgned, int *bitstream); - funkce dekóduje do bufferu *buffer ogg soubor. Buffer má velikost length. Tolik se do něj vejde bajtů zvukových dat. Parametr length kolik bajtů dekódovaného zvuku chceme do bufferu uložit. Další parametry se týkají výstupního formátu dat, v jakém formátu chceme mít dekódovaný zvuk. bigendian udává formát bajtů, big nebo little endian (0 - little endian, 1 - big endian,obvykle 0). word udává velikost slova, 1 - byte, 2 - slovo. Tj. volba mezi 8bitovým a 16bitovým výstupem. sgned říká zda chceme signed int(hodnota 1) nebo unsigned int(hodnota 0). Obvykle se dává 2. Poslední je ukazatel na číslo aktuálního bitového proudu. Více viz ve druhé části. Návratová hodnota 0 znamená úspěch, hodnoty menší než nula chybu. Hodnoty větší než nula znamenají počet bajtů dekódovaných a uložených do bufferu. Funkce při jednom volání dekóduje maximálně 4096 bajtů.

Přesun v souboru (Seeking):

int ov_raw_seek(OggVorbis_File *vf,long pos); - přesune se na pozici pos v ogg souboru. Pozice se udává rozmezí komprimovaných bajtů souboru. Rozmezí získáte voláním funkce ov_raw_total (viz dále) s parametrem -1. Pozici zadejte tak jako kdyby jste zadávali offset v běžném binárním nebo textovém souboru. Návratová hodnota 0 znamená úspěch, hodnoty menší než nula chybu.

int ov_pcm_seek(OggVorbis_File *vf,ogg_int64_t pos); - přesune se na pozici pos v ogg souboru. Pozice se udává v audio vzorcích. Řečeno jinak, zadáte číslo audio vzorku od nuly (doufám :)). Návratová hodnota 0 znamená úspěch, hodnoty menší než nula chybu.

int ov_time_seek(OggVorbis_File *vf, double s); - přesune se na pozici pos v ogg souboru. Pozice se zadává jako čas v sekundách. Asi nejvhodnější funkce k přesunu po souboru. Návratová hodnota 0 znamená úspěch, hodnoty menší než nula chybu.

Informace o souboru:

long ov_bitrate(OggVorbis_File *vf,int i); - vrací průměrný datový tok. Parametr i je číslo bitového proudu (bitstreamu). U zdrojů které nepodporují přesuny (seeking) je ignorován. Pokud chcete bitrate aktuálního bitstreamu, souboru s kterým zrovna pracujete, zadejte -1. Návratové hodnoty menší než nula značí chybu. Hodnoty větší než nula - průměrný datový tok.

long ov_streams(OggVorbis_File *vf); - vrací počet logických bitstreamů v rámci našeho fyzického bitstreamu (ogg souboru). Vrácená hodnota 1 indikuje jeden logický bitstream nebo zdroj který nepodporuje přesuny (seeking). Hodnoty větší než jedna počet logických bitstreamů.

long ov_seekable(OggVorbis_File *vf); - vrací zda zdrojový soubor podporuje přesuny (seeking) - nenulová hodnota, nebo ne - hodnota 0.

long ov_serialnumber(OggVorbis_File *vf,int i); - vrací sériové číslo bitového proudu (bitstreamu) i. i může být -1 pro aktuální bitstream. Vrací -1 pokud bitstream i neexistuje, jinak sériové číslo.

ogg_int64_t ov_raw_total(OggVorbis_File *vf,int i); - vrací celkový počet komprimovaných bajtů zadaného logického bitstreamu. i = -1 pro aktuální bitstream. Vrací číslo větší než nula pokud uspěje. Pokud je i = -1, jedná se o celkový počet komprimovaných bajtů celého souboru.

ogg_int64_t ov_pcm_total(OggVorbis_File *vf,int i); - stejná jako předchozí funkce, ale vracená hodnota má význam audio vzorků. Pro vrácené hodnoty a parametr i platí stejná pravidla.

double ov_time_total(OggVorbis_File *vf,int i); - stejná jako ov_raw_total, ale vracená hodnota je v sekundách. Pro vrácené hodnoty a parametr i platí stejná pravidla.

ogg_int64_t ov_raw_tell(OggVorbis_File *vf); - vrací offset (určuje na jaké pozici od začátku souboru se bude číst a budou se provádět další operace) v souboru v komprimovaných bajtech.

ogg_int64_t ov_pcm_tell(OggVorbis_File *vf); - stejná jako předchozí. Vrácená hodnota má význam audio vzorků.

double ov_time_tell(OggVorbis_File *vf); - stejná jako ov_raw_tell, ale vrací offset v sekundách.

vorbis_info *ov_info(OggVorbis_File *vf,int link); - vrací ukazatel na strukturu vorbis_info i bitstreamu. i = -1, vrátí strukturu pro aktuální bitstream.

vorbis_comment *ov_comment(OggVorbis_File *vf,int link); - vrací ukazatel na strukturu vorbis_comment i bitstreamu. i = -1, vrátí strukturu pro aktuální bitstream.