some corrections to libFLAC section

diff --git a/doc/ru/documentation.html b/doc/ru/documentation.html
index 09127b0..95091d0 100644 (file)
--- a/doc/ru/documentation.html
+++ b/doc/ru/documentation.html
@@ -419,9 +419,9 @@
 <A NAME="libflac">
 <H3><B><TT>libFLAC</TT></B></H3>
 
-<P>Áèáëèîòåêà <B><TT>libFLAC</TT></B> ÿâëÿåòñÿ ðåàëèçàöèåé íà C áàçîâîãî åíêîäåðà è äåêîäåðà. Èñïîëüçóÿ ýòó áèáëèîòåêó è íàïèñàâ íåìíîãî êîäà, ìîæíî äîáàâèòü ïîääåðæêó FLAC â ñâîþ ïðîãðàììó. Óñëîâèÿ ðàñïðîñòðàíåíèÿ - <A HREF="http://www.gnu.org/copyleft/lesser.html">LGPL</A>. Èñõîäíûå êîäû áèáëèîòåêè <B><TT>libFLAC</TT></B>, òàêæå êàê è êîíñîëüíîãî êîäåêà è ïëàãèíîâ äîñòóïíû, è ìîãóò ïîñëóæèòü õîðîøèì ïðèìåðîì äëÿ èñïîëüçîâàíèÿ.</P>
+<P>Áèáëèîòåêà <B><TT>libFLAC</TT></B> ÿâëÿåòñÿ ðåàëèçàöèåé íà C áàçîâîãî åíêîäåðà è äåêîäåðà. Èñïîëüçóÿ ýòó áèáëèîòåêó è íàïèñàâ íåìíîãî êîäà, ìîæíî äîáàâèòü ïîääåðæêó FLAC â ñâîþ ïðîãðàììó. Óñëîâèÿ åå ðàñïðîñòðàíåíèÿ - <A HREF="http://www.gnu.org/copyleft/lesser.html">LGPL</A>. Èñõîäíûå òåêñòû áèáëèîòåêè <B><TT>libFLAC</TT></B>, òàêæå êàê è êîíñîëüíîãî êîäåêà è ïëàãèíîâ, äîñòóïíû, è ìîãóò ïîñëóæèòü õîðîøèì ïðèìåðîì äëÿ èñïîëüçîâàíèÿ.</P>
 
-<P><B><TT>libFLAC</TT></B> òðåáóåò ñòàíäàðòíóþ è ìàòåìàòè÷åñêóþ áèáëèîòåêè äëÿ ÿçûêà C. Ïîòîêè íå èñïîëüçóþòñÿ, îäíàêî, òàê êàê <B><TT>libFLAC</TT></B> íå èñïîëüçóåò ãëîáàëüíûå ïåðåìåííûå, áèáëèîòåêà äîëæíà áûòü thread-safe.</P>
+<P><B><TT>libFLAC</TT></B> òðåáóåò ñòàíäàðòíóþ è ìàòåìàòè÷åñêóþ áèáëèîòåêè äëÿ ÿçûêà C. Ïðîãðàììíûå ïîòîêè íå èñïîëüçóþòñÿ, îäíàêî, òàê êàê <B><TT>libFLAC</TT></B> íå èñïîëüçóåò ãëîáàëüíûå ïåðåìåííûå, áèáëèîòåêà äîëæíà áûòü thread-safe.</P>
 
 <P>Èíòåðôåéñ <B><TT>libFLAC</TT></B> îïèñàí â ïóáëè÷íûõ çàãîëîâî÷íûõ ôàéëàõ â êàòàëîãå include/FLAC. Äëÿ èñïîëüçîâàíèÿ ñêîìïèëèðîâàííîé áèáëèîòåêè íóæíû òîëüêî ïóáëè÷íûå çàãîëîâêè. Îáðàòèòå âíèìàíèå íà òî, ÷òî êîä èç src/libFLAC/, âêëþ÷àÿ çàùèùåííûå çàãîëîâî÷íûå ôàéëû èç src/libFLAC/include/ íå íóæåí.</P>
 
@@ -442,18 +442,18 @@
 
 </OL>
 
