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 + \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.