X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/272c44532a84a9a233a08c0c7707804921652072..3072610753c6e2c43808931e0a9ab9cc740bda8f:/docs/latex/wx/sndbase.tex

diff --git a/docs/latex/wx/sndbase.tex b/docs/latex/wx/sndbase.tex
index ccd563c188..73e9ab84b9 100644
--- a/docs/latex/wx/sndbase.tex
+++ b/docs/latex/wx/sndbase.tex
@@ -16,9 +16,9 @@ Base class for sound streams
 
 No base class
 
-\wxheading{Include file}
+\wxheading{Include files}
 
-wx/mmedia/sndbase.h
+<wx/mmedia/sndbase.h>
 
 \wxheading{Data structures}
 
@@ -26,7 +26,7 @@ wx/mmedia/sndbase.h
 %% wxSoundStream errors
 %%
 
-\wxheading{wxSoundStream errors}\label{wxsoundstreamerrors}
+\wxheading{wxSoundStream errors}
 
 \twocolwidtha{7cm}
 \begin{twocollist}\itemsep=0pt
@@ -56,6 +56,7 @@ may happen when you call wxSoundRouterStream::SetSoundFormat().}
 
 When a sound event is generated, it may either call the internal sound event 
 processor (which can be inherited) or call a C function. Its definition is:
+
 \begin{verbatim}
   typedef void (*wxSoundCallback)(wxSoundStream *stream, int evt,
                                   void *cdata);
@@ -63,13 +64,13 @@ processor (which can be inherited) or call a C function. Its definition is:
 
 The {\bf stream} parameter represents the current wxSoundStream.
 
-The {\bf evt} parameter represents the sound event which is the cause of the calling. (See \helpref{wxSound events}{wxsoundstreamevents})
+The {\bf evt} parameter represents the sound event which is the cause of the calling. (See \helpref{wxSound events}{wxsoundstream}).
 
 The {\bf cdata} parameter represents the user callback data which were specified
 when the user called \helpref{wxSoundStream::Register}{wxsoundstreamregister}.
 
-{\bf\it Note:} There is two other ways to catch sound events: you can inherit the
-sound stream and redefine \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}, or you can reroute the events to another sound stream using \helpref{wxSoundStream::SetEventHandler}{wxsoundstreameventhandler}
+{\it Note:} There are two other ways to catch sound events: you can inherit the
+sound stream and redefine \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}, or you can reroute the events to another sound stream using \helpref{wxSoundStream::SetEventHandler}{wxsoundstreamseteventhandler}.
 
 %%
 %% wxSoundStream streaming mode
@@ -78,18 +79,18 @@ sound stream and redefine \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamons
 \wxheading{wxSound streaming mode}
 
 The wxSoundStream object can work in three different modes. These modes are specified
-at the call to \helpref{wxSoundStream::StartProduction}{wxsoundstreamstartproduction}
-and cannot be changed until you call
+at the call to \helpref{wxSoundStream::StartProduction}{wxsoundstreamstartproduction} 
+and cannot be changed until you call 
 \helpref{wxSoundStream::StopProduction}{wxsoundstreamstopproduction}.
 
-The {\bf wxSOUND\_INPUT} mode is the recording mode. It generates {\bf wxSOUND\_INPUT}
+The {\bf wxSOUND\_INPUT} mode is the recording mode. It generates {\bf wxSOUND\_INPUT} 
 events and you cannot use wxSoundStream::Write().
 
-The {\bf wxSOUND\_OUTPUT} mode is the playing mode. It generates {\bf wxSOUND\_OUTPUT}
+The {\bf wxSOUND\_OUTPUT} mode is the playing mode. It generates {\bf wxSOUND\_OUTPUT} 
 events and you cannot use wxSoundStream::Read().
 