-<P>Äëÿ äåêîäèðîâàíèÿ <B><TT>libFLAC</TT></B> ïðåäîñòàâëÿåò òðè óðîâíÿ äîñòóïà. Íà íèæíåì óðîâíå íàõîäèòñÿ äåêîäåð ïîòîêîâ, äàëåå - äåêîäåð ïîòîêîâ ñ âîçìîæíîñòüþ ïîèñêà, à íà âåðõíåì - ôàéëîâ. Èíòåðôåéñû îïèñàíû â ôàéëàõ <TT>stream_decoder.h</TT>, <TT>seekable_stream_decoder.h</TT> è <TT>file_decoder.h</TT> ñîîòâåòñòâåííî. Îáû÷íî èñïîëüçîâàòü ñòîèò äåêîäåð áîëåå âåðõíåãî óðîâíÿ.</P>
-
-<P>Ïîòîêîâûé äåêîäåð ðàññ÷èòûâàåò íà îáðàòíûå âûçîâû äëÿ âñåãî ââîäà è âûâîäà è íå èìååò ôóíêöèé äëÿ ïîèñêà. Îíè äîáàâëåíû â äåêîäåð ñ âîçìîæíîñòüþ ïîèñêà, êîòîðûé ÿâëÿåòñÿ îáåðòêîé. Îäíàêî, äëÿ èñïîëüçîâàíèÿ âîçìîæíîñòè ïèîñêà âû äîëæíû äîáàâèòü äîïîëíèòåëüíûå îáðàòíûå âûçîâû (seek è tell). Ôàéëîâûé äåêîäåð, ÿâëÿþùèéñÿ îáåðòêîé äëÿ äåêîäåðà ïîòîêîâ ñ âîçìîæíîñòüþ ïîèñêà, ñàì îñóùåñòâëÿåò áîëüøèíñòâî îáðàòíûõ âûçîâîâ.</P>
-
-<P>Åíêîäåð ðåàëèçîâàí òîëüêî íà ïîòîêîâîì óðîâíå (<TT>stream_encoder.h</TT>), òàê êàê ïîèñê âî âðåìÿ êîäèðîâàíèÿ - äîâîëüíî ñòðàííàÿ âîçìîæíîñòü.</P>
+<P>Äëÿ äåêîäèðîâàíèÿ <B><TT>libFLAC</TT></B> ïðåäîñòàâëÿåò òðè óðîâíÿ äîñòóïà. Íà íèæíåì óðîâíå íàõîäèòñÿ äåêîäåð ïîòîêîâ, íà ñëåäóþùåì - äåêîäåð ïîòîêîâ ñ âîçìîæíîñòüþ ïîèñêà, à íà âåðõíåì - äåêîäåð ôàéëîâ. Èíòåðôåéñû îïèñàíû â ôàéëàõ <TT>stream_decoder.h</TT>, <TT>seekable_stream_decoder.h</TT> è <TT>file_decoder.h</TT> ñîîòâåòñòâåííî. Èñïîëüçîâàòü ëó÷øå âñåãî äåêîäåð áîëåå âåðõíåãî óðîâíÿ.</P>\r
+\r
+<P>Ïîòîêîâûé äåêîäåð ðàññ÷èòûâàåò íà îáðàòíûå âûçîâû äëÿ ïîëó÷åíèÿ âõîäíûõ è âûõîäíûõ äàííûõ. Äåêîäåð ñ âîçìîæíîñòüþ ïîèñêà ÿâëÿåòñÿ îáåðòêîé ïîòîêîâîãî äåêîäåðà, ïðåäîñòàâëÿþùèé âîçìîæíîñòü ïîèñêà, îäíàêî äëÿ åãî âûïîëíåíèÿ âàì íåîáõîäèìî äîáàâèòü îáðàòíûå âûçîâû. Ôàéëîâûé äåêîäåð ñàì îñóùåñòâëÿåò îáðàòíûå âûçîâû äëÿ ÷òåíèÿ è ïðåäîñòàâëÿåò ôóíêöèè ïîèñêà.</P>\r
+\r
+<P>Åíêîäåð ïîêà ÷òî ðåàëèçîâàí òîëüêî íà ïîòîêîâîì óðîâíå (<TT>stream_encoder.h</TT>).</P>
 
 <P>Ñòðóêòóðû è êîíñòàíòû, îòíîñÿùèåñÿ ê ôîðìàòó, îïðåäåëåíû â ôàéëå <TT>format.h</TT>.</P>
