No base class
-\wxheading{Include file}
+\wxheading{Include files}
-wx/mmedia/sndbase.h
+<wx/mmedia/sndbase.h>
\wxheading{Data structures}
%% wxSoundStream errors
%%
-\wxheading{wxSoundStream errors}\label{wxsoundstreamerrors}
+\wxheading{wxSoundStream errors}
\twocolwidtha{7cm}
\begin{twocollist}\itemsep=0pt
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);
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
\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.
\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
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
%%
\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
%%
%% 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
\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.
projects / wxWidgets.git / blobdiff