-The {\bf wxSOUND\_DUPLEX} mode activates the full duplex mode. The full duplex needs
-you make synchronous call to \helpref{wxSoundStream::Read}{wxsoundstreamread} and
+The {\bf wxSOUND\_DUPLEX} mode activates the full duplex mode. The full duplex requires
+you to make synchronous call to \helpref{wxSoundStream::Read}{wxsoundstreamread} and 
 \helpref{wxSoundStream::Write}{wxsoundstreamwrite}. This means that you must be
 careful with realtime problems. Each time you call Read you must call Write.
 
@@ -136,30 +137,29 @@ any temporary buffer.
 
 \func{wxSoundStream\&}{Read}{\param{void* }{buffer}, \param{wxUint32 }{len}}
 
-Reads \it{len} bytes from the sound stream. This call may block the user so
+Reads {\it len} bytes from the sound stream. This call may block the user so
 use it carefully when you need to intensively refresh the GUI. You may be
-interested by sound events: see
-\helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}.
+interested by sound events: see \helpref{wxSoundStream::OnSoundEvent}{wxsoundstreamonsoundevent}. 
+
 It is better to use the size returned by \helpref{wxSoundStream::GetBestSize}{wxsoundstreamgetbestsize}: this may improve performance or accuracy of the
 sound event system.
 
-\wxheading{Note on \it{len}}
+\wxheading{Parameters}
 
-\it{len} is expressed in bytes. If you need to do conversions between bytes
+\docparam{len}{{\it len} is expressed in bytes. If you need to do conversions between bytes
 and seconds use wxSoundFormat.
-See \helpref{wxSoundFormatBase}{wxsoundformatbase}, \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}.
-
-\wxheading{Note on data}
+See \helpref{wxSoundFormatBase}{wxsoundformatbase}, \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}.}
 
-Data in \it{buffer} are coded using the sound format attached to this sound 
+\docparam{data}{Data in \it{buffer} are coded using the sound format attached to this sound 
 stream. The format is specified with 
-\helpref{SetSoundFormat}{wxsoundstreamsetsoundformat}
+\helpref{SetSoundFormat}{wxsoundstreamsetsoundformat}.}
 
 %%
 %% Write
 %%
 
 \membersection{wxSoundStream::Write}\label{wxsoundstreamwrite}
+
 \func{wxSoundStream\&}{Write}{\param{const void* }{buffer}, \param{wxUint32 }{len}}
 
 Writes \it{len} bytes to the sound stream. This call may block the user so
@@ -169,17 +169,15 @@ use it carefully. You may be interested by sound events: see
 It is better to use the size returned by \helpref{wxSoundStream::GetBestSize}{wxsoundstreamgetbestsize}: this may improve performance or accuracy of the
 sound event system.
 
-\wxheading{Note on \it{len}}
+\wxheading{Parameters}
 
-\it{len} is expressed in bytes. If you need to do conversions between bytes
+\docparam{len}{This is expressed in bytes. If you need to do conversions between bytes
 and seconds use wxSoundFormat.
-See \helpref{wxSoundFormatBase}{wxsoundformatbase}, \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}.
-
-\wxheading{Note on data}
+See \helpref{wxSoundFormatBase}{wxsoundformatbase}, \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}.}
 
-Data in \it{buffer} are coded using the sound format attached to this sound 
+\docparam{buffer}{Data in \it{buffer} are coded using the sound format attached to this sound 
 stream. The format is specified with 
-\helpref{SetSoundFormat}{wxsoundstreamsetsoundformat}
+\helpref{SetSoundFormat}{wxsoundstreamsetsoundformat}.}
 
 %%
 %% GetBestSize
@@ -199,20 +197,29 @@ will not block for this buffer size.
 %%
 
 \membersection{wxSoundStream::SetSoundFormat}\label{wxsoundstreamsetsoundformat}
+
 \func{bool}{SetSoundFormat}{\param{const wxSoundFormatBase\& }{format}}
 