-
+\r
 
 <P><B>ÄÅÊÎÄÅÐ ÏÎÒÎÊÎÂ</B></P>
  
-<P>Ñíà÷àëà îáñóäèì äåêîäåð ïîòîêîâ. Òèï åãî ýêçåìïëÿðà <TT>FLAC__StreamDecoder</TT>. Îáû÷íî â ïðîãðàììå ýêçåìïëÿð ñîçäàåòñÿ âûçîâîì <TT>FLAC__stream_decoder_new()</TT> è èíèöèàëèçèðóåòñÿ  <TT>FLAC__stream_decoder_init()</TT>. Ïðîãðàììà òàêæå ìîæåò ïðåäîñòàâëÿòü óêàçàòåëü client_data íà <TT>FLAC__stream_decoder_init()</TT>, êîòîðûé áóäåò èñïîëüçîâàòüñÿ äëÿ îáðàòíûõ âûçîâîâ.</P>
+<P>Ñíà÷àëà îáñóäèì äåêîäåð ïîòîêîâ. Òèï åãî ýêçåìïëÿðà <TT>FLAC__StreamDecoder</TT>. Îáû÷íî â ïðîãðàììå ýêçåìïëÿð ñîçäàåòñÿ âûçîâîì <TT>FLAC__stream_decoder_new()</TT>, çàòåì âûçûâàåò ôóíêöèè <TT>FLAC__stream_decoder_set_*()</TT> äëÿ óñòàíîâêè îáðàòíûõ âûçîâîâ è ïîëüçîâàòåëüñêèõ äàííûõ è èíèöèàëèçèðóåòñÿ ôóíêöèåé <TT>FLAC__stream_decoder_init()</TT>. Íåîáõîäèìûå îáðàòíûå âûçîâû:</P>
 
 <UL>
        <LI>Îáðàòíûé âûçîâ äëÿ ÷òåíèÿ. Ýòà ôóíêöèÿ âûçûâàåòñÿ, êîãäà äåêîäåðó íåîáõîäèìû äàííûå.  êà÷åñòâå ïàðàìåòðîâ ïåðåäàåòñÿ àäðåñ áóôåðà, êîòîðûé íóæíî çàïîëíèòü, è åãî ðàçìåð â áàéòàõ. Îáðàòíûé âûçîâ ìîæåò âåðíóòü ìåíüøå äàííûõ è èçìåíèòü ñ÷åò÷èê áàéòîâ, íî íå äîëæåí ïåðåïîëíÿòü áóôåð. Êîä âîçâðàòà ïðè âûõîäå âûáèðàåòñÿ èç <TT>FLAC__StreamDecoderReadStatus</TT>.</LI>
@@ -480,15 +480,28 @@
 <P>Êîãäà äåêîäåð çàêàí÷èâàåò ðàáîòó, ýêçåìïëÿð îáðàáàòûâàåòñÿ ôóíêöèåé <TT>FLAC__stream_decoder_finish()</TT>, êîòîðàÿ ïðîâåðÿåò ñîñòîÿíèå äåêîäåðà è îñâîáîæäàåò ïàìÿòü. Çàòåì ýêçåìïëÿð ìîæåò áûòü óäàëåí ôóíêöèåé <TT>FLAC__stream_decoder_delete()</TT> èëè èíèöèàëèçèðîâàí çàíîâî äëÿ äåêîäèðîâàíèÿ äðóãîãî ïîòîêà.</P>
 
 <P>Îáðàòèòå âíèìàíèå íà òî, ÷òî ïîòîêîâûé äåêîäåð íå èìååò ïðåäñòàâëåíèÿ î ïîçèöèè â ïîòîêå, îí òîëüêî ïðåîáðàçîâûâàåò äàííûå. ×òîáû îñóùåñòâëÿòü ïîèñê â ïîòîêå ôóíêöèè îáðàòíîãî âûçîâà ìîãóò òîëüêî ñáðàñûâàòü äàííûå äåêîäåðà ôóíêöèåé <TT>FLAC__stream_decoder_flush()</TT> è íà÷èíàòü ïîäàâàòü äàííûå ñ íîâîé ïîçèöèè ñ ïîìîùüþ îáðàòíîãî âûçîâà äëÿ ÷òåíèÿ. Äåêîäåð ôàéëîâ ïîñòóïàåò èìåííî òàê.</P>
+\r
+<P><B>ÄÅÊÎÄÅÐ ÏÎÒÎÊÎÂ Ñ ÂÎÇÌÎÆÍÎÑÒÜÞ ÏÎÈÑÊÀ</B></P>\r
 
+<P>Äåêîäåð ïîòîêîâ ñ âîçìîæíîñòüþ ïîèñêà ÿâëÿåòñÿ îáåðòêîé äëÿ ñòàíäàðòíîãî äåêîäåðà ïîòîêîâ. Òèï åãî ýêçåìïëÿðà - <TT>FLAC__SeekableStreamDecoder</TT>. Ê îáðàíûì âûçîâàì äåêîäåðà ïîòîêîâ äëÿ ÷òåíèÿ, çàïèñè, ðàáîòû ñ ìåòàäàííûìè è îáðàáîòêè îøèáîê íåîáõîäèìî äîáàâèòü åùå ñëåäóþùèå:</P>\r
+\r
+<UL>\r
+       <LI>Îáðàòíûé âûçîâ äëÿ ïîèñêà. Ýòà ôóíêöèÿ âûçûâàåòñÿ, êîãäà äåêîäåðó íóæíî íàéòè àáñîëþòíóþ ïîçèöèþ â ïîòîêå.</LI>\r
+       <LI>Îáðàòíûé âûçîâ äëÿ îïðåäåëåíèÿ òåêóùåé ïîçèöèè. Ýòà ôóíêöèÿ âûçûâàåòñÿ, êîãäà äåêîäåðó íóæíî óçíàòü òåêóùóþ ïîçèöèþ â ïîòîêå.</LI>\r
+       <LI>Îáðàòíûé âûçîâ äëÿ îïðåäåëåíèÿ ðàçìåðà ïîòîêà. Ôóíêöèÿ âûçûâàåòñÿ, êîãäà äåêîäåðó íóæíî óçíàòü ðàçìåð ïîòîêà. Èñïîëüçóåìîìó àëãîðèòìó ïîèñêà òðåáóåòñÿ çíàòü îáùèé ðàçìåð ïîòîêà.</LI>\r
+       <LI>Îáðàòíûé âûçîâ äëÿ îïðåäåëåíèÿ êîíöà ïîòîêà. Ôóíêöèÿ âûçûâàåòñÿ, êîãäà äåêîäåðó íóæíî çíàòü, äîñòèã ëè îí êîíöà ïîòîêà. Ýòîãî ðåçóëüòàòà ìîæíî äîáèòüñÿ, èñïîëüçóÿ îáðàòíûå âûçîâû äëÿ îïðåäåëåíèÿ òåêóùåé ïîçèöèè è îáùåãî ðàçìåðà, íî òàêîé ñïîñîá ìîæåò ïîòðåáîâàòü ãîðàçäî áîëüøå ðåñóðñîâ.</LI>\r
+\r
+<P>Ïîèñê îñóùåñâëÿåòñÿ ÷åðåç ìåòîä <TT>FLAC__seekable_stream_decoder_seek_absolute()</TT>.  ëþáîé ìîìåíò ïîñëå èíèöèàëèçàöèè ïîëüçîâàòåë ìîæåò âûçâàòü ýòó ôóíêöèþ äëÿ ïåðåõîäà ê îïðäåëåííîìó ñýìïëó â ïîòîêå. Ïåðâûé îáðàòíûé âûçîâ çàïèñè áóäåò ñîäåðæàòü (âîçìîæíî, íåïîëíûé) áëîê, íà÷èíàþùèéñÿ ñ çàäàííîãî ñýìïëà.</P>\r
+\r
+<P>Äåêîäåð ïîòîêîâ ñ âîçìîæíîñòüþ ïîèñêà ïðåäîñòàâëÿåò ïðîâåðêó ïîäïèñåé MD5. Åñëè åå âêëþ÷èòü ïåðåä èíèöèàëèçàöèåé, ôóíêöèÿ <TT>FLAC__seekable_stream_decoder_finish()</TT> ñîîáùèò ñîâïàäàåò ëè ïîäïèñü MD5 äåêîäèðîâàííîãî ïîòîêà ñ ñîõðàíåííîé áëîêå <TT>STREAMINFO</TT>. Ïðîâåðêà ïîäïèñè MD5 àâòîìàòè÷åñêè îòêëþ÷àåòñÿ ïðè ïîïûòêå ïîñèêà èëè åñëè â áëîêå <TT>STREAMINFO</TT> íå íàéäåíà ïîäïèñü.</TT>\r
 
 <P><B>ÄÅÊÎÄÅÐ ÔÀÉËÎÂ</B></P>
 