-SetSoundFormat is one of the key function of the wxSoundStream object. It specifies
-the sound format the user needs. SetSoundFormat tries to apply the format to the
-current sound stream (it can be a sound file or a sound driver). 
-Then, either it manages to apply it and it returns {\bf TRUE}, or it could not and
-it returns {\bf FALSE}. In this case, you must check the error with
+SetSoundFormat is one of the key function of the wxSoundStream object.
+It specifies the sound format the user needs. SetSoundFormat tries to
+apply the format to the current sound stream (it can be a sound file or a
+sound driver). Then, either it manages to apply it and it returns {\bf TRUE},
+or it could not and it returns {\bf FALSE}. In this case, you must check
+the error with
 \helpref{wxSoundStream::GetError}{wxsoundstreamgeterror}. See
 \helpref{wxSoundStream errors section}{wxsoundstreamerrors} for more details.
 
-\wxheading{Remark}
+
+\wxheading{Note}
 
 The {\bf format} object can be destroyed after the call. The object does not need it.
 
+\wxheading{Note}
+
+If the error is {\bf wxSOUND\_NOTEXACT}, the stream tries to find the best
+approaching format and setups it. You can check the format which it applied
+with \helpref{wxSoundStream::GetSoundFormat}{wxsoundstreamgetsoundformat}.
+
 %%
 %% GetSoundFormat
 %%
@@ -227,11 +234,12 @@ the stream itself.
 %% SetCallback
 %%
 \membersection{wxSoundStream::SetCallback}\label{wxsoundstreamregister}
+
 \func{void}{Register}{\param{int }{evt}, \param{wxSoundCallback }{cbk}, \param{void* }{cdata}}
 
-It installs a C callback for wxSoundStream events. The C callbacks are still useful
-to avoid hard inheritance. You can install only one callback per event. Each callback
-has its callback data.
+It installs a C callback for wxSoundStream events. The C callbacks are still
+useful to avoid hard inheritance. You can install only one callback per event.
+Each callback has its callback data.
 
 %%
 %% StartProduction
@@ -240,38 +248,41 @@ has its callback data.
 
 \func{bool}{StartProduction}{\param{int }{evt}}
 
-Starts the async notifier. After this call, the stream begins either 
-recording or playing or the two at the same time.
+StartProduction starts the sound streaming. {\it evt} may be one of
+{\bf wxSOUND\_INPUT}, {\bf wxSOUND\_OUTPUT} or {\bf wxSOUND\_DUPLEX}.
+You cannot specify several flags at the same time. Starting the production
+may automaticaly in position of buffer underrun (only in the case you activated
+recording). Actually this may happen the sound IO queue is too short.
+It is also advised that you fill quickly enough the sound IO queue when the
+driver requests it (through a wxSoundEvent).
 
 \membersection{wxSoundStream::StopProduction}\label{wxsoundstreamstopproduction}
-
 \func{bool}{StopProduction}{\void}
 
-Stops the async notifier.
-
+I stops the async notifier and the sound streaming straightly.
 
 \membersection{wxSoundStream::SetEventHandler}\label{wxsoundstreamseteventhandler}
-
 \func{void}{SetEventHandler}{\param{wxSoundStream* }{handler}}
 
 Sets the event handler: if it is non-null, all events are routed to it.
 
-
 \membersection{wxSoundStream::GetError}\label{wxsoundstreamgeterror}
 \constfunc{wxSoundError}{GetError}{\void}
 
+It returns the last error which occured.
 
 \membersection{wxSoundStream::GetLastAccess}\label{wxsoundstreamgetlastaccess}
 \constfunc{wxUint32}{GetLastAccess}{\void}
 
+It returns the number of bytes which were effectively written to/read from the sound stream.
 
 \membersection{wxSoundStream::QueueFilled}\label{wxsoundstreamqueuefilled}
 \constfunc{bool}{QueueFilled}{\void}
 
-This is only useful for device (I think).
-
+It returns whether the sound IO queue is full. When it is full, the next IO call will block
+until the IO queue has at least one empty entry.
 
 \membersection{wxSoundStream::OnSoundEvent}\label{wxsoundstreamonsoundevent}
 \func{void}{OnSoundEvent}{\param{int }{evt}}
 
-Handles event
+It is called by the wxSoundStream when a new sound event occured.