-<P>Äåêîäåð ôàéëîâ - ýòî îáîëî÷êà äåêîäåðà ïîòîêîâ, ïðèçâàííàÿ óïðîñòèòü ïðîöåññ äåêîäèðîâàíèÿ ôàéëîâ. Òèï åãî ýêçåìïëÿðà - <TT>FLAC__FileDecoder</TT>. Îòëè÷èå îò ïîòîêîâîãî äåêîäåðà ñîñòîèò â òîì, ÷òî âìåñòî îáðàòíîãî âûçîâà äëÿ ÷òåíèÿ (êîòîðûé îáðàáàòûâàåò ñàì äåêîäåð) ïðè èíèöèàëèçàöèè óêàçûâàåòñÿ ïóòü ê ôàéëó. Îñòàëüíûå ôóíêöèè àíàëîãè÷íû ýêâèâàëåíòàì â äåêîäåðå ïîòîêîâ.</P>
+<P>Äåêîäåð ôàéëîâ - ýòî îáîëî÷êà äåêîäåðà ïîòîêîâ ñ âîçìîæíîñòüþ ïîèñêà, ïðèçâàííàÿ óïðîñòèòü ïðîöåññ äåêîäèðîâàíèÿ ôàéëîâ. Òèï åãî ýêçåìïëÿðà - <TT>FLAC__FileDecoder</TT>. Îòëè÷èå îò ïîòîêîâîãî äåêîäåðà ñîñòîèò â òîì, ÷òî âìåñòî îáðàòíîãî âûçîâà äëÿ ÷òåíèÿ (êîòîðûé îáðàáàòûâàåò ñàì äåêîäåð) ïðè èíèöèàëèçàöèè óêàçûâàåòñÿ ïóòü ê ôàéëó. Âûïîëíåíèå îñòàëüíûõ ôóíêöèé äåêîäåð áåðåò íà ñåáÿ.</P>
 
-<P>Òàê êàê äåêîäåð ôàéëîâ ñàì óïðàâëÿåò âõîäíûìè äàííûìè, îí ìîæåò ïðåäîñòàâèòü è ïîèñê. Îí îñóùåñòâëÿåòñÿ ìåòîäîì <TT>FLAC__file_decoder_seek_absolute()</TT>.  ëþáîé ìîìåíò ïîñëå èíèöèàëèçàöèè äåêîäåðà ôàéëîâ ïðîãðàììà ìîæåò âûçâàòü ýòó ôóíêöèþ äëÿ ïîèñêà ñýìïëà â ôàéëå. Âïîñëåäñòâèè, ïðè ïåðâîì îáðàòíîì âûçîâå äëÿ çàïèñè îí áóäåò ñîäåðæàòü (âîçæîæíî íåïîëíûé) áëîê, íà÷èíàþùèéñÿ ñ ýòîãî ñýìïëà.</P>
+<P>Àíàëîãè÷íî äåêîäåðó ïîòîêîâ ñ âîçìîæíîñòüþ ïîèñêà îí ïðåäîñòàâëÿåò ïîèñê ÷åðåç ìåòîä <TT>FLAC__file_decoder_seek_absolute()</TT>.  ëþáîé ìîìåíò ïîñëå èíèöèàëèçàöèè äåêîäåðà ôàéëîâ ïðîãðàììà ìîæåò âûçâàòü ýòó ôóíêöèþ äëÿ ïîèñêà ñýìïëà â ôàéëå. Âïîñëåäñòâèè, ïðè ïåðâîì îáðàòíîì âûçîâå äëÿ çàïèñè îí áóäåò ñîäåðæàòü (âîçæîæíî íåïîëíûé) áëîê, íà÷èíàþùèéñÿ ñ ýòîãî ñýìïëà.</P>
 
-<P>Äåêîäåð ôàéëîâ òàêæå ïðåäîñòàâëÿåò ïðîâåðêó ïîäïèñè MD5. Åñëè ýòà âîçìîæíîñòü áóäåò âêëþ÷åíà ïåðåä èíèöèàëèçàöèåé, <TT>FLAC__file_decoder_finish()</TT> ñîîáùèò, åñëè ïîäïèñü MD5 ðàñïàêîâàííûõ äàííûõ íå ñîâïàäåò ñ ñîõðàíåííîé â áëîêå STREAMINFO. Ïðîâåðêà MD5 àâòîìàòè÷åñêè âûêëþ÷àåòñÿ, åñëè â áëîêå STREAMINFO íåò ïîäïèñè èëè ïðè ïîïûòêå îñóùåñòâëåíèÿ ïîèñêà.
+<P>Îò äåêîäåðà ïîòîêîâ ñ âîçìîæíîñòüþ ïîèñêà òàêæå íàñëåäóåòñÿ ïðîâåðêà ïîäïèñè MD5. Åñëè ýòà âîçìîæíîñòü áóäåò âêëþ÷åíà ïåðåä èíèöèàëèçàöèåé, <TT>FLAC__file_decoder_finish()</TT> ñîîáùèò, åñëè ïîäïèñü MD5 ðàñïàêîâàííûõ äàííûõ íå ñîâïàäåò ñ ñîõðàíåííîé â áëîêå STREAMINFO. Ïðîâåðêà MD5 àâòîìàòè÷åñêè âûêëþ÷àåòñÿ, åñëè â áëîêå STREAMINFO íåò ïîäïèñè èëè ïðè ïîïûòêå îñóùåñòâëåíèÿ ïîèñêà.
 
 
 <P><B>ÅÍÊÎÄÅÐ ÏÎÒÎÊÎÂ</B></P>
@@ -588,7 +601,7 @@
     <LI>WavPack - ñêîïèðóéòå <B><TT>flac_mac.exe</TT></B> ïîâåðõ <B><TT>External/wavpack.exe</TT></B> è <B><TT>External/wvunpack.exe</TT></B></LI>
     <LI>RKAU - ñêîïèðóéòå <B><TT>flac_mac.exe</TT></B> ïîâåðõ <B><TT>External/rkau.exe</TT></B></LI>
     </UL>
-Åñëè âûáðòàü WavPack, òî äëÿ èçìåíåíèÿ îïöèé FLAC áóäåò äîñòóïíî ìåíþ íàñòðîéêè WavPack Configuration.</LI>
+Åñëè âûáðàòü WavPack, òî äëÿ èçìåíåíèÿ îïöèé FLAC áóäåò äîñòóïíî ìåíþ íàñòðîéêè WavPack Configuration.</LI>
 <LI>Òåïåðü ìîæíî êîäèðîâàòü â ôîðìàò FLAC. Ïåðåèìåíîâàííûé ôàéë <B><TT>flac_mac.exe</TT></B> âûçûâàåò <B><TT>flac.exe</TT></B>, à çàòåì <B><TT>flac_ren.exe</TT></B> äëÿ ïðèñâîåíèÿ ïîëó÷àåìîìó ôàéëó ðàñøèðåíèÿ .flac.</LI>
 </UL>
 </P>